ITunesDB Class Reference

#include <itunesdb.h>

Inheritance diagram for ITunesDB:

itunesdb::utils::NonCopyAble List of all members.

Public Types

typedef itunesdb::utils::SortablePtrVector<
ITunesDBTrack
TrackList
typedef FilteredTrackConstIterator TrackConstIterator
typedef FilteredTrackConstIterator<
itunesdb::TrackPredicates::ByAlbum
AlbumIterator
typedef FilteredTrackConstIterator<
itunesdb::TrackPredicates::ByArtist
ArtistIterator
typedef FilteredTrackConstIterator<
itunesdb::TrackPredicates::Contains
ContainsIterator

Public Member Functions

 ITunesDB (IPodSysInfo &ipodSysInfo)
bool open ()
 Opens the itunesdb file at the given ipod mountpoint.
bool isOpen ()
 Returns true if open() has already been successfully called.
bool writeDatabase (const QString &filename=QString())
 Writes the (changed) database back to the ipod.
bool dbFileChanged () const
 Returns true if the itunesdb file has been changed thus needs to be reloaded or does not exist anymore.
QString getFilename () const
 Returns the name of the filename given with the open() call.
ITunesDBPlaylistcreateNewPlaylist (const QString &title)
 Creates a new empty playlist.
ITunesDBTrackcreateEmptyTrack (Q_UINT32 trackid)
 Creates a new empty track.
ITunesDBTrackcreateNewTrack (const QString &fileExtension=QString::null)
 Returns a new itunesdb::Track instance for adding a new track to the database.
bool addTrack (ITunesDBTrack *track)
 Adds a new track to the database.
ITunesDBTrackgetTrackByID (const Q_UINT32 id) const
 Returns the Track corresponding to the given ID.
ITunesDBTrackfindTrackByDBID (const Q_UINT64 dbid) const
 Returns the first track found with the given dbid.
int getMHITTrackPosFor (Q_UINT32 id) const
 Returns the MHIT position of the track with the given ID.
ITunesDBTrackgetTrackAt (uint mhitTrackPos) const
 Returns the Track at the specified position in the itunesdb.
ITunesDBTrackfindFirstTrackBy (const itunesdb::TrackPredicate &predicate) const
 Returns the first Track where the given predicate returned true.
itunesdb::TrackPtrListgetTracksBy (const itunesdb::TrackPredicate &predicate, itunesdb::TrackPtrList &buffer) const
 Returns all the Tracks where the given itunesdb::TrackPredicate returned true.
template<typename TrackPredicate_T>
FilteredTrackConstIterator<
TrackPredicate_T > 
getTracksBy (const TrackPredicate_T &predicate) const
 Returns all the Tracks where the given itunesdb::TrackPredicate returns true.
ITunesDBTrackfindTrack (const QString &artistname, const QString &albumname, const QString &title, Q_UINT32 trackNum=0) const
 Returns the Track found by the given information or NULL if no such Track could be found.
QStringList * getArtists (QStringList &buffer) const
 Fills the given QStringList with the names of all artists in the database.
QStringList * getAllAlbums (QStringList &buffer) const
 Fills the given QStringList with the names of all albums in the database.
QStringList * getAlbumsByArtist (const QString &artistname, QStringList &buffer) const
 Fills the given QStringList with the names of the albums by the given artist.
bool containsArtist (const QString &artistname) const
 Returns true if the given artist exists.
bool containsAlbum (const QString &artistname, const QString &albumname) const
 Returns true if the given album exists.
itunesdb::TrackPtrListgetAllTracks (itunesdb::TrackPtrList &buffer) const
 Fills the given TrackPtrList with all itunesdb::Track instances in the database.
TrackConstIterator getAllTracks () const
 Returns an Iterator over all the tracks in the database.
itunesdb::TrackPtrListgetAlbum (const QString &artistname, const QString &albumname, itunesdb::TrackPtrList &buffer) const
 Returns an album by the given artistname and title.
AlbumIterator getAlbum (const QString &artistname, const QString &albumname) const
 Returns all the tracks matching the given artist and album.
itunesdb::TrackPtrListgetTracksByArtist (const QString &artistname, itunesdb::TrackPtrList &buffer) const
 Returns all the Tracks by the given artist.
ArtistIterator getTracksByArtist (const QString &artistname) const
 Returns all the tracks matching the given artistname.
itunesdb::TrackPtrListgetTracksContaining (const QString &someString, itunesdb::TrackPtrList &buffer, bool caseSensitive=true) const
 Returns all tracks with the given string in its metadata.
