00001 /***************************************************************************** 00002 * * 00003 * Copyright (C) 2004-2006 by Michael Schulze * 00004 * mike.s@genion.de * 00005 * * 00006 * The code contained in this file is free software; you can redistribute * 00007 * it and/or modify it under the terms of the GNU Lesser General Public * 00008 * License as published by the Free Software Foundation; either version * 00009 * 2.1 of the License, or (at your option) any later version. * 00010 * * 00011 * This file is distributed in the hope that it will be useful, * 00012 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 00013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * 00014 * Lesser General Public License for more details. * 00015 * * 00016 * You should have received a copy of the GNU Lesser General Public * 00017 * License along with this code; if not, write to the Free Software * 00018 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA * 00019 * * 00020 * iTunes and iPod are trademarks of Apple * 00021 * * 00022 * This product is not supported/written/published by Apple! * 00023 *****************************************************************************/ 00024 00025 #ifndef IPOD_H 00026 #define IPOD_H 00027 00028 #include <qfile.h> 00029 #include <qstring.h> 00030 00031 #include "itunesdb.h" 00032 00033 #include "ipoddevicedetails.h" 00034 #include "ipodsysinfo.h" 00035 00036 #define LOGFILEPREFIX "/kio_ipod-" 00037 #define LOG_DEFAULT true 00038 00039 /** 00040 * @mainpage libqtpod - a C++ library providing access to the contents of an Apple iPod 00041 * 00042 * This library provides access to various information stored on an Apple iPod. 00043 * @n 00044 * At the moment this still depends on Trolltechs Qt library and I'll need help changing that 00045 * for future versions since as a library we should only depend on the standard C++ libraries. 00046 * @section Usage 00047 * The following chapter gives a short introduction on how to use the library to open the device 00048 * and access @ref itunesdb "tracks, playlist" and @ref statistics "disc usage statistics". 00049 * @n 00050 * @section ipod The IPod class 00051 * To access the contents of the ipod an instance of the IPod class needs to be instantiated 00052 * with the mountpoint/drive letter of the device and opened with a call to the IPod::open() method. 00053 * @n For linux this would probably something like that 00054 * @code 00055 * IPod ipod( "/media/ipod" ); 00056 * @endcode 00057 * and 00058 * @code 00059 * IPod ipod( "E:" ); 00060 * @endcode 00061 * in a Windows environment. 00062 * @see IPodMountPoint::mountedIPods() returning a list of ipods connected to the system. 00063 * The IPodMountPoint::getMountPoint() method returns the String to initialize the IPod class with. 00064 * 00065 * Open the device with open() 00066 * @code 00067 * if( !ipod.open() ) { 00068 * // failed 00069 * } 00070 * @endcode 00071 * After the IPod instance is opened the information stored on the device is accessible and can be retrieved. 00072 * @n 00073 * @section itunesdb Tracks and Playlists 00074 * Information about the tracks and playlists on the iPod device is stored in a database called ITunesDB and 00075 * libqtpod contains the class ITunesDB representing this database. 00076 * @n The now opened IPod instance holds an instance of this class which is accessible thru the IPod::getITunesDB() method: 00077 * @code 00078 * // get the iTunesDB instance 00079 * ITunesDB& itunesdb = ipod.getITunesDB(); 00080 * @endcode 00081 * @n Now we can iterate over the tracks stored on the device and print out artist, album, title and filename like this 00082 * @code 00083 * // get an Iterator over all tracks found on the device 00084 * ITunesDB::TrackConstIterator iter = itunesdb.getAllTracks(); 00085 * while( iter.hasNext() ) { 00086 * // get the next track 00087 * ITunesDBTrack * track = iter.next(); 00088 * // print track meta data 00089 * printf( "%s\t%s\t%s\t%s\n", 00090 * track->getArtist().ascii(), 00091 * track->getAlbum().ascii(), 00092 * track->getTitle().ascii(), 00093 * itunesdb.getFileForPathInfo( track->getPathInfo() ).ascii() ); 00094 * } 00095 * @endcode 00096 * @see ListTracksTest::run() in @ref listtrackstest.cpp "listtrackstest.cpp" in the "tests" directory for another example on how to list the tracks sorted by artist 00097 * 00098 * Changes made to the database can be easily written back to the device by calling the IPod::synchronize() method: 00099 * @code 00100 * // synchronize with the device 00101 * ipod.synchronize(); 00102 * @endcode 00103 * @n finally close your IPod instance when done 00104 * @code 00105 * ipod.close(); 00106 * @endcode 00107 * @see @ref listtests.cpp "listtests.cpp" showing listing of tracks, playlist and creating smart playlists 00108 * @see Other Testcases in the classes implementing Test in the "tests/" directory 00109 * @n 00110 * @section statistics Device Statistics 00111 * Access to the device statistics is implemented by the class IPodSysInfo accessible by calling getSysInfo() on your opened 00112 * IPod instance: 00113 * @code 00114 * IPodSysInfo& sysinfo = ipod.getSysInfo(); 00115 * @endcode 00116 */ 00117 00118 /** 00119 * @example listtrackstest.cpp 00120 * Example 1: listing of tests/listtrackstest.cpp 00121 */ 00122 00123 /** 00124 * @example listtests.cpp 00125 * Example2 - listtests.cpp showing listing of tracks, playlist and creating smart playlists 00126 */ 00127 00128 /** 00129 This class represents all functionalities to access and modify information about the iPod/itunesDB 00130 00131 @author Michael Schulze 00132 */ 00133 class IPod { 00134 public: 00135 00136 /** 00137 * @brief Constructs a new IPod instance for an iPod at the given path. 00138 * Does not actually read the contents - you need to open it with @c open(). 00139 */ 00140 IPod( const QString& ipodBase ); 00141 00142 /** 00143 * @brief The destructor. 00144 */ 00145 virtual ~IPod(); 00146 00147 /** 00148 * @brief Tries to open an ipod. 00149 * 00150 * That means reading all important information from the device. 00151 * @return true if successful, otherwise false 00152 */ 00153 bool open(); 00154 00155 /** 00156 * @brief Initializes this ipod by creating the nessessary directories and files. 00157 * 00158 * This IPod instance then contains the information about the 00159 * initialized ipod - no need to call open() afterwards. 00160 */ 00161 void initialize( const QString& title ); 00162 00163 /** 00164 * @brief Returns true if open() was called successfully for this instance. 00165 * @return true if open() was called successfully for this instance. 00166 */ 00167 bool isOpen(); 00168 00169 /** 00170 * @brief Returns true if the ipod represented by this instance is still connected to the system 00171 * @return true if the ipod represented by this instance is still connected to the system false otherwise 00172 */ 00173 bool isStillConnected(); 00174 00175 /** 00176 * @brief Clears all data we got from this instance whether or not it was changed. 00177 * 00178 * Resets the state of this instance. 00179 */ 00180 void close(); 00181 00182 /** 00183 * @brief Returns the name of the iPod 00184 * @return the name of the iPod as set in the device details 00185 */ 00186 QString getName() const; 00187 00188 /** 00189 * @brief Sets the name of the iPod. 00190 * 00191 * When the iPod is not opened (isOpen() == false) nothing is changed 00192 * @param name the new name for the iPod 00193 */ 00194 void setName(const QString& name); 00195 00196 /** 00197 * @brief Returns the error occured during read or write 00198 * @return the error occured during read or write 00199 */ 00200 const QString& getItunesDBError() const; 00201 00202 /** 00203 * @brief Returns the IPodSysInfo for this IPod instance (const). 00204 * @return the IPodSysInfo for this IPod instance. 00205 */ 00206 const IPodSysInfo& getSysInfo() const; 00207 00208 /** 00209 * @brief Returns the IPodSysInfo for this IPod instance. 00210 * @return the IPodSysInfo for this IPod instance. 00211 */ 00212 IPodSysInfo& getSysInfo(); 00213 00214 /** 00215 * @brief Returns the ITunesDB for this iPod (const). 00216 * @return the ITunesDB for this iPod. 00217 */ 00218 const ITunesDB& getITunesDB() const; 00219 00220 /** 00221 * @brief Returns the ITunesDB for this iPod. 00222 * @return the ITunesDB for this iPod. 00223 */ 00224 ITunesDB& getITunesDB(); 00225 00226 /** 00227 * @brief Writes back all the changed data to the device. 00228 * 00229 * This only includes control structures like the iTunesDB and DeviceInfo data. 00230 */ 00231 void synchronize(); 00232 00233 /** 00234 * @brief Returns true if this instances data differ somehow from the original 00235 * 00236 * data from the iPod and need to be synchronized. 00237 */ 00238 bool isDirty() const { return m_itunesdb.isDirty(); } 00239 00240 /** 00241 * @brief Lock control functions to prevent concurrent access to the iPod from different programs 00242 * 00243 * locks the iPod 00244 * @param write_lock if true the ipod will be locked exclusively 00245 * @attention not implemented for win32 00246 */ 00247 void lock(bool write_lock); 00248 00249 /** 00250 * @brief Returns true if the iPod got locked 00251 * @return true if the iPod got locked 00252 */ 00253 bool isLocked(); 00254 00255 /** 00256 * @brief unlock an iPod previously locked 00257 */ 00258 void unlock(); 00259 00260 /** 00261 * @brief Returns the base path of the iPod 00262 * 00263 * (i.e. "/media/ipod" on linux or "E:" on a windows machine) 00264 * @return the base path of the iPod 00265 */ 00266 const QString& getBasePath() const { return m_ipodBase; } 00267 00268 /** 00269 * This method creates a string containing the ipod base path encoded 00270 * being distinct between different iPods simultanously connected to the system. 00271 * Most users wont need this method - it's here as a relict from the old ipodslave code 00272 * and may go away in the future 00273 * @deprecated this method doesn't belong here 00274 */ 00275 static QString createDistinctIPodName(const IPod& ipod) __attribute__((deprecated)); 00276 00277 // This method can be removed when we're able to handle podcasts 00278 bool hasPodcasts() { return m_itunesdb.hasPodcasts(); } 00279 00280 /** 00281 * @brief Finds all the files in the Music folders that don't have a track record 00282 * 00283 * The fully qualified pathes will be added to the given list. 00284 * @param list the list to add the unreferences files to 00285 * @return the reference to the given list 00286 */ 00287 QStringList& findUnreferencedMusicFiles( QStringList& list ) const; 00288 00289 protected: 00290 QString m_ipodBase; 00291 00292 private: 00293 IPodSysInfo m_sysInfo; 00294 ITunesDB m_itunesdb; 00295 IPodDeviceDetails m_deviceDetails; 00296 00297 }; 00298 00299 #endif