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:  Controls collection via plug-ins

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef CMPXCOLLECTIONENGINE_H

    21 #define CMPXCOLLECTIONENGINE_H

    22 

    23 #include <e32std.h>

    24 #include <mpxcollectionframeworkdefs.h>

    25 #include <mpxcollectionpluginobserver.h>

    26 #include <mpxpluginhandlerobserver.h>

    27 #include <mpxlog.h>

    28 

    29 #include "mpxcollectionclientcontext.h"

    30 

    31 class CMPXCollectionPluginHandler;

    32 class CMPXCollectionPlugin;

    33 class CMPXCollectionPath;

    34 class CMPXActiveTaskQueue;

    35 class CMPXCollectionType;

    36 class CMPXMedia;

    37 class CMPXCollectionCache;

    38 class TReleaseInfo;

    39 

    40 /**

    41 *  The collection 'engine' which delegates to plug-ins (or 'collections').

    42 *  Unless stated otherwise, methods apply to currently loaded plug-in

    43 */

    44 class CMPXCollectionEngine : public CBase,

    45                              public MMPXCollectionPluginObserver,

    46                              public MMPXPluginHandlerObserver

    47     {

    48 public:

    49     /**

    50     *  Two-phased constructor.

    51     *

    52     *  @return Constructed object

    53     */

    54     IMPORT_C static CMPXCollectionEngine* NewL();

    55 

    56     /**

    57     *  Destructor

    58     */

    59     IMPORT_C ~CMPXCollectionEngine();

    60 

    61     /**

    62     *  Called by each new session, to set up the collection for use

    63     *

    64     *  @aModeId Collection mode id

    65     *  @aClientTid Client Thread ID for tracking

    66     *  @aMsgQueue message queue for the client

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

    68     *         if the operation fails.

    69     *  @return Reference to the client context object

    70     */

    71     IMPORT_C CMPXCollectionClientContext& SessionInitL(

    72                                         const TUid& aModeId,

    73                                         TThreadId aClientTid,

    74                                         CMPXMessageQueue* aMsgQueue);

    75 

    76     /**

    77     *  Broadcasts an event to all contexts

    78     *  @param aMsg message to send

    79     *  @param aData some data

    80     */

    81     IMPORT_C void NotifyL(TMPXCollectionBroadCastMsg aMsg, TInt aData);

    82 

    83     /**

    84     * Retrieves the set of supported file types in the collection server

    85     * @param aArray, array, which on return will be filled with the types

    86     */

    87     IMPORT_C void GetSupportedTypesL(RPointerArray<CMPXCollectionType>& aArray );

    88 

    89     /**

    90     * Lookup a collection Virtual ID to the actual implementation ID

    91     * NOTE: This function is currently hard coded for Inc8,

    92     * need to change plugin schema for INC9

    93     * @param aUid, virtual id to lookup

    94     * @return UID of the implementation

    95     */

    96     IMPORT_C TUid LookupCollectionPluginID(const TUid aUid);

    97 

    98     /**

    99     * Resolve a collection plugin uid

   100     * @param aAry, array of uids to resolve the plugin

   101     * @return Implementation uid of the plugin with the highest score

   102     *         KNullUidValue will be returned if no plugin found

   103     */

   104     IMPORT_C TUid ResolvePluginUid(const TArray<TUid>& aAry);

   105 

   106     /**

   107     *  Get a list of plugins which support uids in aSupportedUids

   108     *

   109     *  @param aEntries a list of plugins

   110     *  @param aSupportedUids a list of supported uids

   111     */

   112     void ListPluginsL(CMPXMedia& aEntries, const TArray<TUid>& aSupportedUids);

   113 

   114     /**

   115     *  Returns a pointer to the plug-in responsible for a certain collection path

   116     *

   117     *  @return collection plugin handler

   118     */

   119     CMPXCollectionPlugin* ResolvePluginL(const CMPXCollectionPath& aPath);

   120 

   121     /**

   122     *  Returns a pointer to the plug-in responsible for a collection uid

   123     *

   124     *  @return collection plugin handler

   125     */

   126     CMPXCollectionPlugin* ResolvePluginL(const TUid& aUid);

   127 

   128     /**

   129     *  Returns a pointer to the plug-in responsible for the URI

   130     *

   131     *  @return collection plugin handler

   132     */

   133     CMPXCollectionPlugin* ResolvePluginL(const TDesC& aUri);

   134 

   135     /**

   136     *  Indicates that a client started using the specified plugin.

   137     *

   138     *  @param aPluginUid plugin UID to be deselected

   139     */

   140     void UsePlugin(const TUid& aPluginUid);

   141 

   142     /**

   143     *  Indicates that a client no longer uses the specified plugin.

   144     *

   145     *  @param aPluginUid plugin UID to be deselected

   146     *  @return ETrue if the plugin was unloaded, EFalse otherwise

   147     */

   148     TBool ReleasePlugin(const TUid& aPluginUid);

   149 

   150     /**

   151     * Get the plugin cacheable attribute

   152     * @param aUid uid to get the cacheable attribute

   153     * @return ETrue / EFalse if plugin is cachable

   154     */

   155     TBool PluginCacheable( const TUid& aUid );

   156 

   157     /**

   158     * Get the list of non-cachable attributes for a plugin

   159     * @param aUid uid of the pluginto get the cacheable attribute

   160     * @return list of UIDs for attributes not cacheable

   161     */

   162     const TArray<TUid> PluginNonCacheableAttributesL( const TUid& aUid );

   163 

   164     /**

   165     * Remove a client context

   166     * @param aContext context to be removed.

   167     */

   168     void RemoveContext(const CMPXCollectionClientContext& aContext);

   169 

   170     /**

   171     * Notify collection change to other client contexts

   172     * @param aNotifier context of notifier

   173     * @param aMessage change event messages

   174     * @param aError error code

   175     */

   176     void NotifyChange(const CMPXCollectionClientContext& aNotifier,

   177                       CMPXMessage* aMessage,

   178                       TInt aError);

   179     /**

   180     * Check if refresh is ongoing

   181     */

   182     inline TBool IsRefreshing();

   183 

   184     /**

   185     *  Remove task for one client which is the observer of tasks

   186     *  @aCallback the observer of the tasks to be removed

   187     */

   188     void RemoveTask(TAny* aCallback);

   189     

   190     /*

   191      * Resets the content of the cache

   192      * @param aPath path defining the context to be removed. 

   193      */

   194     void ResetCacheL(CMPXCollectionPath& aPath);

   195 

   196     /**

   197     *  Pushes the specified plugin on the cleanup stack and the internal stack.

   198     *  @param aPlugin plugin to be pushed on the cleanup stack

   199     */

   200     void CleanupPluginPushL(CMPXCollectionPlugin* aPlugin);

   201 

   202     /**

   203     *  Pops a plugin from the cleanup stack and the internal stack.

   204     */

   205     void PluginPop();

   206 

   207     /**

   208     *  Returns the loaded plugin by implementation uid.

   209     *

   210     *  @param aUid implementation uid of the plugin

   211     *  @return plugin pointer if plugin already loaded or NULL if not loaded

   212     */

   213     CMPXCollectionPlugin* LoadedPlugin(const TUid& aUid);

   214 

   215 public: // From base classes

   216 

   217     ///////////////////////////////////////////////////////////////////////////

   218     // From MMPXCollectionPluginObserver

   219 

   220     /**

   221     * Handle message from plug-in

   222     *

   223     * @param aMessage, message from the plug-in

   224     * @param aError error code

   225     */

   226     inline void HandleMessage(CMPXMessage* aMsg, TInt aError);

   227 

   228     /**

   229     * Handle opening group contents

   230     *

   231     * @param aMedia media, Ownership not transferred.

   232     * @param aErr error code

   233     */

   234     inline void HandleOpen(CMPXMedia* aMedia, TInt aErr);

   235 

   236     /**

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

   238      *

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

   240      *        Ownership not transferred.

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

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

   243      * @param aErr error code

   244      */

   245     inline void HandleOpen(CMPXMedia* aMedia,

   246                            const CMPXCollectionPath* aPath,

   247                            TInt aErr);

   248 

   249 

   250     /**

   251     * Handle opening an item

   252     *

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

   254     * @param aErr error code

   255     */

   256     inline void HandleOpen(CMPXCollectionPath* aPath, TInt aErr);

   257 

   258     /**

   259     *  Handle media

   260     *

   261     *  @param aMedia media, Ownership not transferred.

   262     *  @param aError error code

   263     */

   264     inline void HandleMedia(CMPXMedia* aMedia, TInt aError);

   265 

   266     /**

   267      *  Handle completion of a asynchronous command

   268      *

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

   270      *  @param aError error code

   271      */

   272     inline void HandleCommandComplete(CMPXCommand* aCommandResult,

   273                                       TInt aError);

   274     /**

   275     * Handle Find results

   276     * @param aMedia media item(s)

   277     * @param aError, error code

   278     */

   279     inline void HandleFindAll(CMPXMedia* aMedia, TInt aError);

   280 

   281      /**

   282     * Handles remove results

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

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

   285     * @param aError, error code

   286     */

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

   288 

   289     /*

   290     * From MMPXPluginHandlerObserver

   291     * @see MMPXPluginHandlerObserver

   292     */

   293     void HandlePluginHandlerEvent(TPluginHandlerEvents aEvent, const TUid& aPluginUid,

   294         TBool aLoaded, TInt aData);

   295 

   296 private:  // New functions

   297 

   298 

   299     /**

   300     *  Creates a new context in the list

   301     *

   302     *  @param aModeId context mode id

   303     *  @return The new path object

   304     */

   305     CMPXCollectionClientContext* CreateNewContextL(const TUid& aModeId);

   306 

   307     /**

   308     *  Finds a default context for the given thread

   309     *

   310     *  @param aClientId The calling client's thread ID

   311     *  @return The found path, or NULL if not found

   312     */

   313     CMPXCollectionClientContext* FindDefaultContext(TThreadId aClientId);

   314     /**

   315     *  Releases a plugin. Called when PopAndDestroy is called on a plugin

   316     *  cleanup stack item.

   317     *  @param aEngine pointer to the current engine instance

   318     */

   319     static void CMPXCollectionEngine::ReleasePlugin(TAny* aEngine);

   320 

   321     /**

   322     *  Called when a plugin is unloaded.

   323     *  @param aUid identifies the plugin that was unloaded.

   324     */

   325     void HandlePluginUnloaded(const TUid& aUid);

   326 

   327     /**

   328     * Non leaving function to cleanup collection cache

   329     */

   330     void DoHandlePluginUnloadedL(const TUid& aUid);

   331 

   332     /**

   333     * Handle the collection change message

   334     * @param aMessage message to process

   335     */

   336     void DoNotifyChangeL( const CMPXMessage& aMessage );

   337 

   338     /**

   339     * Handle a single change message

   340     * @param aMessage message to process

   341     * @return ETrue if the cache has been invalidated for a particular plugin

   342     */

   343     TBool DoNotifySingleChangeL( const CMPXMessage& aMessage );

   344 

   345     /**

   346     * Sends a plugin handler message to all clients.

   347     * @param aMessageId the value of the KMPXMessageGeneralId attribute

   348     * @param aPluginUid plugin UID this message is for

   349     * @param aLoaded ETrue if the plugin is loaded

   350     * @param aVersion plugin version

   351     */

   352     void SendPluginHandlerMessageL(TInt aMessageId, const TUid& aPluginUid,

   353         TBool aLoaded, TInt aVersion = 0);

   354 

   355 private:

   356 

   357     /**

   358     *  C++ constructor

   359     *

   360     */

   361     CMPXCollectionEngine();

   362 

   363     /**

   364     *  2nd phase contructor

   365     */

   366     void ConstructL();

   367 

   368 private:

   369 

   370     CMPXCollectionPluginHandler* iPluginHandler;

   371 

   372     /**

   373     *   Playlist/song data

   374     */

   375     RPointerArray<CMPXCollectionClientContext> iContexts;

   376 

   377     TBool iRefreshing;

   378 

   379     /**

   380     *   Collection cache - singleton for all client contexts.

   381     */

   382     CMPXCollectionCache* iCache;

   383 

   384     /**

   385     *  Internal stack used for releasing plugins. This is used in addition to the

   386     *  Symbian cleanup stack.

   387     */

   388     RArray<TReleaseInfo> iCleanupStack;

   389 

   390     /*

   391     * If not KNullUid, indicates the plugin that is currently being upgraded.

   392     */

   393     TUid iUpdatedPluginUid;

   394     };

   395 

   396 #include "mpxcollectionengine.inl"

   397 

   398 #endif // CMPXCOLLECTIONENGINE_H

   399