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 "{License}"

     6 * which accompanies  this distribution, and is available

     7 * at the URL "{LicenseUrl}".

     8 *

     9 * Initial Contributors:

    10 * Chandradeep Gandhi, Sasken Communication Technologies Ltd - Initial contribution

    11 *

    12 * Contributors:

    13 * 

    14 * Description:

    15 * Interface spefication for music related services

    16 *

    17 */

    18 

    19 #ifndef SMFMUSIC_H

    20 #define SMMUSIC_H

    21 

    22 #include <QObject>

    23 

    24 #include <qmobilityglobal.h>

    25 #include <qgeopositioninfo.h>

    26 

    27 #include "smfprovider.h"

    28 #include "smfcontact.h"

    29 

    30 

    31 class SmfProvider; //basic Smf service Provider info

    32 class SmfContact; // Smf contact

    33 class SmfMusicRating;//rating value from 0..31 - services would map accordingly

    34 class SmfMusicProfile; //user profile containing music usage and interest info, extends SmfContact

    35 class SmfTrackInfo; //id, title, album, artist, genre, tag, director,release year, rating, comment info

    36 class SmfMusicFingerPrint; //generation is not in scope of smf

    37 class SmfVenue;

    38 class SmfMusicModel;

    39 class SmfEvents;

    40 class SmfPlaylist;

    41 class SmfLyricsService;

    42 class SmfLyrics;

    43 class SmfSubtitle;

    44 class SmfSubtitleSearchFilter;

    45 

    46 typedef QList<SmfMusicProfile> SmfMusicProfileList;

    47 typedef QList<SmfTrackInfo> SmfTrackInfoList;

    48 typedef QList<SmfEvents> SmfEventsList;

    49 typedef QList<SmfProvider> SmfProviderList;

    50 typedef QList<SmfPlaylist> SmfPlaylistList;

    51 typedef QList<SmfVenue> SmfVenueList;

    52 typedef QList<SmfLyrics> SmfLyricsList;

    53 typedef QList<SmfSubtitle> SmfSubtitleList;

    54 /**

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

    56   */

    57 class SMFCLIENT_EXPORT SmfMusicService : public QObject

    58 {

    59   Q_OBJECT

    60 

    61 public:

    62   /**

    63    * Constructs SmfMusicService.

    64    * @param baseProvider The base provider info

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

    66    *  be generated by SMF factory of some kind

    67    */

    68    SmfMusicService(SmfProvider* baseProvider = 0);

    69   ~SmfMusicService();

    70 

    71 public:

    72   

    73   /**

    74    * Gets self profile information asynchronously.

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

    76    */

    77   virtual void userinfo() = 0; 

    78   

    79   /**

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

    81    * serachInfoAvailable() signal is emitted with SmfMusicProfileList when the info is arrived

    82    */

    83   virtual void searchUser(SmfVenue venue) = 0; 

    84   

    85   /**

    86    * Returns the model

    87    */

    88   virtual SmfMusicModel model() = 0; // maybe we can make a QItemModel-derived model?

    89 

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

    91   

    92   /**

    93    * Gets the base provider info

    94    */

    95   virtual SmfProvider* getProvider() = 0;

    96   

    97   /**

    98    * Sets the base provider info

    99    */

   100   virtual void setProvider(SmfProvider* provider) = 0;

   101 

   102 signals:

   103 	/**

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

   105 	 * @param profile The self profile

   106 	 */

   107 	void userInfoAvailable(SmfMusicProfile* profile, QString error);

   108 private:

   109   SmfProvider* m_baseProvider;

   110 };

   111 SMF_GETSERVICES(SmfMusicService, "org.symbian.smf.client.music.service\0.2")

   112 

   113 

   114 /**

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

   116 */

   117 class SMFCLIENT_EXPORT SmfMusicSearch : public QObject

   118 {

   119   Q_OBJECT

   120 

   121 public:

   122   /**

   123    * Constructs SmfMusicSearch with base provider as arguement.

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

   125    * be generated by SMF factory of some kind

   126    */

   127 

   128   SmfMusicSearch(SmfProvider* baseProvider = 0);

   129   ~SmfMusicSearch();

   130 

   131 public:

   132   // Get the track listing - might be made asynchrnous later

   133   

   134   /**

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

   136    * The signal trackSearchAvailable() is emitted with SmfTrackInfoList

   137    * once its arrived.

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

   139    */

   140   virtual void recommendations(SmfTrackInfo track) = 0; // basic list of track objects

   141   

   142   /**

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

   144    * The signal trackSearchAvailable() is emitted with SmfTrackInfoList

   145    * once its arrived.

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

   147    */

   148   virtual void tracks(SmfTrackInfo track) = 0; // basic list of track objects

   149   

   150   /**

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

   152    * The signal trackSearchAvailable() is emitted with SmfTrackInfoList

   153    * once its arrived.

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

   155    */

   156   virtual void trackInfo(SmfMusicFingerPrint signature) = 0; // search by fingerprint object

   157   

   158   /**

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

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

   161    * @param track The search criteria for stores

   162    */

   163   virtual void stores(SmfTrackInfo track) = 0; 

   164   

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

   166   

   167   /**

   168    * Gets the base provider info

   169    */

   170   virtual SmfProvider* getProvider() = 0;

   171   

   172   /**

   173    * Sets the base provider info

   174    */

   175   virtual void setProvider(SmfProvider* provider) = 0;

   176 

   177 public slots:

   178 

   179 	/**

   180 	 * Posts currently playing track.

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

   182 	 * @param track Track to post

   183 	 */

   184   virtual void postCurrentPlaying(SmfTrackInfo track) = 0;

   185   //virtual int postRating(SmfTrackInfo track, SmfMusicRating rate) = 0;

   186   //virtual int postComments(SmfTrackInfo track, SmfComment comment) = 0;

   187 

   188 signals:

   189 	/**

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

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

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

   193 	 * @param result The search result

   194 	 */

   195 	void trackSearchAvailable(SmfTrackInfoList* result, QString error, int pageNumber=0);

   196 	

   197 	/**

   198 	 *  Emitted when the search result for a store 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 result The search result

   202 	 */

   203 	void storeSearchAvailable(SmfProviderList* result, QString error, int pageNumber=0);

   204 private:

   205   SmfProvider* m_baseProvider;

   206 };

   207 SMF_GETSERVICES(SmfMusicSearch, "org.symbian.smf.client.music.search\0.2")

   208 

   209 

   210 /**

   211  * Remote playlist

   212  */

   213 class SMFCLIENT_EXPORT SmfPlaylist : public QObject

   214 	{

   215 	Q_OBJECT

   216 	

   217 public:

   218 	SmfPlaylist();

   219 	~SmfPlaylist();

   220 	

   221 	/**

   222 	 * Gets tracks in the playlist

   223 	 */

   224 	SmfTrackInfoList* getTrackList();

   225 	

   226 	/**

   227 	 * Gets playlist title

   228 	 */

   229 	QString getPlayListTitle();

   230 	

   231 	/**

   232 	 * Gets the creation date

   233 	 */

   234 	QDateTime getCreationDate();

   235 	

   236 	/**

   237 	 * Sets tracks in the playlist

   238 	 */

   239 	void setTrackList(SmfTrackInfoList* trackList);

   240 	

   241 	/**

   242 	 * Sets playlist title

   243 	 */

   244 	void setPlayListTitle(QString title);

   245 	

   246 	/**

   247 	 * Sets creation date

   248 	 */

   249 	void setCreationDate(QDateTime time);

   250 	

   251 private:

   252 	SmfTrackInfoList* m_trackList;

   253 	QString m_title;

   254 	QDateTime m_creationDate;

   255 	};

   256 

   257 

   258 /**

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

   260  *

   261  * Interface to a remote playlist service. This class

   262  * provides some basic functionality to allow applications

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

   264  *

   265  * Note that branding information for the particular service implementation

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

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

   268  *

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

   270  * specific plug-in object.

   271  *

   272  */

   273 class SMFCLIENT_EXPORT SmfPlaylistService : public QObject

   274 {

   275   Q_OBJECT

   276 

   277 public:

   278   /**

   279    * Constructs SmfPlaylistService with base provider info

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

   281    * be generated by SMF factory of some kind

   282    */

   283   SmfPlaylistService(SmfProvider* baseProvider = 0);

   284   ~SmfPlaylistService();

   285 

   286 public:

   287   

   288   /**

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

   290    * The signal playlistsListAvailable() signal is emitted with 

   291    * SmfPlaylistList once its arrived 

   292    */

   293   virtual void playlists() = 0; // basic list of playlist objects 

   294   

   295   /**

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

   297    * The signal playlistsListAvailable() signal is emitted with 

   298    * SmfPlaylistList once its arrived.

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

   300    */

   301   virtual void playlistsOf(SmfMusicProfile* user) = 0; 

   302 

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

   304   

   305   /**

   306    * Gets the base provider info

   307    */

   308   virtual SmfProvider* getProvider() = 0;

   309   

   310   /**

   311    * Sets the base provider info

   312    */

   313   virtual void setProvider(SmfProvider* provider) = 0;

   314 

   315 public slots:

   316 

   317 	/**

   318 	 * Upload currently playing track to a playlist. Signal

   319 	 * playlistUpdated() can be checked for success value

   320 	 * @param plst The playlist to be added in

   321 	 * @param tracks The list of tracks to uploaded

   322 	 */

   323   virtual int addToPlaylist(SmfPlaylist plst, SmfTrackInfoList* tracks) = 0;

   324   

   325 	/**

   326 	 * Upload currently playing playlist . Signal

   327 	 * playlistUpdated() can be checked for success value

   328 	 * @param plst The playlist to be uploaded

   329 	 */

   330   virtual int postCurrentPlayingPlaylist(SmfPlaylist plst) = 0;

   331 

   332 

   333 signals:

   334 	/**

   335 	 * Notification of availability of list of playlists requested.

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

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

   338 	 */

   339 	void playlistsListAvailable(SmfPlaylistList*, QString error, int pageNumber=0);

   340 	/**

   341 	 * Signals remote updation of playlist with success value

   342 	 */

   343     int playlistUpdated(bool success) ;

   344 private:

   345   SmfProvider* m_baseProvider;

   346 };

   347 SMF_GETSERVICES(SmfPlaylistService, "org.symbian.smf.client.music.playlist\0.2")

   348 

   349 

   350 /**

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

   352 */

   353 class SMFCLIENT_EXPORT SmfMusicEvents : public QObject

   354 {

   355   Q_OBJECT

   356 

   357 public:

   358   /**

   359    * Constructs SmfMusicEvents with base provider info

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

   361    *  be generated by SMF factory of some kind

   362    */

   363   SmfMusicEvents(SmfProvider* baseProvider = 0);

   364   ~SmfMusicEvents();

   365 

   366 public:

   367   

   368   /**

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

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

   371    */

   372   virtual void events(QtMobility::QContactGeolocation location) = 0;

   373   

   374   /**

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

   376    * venuesAvailable() signal is emitted with SmfVenueList once its arrived.

   377    */

   378   virtual void venues(QtMobility::QContactGeolocation location) = 0; // basic list of venue objects

   379   

   380   /**

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

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

   383    */

   384   virtual void events(SmfVenue venue) = 0; // basic list of events objects

   385   

   386 

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

   388   

   389   /**

   390    * Gets the base provider info

   391    */

   392   virtual SmfProvider* getProvider() = 0;

   393   

   394   /**

   395    * Sets the base provider info

   396    */

   397   virtual void setProvider(SmfProvider* provider) = 0;

   398 

   399 public slots:

   400 

   401 	/**

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

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

   404 	 * @param SmfEventsList List of events to be posted

   405 	 */

   406 	 virtual void postEvents(SmfEventsList events); 

   407 

   408 signals:

   409 	

   410 	/**

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

   412 	 */

   413 	void eventsUpdated(bool success);

   414 	

   415 	/**

   416 	 * Notification on arrival of event lists

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

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

   419 	 */

   420 	void eventsAvailable(SmfEventsList* list, QString error, int pageNumber=0);

   421 	

   422 	/**

   423 	 *  Notification on arrival of venues lists

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

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

   426 	 */

   427 	void venuesAvailable(SmfVenueList* list, QString error, int pageNumber=0);

   428 private:

   429   SmfProvider* m_baseProvider;

   430 };

   431 SMF_GETSERVICES(SmfMusicEvents, "org.symbian.smf.client.music.events\0.2")

   432 

   433 

   434 /**

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

   436 */

   437 class SMFCLIENT_EXPORT SmfLyricsService : public QObject

   438 {

   439   Q_OBJECT

   440 

   441 public:

   442   /**

   443    * Constructs SmfLyricsService with base provider info.

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

   445    * be generated by SMF factory of some kind

   446    */

   447 

   448   SmfLyricsService(SmfProvider* baseProvider = 0);

   449   ~SmfLyricsService();

   450 

   451 public:

   452   

   453   /**

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

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

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

   457    */

   458   virtual void lyrics(SmfTrackInfo track) = 0; 

   459   

   460   /**

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

   462    * Subtitle search filter can be applied

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

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

   465    * @param filter Subtitle search filter

   466    */

   467   virtual void subtitles(SmfTrackInfo track, SmfSubtitleSearchFilter filter) = 0; // texts with time information

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

   469   

   470   /**

   471    * Gets the base provider info

   472    */

   473   virtual SmfProvider* getProvider() = 0;

   474   

   475   /**

   476    * Sets the base provider info

   477    */

   478   virtual void setProvider(SmfProvider* provider) = 0;

   479 

   480 public slots:

   481 

   482 

   483 signals:

   484 	

   485 	/**

   486 	 * Notification on arrival of lyrics

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

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

   489 	 */

   490 	void lyricsAvailable(SmfLyricsList* list, QString error, int pageNumber=0);

   491 

   492 	/**

   493 	 * Notification on arrival of subtitle based on filter.

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

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

   496 	 */

   497 	void subtitleAvailable(SmfSubtitleList* list, QString error, int pageNumber=0);

   498 private:

   499   SmfProvider* m_baseProvider;

   500 };

   501 SMF_GETSERVICES(SmfLyricsService, "org.symbian.smf.client.music.lyrics\0.2")

   502 

   503 #endif // SMFMUSIC_H

   504