1 /**

     2  * Copyright (c) 2010 Sasken Communication Technologies Ltd.

     3  * All rights reserved.

     4  * This component and the accompanying materials are made available

     5  * under the terms of the "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  * Chandradeep Gandhi, Sasken Communication Technologies Ltd - Initial contribution

    11  *

    12  * Contributors:

    13  * Manasij Roy, Nalina Hariharan

    14  *

    15  * Description:

    16  * Music related services

    17  *

    18  */

    19 

    20 #ifndef SMFMUSIC_H

    21 #define SMFMUSIC_H

    22 

    23 #include <qmobilityglobal.h>

    24 #include <qgeopositioninfo.h>

    25 #include "smfglobal.h"

    26 #include "smfprovider.h"

    27 #include "smfcontact.h"

    28 #include "smfevent.h"

    29 #include "smfmusicfingerprint.h"

    30 #include "smfmusicrating.h"

    31 #include "smfcomment.h"

    32 #include "smfsubtitle.h"

    33 

    34 #include "smfmusicprofile.h"

    35 #include "smfalbum.h"

    36 #include "smfartists.h"

    37 #include "smfgroup.h"

    38 #include "smflyrics.h"

    39 #include "smfplaylist.h"

    40 #include "smftrackinfo.h"

    41 #include "smflocation.h"

    42 class SmfMusicServicePrivate;

    43 class SmfMusicSearchPrivate;

    44 class SmfLyricsServicePrivate;

    45 class SmfPlaylistServicePrivate;

    46 class SmfMusicEventsPrivate;

    47 

    48 using namespace QtMobility;

    49 

    50 typedef QList<SmfMusicProfile> SmfMusicProfileList;

    51 typedef QList<SmfTrackInfo> SmfTrackInfoList;

    52 typedef QList<SmfPlaylist> SmfPlaylistList;

    53 typedef QList<SmfLyrics> SmfLyricsList;

    54 typedef QList<SmfSubtitle> SmfSubtitleList;

    55 /**

    56  * @ingroup smf_client_group

    57   * Basic music service ("org.symbian.smf.client.music.service")

    58   */

    59 class SMFCLIENT_EXPORT SmfMusicService : public QObject

    60 {

    61   Q_OBJECT

    62 

    63 public:

    64   /**

    65    * Constructs SmfMusicService.

    66    * @param baseProvider The base provider info

    67    * Seeing as this is a plug-in implementation, these will realistically

    68    *  be generated by SMF factory of some kind

    69    */

    70    SmfMusicService(SmfProvider* baseProvider = 0);

    71   ~SmfMusicService();

    72 

    73 public slots:

    74 

    75   /**

    76    * Gets self profile information asynchronously.

    77    * userInfoAvailable() signal is emitted with SmfMusicProfile when the info is arrived

    78    */

    79   void userinfo() ;

    80 

    81   /**

    82    * Asynchronously searches information about other service users for a particular venue

    83    * searchInfoAvailable() signal is emitted with SmfMusicProfileList when the info is arrived.

    84    * When the list is big user can specify the page number and per page item data.

    85    * If not supplied by the user default values are used.

    86    * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query.

    87    * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE

    88    */

    89   void searchUser(SmfLocation venue,int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE) ;

    90 

    91   /**

    92    * Gets the base provider info

    93    */

    94   SmfProvider* getProvider() ;

    95 

    96 

    97 signals:

    98 	/**

    99 	 * Notification on arrival of the self profile as result of userinfo().

   100 	 * @param profile The self profile

   101 	 */

   102 	void userInfoAvailable(SmfMusicProfile* profile, SmfError error);

   103 	/**

   104 	 * Notification on arrival of search info

   105 	 * @param profileList List of music profiles

   106 	 */

   107 	void searchInfoAvailable(SmfMusicProfileList& profileList, SmfError error,SmfResultPage resultPage);

   108 private:

   109   SmfProvider* m_baseProvider;

   110   SmfMusicServicePrivate* m_private;

   111   friend class SmfMusicServicePrivate;

   112 };

   113 SMF_SERVICE_NAME(SmfMusicService, "org.symbian.smf.client.music.service\0.2")

   114 

   115 

   116 /**

   117 * Provides service ("org.symbian.smf.client.music.search") for music search

   118 */

   119 class SMFCLIENT_EXPORT SmfMusicSearch : public QObject

   120 {

   121   Q_OBJECT

   122 

   123 public:

   124   /**

   125    * Constructs SmfMusicSearch with base provider as arguement.

   126    * Seeing as this is a plug-in implementation, these will realistically

   127    * be generated by SMF factory of some kind

   128    */

   129 

   130   SmfMusicSearch(SmfProvider* baseProvider = 0);

   131   ~SmfMusicSearch();

   132 

   133 public:

   134   /**

   135    * Searches for music recommendations similar to a particulartrack asynchronously.

   136    * The signal trackSearchAvailable() is emitted with SmfTrackInfoList

   137    * once its arrived.

   138    * When the list is big user can specify the page number and per page item data.

   139    * If not supplied by the user default values are used.

   140    * @param track The track for which similar recommendations need to be fetched.

   141    * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query.

   142    * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE

   143    */

   144   void recommendations(SmfTrackInfo track,int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE)  ; // basic list of track objects

   145 

   146   /**

   147    * Searches for tracks similar to a given track asynchronously.

   148    * The signal trackSearchAvailable() is emitted with SmfTrackInfoList

   149    * once its arrived.

   150    * When the list is big user can specify the page number and per page item data.

   151    * If not supplied by the user default values are used.

   152    * @param track The search criteria, similar tracks are searched

   153    * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query.

   154    * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE

   155    */

   156   void tracks(SmfTrackInfo track,int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE)  ; // basic list of track objects

   157 

   158   /**

   159    * Searches for a track having similar finger print asynchronously.

   160    * The signal trackSearchAvailable() is emitted with SmfTrackInfoList

   161    * once its arrived.

   162    * @param signature The search criteria,signature to be searched for

   163    * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query.

   164    * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE

   165    */

   166   void trackInfo(SmfMusicFingerPrint signature,int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE)  ; // search by fingerprint object

   167 

   168   /**

   169    * Search information about where to buy this song from asynchronously.

   170    * The signal storeSearchAvailable() is emitted with SmfProviderList once its arrived.

   171    * @param track The search criteria for stores

   172    * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query.

   173    * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE

   174    */

   175   void stores(SmfTrackInfo track,int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE)  ;

   176 

   177   //APIs to get/set base provider info (SmfProvider)

   178 

   179   /**

   180    * Gets the base provider info

   181    */

   182   SmfProvider* getProvider()  ;

   183 

   184 

   185 public slots:

   186 

   187 	/**

   188 	 * Posts currently playing track.

   189 	 * Success can be checked by checking the signal postFinished()

   190 	 * @param track Track to post

   191 	 */

   192   void postCurrentPlaying(SmfTrackInfo track)  ;

   193   void postRating(SmfTrackInfo track, SmfMusicRating rate)  ;

   194   void postComments(SmfTrackInfo track, SmfComment comment)  ;

   195 

   196 signals:

   197 	/**

   198 	 * Emitted when the search result for a track is available.

   199 	 * Note if number of tacks in the search is large, then it can download the list page by page.

   200 	 * In that case this signal is emitted multiple times.

   201 	 * @param resultPage Page number info

   202 	 */

   203 	void trackSearchAvailable(SmfTrackInfoList* result, SmfError error,SmfResultPage resultPage);

   204 

   205 	/**

   206 	 *  Emitted when the search result for a store is available.

   207 	 *  Note if number of tacks in the search is large, then it can download the list page by page.

   208 	 *  In that case this signal is emitted multiple times.

   209 	 *  @param resultPage Page number info

   210 	 */

   211 	void storeSearchAvailable(SmfProviderList* result, SmfError error, SmfResultPage resultPage);

   212 	void postfinished(SmfError error);

   213 private:

   214   SmfProvider* m_baseProvider;

   215   SmfMusicSearchPrivate* m_private;

   216   friend class SmfMusicSearchPrivate;

   217 };

   218 SMF_SERVICE_NAME(SmfMusicSearch, "org.symbian.smf.client.music.search\0.2")

   219 

   220 

   221 /**

   222  * provides service ("org.symbian.smf.client.music.playlist")

   223  *

   224  * Interface to a remote playlist service. This class

   225  * provides some basic functionality to allow applications

   226  * to interact with playlists in some music related service provider (e.g. last.fm).

   227  *

   228  * Note that branding information for the particular service implementation

   229  * is available from getProvider() API. See also:

   230  * SmfProvider::serviceName(), SmfProvider::serviceIcon()

   231  *

   232  * All of the functionality described here should be implemented by a service

   233  * specific plug-in object.

   234  *

   235  */

   236 class SMFCLIENT_EXPORT SmfPlaylistService : public QObject

   237 {

   238   Q_OBJECT

   239 

   240 public:

   241   /**

   242    * Constructs SmfPlaylistService with base provider info

   243    * Seeing as this is a plug-in implementation, these will realistically

   244    * be generated by SMF factory of some kind

   245    */

   246   SmfPlaylistService(SmfProvider* baseProvider = 0);

   247   ~SmfPlaylistService();

   248 

   249 public:

   250 

   251   /**

   252    * Gets the list playlists for the logged-in user asynchronously.

   253    * The signal playlistsListAvailable() signal is emitted with

   254    * SmfPlaylistList once its arrived .

   255    * When the list is big user can specify the page number and per page item data.

   256    * If not supplied by the user default values are used.

   257    * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query.

   258    * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE

   259    */

   260   void playlists(int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE)  ; // basic list of playlist objects

   261 

   262   /**

   263    * Gets the list playlists for the given user asynchronously.

   264    * The signal playlistsListAvailable() signal is emitted with

   265    * SmfPlaylistList once its arrived.

   266    * When the list is big user can specify the page number and per page item data.

   267    * If not supplied by the user default values are used.

   268    * @param user User for which to get the playlists

   269    * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query.

   270    * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE

   271    */

   272   void playlistsOf(SmfMusicProfile* user,int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE)  ;

   273 

   274   //APIs to get/set base provider info (SmfProvider)

   275 

   276   /**

   277    * Gets the base provider info

   278    */

   279   SmfProvider* getProvider()  ;

   280 

   281 

   282 public slots:

   283 

   284 	/**

   285 	 * Upload currently playing track to a playlist. Signal

   286 	 * playlistUpdated() can be checked for success value

   287 	 * @param plst The playlist to be added in

   288 	 * @param tracks The list of tracks to uploaded

   289 	 */

   290   int addToPlaylist(SmfPlaylist plst, SmfTrackInfoList* tracks)  ;

   291 

   292 	/**

   293 	 * Upload currently playing playlist . Signal

   294 	 * playlistUpdated() can be checked for success value

   295 	 * @param plst The playlist to be uploaded

   296 	 */

   297   int postCurrentPlayingPlaylist(SmfPlaylist plst)  ;

   298 

   299 

   300 signals:

   301 	/**

   302 	 * Notification of availability of list of playlists requested.

   303 	 * Note if number of list is large, then it can download the list page by page.

   304 	 * In that case this signal is emitted multiple times.

   305 	 * @param resultPage Page number info

   306 	 */

   307 	void playlistsListAvailable(SmfPlaylistList*, SmfError error, SmfResultPage resultPage);

   308 	/**

   309 	 * Signals remote updation of playlist with success value

   310 	 */

   311     void playlistUpdated(SmfError success) ;

   312 private:

   313   SmfProvider* m_baseProvider;

   314   SmfPlaylistServicePrivate* m_private;

   315   friend class SmfPlaylistServicePrivate;

   316 };

   317 SMF_SERVICE_NAME(SmfPlaylistService, "org.symbian.smf.client.music.playlist\0.2")

   318 

   319 

   320 /**

   321 * provides service ("org.symbian.smf.client.music.events")

   322 */

   323 class SMFCLIENT_EXPORT SmfMusicEvents : public QObject

   324 {

   325   Q_OBJECT

   326 

   327 public:

   328   /**

   329    * Constructs SmfMusicEvents with base provider info

   330    * Seeing as this is a plug-in implementation, these will realistically

   331    *  be generated by SMF factory of some kind

   332    */

   333   SmfMusicEvents(SmfProvider* baseProvider = 0);

   334   ~SmfMusicEvents();

   335 

   336 public:

   337 

   338   /**

   339    * Gets list of events in a particular location asynchronously.

   340    * eventsAvailable() signal is emitted with SmfEventsList once its arrived.

   341    * When the list is big user can specify the page number and per page item data.

   342    * If not supplied by the user default values are used.

   343    * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query.

   344    * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE

   345    */

   346   void events(QContactGeoLocation location,int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE)  ;

   347 

   348   /**

   349    * Gets list of venues of a particular location asynchronously.

   350    * venuesAvailable() signal is emitted with SmfLocationList once its arrived.

   351    * When the list is big user can specify the page number and per page item data.

   352    * If not supplied by the user default values are used.

   353    * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query.

   354    * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE

   355    */

   356   void venues(QContactGeoLocation location,int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE)  ; // basic list of venue objects

   357 

   358   /**

   359    * Gets list of events in a particular venue asynchronously.

   360    * eventsAvailable() signal is emitted with SmfEventsList once its arrived.

   361    * When the list is big user can specify the page number and per page item data.

   362    * If not supplied by the user default values are used.

   363    * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query.

   364    * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE

   365    */

   366   void events(SmfLocation venue,int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE)  ; // basic list of events objects

   367 

   368 

   369   //APIs to get/set base provider info (SmfProvider)

   370 

   371   /**

   372    * Gets the base provider info

   373    */

   374   SmfProvider* getProvider()  ;

   375 

   376 

   377 public slots:

   378 

   379 	/**

   380 	 * Updates events. Might not be supported by all service provider.

   381 	 * eventsUpdated() signal can be checked for success value.

   382 	 * @param SmfEventsList List of events to be posted

   383 	 */

   384 	 void postEvents(SmfEventList events);

   385 

   386 signals:

   387 

   388 	/**

   389 	 * Notification of the success of request to post an event

   390 	 */

   391 	void eventsUpdated(SmfError success);

   392 

   393 	/**

   394 	 * Notification on arrival of event lists

   395 	 * Note if number of list is large, then it can download the list page by page.

   396 	 * In that case this signal is emitted multiple times.

   397 	 * @param resultPage Page number info

   398 	 */

   399 	void eventsAvailable(SmfEventList* list, SmfError error, SmfResultPage resultPage);

   400 

   401 	/**

   402 	 *  Notification on arrival of venues lists

   403 	 * Note if number of list is large, then it can download the list page by page.

   404 	 * In that case this signal is emitted multiple times.

   405 	 * @param resultPage Page number info

   406 	 */

   407 	void venuesAvailable(SmfLocationList* list, SmfError error, SmfResultPage resultPage);

   408 private:

   409   SmfProvider* m_baseProvider;

   410   SmfMusicEventsPrivate* m_private;

   411   friend class SmfMusicEventsPrivate;

   412 };

   413 SMF_SERVICE_NAME(SmfMusicEvents, "org.symbian.smf.client.music.events\0.2")

   414 

   415 

   416 /**

   417 * provides service ("org.symbian.smf.client.music.lyrics")

   418 */

   419 class SMFCLIENT_EXPORT SmfLyricsService : public QObject

   420 {

   421   Q_OBJECT

   422 

   423 public:

   424   /**

   425    * Constructs SmfLyricsService with base provider info.

   426    * Seeing as this is a plug-in implementation, these will realistically

   427    * be generated by SMF factory of some kind

   428    */

   429 

   430   SmfLyricsService(SmfProvider* baseProvider = 0);

   431   ~SmfLyricsService();

   432 

   433 public:

   434 

   435   /**

   436    * Get the lyrics lists asynchrnously, it fetches texts without time info.

   437    * lyricsAvailable() notification comes SmfLyricsList with when the data is available

   438    * @param track Track for which lyrics needs to be fetched.

   439    * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query.

   440    * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE

   441    */

   442   void lyrics(SmfTrackInfo track,int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE)  ;

   443 

   444   /**

   445    * Get the lyrics lists asynchrnously, it fetches texts with time info.

   446    * Subtitle search filter can be applied

   447    * subtitleAvailable() notification comes SmfSubtitleList with when the data is available

   448    * @param track Track for which subtitle needs to be fetched.

   449    * @param filter Subtitle search filter

   450    * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query.

   451    * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE

   452    */

   453   void subtitles(SmfTrackInfo track, SmfSubtitleSearchFilter filter,int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE)  ; // texts with time information

   454   //APIs to get/set base provider info (SmfProvider)

   455 

   456   /**

   457    * Gets the base provider info

   458    */

   459   SmfProvider* getProvider()  ;

   460 signals:

   461 

   462 	/**

   463 	 * Notification on arrival of lyrics

   464 	 * Note if the list is large, then it can download the list page by page.

   465 	 * In that case this signal is emitted multiple times.

   466 	 * @param resultPage Page number info

   467 	 */

   468 	void lyricsAvailable(SmfLyricsList* list, SmfError error, SmfResultPage resultPage);

   469 

   470 	/**

   471 	 * Notification on arrival of subtitle based on filter.

   472 	 * Note if the list is large, then it can download the list page by page.

   473 	 * In that case this signal is emitted multiple times.

   474 	 * @param resultPage Page number info

   475 	 */

   476 	void subtitleAvailable(SmfSubtitleList* list, SmfError error, SmfResultPage resultPage);

   477 private:

   478   SmfProvider* m_baseProvider;

   479   SmfLyricsServicePrivate* m_private;

   480   friend class SmfLyricsServicePrivate;

   481 };

   482 SMF_SERVICE_NAME(SmfLyricsService, "org.symbian.smf.client.music.lyrics\0.2")

   483 

   484 #endif // SMFMUSIC_H

   485