1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  playlist plugin handler

    15 *

    16 */

    17 

    18 

    19 #ifndef MPXPLAYLISTPLUGINHANDLER_H

    20 #define MPXPLAYLISTPLUGINHANDLER_H

    21 

    22 #include <ecom/ecom.h>

    23 #include <mpxpluginhandlerbase.h>

    24 #include "mpxplaylistenginedefs.h"

    25 #include "mpxplaylistplugin.h"

    26 

    27 /**

    28 *   CMPXPlaylistPluginHandler is instantiated and owned by CMPXPlaylistEngine.

    29 *   It provides playlist plugin selection APIs for the external client and

    30 *   the internal client (i.e. CMPXPlaylistEngine) and manages loading and

    31 *   unloading of playlist plugins. A plugin is loaded when selected and

    32 *   unloaded when the plugin has been uninstalled or when CMPXPlaylistEngine

    33 *   is destroyed (CMPXPlaylistEngine destroys CMPXPlaylistPluginHandler when

    34 *   itself is destroyed).

    35 *

    36 *   @lib mpxplaylistengine.lib

    37 */

    38 class CMPXPlaylistPluginHandler : public CMPXPluginHandlerBase

    39     {

    40 public:

    41 

    42     /**

    43     *  Two-phased constructor.

    44     *

    45     *  @since S60 3.2.3

    46     *  @param aPluginObserver playlist plugin observer

    47     *  @param aObserver plugin handler observer

    48     *  @param aFs file session handle

    49     *  @param aTopCharacterSet top character set for the locale

    50     *  @param aAvailableCharacterSet available character set in the system

    51     *  @return Constructed object

    52     */

    53     IMPORT_C static CMPXPlaylistPluginHandler* NewL(

    54         MMPXPlaylistPluginObserver& aPluginObserver,

    55         MMPXPluginHandlerObserver& aObserver,

    56         RFs& aFs,

    57         const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>& aTopCharacterSet,

    58         const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>& aAvailableCharacterSet);

    59 

    60     /**

    61     *  Destructor.

    62     *

    63     *  @since S60 3.2.3

    64     */

    65     ~CMPXPlaylistPluginHandler();

    66 

    67     /**

    68     *  Returns currently loaded plug-in UID, or KNullUid if none loaded.

    69     *

    70     *  @since S60 3.2.3

    71     *  @return UID of the plugin

    72     */

    73     inline TUid PluginUid() const;

    74 

    75     /**

    76     *  Returns currently loaded plug-in type or EMPXPlaylistTypeUnknown if

    77     *  no plugin is loaded.

    78     *

    79     *  @since S60 3.2.3

    80     *  @return plugin type Refer to TMPXPlaylistType for the representation

    81     *                      of each bit of the return value

    82     */

    83     inline TUint32 PluginType() const;

    84 

    85     /**

    86     *  Returns display name for current plug-in or KNullDesC if no plugin

    87     *  is loaded.

    88     *

    89     *  @since S60 3.2.3

    90     *  @return plugin name.

    91     */

    92     inline const TDesC& PluginName() const;

    93 

    94     /**

    95     *  Is a plug-in currently loaded.

    96     *

    97     *  @since S60 3.2.3

    98     *  @return ETrue if a plugin is loaded; EFalse otherwise.

    99     */

   100     inline TBool PluginFound() const;

   101 

   102     /**

   103     *  Returns currently loaded plug-in, or NULL if none. CMPXPlaylistPluginHandler

   104     *  is responsible for the memory management of the return playlist plugin

   105     *  object.

   106     *

   107     *  @since S60 3.2.3

   108     *  @return plugin object interface

   109     */

   110     inline CMPXPlaylistPlugin* Plugin() const;

   111 

   112     /**

   113     *  Selects a plug-in appropriate for a Uri and data type; may already be loaded.

   114     *  If the selected plug-in has not been loaded before, one is instantiated.

   115     *

   116     *  If successful, information related to the currently loaded plugin will reflect

   117     *  this selected plug-in. Leaves with KErrNotSupported if unable to find a

   118     *  suitable plugin.

   119     *

   120     *  @since S60 3.2.3

   121     *  @param aUri URI of the song

   122     *  @param aDataType data type. KNullDesC8 if this parameter is not to be used

   123     *                   for selection.

   124     */

   125     IMPORT_C void SelectPlaylistPluginL(

   126                     const TDesC& aUri,

   127                     const TDesC8& aDataType);

   128 

   129     /**

   130     *  Selects a plug-in appropriate for a file; may already be loaded. If the

   131     *  selected plug-in has not been loaded before, one is instantiated.

   132     *

   133     *  If successful, information related to currently loaded plugin will reflect

   134     *  this selected plug-in. Leaves with KErrNotSupported if unable to find a

   135     *  suitable plugin.

   136     *

   137     *  @since S60 3.2.3

   138     *  @param aFile file handle

   139     */

   140     IMPORT_C void SelectPlaylistPluginL(const RFile& aFile);

   141 

   142     /**

   143     *  Selects a plugin appropriate for the plugin type; may already be loaded.

   144     *  If the selected plugin has not been loaded before, one is instantiated.

   145     *

   146     *  If successful, information related to currently loaded plugin will reflect

   147     *  this selected plug-in. Leaves with KErrNotSupported if unable to find a

   148     *  suitable plugin.

   149     *

   150     *  This is the recommended method for the client to select a plugin prior

   151     *  to issuing an ExternalizePlaylist request.

   152     *

   153     *  @since S60 3.2.3

   154     *  @param aPluginType A plugin type, possible values are defined in

   155     *                    TMPXPlaylistType.

   156     */

   157     IMPORT_C void SelectPlaylistPluginL(TUint32 aPluginType);

   158 

   159     /**

   160     *  Selects a plugin with the specified display name; may already be loaded.

   161     *  If the selected plugin has not been loaded before, one is instantiated.

   162     *

   163     *  If successful, information related to currently loaded plugin will reflect

   164     *  this selected plug-in. Leaves with KErrNotSupported if unable to find

   165     *  a suitable plugin.

   166     *

   167     *  This is not the recommended method for the client to select a plugin

   168     *  prior to issuing an ExternalizePlaylist request. The recommended

   169     *  method is through a plugin type.

   170     *

   171     *  @since S60 3.2.3

   172     *  @param aPluginName The name of the plugin to be selected.

   173     */

   174     IMPORT_C void SelectPlaylistPluginL(const TDesC& aPluginName);

   175 

   176     /**

   177     *  Selects a plug-in with UID aUid, or leaves with KErrNotSupported if not

   178     *  found. If the selected plugin has not been loaded before, one is

   179     *  instantiated.

   180     *

   181     *  If successful, information related to currently loaded plugin will reflect

   182     *  this selected plug-in. Leaves with KErrNotSupported if unable to find

   183     *  the specified plugin.

   184     *

   185     *  @since S60 3.2.3

   186     *  @param aUid UID of the plugin

   187     */

   188     IMPORT_C void SelectPlaylistPluginL(const TUid& aUid);

   189 

   190 private:

   191 

   192     /**

   193     *  C++ constructor.

   194     *

   195     *  @since S60 3.2.3

   196     *  @param aPluginObserver playlist plugin observer

   197     *  @param aObserver plugin handler observer

   198     *  @param aFs file session handle

   199     *  @param aTopCharacterSet top character set for the locale

   200     *  @param aAvailableCharacterSet available character set in the system

   201     */

   202     CMPXPlaylistPluginHandler(

   203         MMPXPlaylistPluginObserver& aPluginObserver,

   204         MMPXPluginHandlerObserver& aObserver,

   205         RFs& aFs,

   206         const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>& aTopCharacterSet,

   207         const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>& aAvailableCharacterSet);

   208 

   209     /**

   210     *  2nd phase contructor.

   211     *

   212     *  @since S60 3.2.3

   213     */

   214     void ConstructL();

   215 

   216     /**

   217     *  Creates a plugin. If already loaded, returns a reference without creating

   218     *  another instance of the plugin.

   219     *

   220     *  @since S60 3.2.3

   221     *  @return plugin object interface

   222     *  @leave The function leaves with one of the system error codes,

   223     */

   224     CMPXPlaylistPlugin* CreatePlaylistPluginL(const TUid& aUid);

   225 

   226     /**

   227     *  From CMPXPluginHandlerBase.

   228     *  Resolves plugin.

   229     *

   230     *  @since S60 3.2.3

   231     */

   232     void ResolvePluginL();

   233 

   234     /**

   235     * Verify the specified plugin is loaded.

   236     *

   237     * @see CMPXPluginHandlerBase

   238     *

   239     * @since S60 3.2.3

   240     */

   241     TBool IsPluginLoaded(const TUid& aPluginUid);

   242 

   243     /**

   244     * Load the specified plugin.

   245     * @see CMPXPluginHandlerBase

   246     *

   247     * @since S60 3.2.3

   248     */

   249     void LoadPluginL(const TUid& aPluginUid);

   250 

   251     /**

   252     * Unload the specified plugin.

   253     * @see CMPXPluginHandlerBase

   254     *

   255     * @since S60 3.2.3

   256     */

   257     void UnloadPlugin(const TUid& aPluginUid);

   258 

   259     /**

   260     * Unloads a plugin by index.

   261     * @since S60 3.2.3

   262     * @param aIndex index of the plugin to unload

   263     *

   264     */

   265     void UnloadPlugin(TInt aIndex);

   266 

   267 private:

   268 

   269     MMPXPlaylistPluginObserver&         iPluginObserver;

   270     RFs&                                iFs;

   271     const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>& iTopCharacterSet;

   272     const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>& iAvailableCharacterSet;

   273 

   274     //

   275     // Loaded. The index must correspond in these arrays

   276     //

   277     RPointerArray<CMPXPlaylistPlugin>   iLoadedPlugins;

   278     RArray<TUid>                        iLoadedPluginsUids;

   279 

   280     //

   281     // Chosen

   282     //

   283     CMPXPlaylistPlugin*                 iPlugin;     // ownership belongs to iLoadedPlugins

   284     TUid                                iPluginUid;

   285     TUint32                             iPluginType;

   286     HBufC*                              iDisplayName;

   287 

   288     };

   289 

   290 #include "mpxplaylistpluginhandler.inl"

   291 

   292 #endif // MPXPLAYLISTPLUGINHANDLER_H