/*
* 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: Implementation of interface for Collection Utility
*
*/
#ifndef CMPXCOLLECTIONUTILITY_H
#define CMPXCOLLECTIONUTILITY_H
#include <mpxcollectionobserver.h>
#include <mpxcollectionmessage.h>
#include <mpxsession.h>
#include <mpxmessageobserver.h>
#include "mpxcollectionserverdefs.h"
#include "mpxcollectionutility.h"
class CMPXMessageMonitor;
class CMPXTaskQueue;
class CMPXMsgBuf;
class CMPXMedia;
/**
* Implementation of collection utility interface
*/
NONSHARABLE_CLASS(CMPXCollectionUtility) : public CActive,
public MMPXCollectionUtility,
public MMPXMessageObserver,
public MMPXCollection
{
public:
/**
* Two-phased constructor
*
* @param aObs observer
* @param aModeId collection mode id
* @return object of constructed
*/
static CMPXCollectionUtility* NewL(const TUid& aModeId,
MMPXCollectionObserver* aObs);
/**
* Destructor
*/
~CMPXCollectionUtility();
private:
/**
* C++ constructor
*/
CMPXCollectionUtility(MMPXCollectionObserver* aObs);
/**
* Second phase constructor
*
* @param aModeId collection mode id
*/
void ConstructL(const TUid& aModeId);
public:
/**
* From MMPXCollectionUtility
* The collection.
*
* @return the collection
*/
MMPXCollection& Collection();
/**
* From MMPXCollectionUtility
* 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
*
* @param aUids, selection criteria
* @return TUid containing the implementation UID of the collection that
* would be selected
*/
TUid CollectionIDL(const TArray<TUid>& aUids);
/**
* From MMPXCollectionUtility
* 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
*/
void Close();
/**
* From MMPXCollection
* Opens the collection in its current state
*
* Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object
* with ID KMPXMediaIdContainer, i.e.contains other media objects
*
* @param aMode, open mode
*/
void OpenL(TMPXOpenMode aMode=EMPXOpenDefault);
/**
* From MMPXCollection
* Opens the collection at a specific index
*
* Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object
* with ID KMPXMediaIdContainer, i.e.contains other media objects
*
* @param aIndex, the index into the currently opened item list
* @param aMode, type of open mode
*/
void OpenL(TInt aIndex,TMPXOpenMode aMode=EMPXOpenDefault);
/**
* From MMPXCollection
* Opens the collection at a specific level
*
* @param aPath, the path of the collection
* @param aMode, open mode
*
* Calls back MMPXCollectionObserver::HandleOpenL()
*/
void OpenL(const CMPXCollectionPath& aPath,
TMPXOpenMode aMode=EMPXOpenDefault);
/**
* From MMPXCollection
* 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
*
* @param aIndex, the index into the currently opened item list
* @param aAttrs, attributes requested.
* @param aMode, type of open mode
*/
void OpenL(TInt aIndex,const TArray<TMPXAttribute>& aAttrs,
TMPXOpenMode aMode=EMPXOpenDefault);
/**
* From MMPXCollection
* 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
*
* @param aPath, the path of the collection
* @param aAttrs, attributes requested.
* @param aMode, type of open mode required
*/
void OpenL(const CMPXCollectionPath& aPath,
const TArray<TMPXAttribute>& aAttrs,
TMPXOpenMode aMode=EMPXOpenDefault);
/**
* From MMPXCollection
* 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.
*
* @param aUids, array of UIDs used to select collection plugins based on
* supported uids in plugin resource file.
* @param aMode, open mode
*/
void OpenL(const TArray<TUid>& aUids,
TMPXOpenMode aMode=EMPXOpenDefault);
/**
* From MMPXCollection
* 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.
*
* @param aUid, single UID used to select a collection
* @param aMode, open mode
*/
void OpenL(const TUid& aUid,
TMPXOpenMode aMode=EMPXOpenDefault);
/**
* From MMPXCollection
* Apply a filter to collection browsing; all subsequent calls
* to OpenL() will have this filter applied.
*
* @param aFilter, the filter to apply, or NULL to remove current
* filter
*/
void SetFilterL(CMPXFilter* aFilter);
/**
* From MMPXCollection
* Current filter that is applied to collection browsing, i.e. results
* returned through MMPXCollectionObserver::HandleOpenL() callback from
* OpenL()
*
* @return filter applied to browsing, or NULL if no filter applied
*/
CMPXFilter* FilterL();
/**
* From MMPXCollection
* Returns current collection plugin implementation UID
*
* @return UID of the collection
*/
TUid UidL() const;
/**
* From MMPXCollection
* The path of the collection in its current state
*
* @return the path of the collection
*/
CMPXCollectionPath* PathL();
/**
* From MMPXCollection
* Navigates back to the container of the current items
* Calls back MMPXCollectionObserver::HandleOpenL()
*/
void BackL();
/**
* From MMPXCollection
* Is this path on a 'remote' collection
*
* @aParam aPath, the collection path
* @return ETrue if is remote collection, otherwise EFalse
*/
TBool IsRemote(const CMPXCollectionPath& aPath);
/**
* From MMPXCollection
* Stops any async operations that are currently under way
*/
void CancelRequest();
/**
* From MMPXCollection
* Adds item(s) to the collection
*
* @param aNewProperties, Properties of the item
*/
void AddL(const CMPXMedia& aNewProperties);
/**
* From MMPXCollection
* Remove an item (or items under a group) from the collection
*
* @param aPath, item(s) to remove
* @param aObs, observer callback for items deleted (Optional)
*/
void RemoveL(const CMPXCollectionPath& aPath,
MMPXCollectionRemoveObserver* aObs = NULL );
/**
* From MMPXCollection
* Removes item(s) to the collection
*
* @param aProperties, Properties of the item
*/
void RemoveL(const CMPXMedia& aProperties);
/**
* From MMPXCollection
*
* Sets/updates the media for the item
* Callback via EMediaChanged message if currently opened
*
* @param aMedia, updated item
*
*/
void SetSyncL(const CMPXMedia& aMedia);
/**
* From MMPXCollection
*
* Sets/updates the media for the item, Asynchronous
* Callback via HandleCollectionMessage, AsyncOp complete
*
* @param aMedia, new value
*
*/
void SetL(const CMPXMedia& aMedia);
/**
* Find a list of media properties based on a search criteria
* The types of supported "queries" are plugin dependent
*
* @param aMedia, criteria to search on
* @param aAttrs, attributes to return
* @param aObs, observer for find callback
* Callback via MMPXCollectionFindObserver::HandleFindL();
*/
void FindAllL(const CMPXMedia& aMedia,
const TArray<TMPXAttribute>& aAttrs,
MMPXCollectionFindObserver& aObs);
/**
* Find a list of media properties based on a search criteria
* The types of supported "queries" are plugin dependent
* This is a SYNCHRONOUS METHOD, use only if necessary.
* @param aMedia, criteria to search on
* @param aAttrs, attributes to return
*/
CMPXMedia* FindAllL(const CMPXMedia& aMedia,
const TArray<TMPXAttribute>& aAttrs);
/**
* From MMPXCollection
* 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.
*
* @param aPath, the path of the collection
* @param aAttrs, attributes requested.
* @aParam aSpecs, specifications for attributes
* @param aFilter, filter to apply
*
* Calls back MMPXCollectionObserver::HandleMediaL()
*/
void MediaL(const CMPXCollectionPath& aPath,
const TArray<TMPXAttribute>& aAttrs,
CMPXAttributeSpecs* aSpecs=NULL,
CMPXFilter* aFilter=NULL);
/**
* From MMPXCollection
* Broadcasts an event to all observers
* @param aMsg event to broadcast
* @param aData data to accompany the event
*/
void NotifyL( TMPXCollectionBroadCastMsg aMsg, TInt aData );
/**
* From MMPXCollection
* Send a Command to the collection server
* aCmd, command to handle
* aData, some data about event (event specific, optional)
*/
void CommandL(TMPXCollectionCommand aCmd, TInt aData = 0);
/**
* From MMPXCollection
* Send a command to the collection server
*
* @param aCmd, command to handle
*/
void CommandL(CMPXCommand& aCmd);
/**
* From MMPXCollection
* Retrieves the set of supported file types
* @param aArray Array to fill with the data
*/
void GetSupportedTypesL( RPointerArray<CMPXCollectionType>& aArray );
/**
* From MMPXCollection
* Retrieves the capabilities for the current collection context
* @arg aCapability, bitmask of the capabilities supported.
*/
void GetSupportedCapabilitiesL(TCollectionCapability& aCapability);
/**
* From MMPXCollection
* 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
*/
TUid CollectionIDL(TUid& aCollection);
/**
* From MMPXCollection
* Adds a message subscription for this client.
* @param aSubscription subscription to be added
*/
void AddSubscriptionL(const CMPXSubscription& aSubscription);
/**
* From MMPXCollection
* Removes a message subscription for this client.
* @param aSubscription subscription to be removed.
*/
void RemoveSubscriptionL(const CMPXSubscription& aSubscription);
/**
* From MMPXCollection
* Removes all message subscriptions for this client.
*/
void ClearSubscriptionsL();
/**
* From MMPXMessageObserver
* Message received
* @param aMsgData message data
* @param aError error code
*/
void MessageReceived(TInt aMsgData, TInt aError);
/**
* From CActive
* Handles an active object's request completion event
*/
void RunL();
/**
* From CActive
* Implements cancellation of an outstanding request.
*/
void DoCancel();
/**
* From CActive
* Handles a leave occurring in the request completion event handler RunL()
*
* @param aError error code
*/
TInt RunError(TInt aError);
private:
/**
* Add a request to the task queue and run the next queue if no outstanding
* task
*
* @param aFunction function code
* @param aObs, observer to callback asynchronously
* @param aParamData data
* @param aBuf, extra data in buffer, ownership transferred.
* @param aPtr, pointer to a object
* @param aAlivePtr1, object to keep alive for a task
ownership transferred
* @param aAlivePtr2, same as aAlivePtr1
*/
void AddRequestL(TMPXCollectionServerOp aFunction,
TAny* aObs,
TInt aParamData=0,
CBufBase* aBuf=NULL,
TAny* aPtr=NULL,
CBase* aAlivePtr1=NULL,
CBase* aAlivePtr2=NULL);
/**
* Send next request to server
*/
void ExecuteNextRequest();
/**
* Handle message from message queue
* @param aMsgData message data
* @param aError error code
*/
void HandleMessageL(TInt aMsgData, TInt aError);
/**
* Handles error in RunL
*
* @param aError error code
*/
void HandleRunErrorL(TInt aError);
#ifdef _ENABLE_GUARD_TIMER
/**
* Gaurd timer callback
*
* @param aPtr pointer the this
*/
static TInt GuardTimerCallback(TAny* aPtr);
#endif
private:
MMPXCollectionObserver* iObserver;
CMPXMessageMonitor* iMsgMonitor;
CMPXTaskQueue* iTaskQueue;
RMPXSession iMcs;
CMPXMedia* iCurrentEntries;
CBufBase* iBuffer;
CArrayFixBase* iArray;
TPckgBuf<TInt> iSizePckg;
TPckgBuf<TInt> iSelectionPckg;
TPckgBuf<TInt> iCompletePckg;
TPckgBuf<TInt> iPropertiesSizePckg;
TInt iSelection;
TBool iCallbackOngoing; // is client processing callback?
// Keep alive pointers on global heap
CMPXMedia* iMedia;
CMPXMedia* iMediaOnError; // media object while handling error
#ifdef _ENABLE_GUARD_TIMER
CPeriodic* iGuardTimer; //guard timer for async request
#endif
};
#endif // CMPXCOLLECTIONUTILITY_H