Update of /cvsroot/gtkpod/libgpod/docs/reference/tmpl
In directory sc8-pr-cvs2.sourceforge.net:/tmp/cvs-serv22787/docs/reference/tmpl
Modified Files:
artwork.sgml device.sgml itunesdb-db.sgml
itunesdb-lowlevel.sgml track.sgml
Added Files:
photodb.sgml
Log Message:
Add PhotoDB functions to the docs.
Incorporate usage overviews from README into the docs.
Fix a few doc comments to allow gtk-doc to parse them.
--- NEW FILE: photodb.sgml ---
<!-- ##### SECTION Title ##### -->
Photo database
<!-- ##### SECTION Short_Description ##### -->
Functions to create, read, write the photo database
<!-- ##### SECTION Long_Description ##### -->
<para>
These functions are for creating, reading, and writing the photo
database.
</para>
<para>
Overview of using the Photo database:
</para>
<para>
itdb_photodb_parse():
Read an existing PhotoDB.
</para>
<para>
itdb_photodb_create():
Create a new #Itdb_PhotoDB structure. The Photo Library Album is
(first album) is created automatically.
</para>
<para>
itdb_photodb_add_photo(), itdb_photodb_add_photo_from_data():
Add a photo to the PhotoDB (from file or from a chunk of
memory). It is automatically added to the Photo Library Album
(first album), which is created if it does not exist already.
</para>
<para>
itdb_photodb_photoalbum_create():
Create and add a new photoalbum.
</para>
<para>
itdb_photodb_photoalbum_add_photo():
Add a photo (#Itdb_Artwork) to an existing photoalbum.
</para>
<para>
itdb_photodb_photoalbum_remove():
Remove an existing photoalbum. Pictures can be kept in the
Photo Library or automatically removed as well.
</para>
<para>
itdb_photodb_remove_photo():
Remove a photo either from a photoalbum or completely from the database.
</para>
<para>
itdb_photodb_write():
Write out your PhotoDB.
</para>
<para>
itdb_photodb_free():
Free all memory taken by the PhotoDB.
</para>
<para>
itdb_photodb_photoalbum_by_name():
Find the first photoalbum with a given name or the Photo
Library Album if called with no name.
</para>
<para>
If you cannot add photos because your iPod is not recognized,
you may have to set the iPod model by calling
</para>
<para>
itdb_device_set_sysinfo (db->device, "ModelNumStr", model);
</para>
<para>
For example, "MA450" would stand for an 80 GB 6th generation iPod Video. See
<ulink type="http"
url="http://gtkpod.cvs.sourceforge.net/*checkout*/gtkpod/libgpod/src/itdb_device.c";>itdb_device.c</ulink>
for a list of supported models.
</para>
<para>
This information will be written to the iPod when the PhotoDB is
saved (itdb_device_write_sysinfo() is called).
</para>
<para>
Have a look at the <ulink type="http"
url="http://gtkpod.cvs.sourceforge.net/*checkout*/gtkpod/libgpod/tests/test-photos.c";>test-photos</ulink>
test program in the <ulink type="http"
url="http://gtkpod.cvs.sourceforge.net/gtkpod/libgpod/tests/";>tests/</ulink>
directory of the libgpod source for an example of how to use the interface.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT Itdb_PhotoAlbum ##### -->
<para>
</para>
@name:
@members:
@album_type:
@playmusic:
@repeat:
@random:
@show_titles:
@transition_direction:
@slide_duration:
@transition_duration:
@song_id:
@unk024:
@unk028:
@unk044:
@unk048:
@album_id:
@prev_album_id:
@usertype:
@userdata:
@userdata_duplicate:
@userdata_destroy:
<!-- ##### STRUCT Itdb_PhotoDB ##### -->
<para>
</para>
@photos:
@photoalbums:
@device:
@usertype:
@userdata:
@userdata_duplicate:
@userdata_destroy:
<!-- ##### FUNCTION itdb_photodb_add_photo ##### -->
<para>
</para>
@db:
@filename:
@position:
@rotation:
@error:
@Returns:
<!-- ##### FUNCTION itdb_photodb_add_photo_from_data ##### -->
<para>
</para>
@db:
@image_data:
@image_data_len:
@position:
@rotation:
@error:
@Returns:
<!-- ##### FUNCTION itdb_photodb_create ##### -->
<para>
</para>
@mountpoint:
@Returns:
<!-- ##### FUNCTION itdb_photodb_free ##### -->
<para>
</para>
@photodb:
<!-- ##### FUNCTION itdb_photodb_parse ##### -->
<para>
</para>
@mp:
@error:
@Returns:
<!-- ##### FUNCTION itdb_photodb_photoalbum_add_photo ##### -->
<para>
</para>
@db:
@album:
@photo:
@position:
<!-- ##### FUNCTION itdb_photodb_photoalbum_by_name ##### -->
<para>
</para>
@db:
@albumname:
@Returns:
<!-- ##### FUNCTION itdb_photodb_photoalbum_create ##### -->
<para>
</para>
@db:
@albumname:
@pos:
@Returns:
<!-- ##### FUNCTION itdb_photodb_photoalbum_remove ##### -->
<para>
</para>
@db:
@album:
@remove_pics:
<!-- ##### FUNCTION itdb_photodb_remove_photo ##### -->
<para>
</para>
@db:
@album:
@photo:
<!-- ##### FUNCTION itdb_photodb_write ##### -->
<para>
</para>
@photodb:
@error:
@Returns:
Index: artwork.sgml
===================================================================
RCS file: /cvsroot/gtkpod/libgpod/docs/reference/tmpl/artwork.sgml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- artwork.sgml 10 Jan 2007 13:25:09 -0000 1.7
+++ artwork.sgml 11 Jan 2007 07:10:55 -0000 1.8
@@ -2,16 +2,18 @@
Artwork
<!-- ##### SECTION Short_Description ##### -->
-Data structure to store iPod artwork (album covers and photos)
+Data structure to store iPod artwork (album covers)
<!-- ##### SECTION Long_Description ##### -->
<para>
-These functions and structures are for adding, changing, and removing artwork.
+These functions and structures are for adding, changing, and removing
+album/track artwork. For working with photos, see the
+<link linkend="photodb">Photo database</link> section.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<link linkend="photodb">Photo database</link>
</para>
<!-- ##### SECTION Stability_Level ##### -->
@@ -102,6 +104,20 @@
@Returns:
+<!-- ##### FUNCTION itdb_artwork_add_thumbnail_from_data ##### -->
+<para>
+
+</para>
+
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
+
+
<!-- ##### FUNCTION itdb_artwork_remove_thumbnail ##### -->
<para>
Index: device.sgml
===================================================================
RCS file: /cvsroot/gtkpod/libgpod/docs/reference/tmpl/device.sgml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- device.sgml 10 Jan 2007 13:25:09 -0000 1.7
+++ device.sgml 11 Jan 2007 07:10:55 -0000 1.8
@@ -72,6 +72,98 @@
@Returns:
+<!-- ##### FUNCTION itdb_device_set_sysinfo ##### -->
+<para>
+
+</para>
+
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
+
+
+<!-- ##### FUNCTION itdb_device_write_sysinfo ##### -->
+<para>
+
+</para>
+
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
+
+
+<!-- ##### FUNCTION itdb_device_get_ipod_info ##### -->
+<para>
+
+</para>
+
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
+
+
+<!-- ##### FUNCTION itdb_info_get_ipod_info_table ##### -->
+<para>
+
+</para>
+
[EMAIL PROTECTED]:
+
+
+<!-- ##### FUNCTION itdb_info_get_ipod_generation_string ##### -->
+<para>
+
+</para>
+
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
+
+
+<!-- ##### FUNCTION itdb_info_get_ipod_model_name_string ##### -->
+<para>
+
+</para>
+
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
+
+
+<!-- ##### FUNCTION itdb_init_ipod ##### -->
+<para>
+
+</para>
+
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
+
+
+<!-- ##### ENUM Itdb_IpodGeneration ##### -->
+<para>
+
+</para>
+
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
+
+<!-- ##### STRUCT Itdb_IpodInfo ##### -->
+<para>
+
+</para>
+
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
+
<!-- ##### ENUM Itdb_IpodModel ##### -->
<para>
Index: itunesdb-db.sgml
===================================================================
RCS file: /cvsroot/gtkpod/libgpod/docs/reference/tmpl/itunesdb-db.sgml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- itunesdb-db.sgml 10 Jan 2007 13:25:09 -0000 1.3
+++ itunesdb-db.sgml 11 Jan 2007 07:10:55 -0000 1.4
@@ -9,6 +9,86 @@
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
[EMAIL PROTECTED]). 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 @@
</para>
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
@error:
@Returns:
Index: itunesdb-lowlevel.sgml
===================================================================
RCS file: /cvsroot/gtkpod/libgpod/docs/reference/tmpl/itunesdb-lowlevel.sgml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- itunesdb-lowlevel.sgml 10 Jan 2007 13:25:09 -0000 1.2
+++ itunesdb-lowlevel.sgml 11 Jan 2007 07:10:55 -0000 1.3
@@ -63,6 +63,15 @@
@Returns:
+<!-- ##### FUNCTION itdb_get_photos_dir ##### -->
+<para>
+
+</para>
+
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
+
+
<!-- ##### FUNCTION itdb_get_itunesdb_path ##### -->
<para>
@@ -72,6 +81,15 @@
@Returns:
+<!-- ##### FUNCTION itdb_get_itunessd_path ##### -->
+<para>
+
+</para>
+
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
+
+
<!-- ##### FUNCTION itdb_get_artworkdb_path ##### -->
<para>
@@ -81,6 +99,24 @@
@Returns:
+<!-- ##### FUNCTION itdb_get_photodb_path ##### -->
+<para>
+
+</para>
+
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
+
+
+<!-- ##### FUNCTION itdb_get_photos_thumb_dir ##### -->
+<para>
+
+</para>
+
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
+
+
<!-- ##### FUNCTION itdb_get_path ##### -->
<para>
Index: track.sgml
===================================================================
RCS file: /cvsroot/gtkpod/libgpod/docs/reference/tmpl/track.sgml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- track.sgml 10 Jan 2007 13:25:09 -0000 1.4
+++ track.sgml 11 Jan 2007 07:10:55 -0000 1.5
@@ -227,6 +227,17 @@
@Returns:
+<!-- ##### FUNCTION itdb_track_set_thumbnails_from_data ##### -->
+<para>
+
+</para>
+
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
[EMAIL PROTECTED]:
+
+
<!-- ##### FUNCTION itdb_track_remove_thumbnails ##### -->
<para>
-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys - and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
gtkpod-cvs2 mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/gtkpod-cvs2
