diff options
Diffstat (limited to 'docs/reference/tmpl/itunesdb-db.sgml')
| -rw-r--r-- | docs/reference/tmpl/itunesdb-db.sgml | 82 |
1 files changed, 81 insertions, 1 deletions
diff --git a/docs/reference/tmpl/itunesdb-db.sgml b/docs/reference/tmpl/itunesdb-db.sgml index ef5db40..d49d074 100644 --- a/docs/reference/tmpl/itunesdb-db.sgml +++ b/docs/reference/tmpl/itunesdb-db.sgml @@ -9,6 +9,86 @@ Functions to create, read, write the iPod database These functions are for creating, reading, writing, and deleting the iPod database and getting the total number of tracks and playlists. </para> +<para> +Overview of using the iPod database: +</para> +<para> +itdb_parse(): read the iTunesDB and ArtworkDB +</para> +<para> +itdb_write(): write the iTunesDB and ArtworkDB +</para> +<para> +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). +</para> +<para> +A number of functions for adding, removing, duplicating tracks +are available. Please see +<link linkend="libgpod-Tracks">Tracks</link> for details. +</para> +<para> +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. +</para> +<para> +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. +</para> +<para> +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. +</para> +<para> +A number of functions to add/remove playlists, or add/remove +tracks are available. Please see +<link linkend="libgpod-Playlists">Playlists</link> for details. +</para> +<para> +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(). +</para> +<para> +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 you 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 Tunes. (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.) +</para> +<para> +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. +</para> <!-- ##### SECTION See_Also ##### --> <para> @@ -82,7 +162,7 @@ database and getting the total number of tracks and playlists. </para> -@db: +@itdb: @error: @Returns: |