File indexing completed on 2024-05-19 04:50:22
0001 /**************************************************************************************** 0002 * Copyright (c) 2007,2008 Casey Link <unnamedrambler@gmail.com> * 0003 * * 0004 * This program is free software; you can redistribute it and/or modify it under * 0005 * the terms of the GNU General Public License as published by the Free Software * 0006 * Foundation; either version 2 of the License, or (at your option) any later * 0007 * version. * 0008 * * 0009 * This program is distributed in the hope that it will be useful, but WITHOUT ANY * 0010 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A * 0011 * PARTICULAR PURPOSE. See the GNU General Public License for more details. * 0012 * * 0013 * You should have received a copy of the GNU General Public License along with * 0014 * this program. If not, see <http://www.gnu.org/licenses/>. * 0015 ****************************************************************************************/ 0016 0017 #ifndef MP3TUNESLOCKER_H 0018 #define MP3TUNESLOCKER_H 0019 0020 extern "C" { 0021 // Get libmp3tunes declarations 0022 #include "libmp3tunes/locker.h" 0023 } 0024 0025 #include "Mp3tunesLockerMeta.h" 0026 0027 #include <QString> 0028 #include <QList> 0029 0030 /** 0031 * A pseudo type to encapsulate the various return types from a search query. 0032 */ 0033 class Mp3tunesSearchResult { 0034 public: 0035 enum SearchType { 0036 ArtistQuery = 1, 0037 AlbumQuery = 2, 0038 TrackQuery = 4 0039 }; 0040 QList<Mp3tunesLockerArtist> artistList; 0041 QList<Mp3tunesLockerAlbum> albumList; 0042 QList<Mp3tunesLockerTrack> trackList; 0043 SearchType searchFor; 0044 }; 0045 0046 /** 0047 * A wrapper class for the libmp3tunes locker object. 0048 * @author Casey Link <unnamedrambler@gmail.com> 0049 */ 0050 class Mp3tunesLocker { 0051 public: 0052 0053 /** 0054 * Initialize the connection, but do not login. 0055 * @param partnerToken your partnerToken to access the mp3tunes API. 0056 */ 0057 explicit Mp3tunesLocker( const QString & partnerToken ); 0058 0059 /** 0060 * Initialize the connection, and login. 0061 * for testing use demo@mp3tunes.com:demo 0062 * @param partnerToken your partnerToken to access the mp3tunes API. 0063 * @param userName the username 0064 * @param password username's password 0065 */ 0066 Mp3tunesLocker( const QString & partnerToken, const QString & userName, const QString & password ); 0067 0068 ~Mp3tunesLocker(); 0069 0070 /** 0071 * Logs into the locker. 0072 * for testing use demo@mp3tunes.com:demo 0073 * @param userName the username 0074 * @param password username's password 0075 * @return if login successful, the sessionId is returned 0076 * if login failed, an empty QString is returned 0077 */ 0078 QString login( const QString & userName, const QString & password ); 0079 0080 /** 0081 * Logs into the locker using stored credentials. 0082 * Useful if a session is no longer valid. 0083 * @return if login successful, the sessionId is returned 0084 * if login failed, an empty QString is returned 0085 */ 0086 QString login(); 0087 0088 /** 0089 * Detects if a session has timed out. 0090 * @return true, if session is still valid. 0091 * false, if session is invalid. 0092 */ 0093 bool sessionValid() const; 0094 0095 /** 0096 * @return a list of all the artists in the locker 0097 */ 0098 QList<Mp3tunesLockerArtist> artists() const; 0099 0100 /** 0101 * Searches the locker for artists containing the query. 0102 * @param query the string to search for 0103 * @return a list of all the artists in the locker containing the query 0104 */ 0105 QList<Mp3tunesLockerArtist> artistsSearch( const QString &query ) const; 0106 0107 /** 0108 * @return a list of all the albums in the locker 0109 */ 0110 QList<Mp3tunesLockerAlbum> albums() const; 0111 0112 /** 0113 * Searches the locker for albums containing the query. 0114 * @param query the string to search for 0115 * @return a list of all the albums in the locker containing the query 0116 */ 0117 QList<Mp3tunesLockerAlbum> albumsSearch( const QString &query ) const; 0118 0119 /** 0120 * @param artistId the id of the artist to list albums for 0121 * @return a QList of albums belonging to the supplied artist 0122 */ 0123 QList<Mp3tunesLockerAlbum> albumsWithArtistId( int artistId ) const; 0124 0125 /** 0126 * @return a list of all the playlists in the locker 0127 */ 0128 QList<Mp3tunesLockerPlaylist> playlists() const; 0129 0130 /** 0131 * @return a list of all the tracks in the locker 0132 */ 0133 QList<Mp3tunesLockerTrack> tracks() const; 0134 0135 /** 0136 * Searches the locker for tracks containing the query. 0137 * @param query the string to search for 0138 * @return a list of all the tracks in the locker containing the query 0139 */ 0140 QList<Mp3tunesLockerTrack> tracksSearch( const QString &query ) const; 0141 0142 /** 0143 * @param playlistId a playlist id 0144 * @return a list of all the tracks with playlistId 0145 */ 0146 QList<Mp3tunesLockerTrack> tracksWithPlaylistId( const QString & playlistId) const; 0147 0148 /** 0149 * @param albumId an album id 0150 * @return a list of all the tracks with albumId 0151 */ 0152 QList<Mp3tunesLockerTrack> tracksWithAlbumId( int albumId ) const; 0153 0154 /** 0155 * @param artistId an artist Id 0156 * @return a list of all the tracks with artistId 0157 */ 0158 QList<Mp3tunesLockerTrack> tracksWithArtistId( int artistId ) const; 0159 0160 /** 0161 * Get a list of tracks from a list of filekeys. 0162 * @param filekeys a list of filekeys 0163 * @return a list of tracks that match the supplied filekeys. The returned list 0164 * of tracks be in the same order as the supplied filekeys. 0165 * Might return an empty List. 0166 */ 0167 QList<Mp3tunesLockerTrack> tracksWithFileKeys(const QStringList &filekeys ) const; 0168 0169 /** 0170 * Get a single track from a single filekey. 0171 * @param filekey the filekey to match to a track 0172 * @return the track that matches the filekey. 0173 */ 0174 Mp3tunesLockerTrack trackWithFileKey( const QString &filekey ) const; 0175 0176 /** 0177 * Searches the Locker for tracks, albums, and/or artists. 0178 * Which type it searches depends on the Mp3tunesSearchResult's 0179 * searchFor passed to it. 0180 * @pre Mp3tunesSearchResult's fields are initialized properly 0181 * depending on the types (artist, track album) you want searched. 0182 * Properly means: If you want a type searched initialize an empty 0183 * QList and set the appropriate SearchType bit. 0184 * @post The Mp3tunesSearchResult's fields will filled with the 0185 * search results. If the search returned empty, then the 0186 * QLists will be empty. 0187 * @param container contains the QList's to be filled with search results 0188 * @param query the query string 0189 * @return @c true if search succeeded. Note: Zero search results is not a failure. 0190 * @c false if search failed. 0191 */ 0192 bool search( Mp3tunesSearchResult &container, const QString &query ) const; 0193 0194 /** 0195 * Uploads a track to the locker using HTTP Put. 0196 * @param path the absolute filename of the track to upload 0197 * @return true if upload succeeded 0198 * false if upload failed 0199 * @pre The track exists and is a filetype that mp3tunes accepts. 0200 */ 0201 bool uploadTrack( const QString &path ); 0202 0203 /** 0204 * Generates the file key identifier for a media file. 0205 * @param path the absolute filename of the track 0206 * @return the file key 0207 * @pre The track exists and is a filetype that mp3tunes accepts. 0208 */ 0209 QString fileKey(const QString &path ); 0210 0211 /** 0212 * Loads a URL into the locker via the LockerLoad API. 0213 * The URL may be password protected, as long as the username 0214 * and password can be transferred in the URL to retrieve the 0215 * file. Any access control based on user sessions cannot be 0216 * used in locker loading. 0217 * @param url the full URL to the track 0218 * @return true if the lockerload succeeded 0219 * false if the lockerload failed. 0220 * @pre The URL must be accessible by the MP3tunes servers, 0221 * it is assumed that all the tracks in the file are 0222 * non-DRM music files. 0223 */ 0224 bool lockerLoad( const QString &url ); 0225 //TODO wrapper for mp3tunes_locker_generate_download_url_from_file_key 0226 //TODO wrapper for mp3tunes_locker_generate_download_url_from_file_key_and_bitrate 0227 //TODO wrapper for mp3tunes_locker_sync_down 0228 0229 QString userName() const; 0230 QString password() const; 0231 QString sessionId() const; 0232 QString firstName() const; 0233 QString lastName() const; 0234 QString nickName() const; 0235 QString partnerToken() const; 0236 QString serverApi() const; 0237 QString serverContent() const; 0238 QString serverLogin() const; 0239 QString errorMessage() const; 0240 bool authenticated() const; 0241 private: 0242 mp3tunes_locker_object_t *m_locker; 0243 }; 0244 #endif