--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mpx/collectionframework/collectionengine/inc/mpxcollectionclientcontext.h Thu Dec 17 08:55:47 2009 +0200
@@ -0,0 +1,652 @@
+/*
+* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: Maintains sessions to paths
+*
+*/
+
+#ifndef CMPXCOLLECTIONCLIENTCONTEXT_H
+#define CMPXCOLLECTIONCLIENTCONTEXT_H
+
+#include <mpxcollectionpluginobserver.h>
+#include <mpxtaskqueueobserver.h>
+#include <mpxcmn.h>
+#include <mpxcommand.h>
+#include <mpxfilter.h>
+#include <mpxattributespecs.h>
+#include <mpxmessagequeue.h>
+#include "mpxcollectioncache.h"
+
+class CMPXClientList;
+class CMPXCollectionPath;
+class CMPXCollectionEngine;
+class CMPXCollectionPlugin;
+class MMPXCollectionEngineObserver;
+class CMPXActiveTaskQueue;
+class CMPXMedia;
+class CMPXCollectionCache;
+
+class CMPXCollectionClientContext : public CBase,
+ public MMPXCollectionPluginObserver,
+ public MMPXTaskQueueObserver
+ {
+public: // DATA type
+ enum TContextType
+ {
+ EContextBrowse, // context for browing
+ EContextMedia, // context for media properties
+ EContextRemove, // context for removing paths
+ EContextCount
+ };
+public:
+ /**
+ * Two-phase constructor
+ *
+ * @param aEngine reference to collection engine
+ * @param aModeId mode id
+ * @return object created
+ */
+ static CMPXCollectionClientContext* NewL(CMPXCollectionEngine& aEngine,
+ CMPXCollectionCache& aCache, const TUid& aModeId);
+
+ /**
+ * Destructor
+ *
+ */
+ ~CMPXCollectionClientContext();
+
+ /**
+ * Open collection by path
+ *
+ * @param aPath collection path. Ownership transferred if not leave
+ * @param aMode, open mode
+ * @param aCallback callback
+ * @leave KErrArgument if aPath is not valid, or other system error
+ */
+ IMPORT_C void OpenL(CMPXCollectionPath* aPath,
+ TInt aMode,
+ MMPXCollectionEngineObserver* aCallback);
+
+ /**
+ * Open collection by index
+ *
+ * @param aIndex the index to current browse path
+ * @param aMode, open mode
+ * @param aAttrs, media attributes requested
+ * @param aCallback callback
+ * @leave system error
+ */
+ IMPORT_C void OpenL(TInt aIndex,
+ TInt aMode,
+ const TArray<TMPXAttribute>& aAttrs,
+ MMPXCollectionEngineObserver* aCallback);
+
+ /**
+ * Open collection by uids. Collections which match the uids will be returned.
+ *
+ * @param aUids a list of uids to be matched
+ * @param aMode, open mode
+ * @param aCallback callback
+ * @leave KErrNotReady if current browse path is invalid,
+ * KErrArgument if aIndex is out of range
+ * or other system error
+ */
+ IMPORT_C void OpenL(const TArray<TUid>& aUids,
+ TInt aMode,
+ MMPXCollectionEngineObserver* aCallback);
+
+ /**
+ * Request current content of browse context
+ *
+ * @param aMode, open mode
+ * @param aCallback callback
+ * @leave system error
+ */
+ IMPORT_C void OpenL(TInt aMode, MMPXCollectionEngineObserver* aCallback);
+
+ /**
+ * Back to previous level
+ * @param aCallback callback
+ * @leave system error
+ */
+ IMPORT_C void BackL(MMPXCollectionEngineObserver* aCallback);
+
+ /**
+ * Media request command
+ *
+ * @param aCmd command of media request
+ * @param aCallback callback
+ * @leave KErrArgument if aCmd is not valid, or other system error
+ */
+ IMPORT_C void MediaL(const CMPXCommand& aCmd,
+ MMPXCollectionEngineObserver* aCallback);
+
+ /**
+ * Add a media
+ *
+ * @param aMedia media object
+ * @leave system error
+ */
+ IMPORT_C void AddL(const CMPXMedia& aMedia);
+
+ /**
+ * Remove a media
+ *
+ * @param aMedia media object
+ * @leave system error
+ */
+ IMPORT_C void RemoveL(const CMPXMedia& aMedia);
+
+ /**
+ * Update a media
+ *
+ * @param aMedia media object
+ * @leave system error
+ */
+ IMPORT_C void SetL(const CMPXMedia& aMedia);
+
+ /**
+ * Remove media by path
+ *
+ * @param aPath collection path. Ownership transferred if not leave
+ * @param aCallback callback
+ * @leave KErrArgument if aPath is not valid, or other system error
+ */
+ IMPORT_C void RemoveL(CMPXCollectionPath* aPath,
+ MMPXCollectionEngineObserver* aCallback);
+
+ /**
+ * Return plugin uid
+ *
+ * @return plugin uid
+ */
+ IMPORT_C TUid PluginId() const;
+
+ /**
+ * Return current collection path
+ *
+ * @return collection path
+ */
+ IMPORT_C const CMPXCollectionPath& Path() const;
+
+ /**
+ * Cancel all requests from aCallback
+ *
+ * @param aCallback callback
+ */
+ IMPORT_C void CancelRequest(MMPXCollectionEngineObserver* aCallback);
+
+ /**
+ * Attach another client to this object. aName is the unique name of the
+ * client, used for identifying the client and passing messages; aId is the
+ * thread id of the client of the interface (not the server session)
+ *
+ * @param aId thread id of the client
+ * @param aMsgQueue message queue for the client
+ * @leave The function leaves with one of the system wide error codes,
+ * if the operation fails.
+ */
+ IMPORT_C void AddClientL(TThreadId aId,
+ CMPXMessageQueue* aMsgQueue);
+
+ /**
+ * Remove the client from the context. aName is the unique name of the
+ * client, used for identifying the client and passing messages.
+ *
+ * @param aMsgQueue message queue for the client
+ */
+ IMPORT_C void RemoveClient(const CMPXMessageQueue& aMsgQueue);
+
+ /**
+ * Get the supported attributes of the current plugin using by the context
+ * @return TCollectionCapability bit mask flag
+ */
+ IMPORT_C TCollectionCapability GetCapabilities();
+
+ /**
+ * Find all
+ *
+ * @param aMedia media object of matching criteria, Ownership transferred
+ * @param aBuf, buffer data, array of attributes for results,
+ * Ownership transferred if find asynchronously
+ * @param aCallback callback
+ * @leave system error
+ */
+ IMPORT_C void FindAllL(const CMPXMedia& aMedia,
+ CBufBase* aBuf,
+ MMPXCollectionEngineObserver* aCallback);
+
+ /** DEPRECATE, Use CommandL(CMPXCommand)
+ * Find all synchronously
+ *
+ * @param aMedia media object of matching criteria
+ * @param aBuf, buffer data, array of attributes for results
+ * @leave system error
+ * @return results of the search
+ */
+ IMPORT_C CMPXMedia* FindAllSyncL(const CMPXMedia& aMedia,
+ const CBufBase& aBuf);
+
+ /**
+ * Set the current filter applied to browsing
+ */
+ IMPORT_C void SetFilterL(const CMPXFilter* aFilter);
+
+ /**
+ * Get the current filter applied to browsing
+ * @return filter
+ */
+ IMPORT_C const CMPXFilter* Filter() const;
+
+ /** DEPRECATED
+ * Handle a collection command
+ * @param aCmd, command to handle
+ * @param aData, optional data
+ */
+ IMPORT_C void CommandL(TMPXCollectionCommand aCmd, TInt aData);
+
+ /**
+ * Handle a collection command
+ * @param aCmd, command to handle
+ * @param aCallback callback
+ * @param aMsgQueue Message Queue for the client
+ * @leave KErrNotReady if not collection opened, or system error
+ */
+ IMPORT_C void CommandL(const CMPXCommand& aCmd,
+ MMPXCollectionEngineObserver* aCallback,
+ const CMPXMessageQueue& aMsgQueue);
+
+ /**
+ * Does this thread have a shareable client? If yes, a default mode
+ * connection can bind to it.
+ *
+ * @param aId thread id of the client
+ * @return ETrue, if shareableclient is in the client list
+ */
+ TBool HasShareableClient(TThreadId aId);
+
+ /**
+ * Notify the client of a collection event
+ * @param aMsg Message type
+ * @param aData some data
+ */
+ void NotifyL( TMPXCollectionBroadCastMsg aMsg, TInt aData );
+
+ /**
+ * Get the mode id of the context
+ * @return collection mode id
+ */
+ const TUid& ModeId() const;
+
+ /**
+ * Handle message from plug-in
+ *
+ * @param aMsg, message from the plug-in
+ * @param aError, error code
+ * @param aNotifyOthers, indicates whether to notify other client contexts
+ * that the collection has changed
+ */
+ void DoHandleMessage(CMPXMessage* aMsg,
+ TInt aError,
+ TBool aNotifyOthers);
+
+private: // From base classes
+
+ ///////////////////////////////////////////////////////////////////////////
+ // From MMPXCollectionPluginObserver
+
+ /**
+ * Handle message from plug-in
+ *
+ * @param aMessage, message from the plug-in, Ownership not transferred.
+ * @param aError error code
+ */
+ void HandleMessage(CMPXMessage* aMsg, TInt aError);
+
+ /**
+ * Handle opening group contents
+ *
+ * @param aMedia media, Ownership not transferred.
+ * @param aErr error code
+ */
+ void HandleOpen(CMPXMedia* aMedia, TInt aErr);
+
+ /**
+ * Handle opening a group, e.g. an artist
+ *
+ * @param aMedia media object returned. NULL will be returned if error.
+ * Ownership not transferred.
+ * @param aPath full path to to current level. Including top level node as well.
+ * NULL will be returned if error. Ownership not transferred
+ * @param aErr error code
+ */
+ void HandleOpen(CMPXMedia* aMedia,
+ const CMPXCollectionPath* aPath,
+ TInt aErr);
+
+ /**
+ * Handle opening an item
+ *
+ * @param aPath selected item, Ownership not transferred.
+ * @param aErr error code
+ */
+ void HandleOpen(CMPXCollectionPath* aPath, TInt aErr);
+
+ /**
+ * Handle media
+ *
+ * @param aMedia media Ownership not transferred.
+ * @param aError error code
+ */
+ void HandleMedia(CMPXMedia* aMedia, TInt aError);
+
+ /**
+ * Handle completion of a asynchronous command
+ *
+ * @param aCommandResult result of the command, NULL if error
+ * Ownership not transferred.
+ * @param aError error code
+ */
+ void HandleCommandComplete(CMPXCommand* aCommandResult,
+ TInt aError);
+
+ /**
+ * Handle Find results
+ * @param aMedia media item(s), Ownership not transferred.
+ * @param aError, error code
+ */
+ void HandleFindAll(CMPXMedia* aMedia, TInt aError);
+
+ /**
+ * Handles remove results
+ * @param aUriArray, NULL if the plugin does not use concept of URI
+ * else, contains the file path to delete a file
+ * @param aError, error code
+ */
+ void HandleRemove(const CDesCArray& aUriArray, TInt aError);
+
+ ///////////////////////////////////////////////////////////////////////////
+ // From MMPXTaskQueueObserver
+
+ /**
+ * Execute a task
+ * @param aTask task number
+ * @param aParamData, parameter
+ * @param aPtrData, any object
+ * @param aBuf, buffer containing externalized parameters for the task.
+ * @param aCallback call back function pointer
+ * @param aCObject1 object 1 owned by task queue
+ * @param aCObject2 object 2 owned by task queue
+ */
+ void ExecuteTask(TInt aTask,
+ TInt aParamData,
+ TAny* aPtrData,
+ const CBufBase& aBuf,
+ TAny* aCallback,
+ CBase* aCObject1,
+ CBase* aCObject2);
+
+ /**
+ * @see MMPXTaskQueueObserver
+ */
+ void HandleTaskError(TInt aTask,
+ TAny* aPtrData,
+ TAny* aCallback,
+ TInt aError);
+
+private:
+ /**
+ * Open current level of collection
+ *
+ */
+ void OpenL();
+
+
+ /**
+ * Back to upper level
+ *
+ */
+ void BackL();
+
+ /**
+ * Reopen current level
+ *
+ */
+ void ReOpenL();
+
+ /**
+ * Find Media Request
+ * @param aMedia, searching criteria
+ * @param aBuf, buffered data
+ * @param aPlugin, plug to handle the find all
+ * @param aResult, sync finding result
+ * @param aSync, flag to indicate sync or async find
+ */
+ void FindAllL(const CMPXMedia& aMedia,
+ const CBufBase& aBuf,
+ CMPXCollectionPlugin& aPlugin,
+ CMPXMedia** aResult = NULL,
+ TBool aSync = EFalse);
+
+ /**
+ * Initialize
+ * @param aCallback callback when initialization completes
+ */
+ void InitL(MMPXCollectionEngineObserver* aCallback);
+
+ /**
+ * Execute a task
+ * @param aTask task number
+ * @param aParamData, parameter
+ * @param aPtrData, any object
+ * @param aCallback call back function pointer
+ * @param aBuf buffer data
+ * @param aCObject1 object 1 owned by task queue
+ * @param aCObject2 object 2 owned by task queue
+ * @param aPlugin out parameter, plugin of the task.
+ */
+ void ExecuteTaskL(TInt aTask,
+ TInt aParamData,
+ TAny* aPtrData,
+ TAny* aCallback,
+ const CBufBase& aBuf,
+ CBase* aCObject1,
+ CBase* aCObject2,
+ CMPXCollectionPlugin*& aPlugin);
+
+ /**
+ * Handle error of execution
+ * @param aPlugin plugin object
+ * @param aErr error number
+ * @param aUnuserPlugin ETrue decrement reference count of plugin
+ */
+ void HandleError(CMPXCollectionPlugin& aPlugin,
+ TInt aErr,
+ TBool aUnusePlugin=EFalse);
+
+ /**
+ * Resolve plugin
+ * @param aPath, Collection path
+ * @param aUid implementation uid of the plugin associated with the path
+ */
+ void ResolvePluginL(const CMPXCollectionPath& aPath, TUid& aUid);
+
+ /**
+ * Resolve plugin for FindAllL
+ *
+ * @param aMedia media object contains matching criteria
+ * @param aPlugin, plugin reutrned
+ */
+ void ResolvePluginL(const CMPXMedia& aMedia,
+ CMPXCollectionPlugin*& aPlugin);
+
+ /**
+ * Add a media into the collection
+ * Unpacks a media item group
+ * @param aOp, operation code
+ * @param aMedia, media object representing a list or a file
+ */
+ void DoUpdateMediaL(TInt aOp, const CMPXMedia& aMedia);
+
+ /**
+ * Add/Remove/Set an "item" into the collection
+ * @param aOp, operation code
+ * @param aMedia, single media "item"
+ */
+ void DoHandleItemL(TInt aOp, const CMPXMedia& aMedia);
+
+ /**
+ * Handle a synchronous collection command
+ * @param aCmd, command to handle
+ * @param aPlugin, plugin to prococess the command
+ */
+ void DoHandleSyncCommandL(const CMPXCommand& aCmd,
+ const CMPXMessageQueue& aMsgQueue,
+ CMPXCollectionPlugin* aPlugin=NULL);
+
+ /**
+ * Handle a select collection command
+ * @param aCmd, command to handle
+ */
+ void DoHandleSelectCommandL(const CMPXCommand& aCmd);
+
+ /**
+ * Handle opening group contents
+ *
+ * @param aMedia media
+ * @param aPath full path to current level
+ * @param aCallback callback of the open request
+ * @param aErr error code
+ * @param aAddtoCache Should this be added to the cache or not
+ * @param aOpenTask is this a OpenL task
+ */
+ void DoHandleOpenL(CMPXMedia* aMedia,
+ const CMPXCollectionPath* aPath,
+ MMPXCollectionEngineObserver* aCallback,
+ TInt aErr,
+ TBool aAddToCache,
+ TBool aOpenTask );
+
+ /**
+ * Handle opening an item
+ *
+ * @param aPath selected item
+ * @param aErr error code
+ */
+ void DoHandleOpenL(CMPXCollectionPath* aPath,
+ TInt aErr);
+
+ /**
+ * Handle message from plug-in
+ *
+ * @param aMsg, message from the plug-in
+ * @param aError, error code
+ */
+ void DoHandleMessageL(const CMPXMessage& aMsg, TInt aError);
+
+ /**
+ * Handles an Open request. First checks the cache and if the results
+ * are not found there it calls the plugin.
+ */
+ void DoPluginOpenL();
+
+ /**
+ * Handle a media request. First checks the cache and if the results
+ * are not found there it calls the plugin.
+ */
+ void DoPluginMediaL( CMPXCollectionPath& aPath,
+ const TCapabilitySet& aCaps,
+ CMPXAttributeSpecs& aSpecs,
+ CMPXFilter& aFilter);
+
+ /**
+ * Sets the plugin of the specified type to the value provided. This method
+ * ensures that if valid, the previous plugin's reference count is decremented.
+ * @param aType identifies the context type
+ * @param aPlugin new plugin
+ */
+ void SetPlugin(TContextType aType, CMPXCollectionPlugin* aPlugin);
+
+ /**
+ * Checks whether or not the attributes are cacheable
+ *
+ * @return ETrue if attributes are cacheable, else EFalse
+ */
+ TBool AttributesCacheableL(
+ const TArray<TMPXAttribute>& aAttrs,
+ const CMPXCollectionPath& aPath );
+
+ /**
+ * Adds a result set to the cache.
+ * @param aPath path defining the context of the results.
+ * @param aAttrs attributes requested by the client application and included in
+ * the result set.
+ * @param aResults result set corresponding to the path. Not owned.
+ * @param aNotCacheableAttrs attributes that are not cacheable
+ * @param aMediaFromOpenL whether or not this media was from an OpenL
+ * @param aPriority result set priority
+ * @return CMPXMedia object in the cache or the original object if add failed
+ */
+ CMPXMedia* AddToCache(
+ const CMPXCollectionPath& aPath,
+ const TArray<TMPXAttribute>& aAttrs,
+ CMPXMedia& aResults,
+ TBool aMediaFromOpenL = EFalse,
+ CMPXCollectionCache::TCachePriority aPriority = CMPXCollectionCache::EPriorityNormal );
+
+ /**
+ * Return loaded plugin of a context
+ *
+ * @param aType identifies the context type. plugin must be loaded for this context
+ * in other words, iPluginUids[aType]!=KNullUid
+ * @return loaded plugin pointer for the context.
+ */
+ CMPXCollectionPlugin* LoadedPlugin(TContextType aType);
+
+private:
+
+ /**
+ * C++ constructor
+ * @param aEngine reference to engine
+ * @param aModeId context mode id
+ */
+ CMPXCollectionClientContext(CMPXCollectionEngine& aEngine,
+ CMPXCollectionCache& aCache, const TUid& aModeId);
+
+ /**
+ * 2nd phase contructor
+ */
+ void ConstructL();
+
+private:
+ TUid iModeId; // context mode id
+
+ TMPXItemId iFocusItemId; // Item id for the currently focused item
+ TInt iIndex; // Focused item in path
+
+ CMPXCollectionEngine& iEngine;
+ CMPXMedia* iMedia; // browsing entries
+ CMPXFilter* iFilter; // filter to apply to browsing
+ TInt iMediaType; // media type for browsing entries
+
+ CMPXClientList* iClientList;
+ CMPXCollectionPath* iBrowsePath; // path for browsing
+ CMPXCollectionPath* iMediaPath;
+ RArray<TUid> iPluginUids; // uids of loaded plugins for context
+ TBool iPathUpdated; // changed due to collection change
+ RArray<TUid> iUids; // Implementation sorted uids of collection plugins
+ CMPXCollectionCache& iCache;
+ TBool iCacheMedia; // Whether or not to cache the media returned
+ };
+
+#endif // CMPXCOLLECTIONCLIENTCONTEXT_H