--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mmappfw_plat/mpx_collection_utility_api/inc/mpxcollectionutility.h Thu Dec 17 08:55:47 2009 +0200
@@ -0,0 +1,467 @@
+/*
+* 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: Interface to collections
+*
+*/
+
+
+#ifndef MMPXCOLLECTIONUTILITY_H
+#define MMPXCOLLECTIONUTILITY_H
+
+#include <mpxcollectionframeworkdefs.h>
+#include <mpxcommonframeworkdefs.h>
+#include <mpxcollectionobserver.h>
+#include <mpxattribute.h>
+#include <mpxfilter.h>
+#include <mpxcommand.h>
+#include <mpxsearchcriteria.h>
+#include <mpxattributespecs.h>
+
+#include <badesca.h>
+
+class CMPXCollectionPath;
+class CMPXCollectionType;
+class MMPXCollection;
+class MMPXCollectionFindObserver;
+class CMPXSubscription;
+
+/********************************************************************************
+*
+* Note:
+*
+* ** remove void CommandL(TMPXCollectionCommand aCmd, TInt aData = 0)
+*
+* ** remove TUid CollectionIDL(TUid& aCollection)
+*
+* ** all methods which do not (necessarily) operate on current collection
+* should be moved from MMPXCollection to MMPXCollectionUtility
+*
+*
+*********************************************************************************/
+
+/**
+ * Main client interface for collections. Some terms used in the documentation of
+ * this interface:
+ *
+ * Context - represents the 'state' of the collection, i.e. the current
+ * browse path (encapsulated in CMPXCollectionPath) and filter applied
+ * (encapsulated in CMPXFilter)
+ *
+ * Playlist - an abstract list of songs. A collection path allows the client
+ * to cross reference the playlist with a collection, for example to
+ * iterate through the playlist, extract user-supplied metadata etc.
+ *
+ * @lib mpxcollectionutility.lib
+ */
+class MMPXCollectionUtility
+ {
+public:
+ /**
+ * Creates the interface for the client. This interface is bound to (i.e.
+ * controls and receives events from) either an existing context or a new
+ * one, according to:
+ *
+ * aModeId=KMcModeDefault - bound to the same context as any other client
+ * running in the same thread, or KMcModeIsolated
+ * context created if the first client in the thread
+ * aModeId=KMcModeIsolated - new context created specifically for client,
+ * may be shared later
+ * aModeId=<UID> - bound to the same context as other clients which have
+ * supplied the same UID. Most common case is application UID
+ * so that clients in external processes can easily bind to
+ * a specific application context
+ *
+ * @since S60 3.2.3
+ * @param aObs collection observer
+ * @param aModeId collection mode id
+ * @return collection utility object
+ */
+ IMPORT_C static MMPXCollectionUtility* NewL(
+ MMPXCollectionObserver* aObs = NULL,
+ const TUid& aModeId = KMcModeDefault);
+
+ /**
+ * The collection.
+ *
+ * @since S60 3.2.3
+ * @return the collection
+ */
+ virtual MMPXCollection& Collection() = 0;
+
+ /**
+ * Retrieves the ID of the collection plugin which matched aUids best.
+ * If multiple plugins match the aUids, the only one with high priority will
+ * be returned.
+ *
+ * @since S60 3.2.3
+ * @param aUids selection criteria
+ * @return TUid containing the implementation UID of the collection that
+ * would be selected
+ */
+ virtual TUid CollectionIDL(const TArray<TUid>& aUids) = 0;
+
+ /**
+ * Frees up client side resources only. A collection is freed when there are no
+ * clients using it, and all resources are freed when the last client closes.
+ *
+ * @since S60 3.2.3
+ */
+ virtual void Close() = 0;
+ };
+
+/**
+ * MPXCollection
+ *
+ * @lib mpxcollectionutility.lib
+ */
+class MMPXCollection
+ {
+public:
+ /**
+ * Opens the collection in its current state.
+ *
+ * Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object
+ * with ID KMPXMediaIdContainer, i.e.contains other media objects.
+ *
+ * @since S60 3.2.3
+ * @param aMode open mode
+ */
+ virtual void OpenL(TMPXOpenMode aMode=EMPXOpenDefault) = 0;
+
+ /**
+ * Opens the collection at a specific index.
+ *
+ * Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object
+ * with ID KMPXMediaIdContainer, i.e.contains other media objects.
+ *
+ * @since S60 3.2.3
+ * @param aIndex the index into the currently opened item list
+ * @param aMode type of open mode
+ */
+ virtual void OpenL(TInt aIndex,TMPXOpenMode aMode=EMPXOpenDefault) = 0;
+
+ /**
+ * Opens the collection at a specific level.
+ *
+ * @since S60 3.2.3
+ * @param aPath the path of the collection
+ * @param aMode type of open mode required
+ *
+ * Calls back MMPXCollectionObserver::HandleOpenL()
+ */
+ virtual void OpenL(const CMPXCollectionPath& aPath,
+ TMPXOpenMode aMode=EMPXOpenDefault) = 0;
+
+ /**
+ * Opens the collection at a specific index.
+ *
+ * Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object
+ * with ID KMPXMediaIdContainer, i.e.contains other media objects which will
+ * contain the attribute values specified by aAttrs.
+ *
+ * @since S60 3.2.3
+ * @param aIndex the index into the currently opened item list
+ * @param aAttrs attributes requested
+ * @param aMode type of open mode
+ */
+ virtual void OpenL(TInt aIndex,
+ const TArray<TMPXAttribute>& aAttrs,
+ TMPXOpenMode aMode=EMPXOpenDefault) = 0;
+
+ /**
+ * Opens the collection at a specific level.
+ *
+ * Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object
+ * with ID KMPXMediaIdContainer, i.e.contains other media objects which will
+ * contain the attribute values specified by aAttrs.
+ *
+ * @since S60 3.2.3
+ * @param aPath the path of the collection
+ * @param aAttrs attributes requested
+ * @param aMode type of open mode required
+ */
+ virtual void OpenL(const CMPXCollectionPath& aPath,
+ const TArray<TMPXAttribute>& aAttrs,
+ TMPXOpenMode aMode=EMPXOpenDefault) = 0;
+
+ /**
+ * Opens the collection with a list of implementation uids to be matched.
+ * If current context matches the criteria, it will return existing browsing
+ * media; otherwise it will be back to root level and only plug-ins which
+ * match all provided uids will be returned, in priority order.
+ *
+ * Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object
+ * with ID KMPXMediaIdContainer. Returned plugins will be sorted by plugin
+ * priority if mulitple plugins support aUids.
+ *
+ * @since S60 3.2.3
+ * @param aUids array of UIDs used to select collection plugins based on
+ * supported uids in plugin resource file.
+ * @param aMode open mode
+ */
+ virtual void OpenL(const TArray<TUid>& aUids,
+ TMPXOpenMode aMode=EMPXOpenDefault) = 0;
+
+ /**
+ * Opens the collection with an uid to be matched.
+ * If current context matches the criteria, it will return existing browsing
+ * media; otherwise it will be back to root level and only plug-ins which
+ * match the uid will be returned, in priority order.
+ *
+ * Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object
+ * with ID KMPXMediaIdContainer. Returned plugins will be sorted by plugin
+ * priority if mulitple plugins support the uid.
+ *
+ * @since S60 3.2.3
+ * @param aUid single UID used to select a collection
+ * @param aMode open mode
+ */
+ virtual void OpenL(const TUid& aUid,
+ TMPXOpenMode aMode=EMPXOpenDefault) = 0;
+
+ /**
+ * Apply a filter to collection browsing. All subsequent calls
+ * to OpenL() will have this filter applied.
+ *
+ * @since S60 3.2.3
+ * @param aFilter the filter to apply, or NULL to remove current
+ * filter
+ */
+ virtual void SetFilterL(CMPXFilter* aFilter) = 0;
+
+ /**
+ * Current filter that is applied to collection browsing. i.e. results
+ * returned through MMPXCollectionObserver::HandleOpenL() callback from
+ * OpenL().
+ *
+ * @since S60 3.2.3
+ * @return filter applied to browsing, or NULL if no filter applied
+ */
+ virtual CMPXFilter* FilterL() = 0;
+
+ /**
+ * Returns current collection plugin implementation UID.
+ *
+ * @since S60 3.2.3
+ * @return UID of the collection, or KNullUid if no collection opened
+ */
+ virtual TUid UidL() const=0;
+
+ /**
+ * The path of the collection in its current state.
+ * Ownsership transferred.
+ *
+ * @since S60 3.2.3
+ * @return the path of the collection
+ */
+ virtual CMPXCollectionPath* PathL() = 0;
+
+ /**
+ * Navigates back to the container of the current items.
+ * Calls back MMPXCollectionObserver::HandleOpenL().
+ *
+ * @since S60 3.2.3
+ */
+ virtual void BackL() = 0;
+
+ /**
+ * Is this path on a 'remote' collection.
+ *
+ * @since S60 3.2.3
+ * @aParam aPath the collection path
+ * @return ETrue if is remote collection, otherwise EFalse
+ */
+ virtual TBool IsRemote(const CMPXCollectionPath& aPath) = 0;
+
+ /**
+ * Stops any async operations that are currently under way.
+ *
+ * @since S60 3.2.3
+ */
+ virtual void CancelRequest() = 0;
+
+ /**
+ * Adds item(s) to the collection.
+ *
+ * @since S60 3.2.3
+ * @param aNewMedia new item(s) to add
+ */
+ virtual void AddL(const CMPXMedia& aNewMedia) = 0;
+
+ /**
+ * Remove an item (or items under a group) from the collection
+ *
+ * @param aPath, item(s) to remove
+ * @param aObs, observer to this operation, Optional callback.
+ * @deprecated please use CommandL (CMPXCommand)
+ */
+ virtual void RemoveL(const CMPXCollectionPath& aPath,
+ MMPXCollectionRemoveObserver* aObs = NULL ) = 0;
+
+ /**
+ * Removes item(s) from the collection.
+ *
+ * @since S60 3.2.3
+ * @param aMedia item(s) to remove
+ */
+ virtual void RemoveL(const CMPXMedia& aMedia) = 0;
+
+ /**
+ * Sets/updates the media for the item.
+ * Callback via EMediaChanged message if currently opened.
+ *
+ * @since S60 3.2.3
+ * @param aMedia updated item
+ *
+ */
+ virtual void SetSyncL(const CMPXMedia& aMedia) = 0;
+
+ /**
+ *
+ * Sets/updates the item specified in the path, Aynchronous
+ * Callback for completion with HandleCollectionMessageL()
+ * event: TMPXCollectionMessage::EAsyncOpComplete
+ * type: EMcsSetMediaAsync
+ * data: error code
+ *
+ * @param aMedia, updated item
+ * @deprecated, please use CommandL(CMPXCommand& aCmd)
+ */
+ virtual void SetL(const CMPXMedia& aMedia) = 0;
+
+ /**
+ * Find a list of media properties based on a search criteria.
+ * The types of supported "queries" are collection dependent.
+ * Callback via MMPXCollectionFindObserver::HandleFindL();
+ *
+ * @since S60 3.2.3
+ * @param aCriteria criteria to search on
+ * @param aAttrs attributes to return
+ * @param aObs observer for find callback
+ *
+ */
+ virtual void FindAllL(const CMPXSearchCriteria& aCriteria,
+ const TArray<TMPXAttribute>& aAttrs,
+ MMPXCollectionFindObserver& aObs) = 0;
+
+ /**
+ * Find a list of media properties based on a search criteria.
+ * The types of supported "queries" are collection dependent.
+ * This is a SYNCHRONOUS METHOD, use only if necessary.
+ *
+ * @since S60 3.2.3
+ * @param aCriteria criteria to search on
+ * @param aAttrs attributes to return
+ * @return search results maching the given criteria
+ */
+ virtual CMPXMedia* FindAllL(const CMPXSearchCriteria& aCriteria,
+ const TArray<TMPXAttribute>& aAttrs) = 0;
+
+ /**
+ * Retrieve media for the item specified in the path.
+ * Note: if selection is set in aPath, HandleMedia will return an array of
+ * media of current selected items.
+ * if no selection is set in aPath, HandleMedia will return media
+ * properities of current item.
+ * Calls back MMPXCollectionObserver::HandleMediaL()
+ *
+ * @since S60 3.2.3
+ * @param aPath the path of the collection
+ * @param aAttrs attributes requested.
+ * @param aSpecs specifications for attributes, Ownership not transferred
+ * @param aFilter filter to apply, Ownership not transferred
+ *
+ */
+ virtual void MediaL(const CMPXCollectionPath& aPath,
+ const TArray<TMPXAttribute>& aAttrs,
+ CMPXAttributeSpecs* aSpecs=NULL,
+ CMPXFilter* aFilter=NULL) = 0;
+
+ /**
+ * Broadcasts an event to all clients or plugins.
+ *
+ * @since S60 3.2.3
+ * @param aMsg event to broadcast
+ * @param aData data to accompany the event
+ */
+ virtual void NotifyL(TMPXCollectionBroadCastMsg aMsg, TInt aData) = 0;
+
+ /**
+ * Send a command to the collection server
+ *
+ * @param aCmd, command to handle
+ * @param aData, some data about event (event specific, optional)
+ * @deprecated use CommandL(CMPXCommand& aCmd)
+ */
+ virtual void CommandL(TMPXCollectionCommand aCmd, TInt aData = 0) = 0;
+
+ /**
+ * Send a command to the collection server.
+ *
+ * @since S60 3.2.3
+ * @param aCmd command to handle
+ */
+ virtual void CommandL(CMPXCommand& aCmd) = 0;
+
+ /**
+ * Retrieves the list of supported types.
+ *
+ * @since S60 3.2.3
+ * @param aArray On return, array will be filled with collection type items
+ */
+ virtual void GetSupportedTypesL(RPointerArray<CMPXCollectionType>& aArray) = 0;
+
+ /**
+ * Fetches the capabilities supported by the current collection context.
+ *
+ * @since S60 3.2.3
+ * @param aCapability bitmask of the capabilities supported.
+ */
+ virtual void GetSupportedCapabilitiesL(TCollectionCapability& aCapability) = 0;
+
+ /**
+ *
+ * Retrieves the real collection UID based on a predefined UID
+ * @param aCollection, UID for lookup, defined in "mpxcollectionframeworkdefs.h"
+ * @return TUid containing the real implementation UID
+ * @deprecated use MMPXCollectionUtility::CollectionIDL
+ */
+ virtual TUid CollectionIDL(TUid& aCollection) = 0;
+
+ /**
+ * Adds a message subscription for this client.
+ *
+ * @since S60 3.2.3
+ * @param aSubscription subscription to be added
+ */
+ virtual void AddSubscriptionL(const CMPXSubscription& aSubscription) = 0;
+
+ /**
+ * Removes a message subscription for this client.
+ *
+ * @since S60 3.2.3
+ * @param aSubscription subscription to be removed.
+ */
+ virtual void RemoveSubscriptionL(const CMPXSubscription& aSubscription) = 0;
+
+ /**
+ * Removes all message subscriptions for this client.
+ *
+ * @since S60 3.2.3
+ */
+ virtual void ClearSubscriptionsL() = 0;
+ };
+
+#endif // MMPXCOLLECTIONUTILITY_H
+