--- /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 <QObject>
+
+#include <qmobilityglobal.h>
+#include <qgeopositioninfo.h>
+
+#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<SmfMusicProfile> SmfMusicProfileList;
+typedef QList<SmfTrackInfo> SmfTrackInfoList;
+typedef QList<SmfEvents> SmfEventsList;
+typedef QList<SmfProvider> SmfProviderList;
+typedef QList<SmfPlaylist> SmfPlaylistList;
+typedef QList<SmfVenue> SmfVenueList;
+typedef QList<SmfLyrics> SmfLyricsList;
+typedef QList<SmfSubtitle> 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
+