/*

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

*

*/

#ifndef MPXPLAYLISTENGINE_H

#define MPXPLAYLISTENGINE_H

#include <barsc.h>

#include <mpxtaskqueueobserver.h>

#include <mpxpluginhandlerobserver.h>

#include "mpxplaylistenginedefs.h"

#include "mpxplaylistengineobserver.h"

#include "mpxplaylistpluginobserver.h"

#include "mpxplaylistpluginhandler.h"

// FORWARD DECLARATIONS

class CMPXActiveTaskQueue;

/**

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

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

*

* Once instantiated, CMPXPlaylistPluginHandler allows the client to select an

* appropriate playlist plugin to handle requests if

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

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

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

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

*

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

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

* engine and the client is notified of the completion through

* MMPXPlaylistEngineObserver for async operations.

*

* @lib mpxplaylistengine.lib

*/

class CMPXPlaylistEngine : public CActive,

                           public MMPXPlaylistPluginObserver,

                           public MMPXTaskQueueObserver,

                           public MMPXPluginHandlerObserver

    {

public:

    /**

    *  Two-phased constructor.

    *

    *  @since S60 3.2.3

    *  @param aObserver A playlist engine observer

    *  @return Constructed playlist engine object

    */

    IMPORT_C static CMPXPlaylistEngine* NewL(MMPXPlaylistEngineObserver& aObserver);

    /**

    *  Destructor.

    *

    *  @since S60 3.2.3

    */

    IMPORT_C ~CMPXPlaylistEngine();

    /**

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

    * to select an appropriate plugin.

    *

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

    * engine.

    *

    * @see CMPXPlaylistPluginHandler

    *

    * @since S60 3.2.3

    * @return reference to playlist plugin handler

    */

    IMPORT_C CMPXPlaylistPluginHandler& PlaylistPluginHandler();

    /**

    * Determines whether the given media is a playlist from available

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

    * file is not part of this validation process.

    *

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

    * appropriate playlist plugin has been installed, the client can

    * retest it and ETrue will be returned.

    *

    * @since S60 3.2.3

    * @param aUri URI of the media to be tested

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

    */

    IMPORT_C TBool IsPlaylistL( const TDesC& aUri );

    /**

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

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

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

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

    * When a request is complete, client is notified through

    * MMPXPlaylistEngineObserver's HandlePlaylistL method. When an

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

    * KErrNotSupported is returned (through MMPXPlaylistEngineObserver's

    * HandlePlaylistL).

    *

    * @see MMPXPlaylistEngineObserver

    *

    * @since S60 3.2.3

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

    *        free this parameter as soon as this request is successfully

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

    *        automatically selected for the client to internalize the playlist.

    * @leave KErrNotFound File does not exist

    */

    IMPORT_C void InternalizePlaylistL(const TDesC& aPlaylistUri);

    /**

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

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

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

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

    * the client is notified through MMPXPlaylistEngineObserver's

    * HandlePlaylistL method. When an appropriate playlist plugin cannot be

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

    *

    * @see MMPXPlaylistEngineObserver

    *

    * @since S60 3.2.3

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

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

    *        this request is successfully submitted.

    *

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

    * automatically selected for the client to internalize the playlist.

    * @leave KErrArgument File handle does not exist

    */

    IMPORT_C void InternalizePlaylistL(const RFile& aPlaylistFileHandle);

    /**

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

    * use CMPXPlaylistPluginHandler to query available plugins and select an

    * appropriate plugin through CMPXPlaylistPluginHandler. A client

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

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

    * MMPXPlaylistEngineObserver's HandlePlaylistL method.

    *

    * NOTE:

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

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

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

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

    *    of the request will result in KErrNotFound error.

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

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

    *    uninstalled when this request is ready for processing, KErrNotSupported

    *    error will be returned through HandlePlaylistL.

    *

    * @see MMPXPlaylistEngineObserver

    *

    * @since S60 3.2.3

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

    *        the following attributes:

    *

    *            KMPXMediaGeneralTitle

    *            KMPXMediaGeneralType:

    *               The value of this attribute must be EMPXItem

    *            KMPXMediaGeneralCategory:

    *               The value of this attribute must be EMPXPlaylist

    *            KMPXMediaArrayContents

    *            KMPXMediaArrayCount

    *

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

    *        the above.

    *

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

    *        attributes:

    *

    *            KMPXMediaGeneralType:

    *               This contains the value of EMPXItem

    *            KMPXMediaGeneralCategory:

    *               This contains the value of EMPXSong

    *

    *            Client is recommended to call CMPXPlaylistPlugin::RequiredAttributes

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

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

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

    *            provide the URI of the media item.

    *

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

    *              as this method returns to save memory consumption as

    *              playlistengine will have made a copy of the playlist and

    *              stored it in the task queue.

    *

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

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

    *        KErrPathNotFound if the given path is invalid.

    * @leave KErrArgument Playlist does not contain expected attribute

    * @leave KErrArgument Media is not a Playlist

    * @leave KErrPathNotFound File path does not exist

    * @leave KErrNotFound Plugin has not been selected

    */

    IMPORT_C void ExternalizePlaylistL(

                        const CMPXMedia& aPlaylist,

                        const TDesC& aFilePath);

    /**

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

    * will be notified through MMPXPlaylistEngineObserver's HandlePlaylistL if

    * there is a current request being cancelled.

    *

    * @since S60 3.2.3

    */

    IMPORT_C void CancelRequests();

private:

    /**

    *  C++ constructor.

    *

    *  @since S60 3.2.3

    *  @param aObserver observer

    */

    CMPXPlaylistEngine(MMPXPlaylistEngineObserver& aObserver);

    /**

    *  2nd phase contructor.

    *

    *  @since S60 3.2.3

    */

    void ConstructL();

    /**

    *  From MMPXPlaylistPluginObserver.

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

    *  task queue, which is currently being processed.

    *

    *  @since S60 3.2.3

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

    *  @param aError error code

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

    *         subsequent callback for the same playlist. EFalse if not

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

    *         subsequent callbacks.

    */

    void HandlePlaylistL(CMPXMedia* aPlaylist,

                         const TInt aError,

                         const TBool aCompleted);

    /**

    *  From MMPXPlaylistPluginObserver.

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

    *  task queue, which is currently being processed.

    *

    *  @since S60 3.2.3

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

    *  @param aError error code

    */

    void HandlePlaylistL(const TDesC& aPlaylistUri,

                         const TInt aError);

    /**

    *  From CActive.

    *  Handles an active object's request completion event.

    *

    *  @since S60 3.2.3

    */

    void RunL();

    /**

    * From CActive.

    * Implements cancellation of an outstanding request.

    *

    * @since S60 3.2.3

    */

    void DoCancel();

    /**

    * From MMPXTaskQueueObserver.

    * Execute a task.

    *

    * @since S60 3.2.3

    * @param aTask task number

    * @param aParamData parameter

    * @param aPtrData any object

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

    * @param aCallback call back function pointer

    * @param aCObject1 object 1 owned by task queue

    * @param aCObject2 object 2 owned by task queue

    */

    void ExecuteTask(TInt aTask,

                     TInt aParamData,

                     TAny* aPtrData,

                     const CBufBase& aBuf,

                     TAny* aCallback,

                     CBase* aCObject1,

                     CBase* aCObject2);

    /**

    * Handle a task error.

    *

    * @see MMPXTaskQueueObserver

    *

    * @since S60 3.2.3

    */

    void HandleTaskError(TInt aTask,

                         TAny* aPtrData,

                         TAny* aCallback,

                         TInt aError);

    /*

    * Handle event from plugin.

    * @see MMPXPluginHandlerObserver

    *

    * @since S60 3.2.3

    */

    void HandlePluginHandlerEvent(TPluginHandlerEvents aEvent, const TUid& aPluginUid,

        TBool aLoaded, TInt aData);

    /**

    * Execute a task.

    *

    * @since S60 3.2.3

    * @param aTask task number

    * @param aBuf externalized parameters for the task

    * @panic KErrInUse, if not active

    * @leave KErrNotSupported Plugin is not found

    */

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

    /**

    * Handles a leave occurring in the request completion event handler

    * ExecuteTaskL.

    *

    * @since S60 3.2.3

    * @param aTask task number

    * @param aError error code

    */

    void HandleExecuteTaskError(TInt aTask, TInt aError);

    /**

    * Handles a leave occurring in the request completion event handler

    * ExecuteTaskL.

    *

    * @since S60 3.2.3

    * @param aTask task number

    * @param aError error code

    */

    void HandleExecuteTaskErrorL(TInt aTask, TInt aError);

    /**

    * Cleanup after processing the current task.

    *

    * @since S60 3.2.3

    */

    void Cleanup();

    /**

    * Generate to character sets based on locale.

    *

    * @since S60 3.2.3

    */

    void GenerateTopCharacterSetsL();

    /**

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

    *

    * @since S60 3.2.3

    * @param aLanguage language to select character sets for

    */

    void SelectCharacterSetsForLanguageL(TInt aLanguage);

    /**

    * reads the character set for the specified resource.

    *

    * @since S60 3.2.3

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

    */

    void ReadCharacterSetResourceL(TInt aResourceId);

    /**

    * Determine whether the given character set is specified

    * as top character set.

    *

    * @since S60 3.2.3

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

    */

    TBool IsInTopCharacterSet(TUint aCharacterSetId);

private:

    // playlist commands

    enum TMPXPlaylistCmd

        {

        EInternalizePlaylist,

        EExternalizePlaylist

        };

private:

    RFs                                     iFs;

    MMPXPlaylistEngineObserver&             iObserver;

    CMPXPlaylistPluginHandler*              iPluginHandler;

    CMPXActiveTaskQueue*                    iTaskQueue;

    // Character set for unicode conversion

    CArrayFix<CCnvCharacterSetConverter::SCharacterSet>* iCharacterSet;

    // Most likely character set for unicode conversion

    CArrayFix<CCnvCharacterSetConverter::SCharacterSet>* iTopCharacterSet;

    RResourceFile                           iRscFile;

    //

    // parameters for the task currently being processed to ensure

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

    // they are freed after each task completion.

    //

    HBufC*                                  iPlaylistUri;

    HBufC*                                  iFilePath;

    CMPXMedia*                              iPlaylist;

    };

#endif // MPXPLAYLISTENGINE_H