/*
* 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