diff -r 1cee9f1b95e0 -r a180113055cb smf/smfservermodule/smfclient/smfmusic.h --- a/smf/smfservermodule/smfclient/smfmusic.h Thu Sep 23 17:20:22 2010 +0530 +++ b/smf/smfservermodule/smfclient/smfmusic.h Thu Sep 23 17:43:31 2010 +0530 @@ -30,15 +30,16 @@ #include #include #include +#include class SmfMusicServicePrivate; class SmfMusicSearchPrivate; class SmfLyricsServicePrivate; class SmfPlaylistServicePrivate; -class SmfMusicEventsPrivate; class SmfMusicFingerPrint; class SmfMusicRating; class SmfComment; +class SmfContact; using namespace QtMobility; @@ -46,6 +47,11 @@ /** * @ingroup smf_client_group * Basic music service ("org.symbian.smf.client.music.service") + * This is the music profile information of a user in this service. Also provides searching + * on music meta information like albums artists etc. For searching for actual music/tracks + * use ("org.symbian.smf.client.music.search") interface from this service provider + * For usual contact information (like address, nickname, friends etc) please + * use ("org.symbian.smf.client.contact.fetcher") interface from this service provider */ class SMFCLIENT_EXPORT SmfMusicService : public QObject { @@ -65,57 +71,166 @@ public slots: /** - * Gets self profile information asynchronously. - * userInfoAvailable() signal is emitted with SmfMusicProfile when the info is arrived + * Gets self profile information (e.g. music likings, feavorites etc) asynchronously. + * userMusicInfoAvailable() signal is emitted with SmfMusicProfile when the info is arrived + * @return SmfError. SmfNoError if success, else appropriate error code + */ + SmfError userMusicInfo ( ); + + /** + * Asynchronously searches information about artists in this service. All information + * in SmfArtists is not required, however more available the better + * searchArtistInfoAvailable() signal is emitted when the info is arrived. + * @param artist The search criteria + * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query. + * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE + * @return SmfError, SmfNoError if success, else appropriate error value + */ + SmfError searchArtist ( SmfArtists artist, int pageNum = SMF_FIRST_PAGE, + int perPage = SMF_ITEMS_PER_PAGE ); + + /** + * Asynchronously searches information about albums in this service. All information + * in SmfAlbum is not required, however more available the better + * searchAlbumInfoAvailable() signal is emitted when the info is arrived. + * @param album The search criteria + * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query. + * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE + * @return SmfError, SmfNoError if success, else appropriate error value */ - void userinfo ( ); + SmfError searchAlbum ( SmfAlbum album, int pageNum = SMF_FIRST_PAGE, + int perPage = SMF_ITEMS_PER_PAGE ); + + /** + * Asynchronously searches information about events in this service. All information + * in SmfEvents is not required, however more available the better + * searchEventsInfoAvailable() signal is emitted when the info is arrived. + * @param event The search criteria + * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query. + * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE + * @return SmfError, SmfNoError if success, else appropriate error value + */ + SmfError searchEvents ( SmfEvent event, int pageNum = SMF_FIRST_PAGE, + int perPage = SMF_ITEMS_PER_PAGE ); + + /** + * Asynchronously searches information about venue in this service. All information + * in SmfVenue is not required, however more available the better + * searchVenueInfoAvailable() signal is emitted when the info is arrived. + * @param location The search criteria + * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query. + * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE + * @return SmfError, SmfNoError if success, else appropriate error value + */ + SmfError searchVenue ( SmfLocation location, int pageNum = SMF_FIRST_PAGE, + int perPage = SMF_ITEMS_PER_PAGE ); /** * Asynchronously searches information about other service users for a particular venue - * searchInfoAvailable() signal is emitted with SmfMusicProfileList when the info is arrived. + * searchUserInfoAvailable() signal is emitted with SmfMusicProfileList when the info is arrived. * When the list is big user can specify the page number and per page item data. * If not supplied by the user default values are used. + * @param location The search criteria * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query. * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE + * @return SmfError, SmfNoError if success, else appropriate error value */ - void searchUser ( SmfLocation venue, int pageNum = SMF_FIRST_PAGE, + SmfError searchUser ( SmfLocation venue, int pageNum = SMF_FIRST_PAGE, int perPage = SMF_ITEMS_PER_PAGE); /** + * Posts currently playing track. + * Success can be checked by checking the signal postFinished() + * @param track Track to post + * @return SmfError, SmfNoError if success, else appropriate error value + */ + SmfError postCurrentPlaying ( SmfTrackInfo track); + + /** + * Rate a music via this API + * Success can be checked by checking the signal postFinished() + * @param track Track on which rating should be posted + * @param rate Rating value + * @return SmfError, SmfNoError if success, else appropriate error value + */ + SmfError postRating ( SmfTrackInfo track, SmfMusicRating rate); + + /** + * Comment on a track via this API + * Success can be checked by checking the signal postFinished() + * @param track Track on which comment should be posted + * @param comment The comemnt to be posted + * @return SmfError, SmfNoError if success, else appropriate error value + */ + SmfError postComments ( SmfTrackInfo track, SmfComment comment); + + /** * Request for a custom operation. The signal customDataAvailable() is emitted * when the result is available. * @param operationId OperationId * @param customData Custom data to be sent + * @return SmfError. SmfNoError if success, else appropriate error code * Note:-Interpretation of operationId and customData is upto the concerned * plugin and client application. service provider should provide some * serializing-deserializing utilities for these custom data */ - void customRequest ( const int& operationId, QByteArray* customData ); + SmfError customRequest ( const int& operationId, QByteArray* customData ); -public slots: - /** - * Posts currently playing track. - * Success can be checked by checking the signal postFinished() - * @param track Track to post - */ - void postCurrentPlaying ( SmfTrackInfo track); + /** + * Cancels a request generated due to the call to any API which results + * into http request. Might return error if no request is currently pending. + * Please note that there can be only one request pending at any point of time + * @return Appropriate SmfError value + */ + SmfError cancelRequest (); - void postRating ( SmfTrackInfo track, SmfMusicRating rate); - void postComments ( SmfTrackInfo track, SmfComment comment); - signals: /** * Notification on arrival of the self profile as result of userinfo(). * @param profile The self profile + * @param error SmfNoError if success, else appropriate error value */ - void userInfoAvailable ( SmfMusicProfile* profile, SmfError error ); + void userMusicInfoAvailable ( SmfMusicProfile* profile, SmfError error ); + + /** + * Notification on arrival of search info + * @param profileList List of music profiles + * @param error SmfNoError if success, else appropriate error value + */ + void searchUserInfoAvailable ( SmfMusicProfileList* profileList, + SmfError error, SmfResultPage resultPage ); /** * Notification on arrival of search info - * @param profileList List of music profiles + * @param artists List of artists + * @param error SmfNoError if success, else appropriate error value + */ + void searchArtistInfoAvailable (QList* artists, + SmfError error, SmfResultPage resultPage ); + + /** + * Notification on arrival of search info + * @param albumList List of albums + * @param error SmfNoError if success, else appropriate error value */ - void searchInfoAvailable ( SmfMusicProfileList* profileList, + void searchAlbumInfoAvailable ( QList* albumList, + SmfError error, SmfResultPage resultPage ); + + /** + * Notification on arrival of search info + * @param eventList List of events + * @param error SmfNoError if success, else appropriate error value + */ + void searchEventsInfoAvailable ( SmfEventList* eventList, + SmfError error, SmfResultPage resultPage ); + + /** + * Notification on arrival of search info + * @param venueList List of venues + * @param error SmfNoError if success, else appropriate error value + */ + void searchVenueInfoAvailable ( SmfLocationList* venueList, SmfError error, SmfResultPage resultPage ); /** @@ -127,7 +242,7 @@ /** * Signals availability of the result of the posting a track or a comment or a rating - * @param error Error if any + * @param error SmfNoError if success, else appropriate error value */ void postfinished ( SmfError error ); @@ -177,8 +292,9 @@ * @param track The track for which similar recommendations need to be fetched. * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query. * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE + * @return SmfNoError if success, else appropriate error value */ - void recommendations ( SmfTrackInfo track, int pageNum = SMF_FIRST_PAGE, + SmfError recommendations ( SmfTrackInfo track, int pageNum = SMF_FIRST_PAGE, int perPage = SMF_ITEMS_PER_PAGE); /** @@ -190,8 +306,37 @@ * @param track The search criteria, similar tracks are searched * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query. * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE + * @return SmfNoError if success, else appropriate error value */ - void tracks ( SmfTrackInfo track, int pageNum = SMF_FIRST_PAGE, + SmfError tracksSimilar ( SmfTrackInfo track, int pageNum = SMF_FIRST_PAGE, + int perPage = SMF_ITEMS_PER_PAGE); + + /** + * Searches for tracks for a given album asynchronously. + * The signal trackSearchAvailable() is emitted with SmfTrackInfoList + * once its arrived. + * When the list is big user can specify the page number and per page item data. + * If not supplied by the user default values are used. + * @param album The album containing the id + * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query. + * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE + * @return SmfNoError if success, else appropriate error value + */ + SmfError tracksOfAlbum ( SmfAlbum album, int pageNum = SMF_FIRST_PAGE, + int perPage = SMF_ITEMS_PER_PAGE); + + /** + * Searches for tracks for a given artist(s) asynchronously. + * The signal trackSearchAvailable() is emitted with SmfTrackInfoList + * once its arrived. + * When the list is big user can specify the page number and per page item data. + * If not supplied by the user default values are used. + * @param artists The artists list + * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query. + * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE + * @return SmfNoError if success, else appropriate error value + */ + SmfError tracksOfArtist ( SmfArtists artists, int pageNum = SMF_FIRST_PAGE, int perPage = SMF_ITEMS_PER_PAGE); /** @@ -201,8 +346,9 @@ * @param signature The search criteria,signature to be searched for * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query. * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE + * @return SmfNoError if success, else appropriate error value */ - void trackInfo ( SmfMusicFingerPrint signature, int pageNum = SMF_FIRST_PAGE, + SmfError trackInfo ( SmfMusicFingerPrint signature, int pageNum = SMF_FIRST_PAGE, int perPage = SMF_ITEMS_PER_PAGE); /** @@ -211,8 +357,9 @@ * @param track The search criteria for stores * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query. * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE + * @return SmfNoError if success, else appropriate error value */ - void stores ( SmfTrackInfo track, int pageNum = SMF_FIRST_PAGE, + SmfError stores ( SmfTrackInfo track, int pageNum = SMF_FIRST_PAGE, int perPage = SMF_ITEMS_PER_PAGE); /** @@ -220,17 +367,27 @@ * when the result is available. * @param operationId OperationId * @param customData Custom data to be sent + * @return SmfNoError if success, else appropriate error value * Note:-Interpretation of operationId and customData is upto the concerned * plugin and client application. service provider should provide some * serializing-deserializing utilities for these custom data */ - void customRequest ( const int& operationId, QByteArray* customData ); + SmfError customRequest ( const int& operationId, QByteArray* customData ); + + /** + * Cancels a request generated due to the call to any API which results + * into http request. Might return error if no request is currently pending. + * Please note that there can be only one request pending at any point of time + * @return Appropriate SmfError value + */ + SmfError cancelRequest (); signals: /** - * Emitted when the search result for a track is available. + * Emitted when the search results for tracks (for album, artist, etc) are available. * Note if number of tacks in the search is large, then it can download the list page by page. - * In that case this signal is emitted multiple times. + * @param result list of tracks + * @param error SmfNoError if success, else appropriate error value * @param resultPage Page number info */ void trackSearchAvailable ( SmfTrackInfoList* result, @@ -239,7 +396,8 @@ /** * Emitted when the search result for a store is available. * Note if number of tacks in the search is large, then it can download the list page by page. - * In that case this signal is emitted multiple times. + * @param result List of stores + * @param error SmfNoError if success, else appropriate error value * @param resultPage Page number info */ void storeSearchAvailable ( SmfProviderList* result, @@ -309,8 +467,9 @@ * If not supplied by the user default values are used. * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query. * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE + * @return SmfNoError if success, else appropriate error value */ - void playlists ( int pageNum = SMF_FIRST_PAGE, + SmfError playlists ( int pageNum = SMF_FIRST_PAGE, int perPage = SMF_ITEMS_PER_PAGE); /** @@ -322,8 +481,9 @@ * @param user User for which to get the playlists * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query. * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE + * @return SmfNoError if success, else appropriate error value */ - void playlistsOf ( SmfMusicProfile* user, int pageNum = SMF_FIRST_PAGE, + SmfError playlistsOf ( SmfContact* user, int pageNum = SMF_FIRST_PAGE, int perPage = SMF_ITEMS_PER_PAGE); public slots: @@ -332,40 +492,53 @@ * playlistUpdated() can be checked for success value * @param plst The playlist to be added in * @param tracks The list of tracks to uploaded + * @return SmfNoError if success, else appropriate error value */ - int addToPlaylist ( SmfPlaylist plst, SmfTrackInfoList* tracks ); + SmfError addToPlaylist ( SmfPlaylist plst, SmfTrackInfoList* tracks ); /** * Upload currently playing playlist . Signal * playlistUpdated() can be checked for success value * @param plst The playlist to be uploaded + * @return SmfNoError if success, else appropriate error value */ - int postCurrentPlayingPlaylist ( SmfPlaylist plst ); + SmfError postCurrentPlayingPlaylist ( SmfPlaylist plst ); /** * Request for a custom operation. The signal customDataAvailable() is emitted * when the result is available. * @param operationId OperationId * @param customData Custom data to be sent + * @return SmfNoError if success, else appropriate error value * Note:-Interpretation of operationId and customData is upto the concerned * plugin and client application. service provider should provide some * serializing-deserializing utilities for these custom data */ - void customRequest ( const int& operationId, QByteArray* customData ); + SmfError customRequest ( const int& operationId, QByteArray* customData ); + + /** + * Cancels a request generated due to the call to any API which results + * into http request. Might return error if no request is currently pending. + * Please note that there can be only one request pending at any point of time + * @return Appropriate SmfError value + */ + SmfError cancelRequest (); signals: /** * Notification of availability of list of playlists requested. * Note if number of list is large, then it can download the list page by page. - * In that case this signal is emitted multiple times. + * @param plst List of playlists + * @param error, SmfNoError if success, else appropriate error value * @param resultPage Page number info */ - void playlistsListAvailable ( SmfPlaylistList*, + void playlistsListAvailable ( SmfPlaylistList* plst, SmfError error, SmfResultPage resultPage ); /** * Signals remote updation of playlist with success value + * @param error, SmfNoError if success, else appropriate error value */ - void playlistUpdated ( SmfError success ); + void playlistUpdated ( SmfError error ); /** * Signals availability of the result of the customRequest @@ -390,114 +563,6 @@ SMF_SERVICE_NAME(SmfPlaylistService, "org.symbian.smf.client.music.playlist\0.2") -/** - * provides service ("org.symbian.smf.client.music.events") - */ -class SMFCLIENT_EXPORT SmfMusicEvents : public QObject - { - Q_OBJECT - -public: - /** - * Constructs SmfMusicEvents with base provider info - * Seeing as this is a plug-in implementation, these will realistically - * be generated by SMF factory of some kind - */ - SmfMusicEvents ( SmfProvider* baseProvider = 0 ); - - /** - * Destructor - */ - ~SmfMusicEvents ( ); - -public: - /** - * Gets list of events in a particular venue asynchronously. - * eventsAvailable() signal is emitted with SmfEventsList once its arrived. - * When the list is big user can specify the page number and per page item data. - * If not supplied by the user default values are used. - * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query. - * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE - */ - void events ( SmfLocation venue, int pageNum = SMF_FIRST_PAGE, - int perPage = SMF_ITEMS_PER_PAGE); - - /** - * Gets list of venues of a particular location asynchronously. - * venuesAvailable() signal is emitted with SmfLocationList once its arrived. - * When the list is big user can specify the page number and per page item data. - * If not supplied by the user default values are used. - * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query. - * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE - */ - void venues ( SmfLocation location, int pageNum = SMF_FIRST_PAGE, - int perPage = SMF_ITEMS_PER_PAGE); - -public slots: - /** - * Updates events. Might not be supported by all service provider. - * eventsUpdated() signal can be checked for success value. - * @param SmfEventsList List of events to be posted - */ - void postEvents ( SmfEventList events ); - - /** - * Request for a custom operation. The signal customDataAvailable() is emitted - * when the result is available. - * @param operationId OperationId - * @param customData Custom data to be sent - * Note:-Interpretation of operationId and customData is upto the concerned - * plugin and client application. service provider should provide some - * serializing-deserializing utilities for these custom data - */ - void customRequest ( const int& operationId, QByteArray* customData ); - -signals: - /** - * Notification on arrival of event lists - * Note if number of list is large, then it can download the list page by page. - * In that case this signal is emitted multiple times. - * @param resultPage Page number info - */ - void eventsAvailable ( SmfEventList* list, - SmfError error, SmfResultPage resultPage ); - - /** - * Notification on arrival of venues lists - * Note if number of list is large, then it can download the list page by page. - * In that case this signal is emitted multiple times. - * @param resultPage Page number info - */ - void venuesAvailable ( SmfLocationList* list, - SmfError error, SmfResultPage resultPage ); - - /** - * Notification of the success of request to post an event - */ - void eventsUpdated ( SmfError success ); - - /** - * Signals availability of the result of the customRequest - * @param operationId The ID to be shared between clients and the plugin - * @param customData data - */ - void customDataAvailable( const int& operationId, QByteArray* customData ); - -private: - /** - * Gets the base provider info - */ - SmfProvider* getProvider() const; - -private: - SmfProvider* m_baseProvider; - SmfMusicEventsPrivate* m_private; - friend class SmfMusicEventsPrivate; - - }; - -SMF_SERVICE_NAME(SmfMusicEvents, "org.symbian.smf.client.music.events\0.2") - /** * provides service ("org.symbian.smf.client.music.lyrics") @@ -524,8 +589,9 @@ * @param track Track for which lyrics needs to be fetched. * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query. * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE + * @return SmfNoError if success, else appropriate error value */ - void lyrics ( SmfTrackInfo track, int pageNum = SMF_FIRST_PAGE, + SmfError lyrics ( SmfTrackInfo track, int pageNum = SMF_FIRST_PAGE, int perPage = SMF_ITEMS_PER_PAGE); /** @@ -536,8 +602,9 @@ * @param filter Subtitle search filter * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query. * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE + * @return SmfNoError if success, else appropriate error value */ - void subtitles ( SmfTrackInfo track, SmfSubtitleSearchFilter filter, + SmfError subtitles ( SmfTrackInfo track, SmfSubtitleSearchFilter filter, int pageNum = SMF_FIRST_PAGE, int perPage = SMF_ITEMS_PER_PAGE); /** @@ -545,17 +612,27 @@ * when the result is available. * @param operationId OperationId * @param customData Custom data to be sent + * @return SmfNoError if success, else appropriate error value * Note:-Interpretation of operationId and customData is upto the concerned * plugin and client application. service provider should provide some * serializing-deserializing utilities for these custom data */ - void customRequest ( const int& operationId, QByteArray* customData ); + SmfError customRequest ( const int& operationId, QByteArray* customData ); + + /** + * Cancels a request generated due to the call to any API which results + * into http request. Might return error if no request is currently pending. + * Please note that there can be only one request pending at any point of time + * @return Appropriate SmfError value + */ + SmfError cancelRequest (); signals: /** * Notification on arrival of lyrics * Note if the list is large, then it can download the list page by page. - * In that case this signal is emitted multiple times. + * @param list List of lyrics + * @param error SmfNoError if success, else appropriate error value * @param resultPage Page number info */ void lyricsAvailable ( SmfLyricsList* list, @@ -564,7 +641,8 @@ /** * Notification on arrival of subtitle based on filter. * Note if the list is large, then it can download the list page by page. - * In that case this signal is emitted multiple times. + * @param list List of subtitles + * @param error SmfNoError if success, else appropriate error value * @param resultPage Page number info */ void subtitleAvailable ( SmfSubtitleList* list, @@ -578,6 +656,7 @@ void customDataAvailable( const int& operationId, QByteArray* customData ); private: + /** * Gets the base provider info */