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:  Playlist engine

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef MPXPLAYLISTENGINE_H

    21 #define MPXPLAYLISTENGINE_H

    22 

    23 #include <barsc.h>

    24 #include <mpxtaskqueueobserver.h>

    25 #include <mpxpluginhandlerobserver.h>

    26 

    27 #include "mpxplaylistenginedefs.h"

    28 #include "mpxplaylistengineobserver.h"

    29 #include "mpxplaylistpluginobserver.h"

    30 #include "mpxplaylistpluginhandler.h"

    31 

    32 // FORWARD DECLARATIONS

    33 class CMPXActiveTaskQueue;

    34 

    35 /**

    36 * This is the main class in playlist engine and the entry point for a client.

    37 * Each instance of a playlist engine is capable of handling one client.

    38 *

    39 * Once instantiated, CMPXPlaylistPluginHandler allows the client to select an

    40 * appropriate playlist plugin to handle requests if

    41 * necessary (e.g. ExternalizePlaylistL). A playlist plugin is loaded when selected

    42 * by a client or in some cases, it's loaded when a request is issued for the plugin

    43 * (e.g. InternalizePlaylistL). It's unloaded when the plugin is uninstalled from

    44 * the system or when the client destroys its playlist engine.

    45 *

    46 * A client can access playlist plugin via Playlist Plugin Handler. However, it's

    47 * recommended that a client direct any request for the plugin through the playlist

    48 * engine and the client is notified of the completion through

    49 * MMPXPlaylistEngineObserver for async operations.

    50 *

    51 * @lib mpxplaylistengine.lib

    52 */

    53 class CMPXPlaylistEngine : public CActive,

    54                            public MMPXPlaylistPluginObserver,

    55                            public MMPXTaskQueueObserver,

    56                            public MMPXPluginHandlerObserver

    57     {

    58 public:

    59 

    60     /**

    61     *  Two-phased constructor.

    62     *

    63     *  @since S60 3.2.3

    64     *  @param aObserver A playlist engine observer

    65     *  @return Constructed playlist engine object

    66     */

    67     IMPORT_C static CMPXPlaylistEngine* NewL(MMPXPlaylistEngineObserver& aObserver);

    68 

    69     /**

    70     *  Destructor.

    71     *

    72     *  @since S60 3.2.3

    73     */

    74     IMPORT_C ~CMPXPlaylistEngine();

    75 

    76     /**

    77     * returns a handle to playlist plugin handler which a client can use

    78     * to select an appropriate plugin.

    79     *

    80     * Lifetime for this playlist plugin handler is the same as the playlist

    81     * engine.

    82     *

    83     * @see CMPXPlaylistPluginHandler

    84     *

    85     * @since S60 3.2.3

    86     * @return reference to playlist plugin handler

    87     */

    88     IMPORT_C CMPXPlaylistPluginHandler& PlaylistPluginHandler();

    89 

    90     /**

    91     * Determines whether the given media is a playlist from available

    92     * playlist plugins currently in the system. The existence of the

    93     * file is not part of this validation process.

    94     *

    95     * An unsupported playlist file is tested as EFalse. But after the

    96     * appropriate playlist plugin has been installed, the client can

    97     * retest it and ETrue will be returned.

    98     *

    99     * @since S60 3.2.3

   100     * @param aUri URI of the media to be tested

   101     * @return ETrue if it's a playlist; otherwise EFalse.

   102     */

   103     IMPORT_C TBool IsPlaylistL( const TDesC& aUri );

   104 

   105     /**

   106     * Internalize a playlist (async). Client is not required to select an

   107     * appropriate plugin as one that is capable of handling the given

   108     * media from its URI is automatically selected. Client can issue

   109     * another request without having to wait for the completion of a request.

   110     * When a request is complete, client is notified through

   111     * MMPXPlaylistEngineObserver's HandlePlaylistL method. When an

   112     * appropriate playlist plugin cannot be found to handle this request,

   113     * KErrNotSupported is returned (through MMPXPlaylistEngineObserver's

   114     * HandlePlaylistL).

   115     *

   116     * @see MMPXPlaylistEngineObserver

   117     *

   118     * @since S60 3.2.3

   119     * @param aPlaylistUri Uri of the playlist to be internalized. Client may

   120     *        free this parameter as soon as this request is successfully

   121     *        submitted. From the URI provided, an appropriate plugin is

   122     *        automatically selected for the client to internalize the playlist.

   123     * @leave KErrNotFound File does not exist

   124     */

   125     IMPORT_C void InternalizePlaylistL(const TDesC& aPlaylistUri);

   126 

   127     /**

   128     * Internalize a playlist (async). Client is not required to select an

   129     * appropriate plugin as one which is capable of handling the given

   130     * file is selected automatically. Client can issue another request without

   131     * having to wait for the completion of a request. When a request is complete,

   132     * the client is notified through MMPXPlaylistEngineObserver's

   133     * HandlePlaylistL method. When an appropriate playlist plugin cannot be

   134     * found to handle this request, KErrNotSupported error is returned.

   135     *

   136     * @see MMPXPlaylistEngineObserver

   137     *

   138     * @since S60 3.2.3

   139     * @param aPlaylistFileHandle a file handle to the playlist to be

   140     *        internalized. Client may close this file handle as soon as

   141     *        this request is successfully submitted.

   142     *

   143     * From the fullname of the given file handle, an appropriate plugin is

   144     * automatically selected for the client to internalize the playlist.

   145     * @leave KErrArgument File handle does not exist

   146     */

   147     IMPORT_C void InternalizePlaylistL(const RFile& aPlaylistFileHandle);

   148 

   149     /**

   150     * Externalize a playlist (async). Before issuing this request, client must

   151     * use CMPXPlaylistPluginHandler to query available plugins and select an

   152     * appropriate plugin through CMPXPlaylistPluginHandler. A client

   153     * can issue another request without having to wait for the completion of

   154     * a request. When a request is complete, client is notified through

   155     * MMPXPlaylistEngineObserver's HandlePlaylistL method.

   156     *

   157     * NOTE:

   158     * 1) If the client does not select a plugin prior to issuing this request,

   159     *    this request may or may not fail depending on whether the client

   160     *    has loaded a plugin through previous operation, e.g.

   161     *    InternalizePlaylistL. When a plugin hasn't been selected, processing

   162     *    of the request will result in KErrNotFound error.

   163     * 2) If the client has successfully selected a playlist plugin prior to

   164     *    issuing this request but the selected playlist plugin has since been

   165     *    uninstalled when this request is ready for processing, KErrNotSupported

   166     *    error will be returned through HandlePlaylistL.

   167     *

   168     * @see MMPXPlaylistEngineObserver

   169     *

   170     * @since S60 3.2.3

   171     * @param aPlaylist a playlist to be externalized. This media must contain

   172     *        the following attributes:

   173     *

   174     *            KMPXMediaGeneralTitle

   175     *            KMPXMediaGeneralType:

   176     *               The value of this attribute must be EMPXItem

   177     *            KMPXMediaGeneralCategory:

   178     *               The value of this attribute must be EMPXPlaylist

   179     *            KMPXMediaArrayContents

   180     *            KMPXMediaArrayCount

   181     *

   182     *        KErrArgument is returned if client fails to comply with any of

   183     *        the above.

   184     *

   185     *        Each media item in the playlist must to contain the following

   186     *        attributes:

   187     *

   188     *            KMPXMediaGeneralType:

   189     *               This contains the value of EMPXItem

   190     *            KMPXMediaGeneralCategory:

   191     *               This contains the value of EMPXSong

   192     *

   193     *            Client is recommended to call CMPXPlaylistPlugin::RequiredAttributes

   194     *            before making a request to export the playlist and provide the rest

   195     *            of attributes required for each media item in the playlist. If client

   196     *            is unable to provide all of those attributes, client MUST at least

   197     *            provide the URI of the media item.

   198     *

   199     *        NOTE: It's recommended that client deletes this playlist as soon

   200     *              as this method returns to save memory consumption as

   201     *              playlistengine will have made a copy of the playlist and

   202     *              stored it in the task queue.

   203     *

   204     * @param aFilePath file path for the playlist to be created, e.g.

   205     *        e:\playlists\. This must be a valid path. Leaves with

   206     *        KErrPathNotFound if the given path is invalid.

   207     * @leave KErrArgument Playlist does not contain expected attribute

   208     * @leave KErrArgument Media is not a Playlist

   209     * @leave KErrPathNotFound File path does not exist

   210     * @leave KErrNotFound Plugin has not been selected

   211     */

   212     IMPORT_C void ExternalizePlaylistL(

   213                         const CMPXMedia& aPlaylist,

   214                         const TDesC& aFilePath);

   215 

   216     /**

   217     * Cancel current request, if any, and all other outstanding requests. Client

   218     * will be notified through MMPXPlaylistEngineObserver's HandlePlaylistL if

   219     * there is a current request being cancelled.

   220     *

   221     * @since S60 3.2.3

   222     */

   223     IMPORT_C void CancelRequests();

   224 

   225 private:

   226 

   227     /**

   228     *  C++ constructor.

   229     *

   230     *  @since S60 3.2.3

   231     *  @param aObserver observer

   232     */

   233     CMPXPlaylistEngine(MMPXPlaylistEngineObserver& aObserver);

   234 

   235     /**

   236     *  2nd phase contructor.

   237     *

   238     *  @since S60 3.2.3

   239     */

   240     void ConstructL();

   241 

   242     /**

   243     *  From MMPXPlaylistPluginObserver.

   244     *  Callback from a plugin for an InternalizePlaylistL request, in the

   245     *  task queue, which is currently being processed.

   246     *

   247     *  @since S60 3.2.3

   248     *  @param aPlaylist a list of media items parsed from the playlist file

   249     *  @param aError error code

   250     *  @param aCompleted a flag that indicates if there will be

   251     *         subsequent callback for the same playlist. EFalse if not

   252     *         all the results have been sent back; there will be

   253     *         subsequent callbacks.

   254     */

   255     void HandlePlaylistL(CMPXMedia* aPlaylist,

   256                          const TInt aError,

   257                          const TBool aCompleted);

   258 

   259     /**

   260     *  From MMPXPlaylistPluginObserver.

   261     *  Callback from a plugin for an ExternalizePlaylistL request, in the

   262     *  task queue, which is currently being processed.

   263     *

   264     *  @since S60 3.2.3

   265     *  @param aPlaylistUri URI for the playlist which has been externalized

   266     *  @param aError error code

   267     */

   268     void HandlePlaylistL(const TDesC& aPlaylistUri,

   269                          const TInt aError);

   270 

   271     /**

   272     *  From CActive.

   273     *  Handles an active object's request completion event.

   274     *

   275     *  @since S60 3.2.3

   276     */

   277     void RunL();

   278 

   279     /**

   280     * From CActive.

   281     * Implements cancellation of an outstanding request.

   282     *

   283     * @since S60 3.2.3

   284     */

   285     void DoCancel();

   286 

   287     /**

   288     * From MMPXTaskQueueObserver.

   289     * Execute a task.

   290     *

   291     * @since S60 3.2.3

   292     * @param aTask task number

   293     * @param aParamData parameter

   294     * @param aPtrData any object

   295     * @param aBuf, buffer containing externalized parameters for the task.

   296     * @param aCallback call back function pointer

   297     * @param aCObject1 object 1 owned by task queue

   298     * @param aCObject2 object 2 owned by task queue

   299     */

   300     void ExecuteTask(TInt aTask,

   301                      TInt aParamData,

   302                      TAny* aPtrData,

   303                      const CBufBase& aBuf,

   304                      TAny* aCallback,

   305                      CBase* aCObject1,

   306                      CBase* aCObject2);

   307 

   308     /**

   309     * Handle a task error.

   310     *

   311     * @see MMPXTaskQueueObserver

   312     *

   313     * @since S60 3.2.3

   314     */

   315     void HandleTaskError(TInt aTask,

   316                          TAny* aPtrData,

   317                          TAny* aCallback,

   318                          TInt aError);

   319 

   320     /*

   321     * Handle event from plugin.

   322     * @see MMPXPluginHandlerObserver

   323     *

   324     * @since S60 3.2.3

   325     */

   326     void HandlePluginHandlerEvent(TPluginHandlerEvents aEvent, const TUid& aPluginUid,

   327         TBool aLoaded, TInt aData);

   328 

   329     /**

   330     * Execute a task.

   331     *

   332     * @since S60 3.2.3

   333     * @param aTask task number

   334     * @param aBuf externalized parameters for the task

   335     * @panic KErrInUse, if not active

   336     * @leave KErrNotSupported Plugin is not found

   337     */

   338     void ExecuteTaskL(TInt aTask, const CBufBase& aBuf);

   339 

   340     /**

   341     * Handles a leave occurring in the request completion event handler

   342     * ExecuteTaskL.

   343     *

   344     * @since S60 3.2.3

   345     * @param aTask task number

   346     * @param aError error code

   347     */

   348     void HandleExecuteTaskError(TInt aTask, TInt aError);

   349 

   350     /**

   351     * Handles a leave occurring in the request completion event handler

   352     * ExecuteTaskL.

   353     *

   354     * @since S60 3.2.3

   355     * @param aTask task number

   356     * @param aError error code

   357     */

   358     void HandleExecuteTaskErrorL(TInt aTask, TInt aError);

   359 

   360     /**

   361     * Cleanup after processing the current task.

   362     *

   363     * @since S60 3.2.3

   364     */

   365     void Cleanup();

   366 

   367     /**

   368     * Generate to character sets based on locale.

   369     *

   370     * @since S60 3.2.3

   371     */

   372     void GenerateTopCharacterSetsL();

   373 

   374     /**

   375     * Select character set(s) for the specified language.

   376     *

   377     * @since S60 3.2.3

   378     * @param aLanguage language to select character sets for

   379     */

   380     void SelectCharacterSetsForLanguageL(TInt aLanguage);

   381 

   382     /**

   383     * reads the character set for the specified resource.

   384     *

   385     * @since S60 3.2.3

   386     * @param aResourceId id of the resource to read from the resource file

   387     */

   388     void ReadCharacterSetResourceL(TInt aResourceId);

   389 

   390     /**

   391     * Determine whether the given character set is specified

   392     * as top character set.

   393     *

   394     * @since S60 3.2.3

   395     * @param aCharacterSetId id of the character set to be tested

   396     */

   397     TBool IsInTopCharacterSet(TUint aCharacterSetId);

   398 

   399 private:

   400 

   401     // playlist commands

   402     enum TMPXPlaylistCmd

   403         {

   404         EInternalizePlaylist,

   405         EExternalizePlaylist

   406         };

   407 

   408 private:

   409 

   410     RFs                                     iFs;

   411 

   412     MMPXPlaylistEngineObserver&             iObserver;

   413 

   414     CMPXPlaylistPluginHandler*              iPluginHandler;

   415 

   416     CMPXActiveTaskQueue*                    iTaskQueue;

   417 

   418     // Character set for unicode conversion

   419     CArrayFix<CCnvCharacterSetConverter::SCharacterSet>* iCharacterSet;

   420     // Most likely character set for unicode conversion

   421     CArrayFix<CCnvCharacterSetConverter::SCharacterSet>* iTopCharacterSet;

   422 

   423     RResourceFile                           iRscFile;

   424 

   425     //

   426     // parameters for the task currently being processed to ensure

   427     // they are available for the duration of the task processing.

   428     // they are freed after each task completion.

   429     //

   430     HBufC*                                  iPlaylistUri;

   431     HBufC*                                  iFilePath;

   432     CMPXMedia*                              iPlaylist;

   433 

   434     };

   435 

   436 #endif // MPXPLAYLISTENGINE_H