diff -r 5d2360e70d9f -r 4b1e636e8a71 example/clientapi/smf/inc/smfclient/smfmusic.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/example/clientapi/smf/inc/smfclient/smfmusic.h Thu Mar 25 14:44:08 2010 +0530 @@ -0,0 +1,504 @@ +/* +* Copyright (c) 2010 Sasken Communication Technologies Ltd. +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of the "{License}" +* which accompanies this distribution, and is available +* at the URL "{LicenseUrl}". +* +* Initial Contributors: +* Chandradeep Gandhi, Sasken Communication Technologies Ltd - Initial contribution +* +* Contributors: +* +* Description: +* Interface spefication for music related services +* +*/ + +#ifndef SMFMUSIC_H +#define SMMUSIC_H + +#include + +#include +#include + +#include "smfprovider.h" +#include "smfcontact.h" + + +class SmfProvider; //basic Smf service Provider info +class SmfContact; // Smf contact +class SmfMusicRating;//rating value from 0..31 - services would map accordingly +class SmfMusicProfile; //user profile containing music usage and interest info, extends SmfContact +class SmfTrackInfo; //id, title, album, artist, genre, tag, director,release year, rating, comment info +class SmfMusicFingerPrint; //generation is not in scope of smf +class SmfVenue; +class SmfMusicModel; +class SmfEvents; +class SmfPlaylist; +class SmfLyricsService; +class SmfLyrics; +class SmfSubtitle; +class SmfSubtitleSearchFilter; + +typedef QList SmfMusicProfileList; +typedef QList SmfTrackInfoList; +typedef QList SmfEventsList; +typedef QList SmfProviderList; +typedef QList SmfPlaylistList; +typedef QList SmfVenueList; +typedef QList SmfLyricsList; +typedef QList SmfSubtitleList; +/** + * Basic music service ("org.symbian.smf.client.music.service") + */ +class SMFCLIENT_EXPORT SmfMusicService : public QObject +{ + Q_OBJECT + +public: + /** + * Constructs SmfMusicService. + * @param baseProvider The base provider info + * Seeing as this is a plug-in implementation, these will realistically + * be generated by SMF factory of some kind + */ + SmfMusicService(SmfProvider* baseProvider = 0); + ~SmfMusicService(); + +public: + + /** + * Gets self profile information asynchronously. + * userInfoAvailable() signal is emitted with SmfMusicProfile when the info is arrived + */ + virtual void userinfo() = 0; + + /** + * Asynchronously searches information about other service users for a particular venue + * serachInfoAvailable() signal is emitted with SmfMusicProfileList when the info is arrived + */ + virtual void searchUser(SmfVenue venue) = 0; + + /** + * Returns the model + */ + virtual SmfMusicModel model() = 0; // maybe we can make a QItemModel-derived model? + + //APIs to get/set base provider info (SmfProvider) + + /** + * Gets the base provider info + */ + virtual SmfProvider* getProvider() = 0; + + /** + * Sets the base provider info + */ + virtual void setProvider(SmfProvider* provider) = 0; + +signals: + /** + * Notification on arrival of the self profile as result of userinfo(). + * @param profile The self profile + */ + void userInfoAvailable(SmfMusicProfile* profile, QString error); +private: + SmfProvider* m_baseProvider; +}; +SMF_GETSERVICES(SmfMusicService, "org.symbian.smf.client.music.service\0.2") + + +/** +* Provides service ("org.symbian.smf.client.music.search") for music search +*/ +class SMFCLIENT_EXPORT SmfMusicSearch : public QObject +{ + Q_OBJECT + +public: + /** + * Constructs SmfMusicSearch with base provider as arguement. + * Seeing as this is a plug-in implementation, these will realistically + * be generated by SMF factory of some kind + */ + + SmfMusicSearch(SmfProvider* baseProvider = 0); + ~SmfMusicSearch(); + +public: + // Get the track listing - might be made asynchrnous later + + /** + * Searches for music recommendations similar to a particulartrack asynchronously. + * The signal trackSearchAvailable() is emitted with SmfTrackInfoList + * once its arrived. + * @param track The track for which similar recommendations need to be fetched. + */ + virtual void recommendations(SmfTrackInfo track) = 0; // basic list of track objects + + /** + * Searches for tracks similar to a given track asynchronously. + * The signal trackSearchAvailable() is emitted with SmfTrackInfoList + * once its arrived. + * @param track The search criteria, similar tracks are searched + */ + virtual void tracks(SmfTrackInfo track) = 0; // basic list of track objects + + /** + * Searches for a track having similar finger print asynchronously. + * The signal trackSearchAvailable() is emitted with SmfTrackInfoList + * once its arrived. + * @param signature The search criteria,signature to be searched for + */ + virtual void trackInfo(SmfMusicFingerPrint signature) = 0; // search by fingerprint object + + /** + * Search information about where to buy this song from asynchronously. + * The signal storeSearchAvailable() is emitted with SmfProviderList once its arrived. + * @param track The search criteria for stores + */ + virtual void stores(SmfTrackInfo track) = 0; + + //APIs to get/set base provider info (SmfProvider) + + /** + * Gets the base provider info + */ + virtual SmfProvider* getProvider() = 0; + + /** + * Sets the base provider info + */ + virtual void setProvider(SmfProvider* provider) = 0; + +public slots: + + /** + * Posts currently playing track. + * Success can be checked by checking the signal postFinished() + * @param track Track to post + */ + virtual void postCurrentPlaying(SmfTrackInfo track) = 0; + //virtual int postRating(SmfTrackInfo track, SmfMusicRating rate) = 0; + //virtual int postComments(SmfTrackInfo track, SmfComment comment) = 0; + +signals: + /** + * Emitted when the search result for a track 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 The search result + */ + void trackSearchAvailable(SmfTrackInfoList* result, QString error, int pageNumber=0); + + /** + * 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 The search result + */ + void storeSearchAvailable(SmfProviderList* result, QString error, int pageNumber=0); +private: + SmfProvider* m_baseProvider; +}; +SMF_GETSERVICES(SmfMusicSearch, "org.symbian.smf.client.music.search\0.2") + + +/** + * Remote playlist + */ +class SMFCLIENT_EXPORT SmfPlaylist : public QObject + { + Q_OBJECT + +public: + SmfPlaylist(); + ~SmfPlaylist(); + + /** + * Gets tracks in the playlist + */ + SmfTrackInfoList* getTrackList(); + + /** + * Gets playlist title + */ + QString getPlayListTitle(); + + /** + * Gets the creation date + */ + QDateTime getCreationDate(); + + /** + * Sets tracks in the playlist + */ + void setTrackList(SmfTrackInfoList* trackList); + + /** + * Sets playlist title + */ + void setPlayListTitle(QString title); + + /** + * Sets creation date + */ + void setCreationDate(QDateTime time); + +private: + SmfTrackInfoList* m_trackList; + QString m_title; + QDateTime m_creationDate; + }; + + +/** + * provides service ("org.symbian.smf.client.music.playlist") + * + * Interface to a remote playlist service. This class + * provides some basic functionality to allow applications + * to interact with playlists in some music related service provider (e.g. last.fm). + * + * Note that branding information for the particular service implementation + * is available from getProvider() API. See also: + * SmfProvider::serviceName(), SmfProvider::serviceIcon() + * + * All of the functionality described here should be implemented by a service + * specific plug-in object. + * + */ +class SMFCLIENT_EXPORT SmfPlaylistService : public QObject +{ + Q_OBJECT + +public: + /** + * Constructs SmfPlaylistService with base provider info + * Seeing as this is a plug-in implementation, these will realistically + * be generated by SMF factory of some kind + */ + SmfPlaylistService(SmfProvider* baseProvider = 0); + ~SmfPlaylistService(); + +public: + + /** + * Gets the list playlists for the logged-in user asynchronously. + * The signal playlistsListAvailable() signal is emitted with + * SmfPlaylistList once its arrived + */ + virtual void playlists() = 0; // basic list of playlist objects + + /** + * Gets the list playlists for the given user asynchronously. + * The signal playlistsListAvailable() signal is emitted with + * SmfPlaylistList once its arrived. + * @param user User for which to get the playlists + */ + virtual void playlistsOf(SmfMusicProfile* user) = 0; + + //APIs to get/set base provider info (SmfProvider) + + /** + * Gets the base provider info + */ + virtual SmfProvider* getProvider() = 0; + + /** + * Sets the base provider info + */ + virtual void setProvider(SmfProvider* provider) = 0; + +public slots: + + /** + * Upload currently playing track to a playlist. Signal + * playlistUpdated() can be checked for success value + * @param plst The playlist to be added in + * @param tracks The list of tracks to uploaded + */ + virtual int addToPlaylist(SmfPlaylist plst, SmfTrackInfoList* tracks) = 0; + + /** + * Upload currently playing playlist . Signal + * playlistUpdated() can be checked for success value + * @param plst The playlist to be uploaded + */ + virtual int postCurrentPlayingPlaylist(SmfPlaylist plst) = 0; + + +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. + */ + void playlistsListAvailable(SmfPlaylistList*, QString error, int pageNumber=0); + /** + * Signals remote updation of playlist with success value + */ + int playlistUpdated(bool success) ; +private: + SmfProvider* m_baseProvider; +}; +SMF_GETSERVICES(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); + ~SmfMusicEvents(); + +public: + + /** + * Gets list of events in a particular location asynchronously. + * eventsAvailable() signal is emitted with SmfEventsList once its arrived + */ + virtual void events(QtMobility::QContactGeolocation location) = 0; + + /** + * Gets list of venues of a particular location asynchronously. + * venuesAvailable() signal is emitted with SmfVenueList once its arrived. + */ + virtual void venues(QtMobility::QContactGeolocation location) = 0; // basic list of venue objects + + /** + * Gets list of events in a particular venue asynchronously. + * eventsAvailable() signal is emitted with SmfEventsList once its arrived + */ + virtual void events(SmfVenue venue) = 0; // basic list of events objects + + + //APIs to get/set base provider info (SmfProvider) + + /** + * Gets the base provider info + */ + virtual SmfProvider* getProvider() = 0; + + /** + * Sets the base provider info + */ + virtual void setProvider(SmfProvider* provider) = 0; + +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 + */ + virtual void postEvents(SmfEventsList events); + +signals: + + /** + * Notification of the success of request to post an event + */ + void eventsUpdated(bool success); + + /** + * 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. + */ + void eventsAvailable(SmfEventsList* list, QString error, int pageNumber=0); + + /** + * 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. + */ + void venuesAvailable(SmfVenueList* list, QString error, int pageNumber=0); +private: + SmfProvider* m_baseProvider; +}; +SMF_GETSERVICES(SmfMusicEvents, "org.symbian.smf.client.music.events\0.2") + + +/** +* provides service ("org.symbian.smf.client.music.lyrics") +*/ +class SMFCLIENT_EXPORT SmfLyricsService : public QObject +{ + Q_OBJECT + +public: + /** + * Constructs SmfLyricsService with base provider info. + * Seeing as this is a plug-in implementation, these will realistically + * be generated by SMF factory of some kind + */ + + SmfLyricsService(SmfProvider* baseProvider = 0); + ~SmfLyricsService(); + +public: + + /** + * Get the lyrics lists asynchrnously, it fetches texts without time info. + * lyricsAvailable() notification comes SmfLyricsList with when the data is available + * @param track Track for which lyrics needs to be fetched. + */ + virtual void lyrics(SmfTrackInfo track) = 0; + + /** + * Get the lyrics lists asynchrnously, it fetches texts with time info. + * Subtitle search filter can be applied + * subtitleAvailable() notification comes SmfSubtitleList with when the data is available + * @param track Track for which subtitle needs to be fetched. + * @param filter Subtitle search filter + */ + virtual void subtitles(SmfTrackInfo track, SmfSubtitleSearchFilter filter) = 0; // texts with time information + //APIs to get/set base provider info (SmfProvider) + + /** + * Gets the base provider info + */ + virtual SmfProvider* getProvider() = 0; + + /** + * Sets the base provider info + */ + virtual void setProvider(SmfProvider* provider) = 0; + +public slots: + + +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. + */ + void lyricsAvailable(SmfLyricsList* list, QString error, int pageNumber=0); + + /** + * 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. + */ + void subtitleAvailable(SmfSubtitleList* list, QString error, int pageNumber=0); +private: + SmfProvider* m_baseProvider; +}; +SMF_GETSERVICES(SmfLyricsService, "org.symbian.smf.client.music.lyrics\0.2") + +#endif // SMFMUSIC_H +