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

Generated on Wed Dec 19 00:15:19 2007 for libqtpod by  doxygen 1.5.0