/*
* 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 plugin handler
*
*/
#ifndef MPXPLAYLISTPLUGINHANDLER_H
#define MPXPLAYLISTPLUGINHANDLER_H
#include <ecom/ecom.h>
#include <mpxpluginhandlerbase.h>
#include "mpxplaylistenginedefs.h"
#include "mpxplaylistplugin.h"
/**
* CMPXPlaylistPluginHandler is instantiated and owned by CMPXPlaylistEngine.
* It provides playlist plugin selection APIs for the external client and
* the internal client (i.e. CMPXPlaylistEngine) and manages loading and
* unloading of playlist plugins. A plugin is loaded when selected and
* unloaded when the plugin has been uninstalled or when CMPXPlaylistEngine
* is destroyed (CMPXPlaylistEngine destroys CMPXPlaylistPluginHandler when
* itself is destroyed).
*
* @lib mpxplaylistengine.lib
*/
class CMPXPlaylistPluginHandler : public CMPXPluginHandlerBase
{
public:
/**
* Two-phased constructor.
*
* @since S60 3.2.3
* @param aPluginObserver playlist plugin observer
* @param aObserver plugin handler observer
* @param aFs file session handle
* @param aTopCharacterSet top character set for the locale
* @param aAvailableCharacterSet available character set in the system
* @return Constructed object
*/
IMPORT_C static CMPXPlaylistPluginHandler* NewL(
MMPXPlaylistPluginObserver& aPluginObserver,
MMPXPluginHandlerObserver& aObserver,
RFs& aFs,
const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>& aTopCharacterSet,
const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>& aAvailableCharacterSet);
/**
* Destructor.
*
* @since S60 3.2.3
*/
~CMPXPlaylistPluginHandler();
/**
* Returns currently loaded plug-in UID, or KNullUid if none loaded.
*
* @since S60 3.2.3
* @return UID of the plugin
*/
inline TUid PluginUid() const;
/**
* Returns currently loaded plug-in type or EMPXPlaylistTypeUnknown if
* no plugin is loaded.
*
* @since S60 3.2.3
* @return plugin type Refer to TMPXPlaylistType for the representation
* of each bit of the return value
*/
inline TUint32 PluginType() const;
/**
* Returns display name for current plug-in or KNullDesC if no plugin
* is loaded.
*
* @since S60 3.2.3
* @return plugin name.
*/
inline const TDesC& PluginName() const;
/**
* Is a plug-in currently loaded.
*
* @since S60 3.2.3
* @return ETrue if a plugin is loaded; EFalse otherwise.
*/
inline TBool PluginFound() const;
/**
* Returns currently loaded plug-in, or NULL if none. CMPXPlaylistPluginHandler
* is responsible for the memory management of the return playlist plugin
* object.
*
* @since S60 3.2.3
* @return plugin object interface
*/
inline CMPXPlaylistPlugin* Plugin() const;
/**
* Selects a plug-in appropriate for a Uri and data type; may already be loaded.
* If the selected plug-in has not been loaded before, one is instantiated.
*
* If successful, information related to the currently loaded plugin will reflect
* this selected plug-in. Leaves with KErrNotSupported if unable to find a
* suitable plugin.
*
* @since S60 3.2.3
* @param aUri URI of the song
* @param aDataType data type. KNullDesC8 if this parameter is not to be used
* for selection.
*/
IMPORT_C void SelectPlaylistPluginL(
const TDesC& aUri,
const TDesC8& aDataType);
/**
* Selects a plug-in appropriate for a file; may already be loaded. If the
* selected plug-in has not been loaded before, one is instantiated.
*
* If successful, information related to currently loaded plugin will reflect
* this selected plug-in. Leaves with KErrNotSupported if unable to find a
* suitable plugin.
*
* @since S60 3.2.3
* @param aFile file handle
*/
IMPORT_C void SelectPlaylistPluginL(const RFile& aFile);
/**
* Selects a plugin appropriate for the plugin type; may already be loaded.
* If the selected plugin has not been loaded before, one is instantiated.
*
* If successful, information related to currently loaded plugin will reflect
* this selected plug-in. Leaves with KErrNotSupported if unable to find a
* suitable plugin.
*
* This is the recommended method for the client to select a plugin prior
* to issuing an ExternalizePlaylist request.
*
* @since S60 3.2.3
* @param aPluginType A plugin type, possible values are defined in
* TMPXPlaylistType.
*/
IMPORT_C void SelectPlaylistPluginL(TUint32 aPluginType);
/**
* Selects a plugin with the specified display name; may already be loaded.
* If the selected plugin has not been loaded before, one is instantiated.
*
* If successful, information related to currently loaded plugin will reflect
* this selected plug-in. Leaves with KErrNotSupported if unable to find
* a suitable plugin.
*
* This is not the recommended method for the client to select a plugin
* prior to issuing an ExternalizePlaylist request. The recommended
* method is through a plugin type.
*
* @since S60 3.2.3
* @param aPluginName The name of the plugin to be selected.
*/
IMPORT_C void SelectPlaylistPluginL(const TDesC& aPluginName);
/**
* Selects a plug-in with UID aUid, or leaves with KErrNotSupported if not
* found. If the selected plugin has not been loaded before, one is
* instantiated.
*
* If successful, information related to currently loaded plugin will reflect
* this selected plug-in. Leaves with KErrNotSupported if unable to find
* the specified plugin.
*
* @since S60 3.2.3
* @param aUid UID of the plugin
*/
IMPORT_C void SelectPlaylistPluginL(const TUid& aUid);
private:
/**
* C++ constructor.
*
* @since S60 3.2.3
* @param aPluginObserver playlist plugin observer
* @param aObserver plugin handler observer
* @param aFs file session handle
* @param aTopCharacterSet top character set for the locale
* @param aAvailableCharacterSet available character set in the system
*/
CMPXPlaylistPluginHandler(
MMPXPlaylistPluginObserver& aPluginObserver,
MMPXPluginHandlerObserver& aObserver,
RFs& aFs,
const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>& aTopCharacterSet,
const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>& aAvailableCharacterSet);
/**
* 2nd phase contructor.
*
* @since S60 3.2.3
*/
void ConstructL();
/**
* Creates a plugin. If already loaded, returns a reference without creating
* another instance of the plugin.
*
* @since S60 3.2.3
* @return plugin object interface
* @leave The function leaves with one of the system error codes,
*/
CMPXPlaylistPlugin* CreatePlaylistPluginL(const TUid& aUid);
/**
* From CMPXPluginHandlerBase.
* Resolves plugin.
*
* @since S60 3.2.3
*/
void ResolvePluginL();
/**
* Verify the specified plugin is loaded.
*
* @see CMPXPluginHandlerBase
*
* @since S60 3.2.3
*/
TBool IsPluginLoaded(const TUid& aPluginUid);
/**
* Load the specified plugin.
* @see CMPXPluginHandlerBase
*
* @since S60 3.2.3
*/
void LoadPluginL(const TUid& aPluginUid);
/**
* Unload the specified plugin.
* @see CMPXPluginHandlerBase
*
* @since S60 3.2.3
*/
void UnloadPlugin(const TUid& aPluginUid);
/**
* Unloads a plugin by index.
* @since S60 3.2.3
* @param aIndex index of the plugin to unload
*
*/
void UnloadPlugin(TInt aIndex);
private:
MMPXPlaylistPluginObserver& iPluginObserver;
RFs& iFs;
const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>& iTopCharacterSet;
const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>& iAvailableCharacterSet;
//
// Loaded. The index must correspond in these arrays
//
RPointerArray<CMPXPlaylistPlugin> iLoadedPlugins;
RArray<TUid> iLoadedPluginsUids;
//
// Chosen
//
CMPXPlaylistPlugin* iPlugin; // ownership belongs to iLoadedPlugins
TUid iPluginUid;
TUint32 iPluginType;
HBufC* iDisplayName;
};
#include "mpxplaylistpluginhandler.inl"
#endif // MPXPLAYLISTPLUGINHANDLER_H