1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Collection plugin interface

    15 *

    16 */

    17 

    18 

    19 #ifndef CMPXCOLLECTIONPLUGIN_H

    20 #define CMPXCOLLECTIONPLUGIN_H

    21 

    22 #include <ecom/ecom.h>

    23 #include <mpxcollectionframeworkdefs.h>

    24 #include <mpxattribute.h>

    25 #include <mpxfilter.h>

    26 #include <mpxcommand.h>

    27 #include <mpxsearchcriteria.h>

    28 #include <mpxattributespecs.h>

    29 

    30 class MMPXCollectionPluginObserver;

    31 class MMPXCollectionEngineObserver;

    32 class CMPXCollectionPath;

    33 class CMPXActiveTaskQueue;

    34 class MMPXTaskQueueObserver;

    35 

    36 const TUid KMPXCollectionInterfaceUid={0x101FFC36};

    37 

    38 /********************************************************************************

    39 *

    40 *  Note:

    41 *

    42 *  ** remove void CommandL(TMPXCollectionCommand aCmd, TInt aArg = 0)

    43 *

    44 *  ** remove MediaL() overload

    45 *

    46 *  ** remove null implementations

    47 *

    48 *  ** rename GetCapabilities() to Capabilities()

    49 *

    50 *********************************************************************************/

    51 

    52 /**

    53  *  CMPXCollectionPlugin class

    54  *

    55  *  Interface to access collection

    56  */

    57 NONSHARABLE_CLASS(CMPXCollectionPlugin): public CBase

    58     {

    59 

    60 public: // Constructors and destructor

    61 

    62     /**

    63      * Two-phased constructor.

    64      *

    65      * @since S60 3.2.3

    66      * @param aUid uid of interface implementation

    67      * @param aObs Reference to the callback interface

    68      * @return object of constructed

    69      */

    70     inline static CMPXCollectionPlugin* NewL(const TUid& aUid,

    71                                              MMPXCollectionPluginObserver& aObs);

    72 

    73     /**

    74      * Destructor.

    75      *

    76      * @since S60 3.2.3

    77      */

    78     inline virtual ~CMPXCollectionPlugin();

    79 

    80 public:

    81 

    82     /**

    83      * Callback setter.

    84      *

    85      * @since S60 3.2.3

    86      * @param aObs Reference to the callback interface

    87      */

    88     inline void SetObserver(MMPXCollectionPluginObserver& aObs);

    89 

    90     /**

    91      * 

    92      *

    93      * @param aCmd a command

    94      * @param aArg optional argument

    95      * @deprecated executes a command on the selected collection, use CommandL(CMPXCommand& aCmd)

    96      */

    97     virtual void CommandL(TMPXCollectionCommand aCmd, TInt aArg = 0)=0;

    98 

    99     /**

   100      * Executes a command.

   101      *

   102      * @since S60 3.2.3

   103      * @param aCmd a command

   104      */

   105     virtual void CommandL(CMPXCommand& /*aCmd*/)

   106         {/*Note: need to implement this */}

   107 

   108     /**

   109      * Navigates to the given path.

   110      *

   111      * @since S60 3.2.3

   112      * @param aPath a path

   113      * @param aAttrs attributes requested

   114      * @param aFilter filter to apply or NULL if none

   115      */

   116     virtual void OpenL(const CMPXCollectionPath& /*aPath*/,

   117                    const TArray<TMPXAttribute>& /*aAttrs*/,

   118                    CMPXFilter* /*aFilter*/) = 0;

   119 

   120     /**

   121      *

   122      *  Media properties of the current file (async).

   123      *  Note: if selection is set in aPath, HandleMedia will return an array of

   124      *        media properties of current selected items.

   125      *        if no selection is set in aPath, HandleMedia will return media

   126      *        properities of current item.

   127      *

   128      * @since S60 3.2.3

   129      * @param aPath path for the media file

   130      * @param aAttr attributes requested

   131      * @param aCaps platsec capabilities of client requesting media; plug-in should also

   132      *        verify its process capabilities

   133      * @param aSpecs, specifications for attributes

   134      * @deprecated use the following version of MediaL

   135      */

   136     virtual void MediaL(const CMPXCollectionPath& /*aPath*/,

   137                         const TArray<TMPXAttribute>& /*aAttrs*/,

   138                         const TArray<TCapability>& /*aCaps*/,

   139                         CMPXAttributeSpecs* /*aSpecs*/) = 0;

   140     /**

   141      * Cancel outstanding request.

   142      *

   143      * @since S60 3.2.3.

   144      */

   145     virtual void CancelRequest()=0;

   146 

   147     /**

   148      *  Adds an item or items to the collection.

   149      *

   150      *  @since S60 3.2.3

   151      *  @param aNewProperties Properties of the item

   152      */

   153     virtual void AddL(const CMPXMedia& aNewMedia) = 0;

   154 

   155     /**

   156      * Remove a collection path.

   157      * Note that the selection indicies are hidden within the path

   158      *

   159      * @since S60 3.2.3

   160      * @param aPath path to remove

   161      *

   162      */

   163     virtual void RemoveL(const CMPXCollectionPath& aPath ) = 0;

   164 

   165     /**

   166      *  Remove an item or items from the collection.

   167      *

   168      *  @since S60 3.2.3

   169      *  @param aProperties Properties of the item. It may cantain URI only

   170      *                      or meta data, all of items matched properties

   171      *                      will be removed.

   172      */

   173     virtual void RemoveL(const CMPXMedia& aMedia) = 0;

   174 

   175     /**

   176      *  Sets/updates the media for the item

   177      *  specified in the path.

   178      *

   179      *  @since S60 3.2.3

   180      *  @param aMedia new value

   181      */

   182     virtual void SetL(const CMPXMedia& aMedia) = 0;

   183 

   184     /**

   185      *  Find a list of items matched (async).

   186      *

   187      *  @since S60 3.2.3

   188      *  @param aCriteria properties to be searched

   189      *  @param aAttrs attributes to return

   190      */

   191     virtual void FindAllL(const CMPXSearchCriteria& aCriteria,

   192                           const TArray<TMPXAttribute>& aAttrs) = 0;

   193 

   194     /**

   195      * Find a list of items matched (sync).

   196      *

   197      *  @since S60 3.2.3

   198      *  @param aCriteria properties to be searched

   199      *  @param aAttrs attributes to return

   200      *  @return results of the search

   201      */

   202     virtual CMPXMedia* FindAllSyncL(const CMPXSearchCriteria& aCriteria,

   203                                     const TArray<TMPXAttribute>& aAttrs) = 0;

   204 

   205     /**

   206      * Get the list of supported capabilities.

   207      *

   208      * @since S60 3.2.3

   209      * @return TCollectionCapability bitmask of supported capabilities

   210      */

   211     virtual TCollectionCapability GetCapabilities() = 0;

   212 

   213     /** Note change it to pure virtual when all of plugins implement this interface

   214      *

   215      *  Media properties of the current file (async).

   216      *  Note: if selection is set in aPath, HandleMedia will return an array of

   217      *        media properties of current selected items.

   218      *        if no selection is set in aPath, HandleMedia will return media

   219      *        properities of current item.

   220      *

   221      * @since S60 3.2.3

   222      * @param aPath path for the media file

   223      * @param aAttr attributes requested

   224      * @param aCaps platsec capabilities of client requesting media; plug-in should also

   225      *        verify its process capabilities

   226      * @param aSpecs, specifications for attributes

   227      * @param aFilter filter to apply or NULL if none

   228      */

   229     virtual void MediaL(const CMPXCollectionPath& aPath,

   230                         const TArray<TMPXAttribute>& aAttrs,

   231                         const TCapabilitySet& aCaps,

   232                         CMPXAttributeSpecs* aSpecs,

   233                         CMPXFilter* /*aFilter*/)

   234             {

   235             RArray<TCapability> caps;

   236             CleanupClosePushL(caps);

   237             if (aCaps.HasCapability(ECapabilityDRM))

   238                 {

   239                 caps.AppendL(ECapabilityDRM);

   240                 }

   241             // else add further "relevant" capabilities here

   242 

   243             // Add "none" capability, if no caps listed

   244             if (caps.Count() == 0)

   245                 {

   246                 caps.AppendL(ECapability_None);

   247                 }

   248             MediaL(aPath, aAttrs, caps.Array(), aSpecs);

   249             CleanupStack::PopAndDestroy(&caps);

   250             };

   251 

   252 public:

   253 

   254     /**

   255      * Implementation uid of plugin.

   256      *

   257      * @since S60 3.2.3

   258      */

   259     inline const TUid& Uid();

   260 

   261     /**

   262      * Current outstanding async task in the task queue.

   263      *

   264      * @since S60 3.2.3

   265      */

   266     inline TInt Task();

   267 

   268     /**

   269      *  Add a task and automatically schedule task.

   270      *

   271      *  @since S60 3.2.3

   272      *  @param aTask task id

   273      *  @param aCallback callback

   274      *  @param aHandler task handler

   275      *  @param aParamData data

   276      *  @param aBuf pointer to the buffer containing

   277      *               externalized parameter data.

   278      *               Client passes ownership of the buffer

   279      *               to TaskQueue.

   280      *  @param aPtrData object pointer

   281      *  @param aCObject1 pointer to CBased object, ownership transferred

   282      *  @param aCObject2 pointer to CBased object, ownership transferred

   283      */

   284      inline void AddTaskL(TInt aTask,

   285                           TAny* aCallback,

   286                           MMPXTaskQueueObserver* aHandler,

   287                           TInt aParamData=0,

   288                           CBufBase* aBuf=NULL,

   289                           TAny* aPtrData=NULL,

   290                           CBase* aCObject1=NULL,

   291                           CBase* aCObject2=NULL);

   292 

   293     /**

   294      *  Complete current task

   295      *

   296      *  @since S60 3.2.3

   297      */

   298     inline void CompleteTask();

   299 

   300     /**

   301      *  Complete all tasks wih the specified error code.

   302      *

   303      *  @since S60 3.2.3

   304      *  @param aError completion error code

   305      */

   306     inline void CompleteAllTasks(TInt aError);

   307 

   308     /**

   309      *  Remove task for one client.

   310      *

   311      *  @since S60 3.2.3

   312      *  @param aCallback callback when task completed

   313      */

   314     inline void RemoveTask(TAny* aCallback);

   315 

   316     /**

   317      * Callback of current active task.

   318      *

   319      * @since S60 3.2.3

   320      * @return pointer to call back object or NULL if no active task

   321      */

   322     inline MMPXCollectionEngineObserver* Callback();

   323 

   324     /**

   325      *  Set call back for current active task. 

   326      *  NULL if there is no active task for this plugin.

   327      *

   328      *  @since S60 3.2.3

   329      *  @param aCallback callback when task completed

   330      */

   331     inline void SetCallback(MMPXCollectionEngineObserver* aCallback);

   332 

   333 private:

   334     /**

   335      * This is internal and not intended for use in plugin side.

   336      *

   337      * @since S60 3.2.3

   338      */

   339     inline void InitializeL();

   340 

   341 protected:

   342 

   343     MMPXCollectionPluginObserver*  iObs; // Not owned

   344 private: // Data

   345 

   346     // identifies the actual plugin instance

   347     TUid iDtorKey;

   348     // Task queue for the plugin

   349     CMPXActiveTaskQueue* iTaskQueue;

   350     TUid iUid; //Implementation uid of the plugin

   351     // Not owned, callback when current active task completed

   352     MMPXCollectionEngineObserver* iCallback;

   353     };

   354 

   355 #include "mpxcollectionplugin.inl"

   356 #endif      // CMPXCOLLECTIONPLUGIN_H

   357 

   358