/*

* 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