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:  Encapsulates a 'playlist' from a collection

    15 *

    16 */

    17 

    18  

    19 

    20 #ifndef CMPXCOLLECTIONPLAYLIST_H

    21 #define CMPXCOLLECTIONPLAYLIST_H

    22 

    23 #include <s32strm.h>

    24 #include <mpxattribute.h>

    25 #include <mpxcollectionobserver.h>

    26 

    27 class CMPXCollectionPath;

    28 class MMPXCollectionUtility;

    29 class RReadStream;

    30 class MMPXCollectionPlaylistObserver;

    31 class CMPXCollectionOpenUtility;

    32 /**

    33  *  Encapsulates a playlist

    34  *

    35  *  @lib mpxcollectionutility.lib

    36  */

    37 class CMPXCollectionPlaylist : public CBase, public MMPXCollectionObserver

    38     {

    39 public: // Data type    

    40     enum TRepeatMode

    41         {

    42         ERepeatOff, // No repeat

    43         ERepeatOne, // Play one track over and over again

    44         ERepeatAll  // Repeat the whole play list

    45         };

    46 public:

    47 

    48    /**

    49     *  Two-phase constructor.

    50     *

    51     *  @since S60 3.2.3

    52     */

    53     IMPORT_C static CMPXCollectionPlaylist* NewL();

    54 

    55    /**

    56     *  Two-phase constructor.

    57     *

    58     *  @since S60 3.2.3

    59     *  @param aPlaylist reference to an existing playlist

    60     *  @param aPlObs playlist observer

    61     *  @return object created

    62     */

    63     IMPORT_C static CMPXCollectionPlaylist* NewL(

    64                                 const CMPXCollectionPlaylist& aPlaylist,

    65                                 MMPXCollectionPlaylistObserver* aPlObs = NULL);

    66 

    67     /**

    68      *  Two-phase constructor.

    69      *

    70      *  @since S60 3.2.3

    71      *  @param aPath reference to a collection path

    72      *  @param aPlObs playlist observer

    73      *  @return object created

    74      */

    75     IMPORT_C static CMPXCollectionPlaylist* NewL(

    76                                 const CMPXCollectionPath& aPath,

    77                                 MMPXCollectionPlaylistObserver* aPlObs = NULL);

    78 

    79     /**

    80      *  Two-phase constructor.

    81      *

    82      *  @since S60 3.2.3

    83      *  @param aStream reference to a collection path

    84      *  @param aPlObs playlist observer

    85      *  @return object created

    86      */

    87     IMPORT_C static CMPXCollectionPlaylist* NewL(

    88                                   RReadStream& aStream,

    89                                   MMPXCollectionPlaylistObserver* aPlObs = NULL);

    90 

    91     /**

    92      *  Destructor.

    93      *

    94      *  @since S60 3.2.3

    95      */

    96     IMPORT_C virtual ~CMPXCollectionPlaylist();

    97     

    98 public: //Iterate through the playlist

    99 

   100     /**

   101      *  Copy content from other playlist.

   102      *

   103      *  @since S60 3.2.3

   104      *  @param aPlaylist reference to an existing playlist

   105      */

   106     IMPORT_C void CopyContentL(const CMPXCollectionPlaylist& aPlaylist);

   107     

   108     /**

   109      *  Next item.

   110      *

   111      *  @since S60 3.2.3

   112      *  @param aIgnoreRepeat ETrue to ignore repeat setting

   113      *  @return ETrue if exists

   114      */

   115     IMPORT_C TBool Next( TBool aIgnoreRepeat=EFalse );

   116 

   117     /**

   118      *  Gets the next index to play.  This method should not change

   119      *  any of the internal index values (const method).

   120      *

   121      *  @since S60 3.2.3

   122      *  @param aIgnoreRepeat ETrue to ignore repeat setting

   123      *  @param aPlaylistIndex Out Parameter - The next index. KErrNotFound if no valid index.

   124      *                                - This is the index in the playlist order.

   125      *  @return ETrue if exists

   126      */

   127     IMPORT_C TBool NextIndex( 

   128         TBool aIgnoreRepeat, 

   129         TInt& aPlaylistIndex ) const;

   130 

   131     /**

   132      *  Gets the path index of the item given it's position in the playlist.

   133      *

   134      *  @since S60 3.2.3

   135      *  @param aPlaylistIndex Index of item in the playlist

   136      *  @return The index of the item in the path

   137      */

   138     IMPORT_C TInt PathIndex( TInt aPlaylistIndex ) const;

   139 

   140     /**

   141      *  Previous item.

   142      *

   143      *  @since S60 3.2.3

   144      *  @param aIgnoreRepeat ETrue to ignore repeat setting

   145      *  @return ETrue if exists    

   146      */

   147     IMPORT_C TBool Previous( TBool aIgnoreRepeat=EFalse );

   148     

   149     /**

   150      *  Go to the first item.

   151      *

   152      *  @since S60 3.2.3

   153      */

   154     IMPORT_C void SetToFirst();

   155 

   156     /**

   157      *  Go to the last item.

   158      *

   159      *  @since S60 3.2.3

   160      */

   161     IMPORT_C void SetToLast();

   162     

   163     /**

   164      * Go to a particular item.

   165      *

   166      * @since S60 3.2.3

   167      * @param aIndex index to goto

   168      *               The index can be -1 for no selection and must be

   169      *               Smaller than the number of items in the playlist

   170      */

   171     IMPORT_C void CMPXCollectionPlaylist::SetToIndex( TInt aIndex );

   172     

   173 public: // State information   

   174     /**

   175      * Number of items.

   176      *

   177      * @since S60 3.2.3

   178      * @return the number of items

   179      */

   180     IMPORT_C TInt Count() const;

   181     

   182     /**

   183      * Depth of the playlist.

   184      *

   185      * @since S60 3.2.3

   186      * @return the depth

   187      */

   188     IMPORT_C TInt Levels() const;

   189     

   190     /**

   191      * Index to current item in the playlist.

   192      *

   193      * @since S60 3.2.3

   194      * @return the index

   195      */

   196     IMPORT_C TInt Index() const;

   197 

   198     /**

   199      * Remote playlist.

   200      *

   201      * @since S60 3.2.3

   202      * @return ETrue remote, EFalse local

   203      */

   204     IMPORT_C TBool Remote() const;

   205 

   206     /**

   207      * Repeat mode.

   208      *

   209      * @since S60 3.2.3

   210      * @return the repeat mode

   211      */

   212     IMPORT_C TRepeatMode RepeatMode() const;

   213 

   214     /**

   215      * Shuffle mode.

   216      *

   217      * @since S60 3.2.3

   218      * @return ETrue shuffle on, EFalse shuffle off

   219      */

   220     IMPORT_C TBool Shuffle() const; 

   221 

   222     /**

   223      * Get collection path.

   224      *

   225      * @since S60 3.2.3

   226      * @return collection path

   227      */

   228     IMPORT_C const CMPXCollectionPath& Path() const;

   229     

   230     /**

   231      * Get extended media of current item.

   232      *

   233      * @since S60 3.2.3

   234      * @param aAttrs attributes requested

   235      * @param aMediaObs properties observer

   236      */    

   237     IMPORT_C void MediaL(const TArray<TMPXAttribute>& aAttrs,

   238                          MMPXCollectionMediaObserver& aMediaObs);

   239     

   240     /**

   241      * Set repeat mode.

   242      *

   243      * @since S60 3.2.3

   244      * @param aMode the repeat mode

   245      */

   246     IMPORT_C void SetRepeatMode(TRepeatMode aMode); 

   247 

   248     /**

   249      * Set repeat enabled.

   250      *

   251      * @since S60 3.2.3

   252      * @param aEnable To enable repeat mode or not

   253      */

   254     IMPORT_C void SetRepeatEnabled( TBool aEnable ); 

   255 

   256     /**

   257      * Turn shuffle mode on/off.

   258      *

   259      * @since S60 3.2.3

   260      * @param aShuffle new shuffle mode

   261      * @param aCurrentToTop move current item to the top

   262      */

   263     IMPORT_C void SetShuffleL(TBool aShuffle, TBool aCurrentToTop);

   264     

   265     /**

   266      * Set shuffle enabled.

   267      *

   268      * @since S60 3.2.3

   269      * @param aEnable To enable shuffle mode or not

   270      */

   271     IMPORT_C void SetShuffleEnabledL( TBool aEnable );

   272     

   273     /**

   274      * Externalize an object of this class to stream.

   275      *

   276      * @since S60 3.2.3

   277      * @param aStream write stream

   278      */

   279     IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   280     

   281     /**

   282      * Internalize an object of this class from stream.

   283      *

   284      * @since S60 3.2.3

   285      * @param aStream read stream

   286      */

   287     IMPORT_C void InternalizeL(RReadStream& aStream);

   288     

   289     /**

   290      * Set a new observer for current request.

   291      * Used when handling pre-initializing.

   292      *

   293      * @since S60 3.2.3

   294      * @param aMediaObs properties observer

   295      * @param aPlObs playlist observer

   296      * @param aCollectionObs collection observer

   297      */    

   298     IMPORT_C void SetObserver(MMPXCollectionMediaObserver& aMediaObs,

   299                               MMPXCollectionPlaylistObserver* aPlObs = NULL,

   300                               MMPXCollectionObserver* aCollectionObs = NULL);

   301     

   302     /**

   303      * Is this playlist launched from embedded mode.

   304      *

   305      * @since S60 3.2.3

   306      * @return ETrue if embedded mode

   307      */

   308     IMPORT_C TBool EmbeddedPlaylist() const;

   309     

   310     /**

   311      * Set or clear the embedded playlist flag.

   312      *

   313      * @since S60 3.2.3

   314      * @param aEmbedded is this playlist embedded?

   315      */

   316     IMPORT_C void SetEmbeddedPlaylist( TBool aEmbedded );

   317     

   318     /**

   319      *  Sets/updates the media for the item provided.

   320      *

   321      *  @since S60 3.2.3

   322      *  @param aMedia new value

   323      *  Callback via EMediaChanged message if currently opened

   324      */

   325     IMPORT_C void SetL( const CMPXMedia& aMedia );

   326     

   327     /**

   328      *  Stops any async operations that are currently under way.

   329      *

   330      *  @since S60 3.2.3

   331      */

   332     IMPORT_C void CancelRequest(); 

   333     

   334     /**

   335      *  Invalidate the playlist.

   336      *  

   337      */

   338     IMPORT_C void Invalidate();

   339     

   340     /**

   341      * AutoPlay

   342      *  

   343      * @since S60 TB9.2

   344      * @return the auto play value

   345      */

   346     IMPORT_C TBool AutoPlay() const;

   347     

   348     /**

   349      * Set auto play.

   350      * 

   351      * @since S60 TB9.2

   352      * @param aAutoPlay new value

   353      */

   354     IMPORT_C void SetAutoPlay(TBool aAutoPlay);

   355     

   356     

   357      /**

   358      * Single item playlist.

   359      *

   360      * @since S60 TB9.2

   361      * @return ETrue for single item, EFalse if not

   362      */

   363      IMPORT_C TBool IsSingleItemPlaylist();

   364     

   365     

   366     /**

   367      * Set single item playlist.

   368      *

   369      * @since S60 TB9.2

   370      */

   371      IMPORT_C void SetSingleItemPlaylist();

   372      

   373      /**

   374      * Pre-initialize next plugin.

   375      *

   376      * @since S60 TB9.2

   377      * @return ETrue for pre-init, EFalse if not

   378      */

   379      IMPORT_C TBool PreInitPlugin() const;

   380 

   381      /**

   382       * Set pre-initialize next plugin.

   383       *

   384       * @since S60 TB9.2

   385       * @param aPreInit new value

   386       */

   387       IMPORT_C void SetPreInitPlugin(TBool aPreInitPlugin);

   388       

   389 private:  // From base class

   390     /**

   391      *  Handle media.

   392      *  From MMPXCollectionObserver / MMPXCollectionMediaObserver.

   393      *

   394      *  @since S60 3.2.3

   395      *  @param aMedia media properties

   396      *  @param aError error code

   397      */

   398     void HandleCollectionMediaL(const CMPXMedia& aMedia, TInt aError);

   399                                    

   400     /**

   401      *  Handle collection message.

   402      *  From MMPXCollectionObserver

   403      *

   404      *  @since S60 3.2.3

   405      *  @param aMessage collection message

   406      *  @param aErr system error code.

   407      */

   408     void HandleCollectionMessage(CMPXMessage* aMessage, TInt aErr);

   409 

   410     /**

   411      *  Handles the collection entries being opened. Typically called

   412      *  when client has Open()'d a folder.

   413      *  From MMPXCollectionObserver    

   414      *

   415      *  @since S60 3.2.3

   416      *  @param aEntries collection entries opened

   417      *  @param aIndex focused entry

   418      *  @param aComplete ETrue no more entries. EFalse more entries

   419      *                   expected

   420      *  @param aError error code   

   421      */

   422     void HandleOpenL(const CMPXMedia& aEntries,

   423                      TInt aIndex,TBool aComplete,TInt aError);

   424     

   425     /**

   426      *  Handles the item being opened. 

   427      *  Typically called when client has Open()'d an item. Client typically 

   428      *  responds by 'playing' the item via the playlist

   429      *  From MMPXCollectionObserver    

   430      *

   431      *  @since S60 3.2.3

   432      *  @param aPlaylist collection playlist

   433      *  @param aError error code   

   434      */                         

   435     void HandleOpenL(const CMPXCollectionPlaylist& aPlaylist,TInt aError);

   436 

   437 private:

   438 

   439     /**

   440      *  Restore ordinal after changes.

   441      *  

   442      *  @since S60 3.2.3

   443      *  @param aEntries collection entries opened

   444      *  @param aIndex index of current item 

   445      *  @leave IfNull 

   446      */

   447     void RestoreOrdinalL(const CMPXMedia& aEntries, TInt aIndex);

   448     

   449     /**

   450      *  Handle collection message.

   451      *

   452      *  @since S60 3.2.3

   453      *  @param aMessage collection message

   454      *  @param aErr system error code.

   455      *  @leave IfNull

   456      */

   457     void DoHandleCollectionMessageL(CMPXMessage* aMessage, TInt aErr);

   458 

   459     /**

   460      * Handle a CMPXCollection message with a change event.

   461      *

   462      * @since S60 3.2.3

   463      * @param aMessage single collection message to handle

   464      * @return ETrue if a re-open is needed, EFalse otherwise

   465      */

   466     TBool DoHandleCollectionChangeMessageL(CMPXMessage& aMessage);

   467     

   468     /**

   469      * Handle starting of fetch for incremental algorithm.

   470      *

   471      * @since S60 3.2.3

   472      */

   473     void DoIncrementalOpenL();

   474     

   475     /**

   476      * Do Restore Ordinal for incremental opens.

   477      *

   478      * @since S60 3.2.3

   479      * @param aMedia media returned from collection

   480      * @param aComplete OpenL Completed or not

   481      */

   482     void DoHandleIncompleteOpenL( const CMPXMedia& aMedia, TBool aComplete);

   483         

   484 private:

   485     

   486     /**

   487      *  C++ default constructor.

   488      *  content not constructed yet, it may be internalized from buffer

   489      *

   490      *  @since S60 3.2.3

   491      *  @param aPlObs playlist observer

   492      */

   493     CMPXCollectionPlaylist(MMPXCollectionPlaylistObserver* aPlObs);

   494     

   495     /**

   496      * 2nd phase constructor.

   497      *

   498      * @since S60 3.2.3

   499      * @param aPath collection path

   500      */

   501     void ConstructL(const CMPXCollectionPath& aPath);

   502                                    

   503     /**

   504      * 2nd phase constructor.

   505      *

   506      * @since S60 3.2.3

   507      * @param aPlaylist playlist

   508      */

   509     void ConstructL(const CMPXCollectionPlaylist& aPlaylist);

   510     

   511     /**

   512      * 2nd phase contructor.

   513      *

   514      * @since S60 3.2.3

   515      * @param aStream stream

   516      */

   517     void ConstructL(RReadStream& aStream);

   518 

   519     /**

   520      * 2nd phase contructor.

   521      *

   522      *  @since S60 3.2.3

   523      */

   524     void ConstructL();

   525     

   526 private:

   527     TRepeatMode iRepeatMode;

   528     TBool iShuffle;

   529     TBool iRemote;

   530     CMPXCollectionPath* iPath;

   531     RArray<TInt> iItemIndexes; // Indexes which define playlist items

   532     TInt iItemIndex; // current index to iItemIndexes array

   533     MMPXCollectionUtility* iColUtil;

   534     MMPXCollectionMediaObserver* iMediaObs;

   535     MMPXCollectionObserver* iCollectionObs;

   536     TBool iEmbedded;

   537     MMPXCollectionPlaylistObserver* iPlObs; 

   538     TBool iRepeatEnabled;

   539     TBool iShuffleEnabled;

   540     CMPXCollectionOpenUtility* iIncOpenUtil;

   541     TBool iReopenForChange;

   542     TBool iAutoPlaylist;

   543     TBool iAutoPlay; // Automatically play next item in playlist if in playing state. Default to TRUE for Music Player.

   544     TBool iSingleItemPlaylist;

   545     TBool iPreInitPlugin;

   546     };

   547 

   548 #endif // CMPXCOLLECTIONPLAYLIST_H