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:  Interface to collections

    15 *

    16 */

    17 

    18 

    19 #ifndef MMPXCOLLECTIONUTILITY_H

    20 #define MMPXCOLLECTIONUTILITY_H

    21 

    22 #include <mpxcollectionframeworkdefs.h>

    23 #include <mpxcommonframeworkdefs.h>

    24 #include <mpxcollectionobserver.h>

    25 #include <mpxattribute.h>

    26 #include <mpxfilter.h>

    27 #include <mpxcommand.h>

    28 #include <mpxsearchcriteria.h>

    29 #include <mpxattributespecs.h>

    30 

    31 #include <badesca.h>

    32 

    33 class CMPXCollectionPath;

    34 class CMPXCollectionType;

    35 class MMPXCollection;

    36 class MMPXCollectionFindObserver;

    37 class CMPXSubscription;

    38 

    39 /********************************************************************************

    40 *

    41 *  Note:

    42 *

    43 *  ** remove void CommandL(TMPXCollectionCommand aCmd, TInt aData = 0)

    44 *

    45 *  ** remove TUid CollectionIDL(TUid& aCollection)

    46 *

    47 *  ** all methods which do not (necessarily) operate on current collection

    48 *     should be moved from MMPXCollection to MMPXCollectionUtility

    49 *

    50 *

    51 *********************************************************************************/

    52 

    53 /**

    54  *  Main client interface for collections. Some terms used in the documentation of

    55  *  this interface:

    56  *

    57  *    Context - represents the 'state' of the collection, i.e. the current

    58  *              browse path (encapsulated in CMPXCollectionPath) and filter applied

    59  *             (encapsulated in CMPXFilter)

    60  *

    61  *    Playlist - an abstract list of songs. A collection path allows the client

    62  *             to cross reference the playlist with a collection, for example to

    63  *             iterate through the playlist, extract user-supplied metadata etc.

    64  *

    65  *  @lib mpxcollectionutility.lib

    66  */

    67 class MMPXCollectionUtility

    68     {

    69 public:

    70     /**

    71      *  Creates the interface for the client. This interface is bound to (i.e.

    72      *  controls and receives events from) either an existing context or a new

    73      *  one, according to:

    74      *

    75      *    aModeId=KMcModeDefault - bound to the same context as any other client

    76      *                             running in the same thread, or KMcModeIsolated

    77      *                             context created if the first client in the thread

    78      *    aModeId=KMcModeIsolated - new context created specifically for client,

    79      *                              may be shared later

    80      *    aModeId=<UID> - bound to the same context as other clients which have

    81      *                    supplied the same UID. Most common case is application UID

    82      *                    so that clients in external processes can easily bind to

    83      *                    a specific application context

    84      *

    85      *  @since S60 3.2.3

    86      *  @param aObs collection observer

    87      *  @param aModeId collection mode id

    88      *  @return collection utility object

    89      */

    90     IMPORT_C static MMPXCollectionUtility* NewL(

    91                                         MMPXCollectionObserver* aObs = NULL,

    92                                         const TUid& aModeId = KMcModeDefault);

    93 

    94     /**

    95      *  The collection.

    96      *

    97      *  @since S60 3.2.3

    98      *  @return the collection

    99      */

   100     virtual MMPXCollection& Collection() = 0;

   101 

   102     /**

   103      * Retrieves the ID of the collection plugin which matched aUids best.

   104      * If multiple plugins match the aUids, the only one with high priority will

   105      * be returned.

   106      *

   107   	 * @since S60 3.2.3

   108      * @param aUids selection criteria

   109      * @return TUid containing the implementation UID of the collection that

   110      * would be selected

   111      */

   112     virtual TUid CollectionIDL(const TArray<TUid>& aUids) = 0;

   113 

   114     /**

   115      *  Frees up client side resources only. A collection is freed when there are no

   116      *  clients using it, and all resources are freed when the last client closes.

   117      *

   118      *  @since S60 3.2.3

   119      */

   120     virtual void Close() = 0;

   121     };

   122 

   123 /**

   124  *  MPXCollection

   125  *

   126  *  @lib mpxcollectionutility.lib

   127  */

   128 class MMPXCollection

   129     {

   130 public:

   131     /**

   132      *  Opens the collection in its current state.

   133      *

   134      *  Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object

   135      *  with ID KMPXMediaIdContainer, i.e.contains other media objects.

   136      *

   137      *  @since S60 3.2.3

   138      *  @param aMode open mode

   139      */

   140     virtual void OpenL(TMPXOpenMode aMode=EMPXOpenDefault) = 0;

   141 

   142     /**

   143      *  Opens the collection at a specific index.

   144      *

   145      *  Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object

   146      *  with ID KMPXMediaIdContainer, i.e.contains other media objects.

   147      *

   148      *  @since S60 3.2.3

   149      *  @param aIndex the index into the currently opened item list

   150      *  @param aMode type of open mode

   151      */

   152     virtual void OpenL(TInt aIndex,TMPXOpenMode aMode=EMPXOpenDefault) = 0;

   153 

   154     /**

   155      *  Opens the collection at a specific level.

   156      *

   157      *  @since S60 3.2.3

   158      *  @param aPath the path of the collection

   159      *  @param aMode type of open mode required

   160      *

   161      *  Calls back MMPXCollectionObserver::HandleOpenL()

   162      */

   163     virtual void OpenL(const CMPXCollectionPath& aPath,

   164                        TMPXOpenMode aMode=EMPXOpenDefault) = 0;

   165 

   166     /**

   167      *  Opens the collection at a specific index.

   168      *

   169      *  Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object

   170      *  with ID KMPXMediaIdContainer, i.e.contains other media objects which will

   171      *  contain the attribute values specified by aAttrs.   

   172      *

   173      *  @since S60 3.2.3

   174      *  @param aIndex the index into the currently opened item list

   175      *  @param aAttrs attributes requested

   176      *  @param aMode type of open mode

   177      */

   178     virtual void OpenL(TInt aIndex,

   179                        const TArray<TMPXAttribute>& aAttrs,

   180                        TMPXOpenMode aMode=EMPXOpenDefault) = 0;

   181 

   182     /**

   183      *  Opens the collection at a specific level.

   184      *

   185      *  Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object

   186      *  with ID KMPXMediaIdContainer, i.e.contains other media objects which will

   187      *  contain the attribute values specified by aAttrs.

   188      *

   189      *  @since S60 3.2.3

   190      *  @param aPath the path of the collection

   191      *  @param aAttrs attributes requested

   192      *  @param aMode type of open mode required

   193      */

   194     virtual void OpenL(const CMPXCollectionPath& aPath,

   195                        const TArray<TMPXAttribute>& aAttrs,

   196                        TMPXOpenMode aMode=EMPXOpenDefault) = 0;

   197 

   198     /**

   199      *  Opens the collection with a list of implementation uids to be matched.

   200      *  If current context matches the criteria, it will return existing browsing

   201      *  media; otherwise it will be back to root level and only plug-ins which

   202      *  match all provided uids will be returned, in priority order.

   203      *

   204      *  Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object

   205      *  with ID KMPXMediaIdContainer. Returned plugins will be sorted by plugin

   206      *  priority if mulitple plugins support aUids.

   207      *

   208      *  @since S60 3.2.3

   209      *  @param aUids array of UIDs used to select collection plugins based on

   210      *  							supported uids in plugin resource file.

   211      *  @param aMode open mode

   212      */

   213     virtual void OpenL(const TArray<TUid>& aUids,

   214                        TMPXOpenMode aMode=EMPXOpenDefault) = 0;

   215 

   216     /**

   217      *  Opens the collection with an uid to be matched.

   218      *  If current context matches the criteria, it will return existing browsing

   219      *  media; otherwise it will be back to root level and only plug-ins which

   220      *  match the uid will be returned, in priority order.

   221      *

   222      *  Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object

   223      *  with ID KMPXMediaIdContainer. Returned plugins will be sorted by plugin

   224      *  priority if mulitple plugins support the uid.

   225      *

   226      *  @since S60 3.2.3

   227      *  @param aUid single UID used to select a collection

   228      *  @param aMode open mode

   229      */

   230     virtual void OpenL(const TUid& aUid,

   231                        TMPXOpenMode aMode=EMPXOpenDefault) = 0;

   232 

   233     /**

   234      *  Apply a filter to collection browsing. All subsequent calls

   235      *  to OpenL() will have this filter applied.

   236      *

   237      *  @since S60 3.2.3

   238      *  @param aFilter the filter to apply, or NULL to remove current

   239      *  filter

   240      */

   241     virtual void SetFilterL(CMPXFilter* aFilter) = 0;

   242 

   243     /**

   244      *  Current filter that is applied to collection browsing. i.e. results

   245      *  returned through MMPXCollectionObserver::HandleOpenL() callback from

   246      *  OpenL().

   247      *

   248      *  @since S60 3.2.3

   249      *  @return filter applied to browsing, or NULL if no filter applied

   250      */

   251     virtual CMPXFilter* FilterL() = 0;

   252 

   253     /**

   254      *  Returns current collection plugin implementation UID.

   255      *

   256      *  @since S60 3.2.3

   257      *  @return UID of the collection, or KNullUid if no collection opened

   258      */

   259     virtual TUid UidL() const=0;

   260 

   261     /**

   262      *  The path of the collection in its current state.

   263      *  Ownsership transferred.

   264      *

   265      *  @since S60 3.2.3

   266      *  @return the path of the collection

   267      */

   268     virtual CMPXCollectionPath* PathL() = 0;

   269 

   270     /**

   271      *  Navigates back to the container of the current items.

   272      *  Calls back MMPXCollectionObserver::HandleOpenL().

   273      *

   274      *  @since S60 3.2.3

   275      */

   276     virtual void BackL() = 0;

   277 

   278     /**

   279      *  Is this path on a 'remote' collection.

   280      *

   281      *  @since S60 3.2.3

   282      *  @aParam aPath the collection path

   283      *  @return ETrue if is remote collection, otherwise EFalse

   284      */

   285     virtual TBool IsRemote(const CMPXCollectionPath& aPath) = 0;

   286 

   287     /**

   288      *  Stops any async operations that are currently under way.

   289      *

   290      *  @since S60 3.2.3

   291      */

   292     virtual void CancelRequest() = 0;

   293 

   294     /**

   295      *  Adds item(s) to the collection.

   296      *

   297      *  @since S60 3.2.3

   298      *  @param aNewMedia new item(s) to add

   299      */

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

   301 

   302     /**

   303      *  Remove an item (or items under a group) from the collection

   304      *

   305      *  @param aPath, item(s) to remove

   306      *  @param aObs, observer to this operation, Optional callback.

   307      *  @deprecated please use CommandL (CMPXCommand)

   308      */

   309     virtual void RemoveL(const CMPXCollectionPath& aPath,

   310                          MMPXCollectionRemoveObserver* aObs = NULL ) = 0;

   311 

   312     /**

   313      *  Removes item(s) from the collection.

   314      *

   315      *  @since S60 3.2.3

   316      *  @param aMedia item(s) to remove

   317      */

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

   319 

   320     /**

   321      *  Sets/updates the media for the item.

   322      *  Callback via EMediaChanged message if currently opened.

   323      *

   324      *  @since S60 3.2.3

   325      *  @param aMedia updated item

   326      *

   327      */

   328     virtual void SetSyncL(const CMPXMedia& aMedia) = 0;

   329 

   330     /** 

   331      *

   332      *  Sets/updates the item specified in the path, Aynchronous

   333      *  Callback for completion with HandleCollectionMessageL()

   334      *           event:  TMPXCollectionMessage::EAsyncOpComplete

   335      *           type:   EMcsSetMediaAsync

   336      *           data:   error code

   337      *

   338      *  @param aMedia, updated item

   339      *  @deprecated, please use CommandL(CMPXCommand& aCmd)

   340      */

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

   342 

   343     /**

   344      * Find a list of media properties based on a search criteria.

   345      * The types of supported "queries" are collection dependent.

   346      * Callback via MMPXCollectionFindObserver::HandleFindL();

   347      *

   348      * @since S60 3.2.3

   349      * @param aCriteria criteria to search on

   350      * @param aAttrs attributes to return

   351      * @param aObs observer for find callback

   352      *    

   353      */

   354     virtual void FindAllL(const CMPXSearchCriteria& aCriteria,

   355                           const TArray<TMPXAttribute>& aAttrs,

   356                           MMPXCollectionFindObserver& aObs) = 0;

   357 

   358     /**

   359      * Find a list of media properties based on a search criteria.

   360      * The types of supported "queries" are collection dependent.

   361      * This is a SYNCHRONOUS METHOD, use only if necessary.

   362      *

   363      * @since S60 3.2.3

   364      * @param aCriteria criteria to search on

   365      * @param aAttrs attributes to return

   366      * @return search results maching the given criteria

   367      */

   368     virtual CMPXMedia* FindAllL(const CMPXSearchCriteria& aCriteria,

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

   370 

   371     /**

   372      *  Retrieve media for the item specified in the path.

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

   374      *        media of current selected items.

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

   376      *        properities of current item.

   377      *  Calls back MMPXCollectionObserver::HandleMediaL()

   378      *

   379      *  @since S60 3.2.3

   380      *  @param aPath the path of the collection

   381      *  @param aAttrs attributes requested.

   382      *  @param aSpecs specifications for attributes, Ownership not transferred

   383      *  @param aFilter filter to apply, Ownership not transferred

   384      *    

   385      */

   386     virtual void MediaL(const CMPXCollectionPath& aPath,

   387                         const TArray<TMPXAttribute>& aAttrs,

   388                         CMPXAttributeSpecs* aSpecs=NULL,

   389                         CMPXFilter* aFilter=NULL) = 0;

   390 

   391     /**

   392      *  Broadcasts an event to all clients or plugins.

   393      *

   394      * @since S60 3.2.3

   395      * @param aMsg event to broadcast

   396      * @param aData data to accompany the event

   397      */

   398     virtual void NotifyL(TMPXCollectionBroadCastMsg aMsg, TInt aData) = 0;

   399 

   400     /**

   401      *  Send a command to the collection server

   402      *

   403      *  @param aCmd, command to handle

   404      *  @param aData, some data about event (event specific, optional)

   405      *  @deprecated use CommandL(CMPXCommand& aCmd)

   406      */

   407     virtual void CommandL(TMPXCollectionCommand aCmd, TInt aData = 0) = 0;

   408 

   409     /**

   410      *  Send a command to the collection server.

   411      *

   412      *  @since S60 3.2.3

   413      *  @param aCmd command to handle

   414      */

   415     virtual void CommandL(CMPXCommand& aCmd) = 0;

   416 

   417     /**

   418      * Retrieves the list of supported types.

   419      *

   420      * @since S60 3.2.3

   421      * @param aArray On return, array will be filled with collection type items

   422      */

   423     virtual void GetSupportedTypesL(RPointerArray<CMPXCollectionType>& aArray) = 0;

   424 

   425     /**

   426      * Fetches the capabilities supported by the current collection context.

   427      *

   428      * @since S60 3.2.3

   429      * @param aCapability bitmask of the capabilities supported.    

   430      */

   431     virtual void GetSupportedCapabilitiesL(TCollectionCapability& aCapability) = 0;

   432 

   433     /**

   434      * 

   435      * Retrieves the real collection UID based on a predefined UID

   436      * @param aCollection, UID for lookup, defined in "mpxcollectionframeworkdefs.h"

   437      * @return TUid containing the real implementation UID

   438      * @deprecated use MMPXCollectionUtility::CollectionIDL

   439      */

   440     virtual TUid CollectionIDL(TUid& aCollection) = 0;

   441 

   442     /**

   443      * Adds a message subscription for this client.

   444      *

   445      * @since S60 3.2.3

   446      * @param aSubscription subscription to be added

   447      */

   448     virtual void AddSubscriptionL(const CMPXSubscription& aSubscription) = 0;

   449 

   450     /**

   451      * Removes a message subscription for this client.

   452      *

   453      * @since S60 3.2.3

   454      * @param aSubscription subscription to be removed.

   455      */

   456     virtual void RemoveSubscriptionL(const CMPXSubscription& aSubscription) = 0;

   457 

   458     /**

   459      * Removes all message subscriptions for this client.

   460      *

   461      * @since S60 3.2.3

   462      */

   463     virtual void ClearSubscriptionsL() = 0;

   464     };

   465 

   466 #endif      // MMPXCOLLECTIONUTILITY_H

   467