diff -r 000000000000 -r a2952bb97e68 mmappfw_plat/mpx_playback_utility_api/inc/mpxplaybackutility.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mmappfw_plat/mpx_playback_utility_api/inc/mpxplaybackutility.h Thu Dec 17 08:55:47 2009 +0200 @@ -0,0 +1,688 @@ +/* +* 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: Interface to playback +* +*/ + + +#ifndef MMPXPLAYBACKUTILITY_H +#define MMPXPLAYBACKUTILITY_H + +#include +#include +#include +#include +#include +#include + +class RFile; +class CMPXMedia; +class MMPXPlayer; +class MMPXSource; +class MMPXPlayerManager; +class MMPXPlaybackObserver; +class MMPXPlaybackCallback; +class CMPXCollectionPlaylist; +class CMPXSubscription; +#ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API +class RFile64; +#endif // SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API + +/** +* Main client interface for playback. Some terms used in the documentation of +* this interface: +* +* Engine - it is the 'engine' which manages the playback and maintains the +* state. An abstract concept for where the playback functionality +* is somehow implemented, but is completely hidden from the client. +* +* Player - the engine may access of a number of 'players' for playback, +* using only one at a time. A player is an abstract concept +* representing the knowledge to play either a 'specific kind of item', +* or 'play in a specific way', or both. The player may therefore +* automatically change between items if required +* ('specific kind of item'), or the client may choose the players +* that are used ('play in a specific way'). +* +* Sub player - a player may support 0 or more 'sub' players, a logical +* concept whereby the client,having chosen a player, can select +* options within this player identified by name (text) +* +* Playlist - an abstract list of items. A collection path allows the client +* to cross reference the playlist with a collection, for example to +* iterate through the playlist, extract user-supplied metadata etc. +* +* @lib mpxplaybackutility.lib +* +*/ +class MMPXPlaybackUtility + { +public: + /** + * Creates the interface for the client. This interface is bound to (i.e. + * controls and recieves events from) either an existing engine or a new + * one, according to: + * + * aModeId=KPbModeDefault - bound to the same engine as any other player + * running in same thread, or KPbModeNewPlayer if none. + * aModeId=KPbModeActivePlayer - bound to whichever engine has audio access, + * else whichever is running, provided the category + * of client and engine match. Else KPbModeNewPlayer if none. + * aModeId=KPbModeNewPlayer - new engine created specifically for client, + * may be shared later. + * aModeId=Application UID - bound to the same engine as the stand alone + * Application. + * When no category is supplied (as with this API), EMPXCategoryMusic is assumed. + * For category description, refer to next API. + * + * @since S60 3.2.3 + * @param aModeId playback mode + * @param aObs plabyback observer + * @return playback utility object + */ + IMPORT_C static MMPXPlaybackUtility* NewL( + const TUid& aModeId = KPbModeDefault, + MMPXPlaybackObserver* aObs=NULL); + + + /** + * Creates the interface for the client. This interface is bound to (i.e. + * controls and recieves events from) either an existing engine or a new + * one, according to: + * + * aModeId=KPbModeDefault - bound to the same engine as any other player + * running in same thread, or KPbModeNewPlayer if none. + * aModeId=KPbModeActivePlayer - bound to whichever engine has audio access, + * else whichever is running, provided the category + * of client and engine match. Else KPbModeNewPlayer if none. + * aModeId=KPbModeNewPlayer - new engine created specifically for client, + * may be shared later. + * aModeId=Application UID - bound to the same engine as the stand alone + * Application. + * + * aCategory - a client can associate itself with a category (TMPXCategory). + * Category is used primarily with the KPbModeActivePlayer mode. The client gets + * EActivePlayerChanged message only when an engine with the same category becomes + * active. If a new engine (player) is created, the engine is tagged + * with the category. When no category is supplied, EMPXCategoryMusic is assumed. + * + * @since S60 3.2.3 + * @param aCategory engine category (TMPXCategory) + * @param aModeId playback mode + * @param aObs plabyback observer + * @return playback utility object + */ + IMPORT_C static MMPXPlaybackUtility* NewL( + const TMPXCategory aCategory, + const TUid& aModeId = KPbModeDefault, + MMPXPlaybackObserver* aObs=NULL); + + /* + * Gets the interface for the client, or creates a new one. + * This interface could be a singleton. + * + * @since S60 3.2.3 + */ + IMPORT_C static MMPXPlaybackUtility* UtilityL( + const TUid& aModeId = KPbModeDefault ); + + /* + * Gets the interface for the client, or creates a new one. + * This interface could be a singleton. + * Variant of API with supplied category + * + * @since S60 3.2.3 + */ + IMPORT_C static MMPXPlaybackUtility* UtilityL( + const TMPXCategory aCategory, + const TUid& aModeId = KPbModeDefault ); + + + /** + * Add a Observer. Clients only receive events from the engine corresponding + * to the specific mode the interface was created in. + * + * @since S60 3.2.3 + * @param aObs observer to be added + */ + virtual void AddObserverL(MMPXPlaybackObserver& aObs)=0; + + /** + * Remove a observer. + * + * @since S60 3.2.3 + * @param aObs observer to be removed + */ + virtual void RemoveObserverL(MMPXPlaybackObserver& aObs)=0; + + /** + * Returns PIds of clients that are using the engine in the mode this + * interface was created in. For example, if a client was interested in all + * the clients' pids with an active engine, they would: + * + * MMPXPlaybackUtility* m=MMPXPlaybackUtility::NewL(EActivePlayer); + * RArray pids; + * m->GetClients(pids); + * ......... + * pids->Close(); + * m->Close(); + * From the Array of clients returned, the first one will be the + * last active one. + * + * @since S60 3.2.3 + * @param aClients Array of Pids returned. + */ + virtual void GetClientsL(RArray& aClients)=0; + + /** + * Initializes a track given by aCollectionPath. + * + * @since S60 3.2.3 + * @param aCollectionPath collection path + * @param aPlay Whether to initialize for playback, or + * else just to setup the engine first + */ + virtual void InitL(const CMPXCollectionPlaylist& aPlaylist, + TBool aPlay=ETrue)=0; + + /** + * Inititialises with a single item, may not be part of any collection. + * + * @since S60 3.2.3 + * @param aUri URI of the item + * @param aType the mime type of the item + */ + virtual void InitL(const TDesC& aUri, const TDesC8* aType=NULL)=0; + + /** + * Inititialises with a single item, may not be part of any collection + * Before this function can be called, the file server session which owns + * this file handle must first be marked as shareable by calling + * RFs::ShareProtected(). + * + * @since S60 3.2.3 + * @param aShareableFile shareable file handle + */ + virtual void InitL(RFile& aShareableFile)=0; + + /** + * Frees up client side resources only; a player is freed when there are no + * clients using it, and all resources are freed when the last client closed. + * + * @since S60 3.2.3 + */ + virtual void Close()=0; + + /** + * Stops any async operations that are currently under way. + * + * @since S60 3.2.3 + */ + virtual void CancelRequest()=0; + + /** + * Issue player commands, with optional data. ECommandReceived and + * ECommandComplete events should follow. + * + * @since S60 3.2.3 + * @param aCmd the command + * @param aData optional data + * @deprecated Use method MMPXPlaybackUtility::CommandL(CMPXCommand& aCmd, + * MMPXPlaybackCallback* aCallback=NULL) instead. + */ + virtual void CommandL(TMPXPlaybackCommand aCmd, TInt aData=0)=0; + + /** + * Send a command to the playback server. + * + * @since S60 3.2.3 + * @param aCmd reference to command object + * @param aCallback call back when command exection completed. + * Asynchronously command only + */ + virtual void CommandL(CMPXCommand& aCmd, + MMPXPlaybackCallback* aCallback=NULL)=0; + + /** + * Current state of player. + * + * @since S60 3.2.3 + * @return current state + */ + virtual TMPXPlaybackState StateL() const=0; + + /** + * Current source of playlist being played, NULL if none was supplied. + * + * @since S60 3.2.3 + * @return source object + */ + virtual MMPXSource* Source()=0; + + /** + * Player manager. + * + * @since S60 3.2.3 + * @return reference to player manager + */ + virtual MMPXPlayerManager& PlayerManager()=0; + + /** + * Set playback property, EPropertyChanged event when complete. + * + * @since S60 3.2.3 + * @param aProperty the property to be set + * @param aValue the the value of the property + */ + virtual void SetL(TMPXPlaybackProperty aProperty, TInt aValue)=0; + + /** + * Get value of a playback property, Asyc. + * + * @since S60 3.2.3 + * @param aCallback playback callback + * @param aProperty the property + * @deprecated Use method MMPXPlaybackUtility::PropertyL( + * MMPXPlaybackCallback& aCallback, + * TMPXPlaybackProperty aProperty) instead. + */ + virtual void ValueL(MMPXPlaybackCallback& aCallback, + TMPXPlaybackProperty aProperty)=0; + + /** + * Get value of a playback property, Asyc. + * Result will be called back in HandleProperty. + * + * @since S60 3.2.3 + * @param aCallback playback callback + * @param aProperty the property + */ + virtual void PropertyL(MMPXPlaybackCallback& aCallback, + TMPXPlaybackProperty aProperty)=0; + + + /** + * Return a list of mime types supported by playback framework. + * + * @since S60 3.2.3 + * @return an array of mime types + */ + virtual CDesCArray* SupportedMimeTypes()=0; + + /** + * Return a list of file extensions supported by playback framework. + * + * @since S60 3.2.3 + * @return an array of extensions + */ + virtual CDesCArray* SupportedExtensions()=0; + + /** + * Return a list of schemas supported by playback framework. + * + * @since S60 3.2.3 + * @return an array of schemas + */ + virtual CDesCArray* SupportedSchemas()=0; + + /** + * Sets the priority of the playback utility. + * + * @since S60 3.2.3 + * @param aPriority Priority to set + */ + virtual void SetPriority( TInt aPriority )=0; + + /** + * Adds a message subscription for this client. + * + * @since S60 3.2.3 + * @param aSubscription subscription to be added + */ + virtual void AddSubscriptionL(const CMPXSubscription& aSubscription) = 0; + + /** + * Removes a message subscription for this client. + * + * @since S60 3.2.3 + * @param aSubscription subscription to be removed. + */ + virtual void RemoveSubscriptionL(const CMPXSubscription& aSubscription) = 0; + + /** + * Removes all message subscriptions for this client. + * + * @since S60 3.2.3 + */ + virtual void ClearSubscriptionsL() = 0; + + /** + * Inititialises for streaming with URI and Access Point + * + * @since S60 9.2 + * @param aUri URI of the item + * @param aType the mime type of the item + * @param aAccessPoint the access point of the item + */ + virtual void InitStreamingL(const TDesC& aUri, const TDesC8* aType, const TInt aAccessPoint)=0; + + /** + * Inititialises for streaming with URI and Access Point, the file may not be part of any collection + * Before this function can be called, the file server session which owns + * this file handle must first be marked as shareable by calling + * RFs::ShareProtected(). + * + * @since S60 9.2 + * @param aShareableFile shareable file handle + * @param aAccessPoint the access point of the item + */ + virtual void InitStreamingL(RFile& aShareableFile, const TInt aAccessPoint)=0; + +#ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API + /** + * Inititialises with a single item, may not be part of any collection + * Before this function can be called, the file server session which owns + * this file handle must first be marked as shareable by calling + * RFs::ShareProtected(). + * + * @since S60 9.2 + * @param aShareableFile shareable RFile64 file handle + */ + virtual void Init64L(RFile64& /*aShareableFile*/) {}; + + /** + * Inititialises for streaming with URI and Access Point, the file may not be part of any collection + * Before this function can be called, the file server session which owns + * this file handle must first be marked as shareable by calling + * RFs::ShareProtected(). + * + * @since S60 9.2 + * @param aShareableFile shareable RFile64 file handle + * @param aAccessPoint the access point of the item + */ + virtual void InitStreaming64L(RFile64& /*aShareableFile*/, const TInt /*aAccessPoint*/) {}; +#endif // SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API + }; + +/** +* Manages the players. Golden rules: by default, all players of type EPbLocal +* are tried and the first one found which can handle the content is used; when +* a specific player is selected by uid, (i.e. SelectPlayerL(TUid aPlayer)) +* then only that player will be considered in the search; when players are +* selected by type (i.e. SelectPlayersL(TMPXPlaybackPlayerType aType)), then only +* players with that type are considered; When a sub player is explicitly +* selected (i.e. SelectSubPlayerL()), then only that player and its sub player +* are considered. +* +* @lib mpxplaybackutility.lib +*/ +class MMPXPlayerManager + { +public: + /** + * Typically, a client will obtain the list of all the (non-duplicated) + * player 'types' in the system from GetPlayerTypesL and present localized + * type names (e.g. "Local","Home network", if possible, else if + * non-standard type,should use PlayerTypeDisplayNameL to get text from + * player). + * + * User should be given opportunity to choose IF there is more than one + * type available, or if there is one type but more than one sub players, + * the user could be presented with the sub player list. + * + * @since S60 3.2.3 + * @param aTypes the list of player types + */ + virtual void GetPlayerTypesL(RArray& aTypes)=0; + + /** + * Returns display name for custom types; standard types should be + * recognized by client and localized - calling this method would then not + * be required. + * + * @since S60 3.2.3 + * @param aType playback type + */ + virtual HBufC* PlayerTypeDisplayNameL(TMPXPlaybackPlayerType aType)=0; + + /** + * Get the list of UIDs of all players. + * + * @since S60 3.2.3 + * @param aPlayers All the players' uids in the system + */ + virtual void GetPlayerListL(RArray& aPlayers)=0; + + /** + * Get the list of UIDs of players with the specific type. + * + * @since S60 3.2.3 + * @param aPlayers All the players' uids with the same type + * @param aType the type of players + */ + virtual void GetPlayerListL(RArray& aPlayers, + TMPXPlaybackPlayerType aType)=0; + + /** + * Get the list of sub player names, Async. + * + * @since S60 3.2.3 + * @param aCallback sub players returned in call back interface + * @param aPlayer UID of the player + */ + virtual void SubPlayerNamesL(MMPXPlaybackCallback& aCallback, + TUid aPlayer)=0; + + /** + * Client selects all players with the type aType, the specific player used + * then being resolved on the basis of the content. + * + * @since S60 3.2.3 + * @param aType the type of player + */ + virtual void SelectPlayersL(TMPXPlaybackPlayerType aType)=0; + + /** + * Client selects specific player aPlayer and sub player aSubPlayerIndex + * from array returned by SubPlayerNamesL. + * NOTE: Once a player is manually selected by UID, all subsequent + * InitL() will continue to use that player, it will not + * try to resolve a plugin. If the client later wants + * the engine to auto resolve the proper plugin, the client must + * call ClearSelectPlayersL() to reset the engine. + * + * @since S60 3.2.3 + * @param aPlayer the UID of player + * @param aSubPlayerIndex the index of the sub player + */ + virtual void SelectSubPlayerL(TUid aPlayer, TInt aSubPlayerIndex)=0; + + /** + * Client selects a specific player. + * NOTE: Once a player is manually selected by UID, all subsequent + * InitL() will continue to use that player, it will not + * try to resolve a plugin. If the client later wants + * the engine to auto resolve the proper plugin, the client must + * call ClearSelectPlayersL() to reset the engine. + * + * @since S60 3.2.3 + * @param aPlayer the UID of the player + */ + virtual void SelectPlayerL(TUid aPlayer)=0; + + /** + * Clears all selection criteria. Essentially the same as + * SelectPlayersL(EPbLocal). + * + * @since S60 3.2.3 + */ + virtual void ClearSelectPlayersL()=0; + + /** + * Retreives the current selection: KNullUid and KErrNotFound are possible + * return values for aPlayer and aSubPlayerIndex respectively if none are + * explicitly selected. + * + * @since S60 3.2.3 + * @param aType player type + * @param aPlayer the UID of player + * @param aSubPlayerIndex index of the subplayer + * @param aSubPlayerName friendly name of the subplayer. + * Notes: Client owns the returned aSubPlayerName object. + */ + virtual void GetSelectionL(TMPXPlaybackPlayerType& aType, + TUid& aPlayer, + TInt& aSubPlayerIndex, + HBufC*& aSubPlayerName)=0; + + /** + * The current player, may change with each item, NULL if none found. + * + * @since S60 3.2.3 + * @return object of current player + */ + virtual MMPXPlayer* CurrentPlayer()=0; + }; + + +/** +* Player functionality specific to selected player. +* +* @lib mpxplaybackutility.lib +*/ +class MMPXPlayer + { +public: + /** + * The 'type' of the player. Built-in types are EPbLocal and EPbRemote, but + * the plug-ins could extend this if they desire to be a different type + * which can be selected by the user. + * + * @since S60 3.2.3 + * @return player type + */ + virtual TMPXPlaybackPlayerType TypeL()=0; + + /** + * If TypeL returns a value that is not known to the UI (and therefore + * can't localize it),then TypeNameL can be used for unlocalized display + * purposes. + * + * @since S60 3.2.3 + * @return player name. + */ + virtual HBufC* TypeNameL()=0; + + /** + * If the player supports other 'players', else array count == 0. + * + * @since S60 3.2.3 + * @param aCallback sub players returned in the callback + */ + virtual void SubPlayerNamesL(MMPXPlaybackCallback& aCallback)=0; + + /** + * Selected sub player index, corresponding to sub player names array. + * + * @since S60 3.2.3 + * @return sub player index. KErrNotFound if none + */ + virtual TInt SubPlayerL() const=0; + + /** + * The UID identifying this player. + * + * @since S60 3.2.3 + * @return UID of the player + */ + virtual TUid UidL() const=0; + }; + +/** +* Media functionality. Each media is identified by its index into a container, +* which is the same as supplied in InitL(const CMPXCollectionPlaylist& aPlaylist). +* +* @lib mpxplaybackutility.lib +*/ +class MMPXSource + { +public: + /** + * Path to the collection, or NULL if not in any collection. + * Ownership transferred. + * + * @since S60 3.2.3 + * @return collection path + */ + virtual CMPXCollectionPlaylist* PlaylistL()=0; + + /** + * File passed in, or NULL if none passed in. + * + * @since S60 3.2.3 + * @return pointer to file handle + */ + virtual RFile* FileL()=0; + + /** + * URI of current item. + * + * @since S60 3.2.3 + * @return URI of the item + */ + virtual HBufC* UriL()=0; + + /** + * + * Request for media properties of current playing item + * HandleMediaL of the callback. + * + * @since S60 3.2.3 + * @param aAttrs attributes requested + * @param aCallback playback callback + * @deprecated Use method MMPXPlaybackUtility::MediaL( + * const TArray& aAttrs, + * MMPXPlaybackCallback& aCallback, + * CMPXAttributeSpecs* aSpecs) instead. + */ + virtual void MediaL(const TArray& aAttrs, + MMPXPlaybackCallback& aCallback)=0; + + /** + * Request for media properties of current playing item + * HandleMediaL of the callback. + * + * @since S60 3.2.3 + * @param aAttrs attributes requested + * @param aCallback playback callback + * @param aSpecs specifications for attributes + */ + virtual void MediaL(const TArray& aAttrs, + MMPXPlaybackCallback& aCallback, + CMPXAttributeSpecs* aSpecs)=0; + +#ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API + /** + * File passed in, or NULL if none passed in. + * + * @since S60 9.2 + * @return pointer to file handle + */ + virtual RFile64* File64L() {return NULL;}; +#endif // SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API + }; + +#endif // MMPXPLAYBACKUTILITY_H + +// End of File