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 <qcontactgeolocation.h>

    24 #include <smfglobal.h>

    25 #include <smfevent.h>

    26 #include <smfsubtitle.h>

    27 #include <smfmusicprofile.h>

    28 #include <smflyrics.h>

    29 #include <smfplaylist.h>

    30 #include <smftrackinfo.h>

    31 #include <smflocation.h>

    32 #include <smfprovider.h>

    33 

    34 class SmfMusicServicePrivate;

    35 class SmfMusicSearchPrivate;

    36 class SmfLyricsServicePrivate;

    37 class SmfPlaylistServicePrivate;

    38 class SmfMusicEventsPrivate;

    39 class SmfMusicFingerPrint;

    40 class SmfMusicRating;

    41 class SmfComment;

    42 

    43 using namespace QtMobility;

    44 

    45 

    46 /**

    47  * @ingroup smf_client_group

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

    49  */

    50 class SMFCLIENT_EXPORT SmfMusicService : public QObject

    51 	{

    52 	Q_OBJECT

    53 

    54 public:

    55 	/**

    56 	 * Constructs SmfMusicService.

    57 	 * @param baseProvider The base provider info

    58 	 */

    59 	SmfMusicService ( SmfProvider* baseProvider = 0 );

    60 	

    61 	/**

    62 	 * Destructor

    63 	 */

    64 	~SmfMusicService ( );

    65 

    66 public slots:

    67 	/**

    68 	 * Gets self profile information asynchronously.

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

    70 	 */

    71 	void userinfo ( );

    72 

    73 	/**

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

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

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

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

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

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

    80 	 */

    81 	void searchUser ( SmfLocation venue, int pageNum = SMF_FIRST_PAGE,

    82 						int perPage = SMF_ITEMS_PER_PAGE);

    83 	

    84 	/**

    85 	 * Request for a custom operation. The signal customDataAvailable() is emitted 

    86 	 * when the result is available.

    87 	 * @param operationId OperationId

    88 	 * @param customData Custom data to be sent

    89 	 * Note:-Interpretation of operationId and customData is upto the concerned

    90 	 * plugin and client application. service provider should provide some

    91 	 * serializing-deserializing utilities for these custom data

    92 	 */

    93 	void customRequest ( const int& operationId, QByteArray* customData );

    94 	

    95 public slots:

    96 	/**

    97 	 * Posts currently playing track.

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

    99 	 * @param track Track to post

   100 	 */

   101 	void postCurrentPlaying ( SmfTrackInfo track);

   102 	

   103 	void postRating ( SmfTrackInfo track, SmfMusicRating rate);

   104 	

   105 	void postComments ( SmfTrackInfo track, SmfComment comment);

   106 

   107 signals:

   108 	/**

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

   110 	 * @param profile The self profile

   111 	 */

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

   113 	

   114 	/**

   115 	 * Notification on arrival of search info

   116 	 * @param profileList List of music profiles

   117 	 */

   118 	void searchInfoAvailable ( SmfMusicProfileList* profileList, 

   119 			SmfError error, SmfResultPage resultPage );

   120 	

   121 	/**

   122 	 * Signals availability of the result of the customRequest

   123 	 * @param operationId The ID to be shared between clients and the plugin

   124 	 * @param customData data

   125 	 */

   126 	void customDataAvailable( const int& operationId, QByteArray* customData );

   127 	

   128 	/**

   129 	 * Signals availability of the result of the posting a track or a comment or a rating

   130 	 * @param error Error if any

   131 	 */

   132 	void postfinished ( SmfError error );

   133 	

   134 private:

   135 	/**

   136 	 * Gets the base provider info

   137 	 */

   138 	SmfProvider* getProvider() const;

   139 	

   140 // Friend Class

   141 	friend class SmfMusicServicePrivate;

   142 	

   143 private:

   144 	SmfProvider* m_baseProvider;

   145 	SmfMusicServicePrivate* m_private;

   146 

   147 	};

   148 

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

   150 

   151 

   152 /**

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

   154  */

   155 class SMFCLIENT_EXPORT SmfMusicSearch : public QObject

   156 	{

   157 	Q_OBJECT

   158 	

   159 public:

   160 	/**

   161 	 * Constructs SmfMusicSearch with base provider as arguement.

   162 	 */

   163 	SmfMusicSearch ( SmfProvider* baseProvider = 0 );

   164 	

   165 	/**

   166 	 * Destructor

   167 	 */

   168 	~SmfMusicSearch();

   169 	

   170 public:

   171 	/**

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

   173 	 * The signal trackSearchAvailable() is emitted with SmfTrackInfoList

   174 	 * once its arrived.

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

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

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

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

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

   180 	 */

   181 	void recommendations ( SmfTrackInfo track, int pageNum = SMF_FIRST_PAGE,

   182 			int perPage = SMF_ITEMS_PER_PAGE);

   183 	

   184 	/**

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

   186 	 * The signal trackSearchAvailable() is emitted with SmfTrackInfoList

   187 	 * once its arrived.

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

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

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

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

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

   193 	 */

   194 	void tracks ( SmfTrackInfo track, int pageNum = SMF_FIRST_PAGE,

   195 			int perPage = SMF_ITEMS_PER_PAGE);

   196 	

   197 	/**

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

   199 	 * The signal trackSearchAvailable() is emitted with SmfTrackInfoList

   200 	 * once its arrived.

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

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

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

   204 	 */

   205 	void trackInfo ( SmfMusicFingerPrint signature, int pageNum = SMF_FIRST_PAGE,

   206 			int perPage = SMF_ITEMS_PER_PAGE);

   207 	

   208 	/**

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

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

   211 	 * @param track The search criteria for stores

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

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

   214 	 */

   215 	void stores ( SmfTrackInfo track, int pageNum = SMF_FIRST_PAGE, 

   216 			int perPage = SMF_ITEMS_PER_PAGE);

   217 	

   218 	/**

   219 	 * Request for a custom operation. The signal customDataAvailable() is emitted 

   220 	 * when the result is available.

   221 	 * @param operationId OperationId

   222 	 * @param customData Custom data to be sent

   223 	 * Note:-Interpretation of operationId and customData is upto the concerned

   224 	 * plugin and client application. service provider should provide some

   225 	 * serializing-deserializing utilities for these custom data

   226 	 */

   227 	void customRequest ( const int& operationId, QByteArray* customData );

   228 	

   229 signals:

   230 	/**

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

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

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

   234 	 * @param resultPage Page number info

   235 	 */

   236 	void trackSearchAvailable ( SmfTrackInfoList* result, 

   237 			SmfError error, SmfResultPage resultPage);

   238 	

   239 	/**

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

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

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

   243 	 *  @param resultPage Page number info

   244 	 */

   245 	void storeSearchAvailable ( SmfProviderList* result, 

   246 			SmfError error, SmfResultPage resultPage );

   247 	

   248 	/**

   249 	 * Signals availability of the result of the customRequest

   250 	 * @param operationId The ID to be shared between clients and the plugin

   251 	 * @param customData data

   252 	 */

   253 	void customDataAvailable( const int& operationId, QByteArray* customData );

   254 	

   255 private:

   256 	/**

   257 	 * Gets the base provider info

   258 	 */

   259 	SmfProvider* getProvider() const;

   260 	

   261 private:

   262 	SmfProvider* m_baseProvider;

   263 	SmfMusicSearchPrivate* m_private;

   264 	friend class SmfMusicSearchPrivate;

   265 	

   266 	};

   267 

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

   269 

   270 

   271 /**

   272  * Provides service ("org.symbian.smf.client.music.playlist")

   273  *

   274  * Interface to a remote playlist service. This class

   275  * provides some basic functionality to allow applications

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

   277  *

   278  * Note that branding information for the particular service implementation

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

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

   281  *

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

   283  * specific plug-in object.

   284  *

   285  */

   286 class SMFCLIENT_EXPORT SmfPlaylistService : public QObject

   287 	{

   288 	Q_OBJECT

   289 	

   290 public:

   291 	/**

   292 	 * Constructs SmfPlaylistService with base provider info

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

   294 	 * be generated by SMF factory of some kind

   295 	 */

   296 	SmfPlaylistService ( SmfProvider* baseProvider = 0 );

   297 	

   298 	/**

   299 	 * Destructor

   300 	 */

   301 	~SmfPlaylistService ( );

   302 	

   303 public:

   304 	/**

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

   306 	 * The signal playlistsListAvailable() signal is emitted with

   307 	 * SmfPlaylistList once its arrived .

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

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

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

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

   312 	 */

   313 	void playlists ( int pageNum = SMF_FIRST_PAGE,

   314 			int perPage = SMF_ITEMS_PER_PAGE);

   315 	

   316 	/**

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

   318 	 * The signal playlistsListAvailable() signal is emitted with

   319 	 * SmfPlaylistList once its arrived.

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

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

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

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

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

   325 	 */

   326 	void playlistsOf ( SmfMusicProfile* user, int pageNum = SMF_FIRST_PAGE,

   327 			int perPage = SMF_ITEMS_PER_PAGE);

   328 	

   329 public slots:

   330 	/**

   331 	 * Upload currently playing track to a playlist. Signal

   332 	 * playlistUpdated() can be checked for success value

   333 	 * @param plst The playlist to be added in

   334 	 * @param tracks The list of tracks to uploaded

   335 	 */

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

   337 	

   338 	/**

   339 	 * Upload currently playing playlist . Signal

   340 	 * playlistUpdated() can be checked for success value

   341 	 * @param plst The playlist to be uploaded

   342 	 */

   343 	int postCurrentPlayingPlaylist ( SmfPlaylist plst );

   344 	

   345 	/**

   346 	 * Request for a custom operation. The signal customDataAvailable() is emitted 

   347 	 * when the result is available.

   348 	 * @param operationId OperationId

   349 	 * @param customData Custom data to be sent

   350 	 * Note:-Interpretation of operationId and customData is upto the concerned

   351 	 * plugin and client application. service provider should provide some

   352 	 * serializing-deserializing utilities for these custom data

   353 	 */

   354 	void customRequest ( const int& operationId, QByteArray* customData );

   355 		

   356 signals:

   357 	/**

   358 	 * Notification of availability of list of playlists requested.

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

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

   361 	 * @param resultPage Page number info

   362 	 */

   363 	void playlistsListAvailable ( SmfPlaylistList*, 

   364 			SmfError error, SmfResultPage resultPage );

   365 	/**

   366 	 * Signals remote updation of playlist with success value

   367 	 */

   368 	void playlistUpdated ( SmfError success );

   369 	

   370 	/**

   371 	 * Signals availability of the result of the customRequest

   372 	 * @param operationId The ID to be shared between clients and the plugin

   373 	 * @param customData data

   374 	 */

   375 	void customDataAvailable( const int& operationId, QByteArray* customData );

   376 

   377 private:

   378 	/**

   379 	 * Gets the base provider info

   380 	 */

   381 	SmfProvider* getProvider() const;

   382 	

   383 private:

   384 	SmfProvider* m_baseProvider;

   385 	SmfPlaylistServicePrivate* m_private;

   386 	friend class SmfPlaylistServicePrivate;

   387 	

   388 	};

   389 

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

   391 

   392 

   393 /**

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

   395  */

   396 class SMFCLIENT_EXPORT SmfMusicEvents : public QObject

   397 	{

   398 	Q_OBJECT

   399 	

   400 public:

   401 	/**

   402 	 * Constructs SmfMusicEvents with base provider info

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

   404 	 *  be generated by SMF factory of some kind

   405 	 */

   406 	SmfMusicEvents ( SmfProvider* baseProvider = 0 );

   407 	

   408 	/**

   409 	 * Destructor

   410 	 */

   411 	~SmfMusicEvents ( );

   412 	

   413 public:

   414 	/**

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

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

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

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

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

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

   421 	 */

   422 	void events ( SmfLocation venue, int pageNum = SMF_FIRST_PAGE,

   423 			int perPage = SMF_ITEMS_PER_PAGE);

   424 	

   425 	/**

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

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

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

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

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

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

   432 	 */

   433 	void venues ( SmfLocation location, int pageNum = SMF_FIRST_PAGE,

   434 			int perPage = SMF_ITEMS_PER_PAGE);

   435 	

   436 public slots:

   437 	/**

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

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

   440 	 * @param SmfEventsList List of events to be posted

   441 	 */

   442 	void postEvents ( SmfEventList events );

   443 	

   444 	/**

   445 	 * Request for a custom operation. The signal customDataAvailable() is emitted 

   446 	 * when the result is available.

   447 	 * @param operationId OperationId

   448 	 * @param customData Custom data to be sent

   449 	 * Note:-Interpretation of operationId and customData is upto the concerned

   450 	 * plugin and client application. service provider should provide some

   451 	 * serializing-deserializing utilities for these custom data

   452 	 */

   453 	void customRequest ( const int& operationId, QByteArray* customData );

   454 	

   455 signals:

   456 	/**

   457 	 * Notification on arrival of event lists

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

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

   460 	 * @param resultPage Page number info

   461 	 */

   462 	void eventsAvailable ( SmfEventList* list, 

   463 			SmfError error, SmfResultPage resultPage );

   464 	

   465 	/**

   466 	 * Notification on arrival of venues lists

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

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

   469 	 * @param resultPage Page number info

   470 	 */

   471 	void venuesAvailable ( SmfLocationList* list, 

   472 			SmfError error, SmfResultPage resultPage );

   473 	

   474 	/**

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

   476 	 */

   477 	void eventsUpdated ( SmfError success );

   478 	

   479 	/**

   480 	 * Signals availability of the result of the customRequest

   481 	 * @param operationId The ID to be shared between clients and the plugin

   482 	 * @param customData data

   483 	 */

   484 	void customDataAvailable( const int& operationId, QByteArray* customData );

   485 	

   486 private:

   487 	/**

   488 	 * Gets the base provider info

   489 	 */

   490 	SmfProvider* getProvider() const;

   491 	

   492 private:

   493 	SmfProvider* m_baseProvider;

   494 	SmfMusicEventsPrivate* m_private;

   495 	friend class SmfMusicEventsPrivate;

   496 	

   497 	};

   498 

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

   500 

   501 

   502 /**

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

   504  */

   505 class SMFCLIENT_EXPORT SmfLyricsService : public QObject

   506 	{

   507 	Q_OBJECT

   508 	

   509 public:

   510 	/**

   511 	 * Constructs SmfLyricsService with base provider info.

   512 	 */

   513 	SmfLyricsService ( SmfProvider* baseProvider = 0 );

   514 	

   515 	/**

   516 	 * Destructor

   517 	 */

   518 	~SmfLyricsService ( );

   519 	

   520 public:

   521 	/**

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

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

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

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

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

   527 	 */

   528 	void lyrics ( SmfTrackInfo track, int pageNum = SMF_FIRST_PAGE,

   529 			int perPage = SMF_ITEMS_PER_PAGE);

   530 	

   531 	/**

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

   533 	 * Subtitle search filter can be applied

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

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

   536 	 * @param filter Subtitle search filter

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

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

   539 	 */

   540 	void subtitles ( SmfTrackInfo track, SmfSubtitleSearchFilter filter,

   541 			int pageNum = SMF_FIRST_PAGE, int perPage = SMF_ITEMS_PER_PAGE);

   542 	

   543 	/**

   544 	 * Request for a custom operation. The signal customDataAvailable() is emitted 

   545 	 * when the result is available.

   546 	 * @param operationId OperationId

   547 	 * @param customData Custom data to be sent

   548 	 * Note:-Interpretation of operationId and customData is upto the concerned

   549 	 * plugin and client application. service provider should provide some

   550 	 * serializing-deserializing utilities for these custom data

   551 	 */

   552 	void customRequest ( const int& operationId, QByteArray* customData );

   553 

   554 signals:

   555 	/**

   556 	 * Notification on arrival of lyrics

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

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

   559 	 * @param resultPage Page number info

   560 	 */

   561 	void lyricsAvailable ( SmfLyricsList* list, 

   562 			SmfError error, SmfResultPage resultPage );

   563 	

   564 	/**

   565 	 * Notification on arrival of subtitle based on filter.

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

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

   568 	 * @param resultPage Page number info

   569 	 */

   570 	void subtitleAvailable ( SmfSubtitleList* list, 

   571 			SmfError error, SmfResultPage resultPage );

   572 	

   573 	/**

   574 	 * Signals availability of the result of the customRequest

   575 	 * @param operationId The ID to be shared between clients and the plugin

   576 	 * @param customData data

   577 	 */

   578 	void customDataAvailable( const int& operationId, QByteArray* customData );

   579 	

   580 private:

   581 	/**

   582 	 * Gets the base provider info

   583 	 */

   584 	SmfProvider* getProvider() const;

   585 	

   586 private:

   587 	SmfProvider* m_baseProvider;

   588 	SmfLyricsServicePrivate* m_private;

   589 	friend class SmfLyricsServicePrivate;

   590 	

   591 	};

   592 

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

   594 

   595 #endif // SMFMUSIC_H