ContainsIterator getTracksContaining (const QString &someString, bool caseSensitive=true) const
 Returns all tracks with the given string in its metadata (artist, album, title or composer).
QStringList * getPlaylistTitles (QStringList &buffer) const
 Returns a list with all playlist names.
ITunesDBPlaylistgetPlaylistByTitle (const QString &playlisttitle) const
 Returns a playlist by the given playlist title.
ITunesDBPlaylistgetPlaylistByID (Q_UINT64 playlistID) const
 Returns the playlist by the given playlistID.
bool removeArtist (const QString &artistname)
 Removes all the tracks of the given artist (an thus the artist itself) from the database.
bool renameAlbum (const QString &artist, const QString &title, const QString &newartist, const QString &newtitle)
 Renames an album with the given title and artist.
bool addPlaylist (ITunesDBPlaylist *playlist)
 Adds a new playlist to the database.
bool removePlaylist (const QString &title, bool delete_instance)
 Removes the playlist with the given title.
void updateSmartPlaylists ()
 Updates all Smart Playlists in this itunesdb instance.
Q_UINT32 removeTrack (Q_UINT32 trackid, bool delete_instance=true)
 Removes the Track with the given trackid from the database.
void clear ()
 Wipes all data from the container.
bool isDirty () const
 Returns true if something in the container's control has been changed.
Q_UINT32 getNumTracks () const
 Returns the number of tracks.
Q_UINT32 getNumPlaylists () const
 Returns the number of playlists.
void lock (bool write_lock)
 Lock control functions to prevent concurrent access to the Database from different instances.
void unlock ()
bool isLocked () const
uint lastModified ()
 Returns the timestamp the database file was modified.
void setTitle (const QString &title)
 sets the title of the database
const QString & getTitle () const
 Returns the title of the database.
bool hasPodcasts () const
 Returns true if the database contains podcasts.
Q_UINT32 getNextFreeTrackID () const
 Returns the next free trackID for a new track.
Q_UINT64 getNextFreeDBID () const
 Returns the next available DBID.
QString getFileForPathInfo (QString pathinfo) const
 Returns the fully qualified path for the given ipod path information.
const QString & getIPodBase () const
 Returns the ipod's base directory.

Public Attributes

QString error

Protected Member Functions

void setDirty (bool dirtyFlag=true)
ITunesDBTrackinsertTrackToDataBase (ITunesDBTrack *track)

Protected Attributes

TrackIDMap m_TrackIdMap
TrackList m_TrackList
QString m_Title
ITunesDB::PlaylistContainerm_playlists
bool m_dirty
Q_UINT32 maxtrackid
Q_UINT64 mMaxDBID

Friends

class ITunesDBPlaylist
class ITunesDBSPLRuleSet
class ITunesDBTrack

Classes

struct  FilteredTrackConstIterator
 An Iterator over a sequence of ITunesDBTrack instances. More...
class  ItunesDBReaderAdapter
class  ItunesDBWriterAdapter
class  PlaylistContainer

Detailed Description

Class representing the contents of your iPods ITunesDB file
Examples:

listtests.cpp, and listtrackstest.cpp.


Member Function Documentation

bool ITunesDB::open (  ) 

Opens the itunesdb file at the given ipod mountpoint.

Returns:
true if the itunesdb does exist and could be opened. For parse errors check the error member afterwards

bool ITunesDB::isOpen (  ) 

Returns true if open() has already been successfully called.

Returns:
true if open has already been successfully called, false otherwise

bool ITunesDB::writeDatabase ( const QString &  filename = QString()  ) 

Writes the (changed) database back to the ipod.

Parameters:
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()
Returns:
true if writing the database was successful
Examples:
listtests.cpp.

bool ITunesDB::dbFileChanged (  )  const

Returns true if the itunesdb file has been changed thus needs to be reloaded or does not exist anymore.

Returns:
true if the itunesdb file has been changed

QString ITunesDB::getFilename (  )  const [inline]

Returns the name of the filename given with the open() call.

ITunesDBPlaylist * ITunesDB::createNewPlaylist ( const QString &  title  ) 

Creates a new empty playlist.

Examples:
listtests.cpp.

ITunesDBTrack * ITunesDB::createEmptyTrack ( Q_UINT32  trackid  ) 

Creates a new empty track.

Only use this function if you know what you're doing.

See also:
createNewTrack() for the right way to create a new Track
Parameters:
trackid the id of the new track in the database.

