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 interface

    15 *

    16 */

    17 

    18 

    19 #ifndef MPXPLAYLISTPLUGIN_H

    20 #define MPXPLAYLISTPLUGIN_H

    21 

    22 #include <ecom/ecom.h>

    23 #include <charconv.h>

    24 #include <mpxmedia.h>

    25 

    26 // FORWARD DECLARATIONS

    27 class MMPXPlaylistPluginObserver;

    28 

    29 /**

    30 *  CMPXPlaylistPlugin: Defines the playlist plugin interface.

    31 *

    32 *  A playlist plugin is instantiated and owned by CMPXPlaylistPluginHandler.

    33 *  But the client of the services a playlist plugin provides is

    34 *  CMPXPlaylistEngine.

    35 *

    36 */

    37 NONSHARABLE_CLASS(CMPXPlaylistPlugin): public CBase

    38     {

    39 

    40 public:

    41 

    42     /**

    43     * Factory method to instantiate a playlist plugin with the matching UID

    44     *

    45     * @param aUid uid of interface implementation

    46     * @param aObserver a playlist plugin observer

    47     * @param aFs a handle to file session

    48     * @param aTopCharacterSet top character set for the current locale

    49     * @param aAvailableCharacterSet available character set in the sytem

    50     * @return constructed object

    51     */

    52     inline static CMPXPlaylistPlugin* NewL(

    53         TUid aUid, 

    54         MMPXPlaylistPluginObserver& aObserver,

    55         RFs& aFs,

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

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

    58 

    59     /**

    60     * Destructor

    61     */

    62     virtual ~CMPXPlaylistPlugin();

    63     

    64 public: 

    65 

    66     /** 

    67     * Internalize a playlist. A MMPXPlaylistPluginObserver::HandlePlaylistL

    68     * callback will be generated on completion.

    69     *

    70     * Parameters are guaranteed by the caller (i.e. CMPXPlaylistEngine) to

    71     * exist until plugin completes this request.

    72     *

    73     * @param aStatus caller's request status

    74     * @param aPlaylistUri URI of the playlist to be internalized

    75     */

    76     virtual void InternalizePlaylistL(

    77         TRequestStatus& aStatus,

    78         const TDesC& aPlaylistUri) = 0;

    79 

    80     /** 

    81     * Externalize a playlist. a MMPXPlaylistPluginObserver::HandlePlaylistL

    82     * callback will be generated on completion.

    83     *

    84     * Parameters are guaranteed by the caller (i.e. CMPXPlaylistEngine) to

    85     * exist until plugin completes this request.

    86     *

    87     * @param aStatus caller's request status

    88     * @param aPlaylist a playlist to be externalized. This media contains

    89     *        the following attributes:

    90     *

    91     *            KMPXMediaGeneralTitle

    92     *            KMPXMediaGeneralType:

    93     *               This contains the value of EMPXItem

    94     *            KMPXMediaGeneralCategory:

    95     *               This contains the value of EMPXPlaylist

    96     *            KMPXMediaArrayContents

    97     *            KMPXMediaArrayCount

    98     *

    99     *        Each media item in the playlist is guaranteed to contain the

   100     *        following attributes:

   101     *

   102     *            KMPXMediaGeneralType:

   103     *               This contains the value of EMPXItem

   104     *            KMPXMediaGeneralCategory:

   105     *               This contains the value of EMPXSong

   106     *

   107     *            The rest of attributes may or may not be present. Client

   108     *            is recommended to call RequiredAttributes before making

   109     *            a request to export the playlist and provide attributes

   110     *            required for each media item in the playlist. However,

   111     *            not every client will be able to comply and supply the

   112     *            required attributes, specifically client may store the

   113     *            information about the media item in a memory card and

   114     *            memory card has been removed from the device. Each

   115     *            playlist plugin MUST be capable of handling the media

   116     *            item containing only the URI in addition to its type and

   117     *            category.

   118     *

   119     * @param aFilePath File path for where the playlist should be placed

   120     */

   121     virtual void ExternalizePlaylistL(

   122         TRequestStatus& aStatus,

   123         const CMPXMedia& aPlaylist,

   124         const TDesC& aFilePath) = 0;

   125 

   126     /**

   127     * Required attributes for the media items in the playlist in order to

   128     * externalize them to a playlist. Client is recommended to call this

   129     * method and provide the required attributes for each media item in

   130     * the playlist before externalizing the playlist.

   131     *

   132     * @return an array of attributes required in order to externalize

   133     * a playlist media into a playlist file.

   134     */

   135     virtual const TArray<TMPXAttribute> RequiredAttributes() const = 0;

   136 

   137     /**

   138     * Optional attributes for the media items in the playlist for externalizing

   139     * them to a playlist.

   140     *

   141     * @return an array of attributes which are optional when externalizing

   142     * a playlist media into a playlist file

   143     */

   144     virtual const TArray<TMPXAttribute> OptionalAttributes() const = 0;

   145     

   146     /**

   147     * Returns the file extension the plugin handles

   148     *

   149     * @return file extension which includes the period.

   150     */

   151     virtual const TDesC& FileExtension() const = 0;

   152 

   153     /**

   154     * Cancel request

   155     */        

   156     virtual void Cancel() = 0;

   157     

   158 protected:

   159 

   160     MMPXPlaylistPluginObserver*  iObserver; // not owned

   161     RFs*                         iFs;       // not owned

   162     const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>* iTopCharacterSet;      // not owned

   163     const CArrayFix<CCnvCharacterSetConverter::SCharacterSet>* iAvailableCharacterSet;// not owned

   164 

   165 private:

   166 

   167     // identifies the actual plugin instance

   168     TUid iDtorKey;

   169     };

   170 

   171 #include "mpxplaylistplugin.inl"

   172 

   173 #endif      // MPXPLAYLISTPLUGIN_H

   174 

   175