diff -r 000000000000 -r a2952bb97e68 mmappfw_plat/mpx_common_api/inc/mpxpluginhandlerbase.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mmappfw_plat/mpx_common_api/inc/mpxpluginhandlerbase.h Thu Dec 17 08:55:47 2009 +0200 @@ -0,0 +1,509 @@ +/* +* 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: Base plugin handler +* +*/ + + +#ifndef CMPXPLUGINHANDLERBASE_H +#define CMPXPLUGINHANDLERBASE_H + +#include +#include +#include "mpxpluginmonitorobserver.h" + +class CMPXPluginMonitor; +class CMPXPluginInfo; +class MMPXPluginHandlerObserver; + +/** +* CMPXPluginHandlerBase instantiates and owns a CMPXPluginMonitor to monitor +* plugins for the designated plugin interface. It also provides plugin +* selection APIs and a common method for resolving a plugin from a set of +* selection criteria. +* +* @lib mpxcommon.lib +*/ +class CMPXPluginHandlerBase : public CBase, + public MMPXPluginMonitorObserver + { +public: + + enum TPluginSelection + { + ESelectionType, // select a plugin by type + ESelectionUid // select a plugin by uid + }; + + public: + + /** + * Constructor. + * + * @since S60 3.2.3 + * @param aInterfaceUid The UID of the ECOM plugin interface this plugin + * handler is designated for + * @param aSelection plugin selection choices as defined in TPluginSelection + * @param aSelectionType specifies the type of plugin for selection + * @param aObserver plugin handler observer instance + * @param aPluginMonitor plugin monitor. It is for the clients to share the + * same plugin monitor object. + */ + IMPORT_C CMPXPluginHandlerBase( + TUid aInterfaceUid, + TPluginSelection aSelection, + TInt aSelectionType, + MMPXPluginHandlerObserver& aObserver, + CMPXPluginMonitor* aPluginMonitor=NULL); + + /** + * Destructor. + * + * @since S60 3.2.3 + */ + IMPORT_C ~CMPXPluginHandlerBase(); + +protected: + /** + * 2nd phase contructor. + * + * @since S60 3.2.3 + */ + IMPORT_C void BaseConstructL(); + +public: + + /** + * Use this particular plugin. + * + * @since S60 3.2.3 + * @param aPluginUid UID of the plugin to be used + */ + IMPORT_C void SelectPluginL(const TUid& aPluginUid); + + /** + * Use the plugin with the specified display name. + * + * @since S60 3.2.3 + * @param aPluginName name of the plugin + */ + IMPORT_C void SelectPluginL(const TDesC& aPluginName); + + /** + * Select a plugin based on the URI and data type of the media given. + * + * @since S60 3.2.3 + * @param aUri URI of the media + * @param aDataType Mime type of the media. KNullDesC8 if not to be + * used for selection. + * @leave KErrArgument Invalid URI + */ + IMPORT_C virtual void SelectPluginL( + const TDesC& aUri, + const TDesC8& aDataType); + + /** + * Select a plugin based on file handle for the given media. + * + * @since S60 3.2.3 + * @param aFile a file handle to the media + */ + IMPORT_C virtual void SelectPluginL(const RFile& aFile); + + /** + * Select a plugin based on the plugin type. + * + * @since S60 3.2.3 + * @param aPluginType plugin type for the appropriate plugin to be used. + * The representation for each bit is to be defined by each plugin + * interface. + */ + IMPORT_C virtual void SelectPluginL(TInt aPluginType); + + /** + * Indicates that this plugin is used by a client. Increments the reference + * count for the plugin. + * + * @since S60 3.2.3 + * @param aPluginUid plugin UID + */ + IMPORT_C void UsePlugin(const TUid& aPluginUid); + + /** + * Indicates that this plugin is no longer used by a client. Plugins are + * reference counted and this call may result in the plugin being unloaded. + * + * @since S60 3.2.3 + * @param aPluginUid plugin UID + * @return ETrue if the plugin is unloaded / EFalse if it is not. + */ + IMPORT_C TBool ReleasePlugin(const TUid& aPluginUid); + + /** + * Retrieves the current selection criteria. + * + * @since S60 3.2.3 + * @param aPluginSelection OUT parameter. the selection choice as defined + * by TPluginSelection + * @param aPluginType OUT parameter. plugin type to be used for selection + * @param aPluginUid OUT parameter. UID of the plugin to be used for selection. + * KNullUid is a possible return value if none is explicitly selected. + * @param aDataType OUT parameter. The data type to be used for selection. + * KNullDesC8 if none is specified. CMPXPluginHandlerBase is + * responsible for the memory management of this parameter. + * @param aScheme OUT parameter. The scheme to be used for selection. + * KNullDesC8 if none is specified. CMPXPluginHandlerBase is + * responsible for the memory management of this parameter. + * @param aExtension OUT parameter. The extension to be used for selection. + * KNullDesC8 if none is specified. CMPXPluginHandlerBase is + * responsible for the memory management of this parameter. + */ + IMPORT_C virtual void GetSelectionCriteria( + TPluginSelection& aPluginSelection, + TInt& aPluginType, + TUid& aPluginUid, + TPtrC8& aDataType, + TPtrC8& aScheme, + TPtrC8& aExtension); + + /** + * Clear selection criteria parameters. + * + * @since S60 3.2.3 + */ + IMPORT_C virtual void ClearSelectionCriteria(); + +#ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API + /** + * Select a plugin based on file handle for the given media. + * + * @since S60 3.2.3 + * @param aFile a 64 bit file handle to the media + */ + IMPORT_C virtual void SelectPlugin64L(const RFile64& aFile); +#endif // SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API + +protected: + + /** + * Resolves a plugin based on properties (iDataType, iExt and iScheme) and + * selection criteria. When a plugin is found, information about the plugin + * is returned through parameters. + * + * @since S60 3.2.3 + * @param aPluginUid This is an OUT parameter. The UID of the matching plugin + * @param aIndex This is an OUT parameter. The index for the plugin info, plugin + * UID, and plugin types array for the matching plugin + * @param aDisplayName This is an OUT parameter. The display name for the matching + * plugin. CMPXPluginHandlerBase is responsible for the memory management + * of this parameter. + * @param aPluginType This is an OUT parameter. The plugin type for the matching + * plugin + * @leave KErrNotSupported Index is not found + */ + IMPORT_C virtual void DoResolvePluginL( + TUid& aPluginUid, + TInt& aIndex, + TPtrC& aDisplayName, + TInt& aPluginType); + + /** + * From MMPXPluginMonitorObserver. This is invoked by CMPXPluginMonitor when + * there is a change in the plugins for the designated plugin interface in + * the system. + * + * @since S60 3.2.3 + */ + IMPORT_C virtual void PluginsChangedL(); + + /** + * From MMPXPluginMonitorObserver. + * + * @since S60 3.2.3 + * @see MMPXPluginMonitorObserver + */ + IMPORT_C virtual void HandlePluginUnload(const TUid& aPluginUid); + + /** + * Resolves a plugin. To be implemented by the child class. This is invoked + * whenever a client selects a plugin and whenever CMPXPluginMonitor notifies + * that there is a change in the plugins for the designated plugin interface + * in the system. + * + * A typical implementation for this method is to invoke DoResolvePluginL + * and instantiate a plugin using the plugin UID returned from DoResolvePluginL. + * + * NOTE: this method is not pure virtual because currently the playlist + * recognizer instantiates this class as opposed to the derived handler. + * This should be fixed and both ResolvePluginL and UnloadPlugin should be + * made pure virtuals. + * + * @since S60 3.2.3 + */ + IMPORT_C virtual void ResolvePluginL(); + + /** + * Checks if the specified plugin is loaded. + * + * @since S60 3.2.3 + * @param aPluginUid identifies the plugin + * @return ETrue if the plugin is loaded, EFalse otherwise + */ + IMPORT_C virtual TBool IsPluginLoaded(const TUid& aPluginUid); + + /** + * Request to the derived class to load a specified plugin. + * + * @since S60 3.2.3 + * @param aPluginUid identifies the plugin + */ + IMPORT_C virtual void LoadPluginL(const TUid& aPluginUid); + + /** + * Request to the derived class to unload a specified plugin. + * + * @since S60 3.2.3 + * @param aPluginUid identifies the plugin + */ + IMPORT_C virtual void UnloadPlugin(const TUid& aPluginUid); + + /** + * Constructs the plugins info class. + * Can be overwritten by subclasses to construct specialized instances of the plugin info. + * Default implementation constructs a CMPXPluginInfo class. + * + * @since S60 3.2.3 + * @param aData implementation data + */ + IMPORT_C virtual CMPXPluginInfo* ConstructPluginInfoLC( const CImplementationInformation& aData ); + +#ifdef _DEBUG + + /** + * Prints all plugin info entries to the debug log. + * + * @since S60 3.2.3 + */ + void PrintPluginInfo(); + +#endif + +public: + + /** + * Returns display name for plugin with the given type. + * + * @since S60 3.2.3 + * @param aType plugin type. + * @return plugin name. KNullDesC returned if not found. + */ + IMPORT_C const TDesC& PluginName(TInt aPluginType) const; + + /** + * Returns display name for plugin with the given uid. + * + * @since S60 3.2.3 + * @param aUid plugin id + * @return plugin name. KNullDesC returned if not found. + */ + IMPORT_C const TDesC& PluginName(const TUid& aUid) const; + + /** + * Returns a list of display names for the plugins. + * + * @since S60 3.2.3 + * @return an array of display names. Client is responsible + * for the memory management of this array and its + * items. + */ + IMPORT_C CDesCArray* PluginNamesL(); + + /** + * Return a list of mime types supported by plugins. + * + * @since S60 3.2.3 + * @return an array of mime types. Client is responsible + * for the memory management of this array and its + * items. + */ + IMPORT_C CDesCArray* SupportedMimeTypesL(); + + /** + * Return a list of file extensions supported by plugins. + * + * @since S60 3.2.3 + * @return an array of extensions. Client is responsible + * for the memory management of this array and its + * items. + */ + IMPORT_C CDesCArray* SupportedExtensionsL(); + + /** + * Return a list of schemas supported by plugins. + * + * @since S60 3.2.3 + * @return an array of schemas. Client is responsible for + * the memory management of this array and its + * items. + */ + IMPORT_C CDesCArray* SupportedSchemasL(); + + /** + * Return a list of mime types supported by a plugin. + * + * @since S60 3.2.3 + * @param aUid plugin id + * @return an array of mime types. Client is responsible + * for the memory management of this array and its + * items. + */ + IMPORT_C CDesCArray* SupportedMimeTypesL(const TUid& aUid); + + /** + * Return a list of file extensions supported by a plugin. + * + * @since S60 3.2.3 + * @param aUid plugin id + * @return an array of extensions. Client is responsible + * for the memory management of this array and its + * items. + */ + IMPORT_C CDesCArray* SupportedExtensionsL(const TUid& aUid); + + /** + * Get plugin type for a given implementation UID. + * + * @since S60 3.2.3 + * @param aUid plugin's implementation Uid + * @return plugin's type Uid, or KNullUid if not found + */ + IMPORT_C TUid PluginType( const TUid& aUid ) const; + + /** + * Get supported app uid for a given implementation UID + * + * @param aUid plugin's implementation Uid + * @return plugin's supported app Uid, or KNullUid if not found + */ + IMPORT_C TUid SupportedAppUid( const TUid& aUid ) const; + + /** + * Get plugin flag for a given implementation UID. + * + * @since S60 3.2.3 + * @param aUid plugin's implementation Uid + * @return Plugin's flag, or leave with KErrNotFound if not found + * @leave KErrNotFound Uid is not found + */ + IMPORT_C TUint PluginFlagsL( const TUid& aUid ) const; + + /** + * Get currently available plug-in types. + * + * @since S60 3.2.3 + * @param aType contains plugins types + */ + IMPORT_C void GetPluginTypes(RArray& aTypes) const; + + /** + * Get currently available plug-in UIDs. + * + * @since S60 3.2.3 + * @param aUids contains plugin uids + */ + IMPORT_C void GetPluginUids(RArray& aUids) const; + + /** + * All the UIDs of the plug-ins in the system of a specific type. + * + * @since S60 3.2.3 + * @param aPlugins OUT parameter. Array of UIDs of all plugins of type + * aPluginType. Client is responsible for the memory + * management of this RArray. + * @param aPluginType IN parameter. Plugin type + */ + IMPORT_C void GetPluginUidsL(RArray& aPlugins, + TInt aPluginType) const; + + /** + * Returns the UID of the plugin with the specified display name. + * + * @since S60 3.2.3 + * @param aPluginName a plugin's display name + * @return UID of the plugin. KNullUid is returned if there is no + * plugin by that name. + */ + IMPORT_C TUid PluginUid(const TDesC& aPluginName) const; + + /** + * Returns the index of the specified plugin. + * + * @param aPluginUid UID of the plugin to search for + * @return index of the specified plugin in CMPXPluginMonitor's 3 + * arrays, iPluginsInfo, iPluginUids, and iPluginTypes. + * KErrNotFound, if no matching object can be found. + */ + IMPORT_C TInt IndexOf(const TUid& aPluginUid) const; + + /** + * Create a list of plugins. + * + * @since S60 3.2.3 + */ + IMPORT_C void CreatePluginListL(); + + /** + * Check if the plugin supports the array of uids. + * + * @since S60 3.2.3 + * @param aPluginId plugin id + * @param aUids contains plugin uids + * @return ETrue if plugin supports all uids + */ + IMPORT_C TBool SupportUids(const TUid& aPluginId, + const TArray& aUids) const; + + /** + * Find a plugin with matches the array of uids the best. + * + * @since S60 3.2.3 + * @param aUids contains plugin uids + * @return Implementation id of collection plugin, + * KNullUidValue will be returned if no plugin found + */ + IMPORT_C TUid FindPlugin(const TArray& aUids) const; + +protected: + MMPXPluginHandlerObserver& iObserver; // observer + TUid iInterfaceUid; // plugin interface Uid + CMPXPluginMonitor* iPluginMonitor; + RPointerArray iPluginInfoArray; // Ordered by priority + TBool iOwnedPluginMonitor; + + // + // Selection parameters + // + TPluginSelection iSelection; + TInt iSelectedType; + TUid iSelectedUid; + + // + // Resolution parameters + // + HBufC8* iDataType; + HBufC8* iScheme; + HBufC8* iExt; + }; + +#endif // CMPXPLUGINHANDLERBASE_H