ITunesDBTrack * ITunesDB::createNewTrack ( const QString &  fileExtension = QString::null  ) 

Returns a new itunesdb::Track instance for adding a new track to the database.

The new instance gets initialized with an unused trackid and trackpath. Subsequent calls will get itunesdb::Track with the same trackid until the returned track is as added via addTrack() thus a call to addTrack() has to be done afterwards.

Parameters:
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

bool ITunesDB::addTrack ( ITunesDBTrack track  ) 

Adds a new track to the database.

This only adds the control information to the database, the track itself (the file) has to by copied by the calling application.

Parameters:
track the track to add to the database
Returns:
true if the track was successfully added

ITunesDBTrack * ITunesDB::getTrackByID ( const Q_UINT32  id  )  const

Returns the Track corresponding to the given ID.

Parameters:
id ID of the track
Returns:
the Track corresponding to the given ID

ITunesDBTrack * ITunesDB::findTrackByDBID ( const Q_UINT64  dbid  )  const

Returns the first track found with the given dbid.

Parameters:
dbid the 64bit DBID being unique for all objects in the database
Returns:
the Track corresponding to the given DBID

int ITunesDB::getMHITTrackPosFor ( Q_UINT32  id  )  const

Returns the MHIT position of the track with the given ID.

Parameters:
id ID of the track
Returns:
the position of the track in the MHIT section or -1 if there's no such track.

ITunesDBTrack * ITunesDB::getTrackAt ( uint  mhitTrackPos  )  const

Returns the Track at the specified position in the itunesdb.

Parameters:
mhitTrackPos the position of the desired track
Returns:
the track at the specified position or NULL if the given position is out of range

ITunesDBTrack * ITunesDB::findFirstTrackBy ( const itunesdb::TrackPredicate predicate  )  const

Returns the first Track where the given predicate returned true.

The given trackpredicate needs to contain a method that gets a track, and returns a bool if it's the desired track

Returns:
the first Track where the given predicate returned true
See also:
TrackPredicate for details about TrackPredicates

TrackPtrList * ITunesDB::getTracksBy ( const itunesdb::TrackPredicate predicate,
itunesdb::TrackPtrList buffer 
) const

Returns all the Tracks where the given itunesdb::TrackPredicate returned true.

More formally the method fills in the Tracks where the given itunesdb::TrackPredicate returned true into the given TrackPtrList and returns a pointer to the list if at least one track got added.

See also:
getTracksBy() function below for a better way to get access to a sequence of tracks. The returned iterator will deliver ITunesDBTrack instances with some extra functionalities.

itunesdb::TrackPredicates for a list of predefined predicates

template<typename TrackPredicate_T>
FilteredTrackConstIterator<TrackPredicate_T> ITunesDB::getTracksBy ( const TrackPredicate_T &  predicate  )  const [inline]

Returns all the Tracks where the given itunesdb::TrackPredicate returns true.

The next() method of the returned Iterator delivers pointers to ITunesDBTrack instances

See also:
itunesdb::TrackPredicates for a list of predefined predicates
Returns:
an iterator over the Tracks where the given itunesdb::TrackPredicate returns true

ITunesDBTrack * ITunesDB::findTrack ( const QString &  artistname,
const QString &  albumname,
const QString &  title,
Q_UINT32  trackNum = 0 
) const

Returns the Track found by the given information or NULL if no such Track could be found.

Parameters:
artistname the name of the artist
albumname the name of the album
title the title of the track
trackNum the position of the track in its album
Returns:
the Track found or NULL if no track matched the given criteria.

QStringList * ITunesDB::getArtists ( QStringList &  buffer  )  const

Fills the given QStringList with the names of all artists in the database.

Parameters:
buffer a QStringList to fill in the artist names
Returns:
a pointer to the StringList
Examples:
listtests.cpp.

QStringList * ITunesDB::getAllAlbums ( QStringList &  buffer  )  const

Fills the given QStringList with the names of all albums in the database.

QStringList * ITunesDB::getAlbumsByArtist ( const QString &  artistname,
QStringList &  buffer 
) const

Fills the given QStringList with the names of the albums by the given artist.

Parameters:
artistname the name of the artist to look for
buffer the list to put the names of the albums found
Returns:
a pointer to the given QStringList or NULL if no such artist exists
Examples:
listtests.cpp.

bool ITunesDB::containsArtist ( const QString &  artistname  )  const

Returns true if the given artist exists.

