ipod.h

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

Generated on Wed Nov 28 03:04:37 2007 for libqtpod by  doxygen 1.5.0