![]() |
![]() |
![]() |
libgpod Reference Manual | ![]() |
---|---|---|---|---|
iPod database reading/writingiPod database reading/writing — Functions to create, read, write the iPod database |
Itdb_iTunesDB; void (*ItdbUserDataDestroyFunc) (gpointer userdata); gpointer (*ItdbUserDataDuplicateFunc) (gpointer userdata); Itdb_iTunesDB* itdb_new (void); void itdb_free (Itdb_iTunesDB *itdb); Itdb_iTunesDB* itdb_parse (const gchar *mp, GError **error); gboolean itdb_write (Itdb_iTunesDB *itdb, GError **error); void itdb_set_mountpoint (Itdb_iTunesDB *itdb, const gchar *mp); const gchar* itdb_get_mountpoint (Itdb_iTunesDB *itdb); guint32 itdb_tracks_number (Itdb_iTunesDB *itdb); guint32 itdb_tracks_number_nontransferred (Itdb_iTunesDB *itdb); guint32 itdb_playlists_number (Itdb_iTunesDB *itdb);
These functions are for creating, reading, writing, and deleting the iPod database and getting the total number of tracks and playlists.
Overview of using the iPod database:
itdb_parse()
: read the iTunesDB and ArtworkDB
itdb_write()
: write the iTunesDB and ArtworkDB
itdb_parse()
will return a Itdb_iTunesDB structure with GLists
containing all tracks (each track is represented by a Itdb_Track
structure) and the playlists (each playlist is represented by a
Itdb_Playlist structure).
A number of functions for adding, removing, duplicating tracks are available. Please see Tracks for details.
In each Itdb_Playlist structure you can find a GList called 'members' with listing all member tracks. Each track referenced in a playlist must also be present in the tracks GList of the iTunesDB.
The iPod must contain one master playlist (MPL) containing all tracks accessible on the iPod through the Music->Tracks/Albums/Artists... menu. Besides the MPL there can be a number of normal playlists accessible through the Music->Playlists menu on the iPod. Tracks that are a member of one of these normal playlists must also be a member of the MPL.
The Podcasts playlist is just another playlist with some internal flags set differently. Also, member tracks in the Podcasts playlist are not normally members of the MPL (so on the iPod they will only show up under the Podcasts menu). All tracks referenced must be in the tracklist of the Itdb_iTunesDB, however.
A number of functions to add/remove playlists, or add/remove tracks are available. Please see Playlists for details.
Each track can have a thumbnail associated with it. You can
retrieve a GdkPixmap of the thumbnail using
itdb_thumb_get_gdk_pixbuf()
(tracks have thumbnails of the
following types associated: ITDB_THUMB_COVER_SMALL
and
ITDB_THUMB_COVER_LARGE
). You can remove a thumbnail with
itdb_track_remove_thumbnails()
. And finally, you can set a
new thumbnail using itdb_track_set_thumbnails()
.
Please note that iTunes additionally stores the artwork as tags in the original music file. That's also from where the data is read when artwork is displayed in iTunes, and there can be more than one piece of artwork. libgpod does not store the artwork as tags in the original music file. As a consequence, if iTunes attempts to access the artwork, it will find none, and remove libgpod's artwork. Luckily, iTunes will only attempt to access the artwork if you select a track in iTunes. (To work around this, gtkpod keeps a list of the original filename of all artwork and silently adds the thumbnails if they were 'lost'. Your application might want to do something similar, or you can supply patches for (optionally!) adding tags to the original music files.)
The Itdb_iTunesDB, Itdb_Playlist and Itdb_Track structures each
have a userdata and a usertype field that can be used by the
application to store application-specific additional data. If
userdata is a pointer to an external structure, you can supply a
ItdbUserDataDuplicateFunc and a ItdbUserDataDestroyFunc so that
this data can be duplicated or freed automatically with a call
to the library _duplicate()
/_free()
functions.
typedef struct { GList *tracks; GList *playlists; gchar *filename; /* filename of iTunesDB */ Itdb_Device *device;/* iPod device info */ guint32 version; guint64 id; /* reserved for future use */ gint32 reserved_int1; gint32 reserved_int2; gpointer reserved1; gpointer reserved2; /* below is for use by application */ guint64 usertype; gpointer userdata; /* functions called to duplicate/free userdata */ ItdbUserDataDuplicateFunc userdata_duplicate; ItdbUserDataDestroyFunc userdata_destroy; } Itdb_iTunesDB;
gpointer (*ItdbUserDataDuplicateFunc) (gpointer userdata);
userdata : |
|
Returns : |
Itdb_iTunesDB* itdb_new (void);
Creates a new Itdb_iTunesDB with the unknowns filled in to reasonable values.
Returns : | a newly created Itdb_iTunesDB to be freed with itdb_free()
when it's no longer needed
|
void itdb_free (Itdb_iTunesDB *itdb);
Free the memory taken by itdb
.
itdb : |
an Itdb_iTunesDB |
Itdb_iTunesDB* itdb_parse (const gchar *mp, GError **error);
Parse the Itdb_iTunesDB of the iPod located at mp
mp : |
mount point of the iPod (eg "/mnt/ipod) in local encoding |
error : |
return location for a GError or NULL |
Returns : | a newly allocated Itdb_iTunesDB struct holding the tracks and
the playlists present on the iPod at mp , NULL if mp isn't an iPod mount
point. If non-NULL, the Itdb_iTunesDB is to be freed with itdb_free() when
it's no longer needed
|
gboolean itdb_write (Itdb_iTunesDB *itdb, GError **error);
Write out an iTunesDB. It reassigns unique IDs to all tracks. An existing "Play Counts" file is renamed to "Play Counts.bak" if the export was successful. An existing "OTGPlaylistInfo" file is removed if the export was successful.
itdb : |
the Itdb_iTunesDB to write to disk |
error : |
return location for a GError or NULL |
Returns : | TRUE on success, FALSE on error, in which case error is
set accordingly.
|
void itdb_set_mountpoint (Itdb_iTunesDB *itdb, const gchar *mp);
Sets the mountpoint of db
. Always use this function to set the mountpoint
of an Itdb_iTunesDB as it will reset the number of available
/iPod_Control/Music/F.. dirs. It doesn't attempt to parse an iPod database
that may be present on the iPod at mp
itdb : |
an Itdb_iTunesDB |
mp : |
new mount point |
const gchar* itdb_get_mountpoint (Itdb_iTunesDB *itdb);
Retrieve a reference to the mountpoint of itdb
itdb : |
an Itdb_iTunesDB |
Returns : | the itdb mountpoint, this string shouldn't be freed nor
modified
|
guint32 itdb_tracks_number (Itdb_iTunesDB *itdb);
Counts the number of tracks stored in itdb
itdb : |
an Itdb_iTunesDB |
Returns : | the number of tracks in itdb
|
guint32 itdb_tracks_number_nontransferred (Itdb_iTunesDB *itdb);
Counts the number of non-transferred tracks in itdb
itdb : |
an Itdb_iTunesDB |
Returns : | the number of tracks in itdb that haven't been transferred
to the iPod yet (ie the number of Itdb_Track in which the transferred field
is false)
|
guint32 itdb_playlists_number (Itdb_iTunesDB *itdb);
Counts the number of playlists stored in itdb
itdb : |
an Itdb_iTunesDB |
Returns : | the number of playlists in itdb (including the master
playlist)
|