Parameters:
artistname the artists name to check for.
Returns:
true if the artist exists, false otherwise.

bool ITunesDB::containsAlbum ( const QString &  artistname,
const QString &  albumname 
) const

Returns true if the given album exists.

Parameters:
artistname the artists name to check for
albumname the name of the album
Returns:
true if such an album exists for the given artist, false otherwise.

TrackPtrList * ITunesDB::getAllTracks ( itunesdb::TrackPtrList buffer  )  const

Fills the given TrackPtrList with all itunesdb::Track instances in the database.

Fills the given TrackPtrList with all itunesdb::Track instances in the database and returns a pointer to the given list.

See also:
getAllTracks() function below for a better way to get access to a sequence of tracks. The returned iterator will deliver ITunesDBTrack instances with some extra functionalities.
Parameters:
buffer the list to put the tracks into.
Returns:
the pointer to the given filled list
Examples:
listtrackstest.cpp.

TrackConstIterator ITunesDB::getAllTracks (  )  const [inline]

Returns an Iterator over all the tracks in the database.

Returns:
an Iterator over all the tracks in the database

TrackPtrList * ITunesDB::getAlbum ( const QString &  artistname,
const QString &  albumname,
itunesdb::TrackPtrList buffer 
) const

Returns an album by the given artistname and title.

This method fills in all tracks matching the given artist/album information to the given TrackPtrList

See also:
getAlbum() function below for a better way to get access to a sequence of tracks. The returned iterator will deliver ITunesDBTrack instances with some extra functionalities.
Parameters:
artistname name of the artist of the album in question
albumname name of the album
buffer the list the tracks of the album will be put to
Returns:
a pointer to the given buffer or NULL if no such album could by found
Examples:
listtests.cpp.

AlbumIterator ITunesDB::getAlbum ( const QString &  artistname,
const QString &  albumname 
) const [inline]

Returns all the tracks matching the given artist and album.

Parameters:
artistname name of the artist of the album in question
albumname name of the album
Returns:
an iterator over the tracks matching the given artist and album

TrackPtrList * ITunesDB::getTracksByArtist ( const QString &  artistname,
itunesdb::TrackPtrList buffer 
) const

Returns all the Tracks by the given artist.

This method fills in all tracks matching the artist to the given TrackPtrList

See also:
getTracksByArtist() function below for a better way to get access to a sequence of tracks. The returned iterator will deliver ITunesDBTrack instances with some extra functionalities.
Parameters:
artistname the name of the artist to look for.
buffer the list to put the found tracks into.
Returns:
the pointer to the given buffer or NULL if no such artist exists.
Examples:
listtests.cpp.

ArtistIterator ITunesDB::getTracksByArtist ( const QString &  artistname  )  const [inline]

Returns all the tracks matching the given artistname.

Parameters:
artistname the name of the artist to look for.
Returns:
an iterator over the tracks matching the given artist name

TrackPtrList * ITunesDB::getTracksContaining ( const QString &  someString,
itunesdb::TrackPtrList buffer,
bool  caseSensitive = true 
) const

Returns all tracks with the given string in its metadata.

This method fills in all tracks matching the given String in its metadata (artist, album, title or composer) to the TrackPtrList.

See also:
getTracksContaining() function below for a better way to get access to a sequence of tracks. The returned iterator will deliver ITunesDBTrack instances with some extra functionalities.
Parameters:
someString the string to look for
buffer the list to put the found tracks into
caseSensitive set to false if uppercase/lowercase should be ignored
Returns:
the pointer to the given list or NULL if no such tracks exist.

ContainsIterator ITunesDB::getTracksContaining ( const QString &  someString,
bool  caseSensitive = true 
) const [inline]

Returns all tracks with the given string in its metadata (artist, album, title or composer).

Parameters:
someString the string to look for
caseSensitive set to false if uppercase/lowercase should be ignored
Returns:
an iterator over the tracks matching the given String name

QStringList * ITunesDB::getPlaylistTitles ( QStringList &  buffer  )  const

Returns a list with all playlist names.

Parameters:
buffer the list to put the playlisttitles into
Returns:
the pointer to the given buffer
Examples:
listtests.cpp.

ITunesDBPlaylist * ITunesDB::getPlaylistByTitle ( const QString &  playlisttitle  )  const

Returns a playlist by the given playlist title.

Parameters:
playlisttitle title of the playlist in question
Returns:
a pointer to the playlist found or NULL if no such playlist exists
Examples:
listtests.cpp.

