CMPXPlaylistEngine Class Reference

class CMPXPlaylistEngine : public CActive

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.

mpxplaylistengine.lib

Inherits from

Public Member Functions
~CMPXPlaylistEngine ()
IMPORT_C void CancelRequests ()
IMPORT_C void ExternalizePlaylistL (const CMPXMedia &, const TDesC &)
IMPORT_C void InternalizePlaylistL (const TDesC &)
IMPORT_C void InternalizePlaylistL (const RFile &)
IMPORT_C TBool IsPlaylistL (const TDesC &)
IMPORT_C CMPXPlaylistEngine * NewL (MMPXPlaylistEngineObserver &)
IMPORT_C CMPXPlaylistPluginHandler & PlaylistPluginHandler ()
Private Member Functions
CMPXPlaylistEngine (MMPXPlaylistEngineObserver &)
void Cleanup ()
void ConstructL ()
void DoCancel ()
void ExecuteTask ( TInt , TInt , TAny *, const CBufBase &, TAny *, CBase *, CBase *)
void ExecuteTaskL ( TInt , const CBufBase &)
void GenerateTopCharacterSetsL ()
void HandleExecuteTaskError ( TInt , TInt )
void HandleExecuteTaskErrorL ( TInt , TInt )
void HandlePlaylistL ( CMPXMedia *, const TInt , const TBool )
void HandlePlaylistL (const TDesC &, const TInt )
void HandlePluginHandlerEvent (TPluginHandlerEvents, const TUid &, TBool , TInt )
void HandleTaskError ( TInt , TAny *, TAny *, TInt )
TBool IsInTopCharacterSet ( TUint )
void ReadCharacterSetResourceL ( TInt )
void RunL ()
void SelectCharacterSetsForLanguageL ( TInt )
Inherited Functions
CActive::CActive(TInt)
CActive::Cancel()
CActive::Deque()
CActive::Extension_(TUint,TAny *&,TAny *)
CActive::IsActive()const
CActive::IsAdded()const
CActive::Priority()const
CActive::RunError(TInt)
CActive::SetActive()
CActive::SetPriority(TInt)
CActive::~CActive()
CBase::CBase()
CBase::Delete(CBase *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()
Private Member Enumerations
enum TMPXPlaylistCmd { EInternalizePlaylist , EExternalizePlaylist }
Inherited Enumerations
CActive:TPriority
Private Attributes
CArrayFix < CCnvCharacterSetConverter::SCharacterSet > * iCharacterSet
HBufC * iFilePath
RFs iFs
MMPXPlaylistEngineObserver & iObserver
CMPXMedia * iPlaylist
HBufC * iPlaylistUri
CMPXPlaylistPluginHandler * iPluginHandler
RResourceFile iRscFile
CMPXActiveTaskQueue * iTaskQueue
CArrayFix < CCnvCharacterSetConverter::SCharacterSet > * iTopCharacterSet
Inherited Attributes
CActive::iStatus

Constructor & Destructor Documentation

CMPXPlaylistEngine(MMPXPlaylistEngineObserver &)

CMPXPlaylistEngine ( MMPXPlaylistEngineObserver & aObserver ) [private]

C++ constructor.

Since
S60 3.2.3

Parameters

MMPXPlaylistEngineObserver & aObserver observer

~CMPXPlaylistEngine()

IMPORT_C ~CMPXPlaylistEngine ( )

Destructor.

Since
S60 3.2.3

Member Functions Documentation

CancelRequests()

IMPORT_C void CancelRequests ( )

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

Cleanup()

void Cleanup ( ) [private]

Cleanup after processing the current task.

Since
S60 3.2.3

ConstructL()

void ConstructL ( ) [private]

2nd phase contructor.

Since
S60 3.2.3

DoCancel()

void DoCancel ( ) [private, virtual]

From CActive . Implements cancellation of an outstanding request.

Since
S60 3.2.3

ExecuteTask(TInt, TInt, TAny *, const CBufBase &, TAny *, CBase *, CBase *)

void ExecuteTask ( TInt aTask,
TInt aParamData,
TAny * aPtrData,
const CBufBase & aBuf,
TAny * aCallback,
CBase * aCObject1,
CBase * aCObject2
) [private]

From MMPXTaskQueueObserver. Execute a task.

Since
S60 3.2.3

Parameters

TInt aTask task number
TInt aParamData parameter
TAny * aPtrData any object
const CBufBase & aBuf
TAny * aCallback call back function pointer
CBase * aCObject1 object 1 owned by task queue
CBase * aCObject2 object 2 owned by task queue

ExecuteTaskL(TInt, const CBufBase &)

void ExecuteTaskL ( TInt aTask,
const CBufBase & aBuf
) [private]

Execute a task.

Since
S60 3.2.3
panic
KErrInUse, if not active
leave
KErrNotSupported Plugin is not found

Parameters

TInt aTask task number
const CBufBase & aBuf externalized parameters for the task

ExternalizePlaylistL(const CMPXMedia &, const TDesC &)

IMPORT_C void ExternalizePlaylistL ( const CMPXMedia & aPlaylist,
const TDesC & aFilePath
)

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.

MMPXPlaylistEngineObserver
Since
S60 3.2.3
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.

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

Parameters

const CMPXMedia & aPlaylist a playlist to be externalized. This media must contain the following attributes:
const TDesC & aFilePath file path for the playlist to be created, e.g. e:\. This must be a valid path. Leaves with KErrPathNotFound if the given path is invalid.

GenerateTopCharacterSetsL()

void GenerateTopCharacterSetsL ( ) [private]

Generate to character sets based on locale.

Since
S60 3.2.3

HandleExecuteTaskError(TInt, TInt)

void HandleExecuteTaskError ( TInt aTask,
TInt aError
) [private]

Handles a leave occurring in the request completion event handler ExecuteTaskL.

Since
S60 3.2.3

Parameters

TInt aTask task number
TInt aError error code

HandleExecuteTaskErrorL(TInt, TInt)

void HandleExecuteTaskErrorL ( TInt aTask,
TInt aError
) [private]

Handles a leave occurring in the request completion event handler ExecuteTaskL.

Since
S60 3.2.3

Parameters

TInt aTask task number
TInt aError error code

HandlePlaylistL(CMPXMedia *, const TInt, const TBool)

void HandlePlaylistL ( CMPXMedia * aPlaylist,
const TInt aError,
const TBool aCompleted
) [private]

From MMPXPlaylistPluginObserver. Callback from a plugin for an InternalizePlaylistL request, in the task queue, which is currently being processed.

Since
S60 3.2.3

Parameters

CMPXMedia * aPlaylist a list of media items parsed from the playlist file
const TInt aError error code
const TBool 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.

HandlePlaylistL(const TDesC &, const TInt)

void HandlePlaylistL ( const TDesC & aPlaylistUri,
const TInt aError
) [private]

From MMPXPlaylistPluginObserver. Callback from a plugin for an ExternalizePlaylistL request, in the task queue, which is currently being processed.

Since
S60 3.2.3

Parameters

const TDesC & aPlaylistUri URI for the playlist which has been externalized
const TInt aError error code

HandlePluginHandlerEvent(TPluginHandlerEvents, const TUid &, TBool, TInt)

void HandlePluginHandlerEvent ( TPluginHandlerEvents aEvent,
const TUid & aPluginUid,
TBool aLoaded,
TInt aData
) [private]

Parameters

TPluginHandlerEvents aEvent
const TUid & aPluginUid
TBool aLoaded
TInt aData

HandleTaskError(TInt, TAny *, TAny *, TInt)

void HandleTaskError ( TInt aTask,
TAny * aPtrData,
TAny * aCallback,
TInt aError
) [private]

Handle a task error.

MMPXTaskQueueObserver
Since
S60 3.2.3

Parameters

TInt aTask
TAny * aPtrData
TAny * aCallback
TInt aError

InternalizePlaylistL(const TDesC &)

IMPORT_C void InternalizePlaylistL ( const TDesC & aPlaylistUri )

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).

