itunesdb.h

00001  /*****************************************************************************
00002  *   Copyright (C) 2004 by Michael Schulze                                    *
00003  *   mike.s@genion.de                                                         *
00004  *                                                                            *
00005  *  The code contained in this file is free software; you can redistribute    *
00006  *  it and/or modify it under the terms of the GNU Lesser General Public      *
00007  *  License as published by the Free Software Foundation; either version      *
00008  *  2.1 of the License, or (at your option) any later version.                *
00009  *                                                                            *
00010  *  This file is distributed in the hope that it will be useful,              *
00011  *  but WITHOUT ANY WARRANTY; without even the implied warranty of            *
00012  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU         *
00013  *  Lesser General Public License for more details.                           *
00014  *                                                                            *
00015  *  You should have received a copy of the GNU Lesser General Public          *
00016  *  License along with this code; if not, write to the Free Software          *
00017  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA *
00018  *                                                                            *
00019  *  iTunes and iPod are trademarks of Apple                                   *
00020  *                                                                            *
00021  *  This product is not supported/written/published by Apple!                 *
00022  *****************************************************************************/
00023 
00024 #ifndef ITUNESDB_H
00025 #define ITUNESDB_H
00026 
00027 #include <qdatetime.h>
00028 #include <qfile.h>
00029 #include <qstringlist.h>
00030 
00031 #include "playlist.h"
00032 #include "playlistitem.h"
00033 #include "track.h"
00034 #include "ipodsysinfo.h"
00035 #include "utils.h"
00036 
00037 #define RECENTLY_PLAYED_LIST_NAME "KPOD:Recently Played"
00038 
00039 /**
00040 @author Michael Schulze
00041 */
00042 
00043 class ITunesDBTrack : public itunesdb::Track, itunesdb::utils::NonCopyAble {
00044 
00045     friend class ITunesDB;
00046 
00047     class ITunesDB& m_itunesdb;
00048 
00049     ITunesDBTrack( Q_UINT32 trackid, ITunesDB& itunesdb );
00050     ITunesDBTrack( const ITunesDBTrack& src );
00051 
00052 public:
00053     virtual ~ITunesDBTrack();
00054 
00055     void setDateAdded( Q_UINT32 date );
00056 
00057     /**
00058      * Returns the file on the iPod this Track instance refers to.
00059      */
00060     QString getFilePath() const;
00061 
00062 protected:
00063     virtual void setDirty( bool dirtyFlag = true );
00064 };
00065 
00066 
00067 /**
00068  * This class represents all the rules and limits making up a smart playlist.
00069  * see @c itunesdb::SmartPlaylistRuleSet for further information.
00070  */
00071 class ITunesDBSPLRuleSet
00072     : public itunesdb::SmartPlaylistRuleSet,
00073       public itunesdb::TrackPredicate,
00074       itunesdb::utils::NonCopyAble
00075 {
00076 
00077     const class ITunesDB& mItunesdb;
00078     class ITunesDBPlaylist& mPlaylist;
00079 
00080     itunesdb::TrackComparatorPtr getComparatorFor( itunesdb::SPLLimitSort limitSort ) const;
00081 
00082     void applyLimits( itunesdb::TrackPtrList& trackList ) const;
00083 
00084     uint mLastSeenItunesDBVersion;
00085     uint mLastSeenRuleSetVersion;
00086     uint mRuleSetVersion;
00087 
00088 protected:
00089 
00090     virtual itunesdb::SmartPlaylistRule * createStringRule(
00091         itunesdb::SPLStringField field,
00092         itunesdb::SPLStringAction action,
00093         const QString& testString );
00094 
00095     virtual itunesdb::SmartPlaylistRule * createUIntRule(
00096         itunesdb::SPLUIntField field, itunesdb::SPLUIntAction action,
00097         Q_UINT64 fromValue, Q_UINT64 toValue,
00098         Q_INT64  fromDate,  Q_INT64  toDate,
00099         Q_UINT64 fromUnits, Q_UINT64 toUnits );
00100 
00101     virtual bool operator() ( const itunesdb::Track * track ) const;
00102 
00103 public:
00104 
00105     ITunesDBSPLRuleSet( const itunesdb::SmartPlaylistRuleSet& src,
00106                         ITunesDBPlaylist& playlist, const ITunesDB& itunesdb );
00107 
00108     ITunesDBSPLRuleSet( ITunesDBPlaylist& playlist, const ITunesDB& itunesdb );
00109 
00110     virtual ~ITunesDBSPLRuleSet();
00111 
00112     /**
00113      * adds a string based rule to the rule set and returns true if successful.
00114      */
00115     virtual bool addStringRule( itunesdb::SPLStringField field,
00116                  itunesdb::SPLStringAction action, const QString& testString, int position = -1 );
00117 
00118     /**
00119      * adds a uint based rule to the rule set and returns true if successful.
00120      */
00121     virtual bool addUIntRule( itunesdb::SPLUIntField field,
00122                               itunesdb::SPLUIntAction action,
00123                               Q_UINT64 fromValue, Q_UINT64 toValue,
00124                                Q_INT64 fromDate,   Q_INT64 toDate,
00125                               Q_UINT64 fromUnits, Q_UINT64 toUnits,
00126                               int position = -1 );
00127 
00128     /**
00129      * Refreshes the playlist associated with this set of rules. If the database didn't
00130      * change since the last refresh and @c force is false the playlist won't be updated.
00131      * @param force forces the rule set to update the playlist even if the database didn't change.
00132      */
00133     void refreshPlaylist( bool force = false );
00134 
00135 };
00136 
00137 
00138 /**
00139  * Special playlist implementation to use with the ITunesDB class. This adds important
00140  * functionalities like setting the sort order and updating the contents of smart playlists.<br>
00141  * To create a new ITunesDBPlaylist instance use the
00142  * @c ITunesDB::createNewPlaylist( const QString& ) factory method and use the
00143  * @c ITunesDB::addPlaylist( ITunesDBPlaylist* ) to add it to the database.<br>
00144  * Here is an example on how to create a "recently played" Smart Playlist:
00145  * <pre><code>
00146  *  // create a new playlist
00147  *  ITunesDBPlaylist * recentlyPlayed = itunesdb.createNewPlaylist( "recently played" );
00148  *  recentlyPlayed->setSortOrder( Playlist::SORTORDER_TIME_PLAYED );
00149  *
00150  *  // make it a smart playlist and get the ruleset
00151  *  SmartPlaylistRuleSet& ruleSet = recentlyPlayed->enableSmartPlaylist();
00152  *
00153  *  // add the rule "last played in the last 2 weeks"
00154  *  ruleSet.addInTheLastRule( FIELD_LASTPLAYED, false, -2, IN_THE_LAST_WEEKS );
00155  *
00156  *  // limit to the first 30 songs, sorted by last played date
00157  *  ruleSet.setLimits( LIMIT_SORT_LASTPLAYED, LIMIT_TYPE_SONGS, 30 );
00158  *
00159  *  // match ANY rule (doesn't really matter since we only have one rule)
00160  *  ruleSet.setMatchAnyFlag( true );
00161  *
00162  *  // enable live update (updates the playlist on the go)
00163  *  ruleSet.setLiveUpdateFlag( true );
00164  *
00165  *  // finally add the playlist to the database
00166  *  itunesdb.addPlaylist( recentlyPlayed );
00167  * </code></pre>
00168  */
00169 class ITunesDBPlaylist : public itunesdb::Playlist {
00170 
00171     friend class ITunesDB;
00172 
00173     ITunesDB& m_itunesdb;
00174     ITunesDBPlaylist( const ITunesDBPlaylist& );
00175     ITunesDBPlaylist( ITunesDB& itunesdb );
00176     ITunesDBPlaylist( ITunesDB& itunesdb, const itunesdb::Playlist& playlist );
00177     itunesdb::TrackComparatorPtr getTrackComparatorFor( Q_UINT32 sortOrder );
00178 
00179     /**
00180      * @see @c itunesdb::ListItem
00181      */
00182     void doPostParsingChecks();
00183 
00184 public:
00185 
00186     /**
00187      * An entry in this playlist. It directly refers to an existing track in the
00188      * database.
00189      */
00190     class Entry : public itunesdb::PlaylistItem {
00191         friend class ITunesDBPlaylist;
00192         unsigned int m_mhitTrackPos;
00193         Entry( Q_UINT32 id, uint trackpos );
00194     public:
00195         virtual ~Entry();
00196 
00197         unsigned int getMHITTrackPos() const {
00198             return m_mhitTrackPos;
00199         }
00200     };
00201 
00202     virtual ~ITunesDBPlaylist();
00203 
00204     /**
00205      * Creates a new instance of the Entry class.
00206      */
00207     virtual itunesdb::PlaylistItem * createNewItem( Q_UINT32 itemid );
00208 
00209     /**
00210      * Updates the content of this smart playlist against the database
00211      * Nothing happens if this playlist is not a smart playlist.
00212      * @see itunesdb::Playlist::enableSmartPlaylist()
00213      * @see itunesdb::Playlist::getSmartPlaylistRules()
00214      */
00215     void updateSmartPlaylist( bool force = false );
00216 
00217     /**
00218      * Sets the sort order field.
00219      * @see itunesdb::Playlist::ItdbPlaylistSortOrder
00220      */
00221     void setSortOrder( Sortorder sortOrder );
00222 
00223     /**
00224      * Returns the track the playlist entry at the given position is referring to
00225      */
00226     ITunesDBTrack * getTrackAt( uint position ) const;
00227 
00228     /**
00229      * Returns the track for a given playlist item
00230      * @param plItem the PlaylistItem to get the referred track 
00231      * @return the track for the given playlist item
00232      */
00233     ITunesDBTrack * getTrack( const itunesdb::PlaylistItem& plItem ) const;
00234 
00235 protected:
00236 
00237     /**
00238      * reads mhods with type above type 15 (mhods not containing strings)
00239      */
00240     virtual void readNonStringMHOD( QDataStream& stream, Q_UINT32 type, Q_UINT32 blocklen );
00241 
00242     virtual void setDirty( bool dirtyFlag = true );
00243 
00244     virtual itunesdb::SmartPlaylistRuleSet * createNewSplRuleSet();
00245 
00246 };
00247 
00248 
00249 /**
00250  * Class representing the contents of your iPods ITunesDB file
00251  */
00252 class ITunesDB : itunesdb::utils::NonCopyAble {
00253     class ItunesDBReaderAdapter;    // Adapter class for reading the itunesdb file
00254     class ItunesDBWriterAdapter;    // Adapter class for writing the itunesdb file
00255 
00256     // friends
00257     friend class ITunesDBPlaylist;
00258     friend class ITunesDBSPLRuleSet;
00259     friend class ITunesDBTrack;
00260 
00261     typedef std::map<Q_UINT32,uint> TrackIDMap;
00262 
00263     bool mDoDirtyFlagHandling;
00264     uint mInternalVersion;
00265 
00266     // TODO implement shared PImpl thus making it copyable
00267 
00268 public:
00269 
00270     typedef itunesdb::utils::SortablePtrVector<ITunesDBTrack> TrackList;
00271 
00272     /**
00273      * @brief An Iterator over a sequence of ITunesDBTrack instances
00274      *
00275      * An Iterator over all ITunesDBTrack instances matching the given predicate, delivering pointers
00276      * to ITunesDBTrack instances by its next() method
00277      */
00278     template <typename TrackPredicate_T = itunesdb::TrackPredicates::AllTracks>
00279     struct FilteredTrackConstIterator
00280         : public TrackList::FilteredConstIterator<TrackPredicate_T> {
00281 
00282         /**
00283          * @brief Creates a new FilteredTrackConstIterator over all ITunesDBTrack instances matching the given predicate.
00284          * @param container the main TrackList to iterate over
00285          * @param predicate the predicate to match the tracks against
00286          */
00287         FilteredTrackConstIterator( const TrackList& tracklst, const TrackPredicate_T& pred =
00288             TrackPredicate_T() )
00289                 : TrackList::FilteredConstIterator<TrackPredicate_T>( tracklst, pred ) {}
00290     };
00291     typedef FilteredTrackConstIterator<> TrackConstIterator;
00292 
00293     QString error;
00294 
00295     ITunesDB( IPodSysInfo& ipodSysInfo );
00296 
00297     virtual ~ITunesDB();
00298 
00299     /**
00300      * @brief Opens the itunesdb file at the given ipod mountpoint
00301      * @return true if the itunesdb does exist and could be opened. For parse errors check the error member afterwards
00302      */
00303     bool open();
00304 
00305     /**
00306      * @brief Returns true if open() has already been successfully called.
00307      * @return true if open has already been successfully called, false otherwise
00308      */
00309     bool isOpen();
00310 
00311     /**
00312      * @brief Writes the (changed) database back to the ipod
00313      * @param filename the name of the file to be written. If no filename is given the database will be written to the file read whith open()
00314      * @return true if writing the database was successful
00315      */
00316     bool writeDatabase(const QString& filename = QString());
00317 
00318     /**
00319      * @brief Returns true if the itunesdb file has been changed thus needs to be reloaded or does not exist anymore
00320      * @return true if the itunesdb file has been changed
00321      */
00322     bool dbFileChanged() const;
00323 
00324     /**
00325      * @brief Returns the name of the filename given with the open() call
00326      */
00327     QString getFilename() const { return itunesdbfile.name(); }
00328 
00329     /**
00330      * @brief Creates a new empty playlist
00331      */
00332     ITunesDBPlaylist * createNewPlaylist( const QString& title );
00333 
00334     /**
00335      * @brief Creates a new empty track
00336      *
00337      * Only use this function if you know what you're doing.
00338      * @see createNewTrack() for the right way to create a new Track
00339      * @param trackid the id of the new track in the database.
00340      */
00341     ITunesDBTrack * createEmptyTrack( Q_UINT32 trackid );
00342 
00343     /**
00344      * @brief Returns a new itunesdb::Track instance for adding a new track to the database.
00345      *
00346      * The new instance gets initialized with an unused trackid and trackpath.
00347      * Subsequent calls will get itunesdb::Track with the same trackid until the returned track is as added
00348      * via addTrack() thus a call to addTrack() has to be done afterwards.
00349      * @param fileExtension file extension of the file representing the track. If you don't know the file extension yet leave empty and set it with Track::setFileExtension() later
00350      */
00351     ITunesDBTrack * createNewTrack( const QString& fileExtension = QString::null );
00352 
00353     /**
00354      * @brief Adds a new track to the database.
00355      *
00356      * This only adds the control information to the database, the track itself (the file) has to by copied by the calling application.
00357      * @param track the track to add to the database
00358      * @return true if the track was successfully added
00359      */
00360     bool addTrack( ITunesDBTrack * track );
00361 
00362     /**
00363      * @brief Returns the Track corresponding to the given ID
00364      * @param id ID of the track
00365      * @return the Track corresponding to the given ID
00366      */
00367     ITunesDBTrack * getTrackByID( const Q_UINT32 id ) const;
00368 
00369     /**
00370      * @brief Returns the first track found with the given dbid
00371      * @param dbid the 64bit DBID being unique for all objects in the database
00372      * @return the Track corresponding to the given DBID
00373      */
00374     ITunesDBTrack * findTrackByDBID( const Q_UINT64 dbid ) const;
00375 
00376     /**
00377      * @brief Returns the MHIT position of the track with the given ID
00378      * @param id ID of the track
00379      * @return the position of the track in the MHIT section or -1 if there's no such track.
00380      */
00381     int getMHITTrackPosFor( Q_UINT32 id ) const;
00382 
00383     /**
00384      * @brief Returns the Track at the specified position in the itunesdb
00385      * @param mhitTrackPos the position of the desired track
00386      * @return the track at the specified position or NULL if the given position is out of range
00387      */
00388     ITunesDBTrack * getTrackAt( uint mhitTrackPos) const;
00389 
00390     /**
00391      * @brief Returns the first Track where the given predicate returned true
00392      *
00393      * The given trackpredicate needs to contain a method that gets a track, and returns a bool
00394      * if it's the desired track
00395      * @return the first Track where the given predicate returned true
00396      * @see TrackPredicate for details about TrackPredicates
00397      */
00398     ITunesDBTrack * findFirstTrackBy( const itunesdb::TrackPredicate& predicate ) const;
00399 
00400     /**
00401      * @brief Returns all the Tracks where the given @c itunesdb::TrackPredicate returned true
00402      *
00403      * More formally the method fills in the Tracks where the given @c itunesdb::TrackPredicate
00404      * returned true into the given TrackPtrList and returns a pointer to the list if at least
00405      * one track got added.
00406      * @see getTracksBy() function below for a better way to get access to a sequence of tracks.
00407      * The returned iterator will deliver ITunesDBTrack instances with some extra functionalities.
00408      * @see itunesdb::TrackPredicates for a list of predefined predicates
00409      */
00410     itunesdb::TrackPtrList * getTracksBy( const itunesdb::TrackPredicate& predicate, itunesdb::TrackPtrList& buffer ) const;
00411 
00412     /**
00413      * @brief Returns all the Tracks where the given @c itunesdb::TrackPredicate returns true
00414      *
00415      * The next() method of the returned Iterator delivers pointers to ITunesDBTrack instances
00416      * @see itunesdb::TrackPredicates for a list of predefined predicates
00417      * @return an iterator over the Tracks where the given @c itunesdb::TrackPredicate returns true
00418      */
00419     template <typename TrackPredicate_T>
00420     inline FilteredTrackConstIterator<TrackPredicate_T> getTracksBy( const TrackPredicate_T& predicate ) const {
00421         return FilteredTrackConstIterator<TrackPredicate_T>( m_TrackList, predicate );
00422     }
00423 
00424     /**
00425      * @brief Returns the Track found by the given information or NULL if no such Track could be found
00426      * @param artistname the name of the artist
00427      * @param albumname the name of the album
00428      * @param title the title of the track
00429      * @param trackNum the position of the track in its album
00430      * @return the Track found or NULL if no track matched the given criteria.
00431      */
00432     ITunesDBTrack * findTrack(const QString& artistname, const QString& albumname, const QString& title, Q_UINT32 trackNum = 0 ) const;
00433 
00434     /**
00435      * @brief Fills the given QStringList with the names of all artists in the database
00436      * @param buffer a QStringList to fill in the artist names
00437      * @return a pointer to the StringList
00438      */
00439     QStringList * getArtists( QStringList& buffer ) const;
00440 
00441     /**
00442      * @brief Fills the given QStringList with the names of all albums in the database
00443      */
00444     QStringList * getAllAlbums( QStringList& buffer ) const;
00445 
00446     /**
00447      * @brief Fills the given QStringList with the names of the albums by the given artist
00448      * @param artistname the name of the artist to look for
00449      * @param buffer the list to put the names of the albums found
00450      * @return a pointer to the given QStringList or NULL if no such artist exists
00451      */
00452     QStringList * getAlbumsByArtist( const QString& artistname, QStringList& buffer ) const;
00453 
00454     /**
00455      * @brief Returns true if the given artist exists.
00456      * @param artistname the artists name to check for.
00457      * @return true if the artist exists, false otherwise.
00458      */
00459     bool containsArtist( const QString& artistname ) const;
00460 
00461     /**
00462      * @brief Returns true if the given album exists.
00463      * @param artistname the artists name to check for
00464      * @param albumname the name of the album
00465      * @return true if such an album exists for the given artist, false otherwise.
00466      */
00467     bool containsAlbum( const QString& artistname, const QString& albumname ) const;
00468 
00469     /**
00470      * @brief Fills the given TrackPtrList with all itunesdb::Track instances in the database.
00471      *
00472      * Fills the given TrackPtrList with all itunesdb::Track instances in the database and returns
00473      * a pointer to the given list.
00474      * @see getAllTracks() function below for a better way to get access to a sequence of tracks.
00475      * The returned iterator will deliver ITunesDBTrack instances with some extra functionalities.
00476      * @param buffer the list to put the tracks into.
00477      * @return the pointer to the given filled list
00478      */
00479     itunesdb::TrackPtrList * getAllTracks( itunesdb::TrackPtrList& buffer ) const;
00480 
00481     /**
00482      * @brief Returns an Iterator over all the tracks in the database
00483      *
00484      * @return an Iterator over all the tracks in the database
00485      */
00486     inline TrackConstIterator getAllTracks() const {
00487         return ITunesDB::TrackConstIterator( m_TrackList );
00488     }
00489 
00490     /**
00491      * @brief Returns an album by the given artistname and title.
00492      *
00493      * This method fills in all tracks matching the given artist/album information to the given TrackPtrList
00494      * @see getAlbum() function below for a better way to get access to a sequence of tracks.
00495      * The returned iterator will deliver ITunesDBTrack instances with some extra functionalities.
00496      * @param artistname name of the artist of the album in question
00497      * @param albumname name of the album
00498      * @param buffer the list the tracks of the album will be put to
00499      * @return a pointer to the given buffer or NULL if no such album could by found
00500      */
00501     itunesdb::TrackPtrList *
00502         getAlbum( const QString& artistname, const QString& albumname, itunesdb::TrackPtrList& buffer ) const;
00503 
00504     typedef FilteredTrackConstIterator<itunesdb::TrackPredicates::ByAlbum> AlbumIterator;
00505     /**
00506      * @brief Returns all the tracks matching the given artist and album
00507      * @param artistname name of the artist of the album in question
00508      * @param albumname name of the album
00509      * @return an iterator over the tracks matching the given artist and album
00510      */
00511     inline AlbumIterator getAlbum( const QString& artistname, const QString& albumname ) const {
00512         return getTracksBy( itunesdb::TrackPredicates::ByAlbum( artistname, albumname ) );
00513     }
00514 
00515     /**
00516      * @brief Returns all the Tracks by the given artist.
00517      *
00518      * This method fills in all tracks matching the artist to the given TrackPtrList
00519      * @see getTracksByArtist() function below for a better way to get access to a sequence of tracks.
00520      * The returned iterator will deliver ITunesDBTrack instances with some extra functionalities.
00521      * @param artistname the name of the artist to look for.
00522      * @param buffer the list to put the found tracks into.
00523      * @return the pointer to the given buffer or NULL if no such artist exists.
00524      */
00525     itunesdb::TrackPtrList *
00526         getTracksByArtist( const QString& artistname, itunesdb::TrackPtrList& buffer ) const;
00527 
00528 
00529     typedef FilteredTrackConstIterator<itunesdb::TrackPredicates::ByArtist> ArtistIterator;
00530     /**
00531      * @brief Returns all the tracks matching the given artistname
00532      * @param artistname the name of the artist to look for.
00533      * @return an iterator over the tracks matching the given artist name
00534      */
00535     inline ArtistIterator getTracksByArtist( const QString& artistname ) const {
00536         return getTracksBy( itunesdb::TrackPredicates::ByArtist( artistname ) );
00537     }
00538 
00539     /**
00540      * @brief Returns all tracks with the given string in its metadata
00541      *
00542      * This method fills in all tracks matching the given String in its metadata (artist, album, title or composer)
00543      * to the TrackPtrList.
00544      * @see getTracksContaining() function below for a better way to get access to a sequence of tracks.
00545      * The returned iterator will deliver ITunesDBTrack instances with some extra functionalities.
00546      * @param someString the string to look for
00547      * @param buffer the list to put the found tracks into
00548      * @param caseSensitive set to false if uppercase/lowercase should be ignored
00549      * @return the pointer to the given list or NULL if no such tracks exist.
00550      */
00551     itunesdb::TrackPtrList *
00552         getTracksContaining( const QString& someString, itunesdb::TrackPtrList& buffer, bool caseSensitive = true ) const;
00553 
00554     typedef FilteredTrackConstIterator<itunesdb::TrackPredicates::Contains> ContainsIterator;
00555     /**
00556      * @brief Returns all tracks with the given string in its metadata (artist, album, title or composer)
00557      * @param someString the string to look for
00558      * @param caseSensitive set to false if uppercase/lowercase should be ignored
00559      * @return an iterator over the tracks matching the given String name
00560      */
00561     inline ContainsIterator getTracksContaining( const QString& someString, bool caseSensitive = true ) const {
00562         return getTracksBy( itunesdb::TrackPredicates::Contains( someString, caseSensitive ) );
00563     }
00564 
00565     /**
00566      * @brief Returns a list with all playlist names
00567      * @param buffer the list to put the playlisttitles into
00568      * @return the pointer to the given buffer
00569      */
00570     QStringList * getPlaylistTitles( QStringList& buffer ) const;
00571 
00572     /**
00573      * @brief Returns a playlist by the given playlist title.
00574      * @param playlisttitle title of the playlist in question
00575      * @return a pointer to the playlist found or NULL if no such playlist exists
00576      */
00577     ITunesDBPlaylist * getPlaylistByTitle(const QString& playlisttitle) const;
00578 
00579     /**
00580      * @brief Returns the playlist by the given playlistID.
00581      * @param playlistID the DB ID of the desired playlist
00582      * @return the playlist found or NULL if no such playlist could be found.
00583      */
00584     ITunesDBPlaylist * getPlaylistByID( Q_UINT64 playlistID ) const;
00585 
00586     /**
00587      * @brief Removes all the tracks of the given artist (an thus the artist itself)
00588      * from the database.
00589      * @param artistname the name of the artist
00590      * @return true if tracks were found and removed, false otherwise.
00591      */
00592     bool removeArtist(const QString& artistname);
00593 
00594     /**
00595      * @brief Renames an album with the given title and artist
00596      *
00597      * Renames an album with the given title and artist to newtitle, newartist by
00598      * changing the artist and album properties of all the tracks found by the
00599      * given artist/album combination to newartist/newalbum.
00600      * @param artist the artist to look for
00601      * @param title the album to look for
00602      * @param newartist the new artist name to set. Give an empty or QString::null string if the artist property should remain unchanged.
00603      * @param newtitle the new album title to set. Give an empty or QString::null string if the album property should remain unchanged.
00604      * @return true if tracks were found and changed, false otherwise
00605      */
00606     bool renameAlbum(const QString& artist, const QString& title, const QString& newartist, const QString& newtitle);
00607 
00608     /**
00609      * @brief Adds a new playlist to the database.
00610      * @param playlist The playlist to be added to the database.
00611      * @return false if a playlist with the same title already exists, true otherwise
00612      */
00613     bool addPlaylist( ITunesDBPlaylist * playlist );
00614 
00615     /**
00616      * @brief Removes the playlist with the given title
00617      * @param title the title of the playlist to be removed
00618      * @param delete_instance if set to true the element gets deleted during removal
00619      * @return true if successful, otherwise false
00620      */
00621     bool removePlaylist( const QString& title, bool delete_instance);
00622 
00623     /**
00624      * @brief Updates all Smart Playlists in this itunesdb instance.
00625      */
00626     void updateSmartPlaylists();
00627 
00628     /**
00629      * @brief Removes the Track with the given trackid from the database.
00630      *
00631      * This also removes all playlist references to this track
00632      * @param trackid ID of the track to be deleted
00633      * @param delete_instance if set to true (default) the Track gets deleted during removal
00634      * @return the trackid of the Track or 0 if no such Track exists
00635      */
00636     Q_UINT32 removeTrack(Q_UINT32 trackid, bool delete_instance = true);
00637 
00638     /**
00639      * @brief Wipes all data from the container.
00640      */
00641     void clear();
00642 
00643     /**
00644      * @brief Returns true if something in the container's control has been changed.
00645      *
00646      * A change to a Playlist or a Track for example will not set the change flag yet.
00647      * @return true if something in the container's control has been changed.
00648      */
00649     bool isDirty() const;
00650 
00651     /**
00652      * @brief Returns the number of tracks
00653      * @return the number of tracks
00654      */
00655     Q_UINT32 getNumTracks() const;
00656 
00657     /**
00658      * @brief Returns the number of playlists
00659      * @return the number of playlists
00660      */
00661     Q_UINT32 getNumPlaylists() const;
00662 
00663     /**
00664      * @brief Lock control functions to prevent concurrent access to the Database from different instances
00665      */
00666     void lock(bool write_lock);
00667     void unlock();
00668     bool isLocked() const;
00669 
00670     /**
00671      * @brief Returns the timestamp the database file was modified.
00672      */
00673     uint lastModified() { return timestamp.toTime_t(); }
00674 
00675     /**
00676      * @brief sets the title of the database
00677      *
00678      * The title will be stored as the title of the main track list
00679      * @param title the new title for the database
00680      */
00681     void setTitle( const QString& title );
00682 
00683     /**
00684      * @brief Returns the title of the database
00685      * @return the title of the main database
00686      */
00687     const QString& getTitle() const { return m_Title; }
00688 
00689     /**
00690      * @brief Returns true if the database contains podcasts
00691      * @return true if the database contains podcasts
00692      */
00693     bool hasPodcasts() const { return hasPodcastsFlag; }
00694 
00695     /**
00696      * @brief Returns the next free trackID for a new track
00697      * @return the next free trackID for a new track
00698      */
00699     Q_UINT32 getNextFreeTrackID() const;
00700 
00701     /**
00702      * @brief Returns the next available DBID.
00703      * @return the next available DBID.
00704      */
00705     Q_UINT64 getNextFreeDBID() const;
00706 
00707     /**
00708      * @brief Returns the fully qualified path for the given ipod path information
00709      *
00710      * Translates the pathinfo stored on the ipod to a real path info and adds the
00711      * ipodBase path so we can access the real file. The caller needs to check if
00712      * the file actually exists.
00713      * @param pathinfo the path property in database items
00714      * @return the path pointing to the file.
00715      */
00716     QString getFileForPathInfo( QString pathinfo ) const;
00717 
00718     /**
00719      * @brief Returns the ipod's base directory.
00720      * @return the ipod's base directory.
00721      */
00722     const QString& getIPodBase() const {
00723         return m_ipodSysInfo.getDeviceMountpoint();
00724     }
00725 
00726 protected:
00727 
00728     TrackIDMap m_TrackIdMap;
00729     TrackList m_TrackList;
00730     QString m_Title;
00731 
00732     /**
00733      * The container that holds all the playlist for this iTunesDB instance.
00734      */
00735     class PlaylistContainer : public std::vector<ITunesDBPlaylist *> {
00736     public:
00737         PlaylistContainer() : std::vector<ITunesDBPlaylist *>() {}
00738         virtual ~PlaylistContainer() { clear(); }
00739     } * m_playlists;
00740 
00741     bool m_dirty;
00742     void setDirty( bool dirtyFlag = true );
00743 
00744     Q_UINT32 maxtrackid;
00745     Q_UINT64 mMaxDBID;
00746 
00747     ITunesDBTrack * insertTrackToDataBase( ITunesDBTrack * track );
00748 
00749 private:
00750 
00751     void removeFromAllPlaylists( Q_UINT32 trackid );
00752     IPodSysInfo& m_ipodSysInfo;
00753     QFile itunesdbfile;
00754     QFile itunessdfile;
00755     QDateTime timestamp;
00756 
00757     bool hasPodcastsFlag;
00758     bool locked;
00759 };
00760 
00761 
00762 #endif

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