ITunesDBPlaylist * ITunesDB::getPlaylistByID ( Q_UINT64  playlistID  )  const

Returns the playlist by the given playlistID.

Parameters:
playlistID the DB ID of the desired playlist
Returns:
the playlist found or NULL if no such playlist could be found.

bool ITunesDB::removeArtist ( const QString &  artistname  ) 

Removes all the tracks of the given artist (an thus the artist itself) from the database.

Parameters:
artistname the name of the artist
Returns:
true if tracks were found and removed, false otherwise.

bool ITunesDB::renameAlbum ( const QString &  artist,
const QString &  title,
const QString &  newartist,
const QString &  newtitle 
)

Renames an album with the given title and artist.

Renames an album with the given title and artist to newtitle, newartist by changing the artist and album properties of all the tracks found by the given artist/album combination to newartist/newalbum.

Parameters:
artist the artist to look for
title the album to look for
newartist the new artist name to set. Give an empty or QString::null string if the artist property should remain unchanged.
newtitle the new album title to set. Give an empty or QString::null string if the album property should remain unchanged.
Returns:
true if tracks were found and changed, false otherwise

bool ITunesDB::addPlaylist ( ITunesDBPlaylist playlist  ) 

Adds a new playlist to the database.

Parameters:
playlist The playlist to be added to the database.
Returns:
false if a playlist with the same title already exists, true otherwise
Examples:
listtests.cpp.

bool ITunesDB::removePlaylist ( const QString &  title,
bool  delete_instance 
)

Removes the playlist with the given title.

Parameters:
title the title of the playlist to be removed
delete_instance if set to true the element gets deleted during removal
Returns:
true if successful, otherwise false

void ITunesDB::updateSmartPlaylists (  ) 

Updates all Smart Playlists in this itunesdb instance.

Q_UINT32 ITunesDB::removeTrack ( Q_UINT32  trackid,
bool  delete_instance = true 
)

Removes the Track with the given trackid from the database.

This also removes all playlist references to this track

Parameters:
trackid ID of the track to be deleted
delete_instance if set to true (default) the Track gets deleted during removal
Returns:
the trackid of the Track or 0 if no such Track exists

void ITunesDB::clear (  ) 

Wipes all data from the container.

bool ITunesDB::isDirty (  )  const

Returns true if something in the container's control has been changed.

A change to a Playlist or a Track for example will not set the change flag yet.

Returns:
true if something in the container's control has been changed.

Q_UINT32 ITunesDB::getNumTracks (  )  const

Returns the number of tracks.

Returns:
the number of tracks

Q_UINT32 ITunesDB::getNumPlaylists (  )  const

Returns the number of playlists.

Returns:
the number of playlists
Examples:
listtests.cpp.

void ITunesDB::lock ( bool  write_lock  ) 

Lock control functions to prevent concurrent access to the Database from different instances.

uint ITunesDB::lastModified (  )  [inline]

Returns the timestamp the database file was modified.

void ITunesDB::setTitle ( const QString &  title  ) 

sets the title of the database

The title will be stored as the title of the main track list

Parameters:
title the new title for the database

const QString& ITunesDB::getTitle (  )  const [inline]

Returns the title of the database.

Returns:
the title of the main database

bool ITunesDB::hasPodcasts (  )  const [inline]

Returns true if the database contains podcasts.

Returns:
true if the database contains podcasts

Q_UINT32 ITunesDB::getNextFreeTrackID (  )  const

Returns the next free trackID for a new track.

Returns:
the next free trackID for a new track

Q_UINT64 ITunesDB::getNextFreeDBID (  )  const

Returns the next available DBID.

Returns:
the next available DBID.

QString ITunesDB::getFileForPathInfo ( QString  pathinfo  )  const

Returns the fully qualified path for the given ipod path information.

Translates the pathinfo stored on the ipod to a real path info and adds the ipodBase path so we can access the real file. The caller needs to check if the file actually exists.

Parameters:
pathinfo the path property in database items
Returns:
the path pointing to the file.
Examples:
listtrackstest.cpp.

const QString& ITunesDB::getIPodBase (  )  const [inline]

Returns the ipod's base directory.

Returns:
the ipod's base directory.


Member Data Documentation

ITunesDB::PlaylistContainer * ITunesDB::m_playlists [protected]

The container that holds all the playlist for this iTunesDB instance.


The documentation for this class was generated from the following files:
Generated on Wed Nov 28 03:04:38 2007 for libqtpod by  doxygen 1.5.0