1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Maintains sessions to paths

    15 *

    16 */

    17 

    18 #ifndef CMPXCOLLECTIONCLIENTCONTEXT_H

    19 #define CMPXCOLLECTIONCLIENTCONTEXT_H

    20 

    21 #include <mpxcollectionpluginobserver.h>

    22 #include <mpxtaskqueueobserver.h>

    23 #include <mpxcmn.h>

    24 #include <mpxcommand.h>

    25 #include <mpxfilter.h>

    26 #include <mpxattributespecs.h>

    27 #include <mpxmessagequeue.h>

    28 #include "mpxcollectioncache.h"

    29 

    30 class CMPXClientList;

    31 class CMPXCollectionPath;

    32 class CMPXCollectionEngine;

    33 class CMPXCollectionPlugin;

    34 class MMPXCollectionEngineObserver;

    35 class CMPXActiveTaskQueue;

    36 class CMPXMedia;

    37 class CMPXCollectionCache;

    38 

    39 class CMPXCollectionClientContext : public CBase,

    40                                     public MMPXCollectionPluginObserver,

    41                                     public MMPXTaskQueueObserver

    42     {

    43 public: // DATA type

    44     enum TContextType

    45         {

    46         EContextBrowse, // context for browing

    47         EContextMedia, // context for media properties

    48         EContextRemove, // context for removing paths

    49         EContextCount

    50         };

    51 public:

    52     /**

    53     *  Two-phase constructor

    54     *

    55     *  @param aEngine reference to collection engine

    56     *  @param aModeId mode id

    57     *  @return object created

    58     */

    59     static CMPXCollectionClientContext* NewL(CMPXCollectionEngine& aEngine,

    60         CMPXCollectionCache& aCache, const TUid& aModeId);

    61 

    62     /**

    63     *  Destructor

    64     *

    65     */

    66     ~CMPXCollectionClientContext();

    67 

    68     /**

    69     *  Open collection by path

    70     *

    71     *  @param aPath collection path. Ownership transferred if not leave

    72     *  @param aMode, open mode

    73     *  @param aCallback callback

    74     *  @leave KErrArgument if aPath is not valid, or other system error

    75     */

    76     IMPORT_C void OpenL(CMPXCollectionPath* aPath,

    77                         TInt aMode,

    78                         MMPXCollectionEngineObserver* aCallback);

    79 

    80     /**

    81     *  Open collection by index

    82     *

    83     *  @param aIndex the index to current browse path

    84     *  @param aMode, open mode

    85     *  @param aAttrs, media attributes requested

    86     *  @param aCallback callback

    87     *  @leave system error

    88     */

    89     IMPORT_C void OpenL(TInt aIndex,

    90                         TInt aMode,

    91                         const TArray<TMPXAttribute>& aAttrs,

    92                         MMPXCollectionEngineObserver* aCallback);

    93 

    94     /**

    95     *  Open collection by uids. Collections which match the uids will be returned.

    96     *

    97     *  @param aUids a list of uids to be matched

    98     *  @param aMode, open mode

    99     *  @param aCallback callback

   100     *  @leave KErrNotReady if current browse path is invalid,

   101     *         KErrArgument if aIndex is out of range

   102     *         or other system error

   103     */

   104     IMPORT_C void OpenL(const TArray<TUid>& aUids,

   105                         TInt aMode,

   106                         MMPXCollectionEngineObserver* aCallback);

   107 

   108     /**

   109      *  Request current content of browse context

   110      *

   111      *  @param aMode, open mode

   112      *  @param aCallback callback

   113      *  @leave system error

   114      */

   115     IMPORT_C void OpenL(TInt aMode, MMPXCollectionEngineObserver* aCallback);

   116 

   117     /**

   118      *  Back to previous level

   119      *  @param aCallback callback

   120      *  @leave system error

   121      */

   122     IMPORT_C void BackL(MMPXCollectionEngineObserver* aCallback);

   123 

   124     /**

   125      *  Media request command

   126      *

   127      *  @param aCmd  command of media request

   128      *  @param aCallback callback

   129      *  @leave KErrArgument if aCmd is not valid, or other system error

   130      */

   131     IMPORT_C void MediaL(const CMPXCommand& aCmd,

   132                          MMPXCollectionEngineObserver* aCallback);

   133 

   134     /**

   135      *  Add a media

   136      *

   137      *  @param aMedia media object

   138      *  @leave system error

   139      */

   140     IMPORT_C void AddL(const CMPXMedia& aMedia);

   141 

   142     /**

   143      *  Remove a media

   144      *

   145      *  @param aMedia media object

   146      *  @leave system error

   147      */

   148     IMPORT_C void RemoveL(const CMPXMedia& aMedia);

   149 

   150     /**

   151      *  Update a media

   152      *

   153      *  @param aMedia media object

   154      *  @leave system error

   155      */

   156     IMPORT_C void SetL(const CMPXMedia& aMedia);

   157 

   158     /**

   159      *  Remove media by path

   160      *

   161      *  @param aPath collection path. Ownership transferred if not leave

   162      *  @param aCallback callback

   163      *  @leave KErrArgument if aPath is not valid, or other system error

   164      */

   165     IMPORT_C void RemoveL(CMPXCollectionPath* aPath,

   166                           MMPXCollectionEngineObserver* aCallback);

   167 

   168     /**

   169     *  Return plugin uid

   170     *

   171     *  @return plugin uid

   172     */

   173     IMPORT_C TUid PluginId() const;

   174 

   175     /**

   176     *  Return current collection path

   177     *

   178     *  @return collection path

   179     */

   180     IMPORT_C const CMPXCollectionPath& Path() const;

   181 

   182     /**

   183     *  Cancel all requests from aCallback

   184     *

   185     *  @param aCallback callback

   186     */

   187     IMPORT_C void CancelRequest(MMPXCollectionEngineObserver* aCallback);

   188 

   189     /**

   190     *  Attach another client to this object. aName is the unique name of the

   191     *  client, used for identifying the client and passing messages; aId is the

   192     *  thread id of the client of the interface (not the server session)

   193     *

   194     *  @param aId thread id of the client

   195     *  @param aMsgQueue message queue for the client

   196     *  @leave The function leaves with one of the system wide error codes,

   197     *         if the operation fails.

   198     */

   199     IMPORT_C void AddClientL(TThreadId aId,

   200                              CMPXMessageQueue* aMsgQueue);

   201 

   202     /**

   203     *  Remove the client from the context. aName is the unique name of the

   204     *  client, used for identifying the client and passing messages.

   205     *

   206     *  @param aMsgQueue message queue for the client

   207     */

   208     IMPORT_C void RemoveClient(const CMPXMessageQueue& aMsgQueue);

   209 

   210     /**

   211     * Get the supported attributes of the current plugin using by the context

   212     * @return TCollectionCapability bit mask flag

   213     */

   214     IMPORT_C TCollectionCapability GetCapabilities();

   215 

   216     /**

   217      *  Find all

   218      *

   219      *  @param aMedia media object of matching criteria, Ownership transferred

   220      *  @param aBuf, buffer data, array of attributes for results,

   221      *               Ownership transferred if find asynchronously

   222      *  @param aCallback callback

   223      *  @leave system error

   224      */

   225     IMPORT_C void FindAllL(const CMPXMedia& aMedia,

   226                            CBufBase* aBuf,

   227                            MMPXCollectionEngineObserver* aCallback);

   228 

   229    /** DEPRECATE, Use CommandL(CMPXCommand)

   230     *  Find all synchronously

   231     *

   232     *  @param aMedia media object of matching criteria

   233     *  @param aBuf, buffer data, array of attributes for results

   234     *  @leave system error

   235     *  @return results of the search

   236     */

   237     IMPORT_C CMPXMedia* FindAllSyncL(const CMPXMedia& aMedia,

   238                                      const CBufBase& aBuf);

   239 

   240     /**

   241      * Set the current filter applied to browsing

   242      */

   243     IMPORT_C void SetFilterL(const CMPXFilter* aFilter);

   244 

   245     /**

   246     * Get the current filter applied to browsing

   247     * @return filter

   248     */

   249     IMPORT_C const CMPXFilter* Filter() const;

   250 

   251     /** DEPRECATED

   252      * Handle a collection command

   253      * @param aCmd, command to handle

   254      * @param aData, optional data

   255      */

   256     IMPORT_C void CommandL(TMPXCollectionCommand aCmd, TInt aData);

   257 

   258     /**

   259      * Handle a collection command

   260      * @param aCmd, command to handle

   261      * @param aCallback callback

   262      * @param aMsgQueue Message Queue for the client

   263      * @leave KErrNotReady if not collection opened, or system error

   264      */

   265     IMPORT_C void CommandL(const CMPXCommand& aCmd,

   266                            MMPXCollectionEngineObserver* aCallback,

   267                            const CMPXMessageQueue& aMsgQueue);

   268 

   269     /**

   270     *  Does this thread have a shareable client?  If yes, a default mode

   271     *  connection can bind to it.

   272     *

   273     *  @param aId thread id of the client

   274     *  @return ETrue, if shareableclient is in the client list

   275     */

   276     TBool HasShareableClient(TThreadId aId);

   277 

   278     /**

   279     *  Notify the client of a collection event

   280     *  @param aMsg Message type

   281     *  @param aData some data

   282     */

   283     void NotifyL( TMPXCollectionBroadCastMsg aMsg, TInt aData );

   284 

   285     /**

   286     * Get the mode id of the context

   287     * @return collection mode id

   288     */

   289     const TUid& ModeId() const;

   290 

   291     /**

   292     * Handle message from plug-in

   293     *

   294     * @param aMsg, message from the plug-in

   295     * @param aError, error code

   296     * @param aNotifyOthers, indicates whether to notify other client contexts

   297     *        that the collection has changed

   298     */

   299     void DoHandleMessage(CMPXMessage* aMsg,

   300                          TInt aError,

   301                          TBool aNotifyOthers);

   302 

   303 private: // From base classes

   304 

   305     ///////////////////////////////////////////////////////////////////////////

   306     // From MMPXCollectionPluginObserver

   307 

   308     /**

   309     * Handle message from plug-in

   310     *

   311     * @param aMessage, message from the plug-in, Ownership not transferred.

   312     * @param aError error code

   313     */

   314     void HandleMessage(CMPXMessage* aMsg, TInt aError);

   315 

   316     /**

   317     * Handle opening group contents

   318     *

   319     * @param aMedia media, Ownership not transferred.

   320     * @param aErr error code

   321     */

   322     void HandleOpen(CMPXMedia* aMedia, TInt aErr);

   323 

   324     /**

   325      * Handle opening a group, e.g. an artist

   326      *

   327      * @param aMedia media object returned. NULL will be returned if error.

   328      *        Ownership not transferred.

   329      * @param aPath full path to to current level. Including top level node as well.

   330      *         NULL will be returned if error. Ownership not transferred

   331      * @param aErr error code

   332      */

   333     void HandleOpen(CMPXMedia* aMedia,

   334                     const CMPXCollectionPath* aPath,

   335                     TInt aErr);

   336 

   337     /**

   338     * Handle opening an item

   339     *

   340     * @param aPath selected item, Ownership not transferred.

   341     * @param aErr error code

   342     */

   343     void HandleOpen(CMPXCollectionPath* aPath, TInt aErr);

   344 

   345     /**

   346     *  Handle media

   347     *

   348     *  @param aMedia media Ownership not transferred.

   349     *  @param aError error code

   350     */

   351     void HandleMedia(CMPXMedia* aMedia, TInt aError);

   352 

   353     /**

   354      *  Handle completion of a asynchronous command

   355      *

   356      *  @param aCommandResult result of the command, NULL if error

   357      * Ownership not transferred.

   358      *  @param aError error code

   359      */

   360      void HandleCommandComplete(CMPXCommand* aCommandResult,

   361                                 TInt aError);

   362 

   363     /**

   364     * Handle Find results

   365     * @param aMedia media item(s), Ownership not transferred.

   366     * @param aError, error code

   367     */

   368     void HandleFindAll(CMPXMedia* aMedia, TInt aError);

   369 

   370      /**

   371     * Handles remove results

   372     * @param aUriArray, NULL if the plugin does not use concept of URI

   373     *                   else, contains the file path to delete a file

   374     * @param aError, error code

   375     */

   376     void HandleRemove(const CDesCArray& aUriArray, TInt aError);

   377 

   378     ///////////////////////////////////////////////////////////////////////////

   379     // From MMPXTaskQueueObserver

   380 

   381     /**

   382     * Execute a task

   383     * @param aTask task number

   384     * @param aParamData, parameter

   385     * @param aPtrData, any object

   386     * @param aBuf, buffer containing externalized parameters for the task.

   387     * @param aCallback call back function pointer

   388     * @param aCObject1 object 1 owned by task queue

   389     * @param aCObject2 object 2 owned by task queue

   390     */

   391     void ExecuteTask(TInt aTask,

   392                      TInt aParamData,

   393                      TAny* aPtrData,

   394                      const CBufBase& aBuf,

   395                      TAny* aCallback,

   396                      CBase* aCObject1,

   397                      CBase* aCObject2);

   398 

   399     /**

   400     * @see MMPXTaskQueueObserver

   401     */

   402     void HandleTaskError(TInt aTask,

   403                          TAny* aPtrData,

   404                          TAny* aCallback,

   405                          TInt aError);

   406 

   407 private:

   408     /**

   409     *  Open current level of collection

   410     *

   411     */

   412     void OpenL();

   413 

   414 

   415     /**

   416     *  Back to upper level

   417     *

   418     */

   419     void BackL();

   420 

   421     /**

   422     *  Reopen current level

   423     *

   424     */

   425     void ReOpenL();

   426 

   427     /**

   428     * Find Media Request

   429     * @param aMedia, searching criteria

   430     * @param aBuf, buffered data

   431     * @param aPlugin, plug to handle the find all

   432     * @param aResult, sync finding result

   433     * @param aSync, flag to indicate sync or async find

   434     */

   435     void FindAllL(const CMPXMedia& aMedia,

   436                   const CBufBase& aBuf,

   437                   CMPXCollectionPlugin& aPlugin,

   438                   CMPXMedia** aResult = NULL,

   439                   TBool aSync = EFalse);

   440 

   441     /**

   442     * Initialize

   443     * @param aCallback callback when initialization completes

   444     */

   445     void InitL(MMPXCollectionEngineObserver* aCallback);

   446 

   447     /**

   448     * Execute a task

   449     * @param aTask task number

   450     * @param aParamData, parameter

   451     * @param aPtrData, any object

   452     * @param aCallback call back function pointer

   453     * @param aBuf buffer data

   454     * @param aCObject1 object 1 owned by task queue

   455     * @param aCObject2 object 2 owned by task queue

   456     * @param aPlugin out parameter, plugin of the task.

   457     */

   458     void ExecuteTaskL(TInt aTask,

   459                       TInt aParamData,

   460                       TAny* aPtrData,

   461                       TAny* aCallback,

   462                       const CBufBase& aBuf,

   463                       CBase* aCObject1,

   464                       CBase* aCObject2,

   465                       CMPXCollectionPlugin*& aPlugin);

   466 

   467     /**

   468     * Handle error of execution

   469     * @param aPlugin plugin object

   470     * @param aErr error number

   471     * @param aUnuserPlugin ETrue decrement reference count of plugin

   472     */

   473     void HandleError(CMPXCollectionPlugin& aPlugin,

   474                      TInt aErr,

   475                      TBool aUnusePlugin=EFalse);

   476 

   477     /**

   478     * Resolve plugin

   479     * @param aPath, Collection path

   480     * @param aUid implementation uid of the plugin associated with the path

   481     */

   482     void ResolvePluginL(const CMPXCollectionPath& aPath, TUid& aUid);

   483 

   484     /**

   485     * Resolve plugin for FindAllL

   486     *

   487     * @param aMedia media object contains matching criteria

   488     * @param aPlugin, plugin reutrned

   489     */

   490     void ResolvePluginL(const CMPXMedia& aMedia,

   491                         CMPXCollectionPlugin*& aPlugin);

   492 

   493     /**

   494     * Add a media into the collection

   495     * Unpacks a media item group

   496     * @param aOp, operation code

   497     * @param aMedia, media object representing a list or a file

   498     */

   499     void DoUpdateMediaL(TInt aOp, const CMPXMedia& aMedia);

   500 

   501     /**

   502     * Add/Remove/Set an "item" into the collection

   503     * @param aOp, operation code

   504     * @param aMedia, single media "item"

   505     */

   506     void DoHandleItemL(TInt aOp, const CMPXMedia& aMedia);

   507 

   508     /**

   509     * Handle a synchronous collection command

   510     * @param aCmd, command to handle

   511     * @param aPlugin, plugin to prococess the command

   512     */

   513     void DoHandleSyncCommandL(const CMPXCommand& aCmd,

   514                               const CMPXMessageQueue& aMsgQueue,

   515                               CMPXCollectionPlugin* aPlugin=NULL);

   516 

   517     /**

   518     * Handle a select collection command

   519     * @param aCmd, command to handle

   520     */

   521     void DoHandleSelectCommandL(const CMPXCommand& aCmd);

   522 

   523     /**

   524     * Handle opening group contents

   525     *

   526     * @param aMedia media

   527     * @param aPath full path to current level

   528     * @param aCallback callback of the open request

   529     * @param aErr error code

   530     * @param aAddtoCache Should this be added to the cache or not

   531     * @param aOpenTask is this a OpenL task

   532     */

   533     void DoHandleOpenL(CMPXMedia* aMedia,

   534                        const CMPXCollectionPath* aPath,

   535                        MMPXCollectionEngineObserver* aCallback,

   536                        TInt aErr,

   537                        TBool aAddToCache,

   538                        TBool aOpenTask );

   539 

   540     /**

   541     * Handle opening an item

   542     *

   543     * @param aPath selected item

   544     * @param aErr error code

   545     */

   546     void DoHandleOpenL(CMPXCollectionPath* aPath,

   547                        TInt aErr);

   548 

   549     /**

   550     * Handle message from plug-in

   551     *

   552     * @param aMsg, message from the plug-in

   553     * @param aError, error code

   554     */

   555     void DoHandleMessageL(const CMPXMessage& aMsg, TInt aError);

   556 

   557     /**

   558     * Handles an Open request. First checks the cache and if the results

   559     * are not found there it calls the plugin.

   560     */

   561     void DoPluginOpenL();

   562 

   563     /**

   564     * Handle a media request.  First checks the cache and if the results

   565     * are not found there it calls  the plugin.

   566     */

   567     void DoPluginMediaL( CMPXCollectionPath& aPath,

   568                          const TCapabilitySet& aCaps,

   569                          CMPXAttributeSpecs& aSpecs,

   570                          CMPXFilter& aFilter);

   571 

   572     /**

   573     * Sets the plugin of the specified type to the value provided. This method

   574     * ensures that if valid, the previous plugin's reference count is decremented.

   575     * @param aType identifies the context type

   576     * @param aPlugin new plugin

   577     */

   578     void SetPlugin(TContextType aType, CMPXCollectionPlugin* aPlugin);

   579 

   580     /**

   581      * Checks whether or not the attributes are cacheable

   582      *

   583      * @return ETrue if attributes are cacheable, else EFalse

   584      */

   585     TBool AttributesCacheableL(

   586         const TArray<TMPXAttribute>& aAttrs,

   587         const CMPXCollectionPath& aPath );

   588 

   589     /**

   590     *  Adds a result set to the cache.

   591     *  @param aPath path defining the context of the results.

   592     *  @param aAttrs attributes requested by the client application and included in

   593     *         the result set.

   594     *  @param aResults result set corresponding to the path.  Not owned.

   595     *  @param aNotCacheableAttrs attributes that are not cacheable

   596     *  @param aMediaFromOpenL whether or not this media was from an OpenL

   597     *  @param aPriority result set priority

   598     *  @return CMPXMedia object in the cache or the original object if add failed

   599     */

   600     CMPXMedia* AddToCache(

   601         const CMPXCollectionPath& aPath,

   602         const TArray<TMPXAttribute>& aAttrs,

   603         CMPXMedia& aResults,

   604         TBool aMediaFromOpenL = EFalse,

   605         CMPXCollectionCache::TCachePriority aPriority = CMPXCollectionCache::EPriorityNormal );

   606 

   607     /**

   608     * Return loaded plugin of a context

   609     *

   610     * @param aType identifies the context type. plugin must be loaded for this context

   611     *              in other words, iPluginUids[aType]!=KNullUid

   612     * @return loaded plugin pointer for the context.

   613     */

   614     CMPXCollectionPlugin* LoadedPlugin(TContextType aType);

   615 

   616 private:

   617 

   618     /**

   619     * C++ constructor

   620     * @param aEngine reference to engine

   621     * @param aModeId context mode id

   622     */

   623     CMPXCollectionClientContext(CMPXCollectionEngine& aEngine,

   624         CMPXCollectionCache& aCache, const TUid& aModeId);

   625 

   626     /**

   627     * 2nd phase contructor

   628     */

   629     void ConstructL();

   630 

   631 private:

   632     TUid iModeId; // context mode id

   633 

   634     TMPXItemId iFocusItemId; // Item id for the currently focused item

   635     TInt iIndex; // Focused item in path

   636 

   637     CMPXCollectionEngine& iEngine;

   638     CMPXMedia* iMedia; // browsing entries

   639     CMPXFilter* iFilter; // filter to apply to browsing

   640     TInt iMediaType; // media type for browsing entries

   641 

   642     CMPXClientList* iClientList;

   643     CMPXCollectionPath* iBrowsePath; // path for browsing

   644     CMPXCollectionPath* iMediaPath;

   645     RArray<TUid> iPluginUids; // uids of loaded plugins for context

   646     TBool iPathUpdated; // changed due to collection change

   647     RArray<TUid> iUids; // Implementation sorted uids of collection plugins

   648     CMPXCollectionCache& iCache;

   649     TBool iCacheMedia; // Whether or not to cache the media returned

   650     };

   651 

   652 #endif  // CMPXCOLLECTIONCLIENTCONTEXT_H