--- /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 <ecom/ecom.h>
+#include <badesca.h>
+#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<TInt>& aTypes) const;
+
+ /**
+ * Get currently available plug-in UIDs.
+ *
+ * @since S60 3.2.3
+ * @param aUids contains plugin uids
+ */
+ IMPORT_C void GetPluginUids(RArray<TUid>& 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<TUid>& 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<TUid>& 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<TUid>& aUids) const;
+
+protected:
+ MMPXPluginHandlerObserver& iObserver; // observer
+ TUid iInterfaceUid; // plugin interface Uid
+ CMPXPluginMonitor* iPluginMonitor;
+ RPointerArray<CMPXPluginInfo> 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