/*
* 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: Collection plugin interface
*
*/
#ifndef CMPXCOLLECTIONPLUGIN_H
#define CMPXCOLLECTIONPLUGIN_H
#include <ecom/ecom.h>
#include <mpxcollectionframeworkdefs.h>
#include <mpxattribute.h>
#include <mpxfilter.h>
#include <mpxcommand.h>
#include <mpxsearchcriteria.h>
#include <mpxattributespecs.h>
class MMPXCollectionPluginObserver;
class MMPXCollectionEngineObserver;
class CMPXCollectionPath;
class CMPXActiveTaskQueue;
class MMPXTaskQueueObserver;
const TUid KMPXCollectionInterfaceUid={0x101FFC36};
/********************************************************************************
*
* Note:
*
* ** remove void CommandL(TMPXCollectionCommand aCmd, TInt aArg = 0)
*
* ** remove MediaL() overload
*
* ** remove null implementations
*
* ** rename GetCapabilities() to Capabilities()
*
*********************************************************************************/
/**
* CMPXCollectionPlugin class
*
* Interface to access collection
*/
NONSHARABLE_CLASS(CMPXCollectionPlugin): public CBase
{
public: // Constructors and destructor
/**
* Two-phased constructor.
*
* @since S60 3.2.3
* @param aUid uid of interface implementation
* @param aObs Reference to the callback interface
* @return object of constructed
*/
inline static CMPXCollectionPlugin* NewL(const TUid& aUid,
MMPXCollectionPluginObserver& aObs);
/**
* Destructor.
*
* @since S60 3.2.3
*/
inline virtual ~CMPXCollectionPlugin();
public:
/**
* Callback setter.
*
* @since S60 3.2.3
* @param aObs Reference to the callback interface
*/
inline void SetObserver(MMPXCollectionPluginObserver& aObs);
/**
*
*
* @param aCmd a command
* @param aArg optional argument
* @deprecated executes a command on the selected collection, use CommandL(CMPXCommand& aCmd)
*/
virtual void CommandL(TMPXCollectionCommand aCmd, TInt aArg = 0)=0;
/**
* Executes a command.
*
* @since S60 3.2.3
* @param aCmd a command
*/
virtual void CommandL(CMPXCommand& /*aCmd*/)
{/*Note: need to implement this */}
/**
* Navigates to the given path.
*
* @since S60 3.2.3
* @param aPath a path
* @param aAttrs attributes requested
* @param aFilter filter to apply or NULL if none
*/
virtual void OpenL(const CMPXCollectionPath& /*aPath*/,
const TArray<TMPXAttribute>& /*aAttrs*/,
CMPXFilter* /*aFilter*/) = 0;
/**
*
* Media properties of the current file (async).
* Note: if selection is set in aPath, HandleMedia will return an array of
* media properties of current selected items.
* if no selection is set in aPath, HandleMedia will return media
* properities of current item.
*
* @since S60 3.2.3
* @param aPath path for the media file
* @param aAttr attributes requested
* @param aCaps platsec capabilities of client requesting media; plug-in should also
* verify its process capabilities
* @param aSpecs, specifications for attributes
* @deprecated use the following version of MediaL
*/
virtual void MediaL(const CMPXCollectionPath& /*aPath*/,
const TArray<TMPXAttribute>& /*aAttrs*/,
const TArray<TCapability>& /*aCaps*/,
CMPXAttributeSpecs* /*aSpecs*/) = 0;
/**
* Cancel outstanding request.
*
* @since S60 3.2.3.
*/
virtual void CancelRequest()=0;
/**
* Adds an item or items to the collection.
*
* @since S60 3.2.3
* @param aNewProperties Properties of the item
*/
virtual void AddL(const CMPXMedia& aNewMedia) = 0;
/**
* Remove a collection path.
* Note that the selection indicies are hidden within the path
*
* @since S60 3.2.3
* @param aPath path to remove
*
*/
virtual void RemoveL(const CMPXCollectionPath& aPath ) = 0;
/**
* Remove an item or items from the collection.
*
* @since S60 3.2.3
* @param aProperties Properties of the item. It may cantain URI only
* or meta data, all of items matched properties
* will be removed.
*/
virtual void RemoveL(const CMPXMedia& aMedia) = 0;
/**
* Sets/updates the media for the item
* specified in the path.
*
* @since S60 3.2.3
* @param aMedia new value
*/
virtual void SetL(const CMPXMedia& aMedia) = 0;
/**
* Find a list of items matched (async).
*
* @since S60 3.2.3
* @param aCriteria properties to be searched
* @param aAttrs attributes to return
*/
virtual void FindAllL(const CMPXSearchCriteria& aCriteria,
const TArray<TMPXAttribute>& aAttrs) = 0;
/**
* Find a list of items matched (sync).
*
* @since S60 3.2.3
* @param aCriteria properties to be searched
* @param aAttrs attributes to return
* @return results of the search
*/
virtual CMPXMedia* FindAllSyncL(const CMPXSearchCriteria& aCriteria,
const TArray<TMPXAttribute>& aAttrs) = 0;
/**
* Get the list of supported capabilities.
*
* @since S60 3.2.3
* @return TCollectionCapability bitmask of supported capabilities
*/
virtual TCollectionCapability GetCapabilities() = 0;
/** Note change it to pure virtual when all of plugins implement this interface
*
* Media properties of the current file (async).
* Note: if selection is set in aPath, HandleMedia will return an array of
* media properties of current selected items.
* if no selection is set in aPath, HandleMedia will return media
* properities of current item.
*
* @since S60 3.2.3
* @param aPath path for the media file
* @param aAttr attributes requested
* @param aCaps platsec capabilities of client requesting media; plug-in should also
* verify its process capabilities
* @param aSpecs, specifications for attributes
* @param aFilter filter to apply or NULL if none
*/
virtual void MediaL(const CMPXCollectionPath& aPath,
const TArray<TMPXAttribute>& aAttrs,
const TCapabilitySet& aCaps,
CMPXAttributeSpecs* aSpecs,
CMPXFilter* /*aFilter*/)
{
RArray<TCapability> caps;
CleanupClosePushL(caps);
if (aCaps.HasCapability(ECapabilityDRM))
{
caps.AppendL(ECapabilityDRM);
}
// else add further "relevant" capabilities here
// Add "none" capability, if no caps listed
if (caps.Count() == 0)
{
caps.AppendL(ECapability_None);
}
MediaL(aPath, aAttrs, caps.Array(), aSpecs);
CleanupStack::PopAndDestroy(&caps);
};
public:
/**
* Implementation uid of plugin.
*
* @since S60 3.2.3
*/
inline const TUid& Uid();
/**
* Current outstanding async task in the task queue.
*
* @since S60 3.2.3
*/
inline TInt Task();
/**
* Add a task and automatically schedule task.
*
* @since S60 3.2.3
* @param aTask task id
* @param aCallback callback
* @param aHandler task handler
* @param aParamData data
* @param aBuf pointer to the buffer containing
* externalized parameter data.
* Client passes ownership of the buffer
* to TaskQueue.
* @param aPtrData object pointer
* @param aCObject1 pointer to CBased object, ownership transferred
* @param aCObject2 pointer to CBased object, ownership transferred
*/
inline void AddTaskL(TInt aTask,
TAny* aCallback,
MMPXTaskQueueObserver* aHandler,
TInt aParamData=0,
CBufBase* aBuf=NULL,
TAny* aPtrData=NULL,
CBase* aCObject1=NULL,
CBase* aCObject2=NULL);
/**
* Complete current task
*
* @since S60 3.2.3
*/
inline void CompleteTask();
/**
* Complete all tasks wih the specified error code.
*
* @since S60 3.2.3
* @param aError completion error code
*/
inline void CompleteAllTasks(TInt aError);
/**
* Remove task for one client.
*
* @since S60 3.2.3
* @param aCallback callback when task completed
*/
inline void RemoveTask(TAny* aCallback);
/**
* Callback of current active task.
*
* @since S60 3.2.3
* @return pointer to call back object or NULL if no active task
*/
inline MMPXCollectionEngineObserver* Callback();
/**
* Set call back for current active task.
* NULL if there is no active task for this plugin.
*
* @since S60 3.2.3
* @param aCallback callback when task completed
*/
inline void SetCallback(MMPXCollectionEngineObserver* aCallback);
private:
/**
* This is internal and not intended for use in plugin side.
*
* @since S60 3.2.3
*/
inline void InitializeL();
protected:
MMPXCollectionPluginObserver* iObs; // Not owned
private: // Data
// identifies the actual plugin instance
TUid iDtorKey;
// Task queue for the plugin
CMPXActiveTaskQueue* iTaskQueue;
TUid iUid; //Implementation uid of the plugin
// Not owned, callback when current active task completed
MMPXCollectionEngineObserver* iCallback;
};
#include "mpxcollectionplugin.inl"
#endif // CMPXCOLLECTIONPLUGIN_H