MMPXPlaylistEngineObserver
Since
S60 3.2.3
leave
KErrNotFound File does not exist

Parameters

const TDesC & 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.

InternalizePlaylistL(const RFile &)

IMPORT_C void InternalizePlaylistL ( const RFile & aPlaylistFileHandle )

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.

MMPXPlaylistEngineObserver
Since
S60 3.2.3
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

Parameters

const RFile & aPlaylistFileHandle a file handle to the playlist to be internalized. Client may close this file handle as soon as this request is successfully submitted.

IsInTopCharacterSet(TUint)

TBool IsInTopCharacterSet ( TUint aCharacterSetId ) [private]

Determine whether the given character set is specified as top character set.

Since
S60 3.2.3

Parameters

TUint aCharacterSetId id of the character set to be tested

IsPlaylistL(const TDesC &)

IMPORT_C TBool IsPlaylistL ( const TDesC & aUri )

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

Parameters

const TDesC & aUri URI of the media to be tested

NewL(MMPXPlaylistEngineObserver &)

IMPORT_C CMPXPlaylistEngine * NewL ( MMPXPlaylistEngineObserver & aObserver ) [static]

Two-phased constructor.

Since
S60 3.2.3

Parameters

MMPXPlaylistEngineObserver & aObserver A playlist engine observer

PlaylistPluginHandler()

IMPORT_C CMPXPlaylistPluginHandler & PlaylistPluginHandler ( )

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.

ReadCharacterSetResourceL(TInt)

void ReadCharacterSetResourceL ( TInt aResourceId ) [private]

reads the character set for the specified resource.

Since
S60 3.2.3

Parameters

TInt aResourceId id of the resource to read from the resource file

RunL()

void RunL ( ) [private, virtual]

From CActive . Handles an active object's request completion event.

Since
S60 3.2.3

SelectCharacterSetsForLanguageL(TInt)

void SelectCharacterSetsForLanguageL ( TInt aLanguage ) [private]

Select character set(s) for the specified language.

Since
S60 3.2.3

Parameters

TInt aLanguage language to select character sets for

Member Enumerations Documentation

Enum TMPXPlaylistCmd

Enumerators

EInternalizePlaylist
EExternalizePlaylist

Member Data Documentation

CArrayFix< CCnvCharacterSetConverter::SCharacterSet > * iCharacterSet

CArrayFix < CCnvCharacterSetConverter::SCharacterSet > * iCharacterSet [private]

HBufC * iFilePath

HBufC * iFilePath [private]

RFs iFs

RFs iFs [private]

MMPXPlaylistEngineObserver & iObserver

MMPXPlaylistEngineObserver & iObserver [private]

CMPXMedia * iPlaylist

CMPXMedia * iPlaylist [private]

HBufC * iPlaylistUri

HBufC * iPlaylistUri [private]

CMPXPlaylistPluginHandler * iPluginHandler

CMPXPlaylistPluginHandler * iPluginHandler [private]

RResourceFile iRscFile

RResourceFile iRscFile [private]

CMPXActiveTaskQueue * iTaskQueue

CMPXActiveTaskQueue * iTaskQueue [private]

CArrayFix< CCnvCharacterSetConverter::SCharacterSet > * iTopCharacterSet

CArrayFix < CCnvCharacterSetConverter::SCharacterSet > * iTopCharacterSet [private]