From 517d4c9dca936c1a0ccb93271a3fa492df9951fc Mon Sep 17 00:00:00 2001 From: Todd Zullinger Date: Thu, 11 Jan 2007 07:10:55 +0000 Subject: 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. git-svn-id: https://gtkpod.svn.sf.net/svnroot/gtkpod/libgpod/trunk@1356 f01d2545-417e-4e96-918e-98f8d0dbbcb6 --- ChangeLog | 16 ++ README | 2 +- docs/reference/libgpod-docs.xml | 55 +++++-- docs/reference/libgpod-sections.txt | 18 +++ docs/reference/tmpl/artwork.sgml | 22 ++- docs/reference/tmpl/device.sgml | 92 +++++++++++ docs/reference/tmpl/itunesdb-db.sgml | 82 +++++++++- docs/reference/tmpl/itunesdb-lowlevel.sgml | 36 +++++ docs/reference/tmpl/photodb.sgml | 248 +++++++++++++++++++++++++++++ docs/reference/tmpl/track.sgml | 11 ++ src/itdb.h | 2 +- src/itdb_photoalbum.c | 17 +- 12 files changed, 575 insertions(+), 26 deletions(-) create mode 100644 docs/reference/tmpl/photodb.sgml diff --git a/ChangeLog b/ChangeLog index 6df8c6b..d56e064 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,19 @@ +2007-01-11 Todd Zullinger + + * README + docs/reference/libgpod-docs.xml + docs/reference/libgpod-sections.txt + docs/reference/tmpl/artwork.sgml + docs/reference/tmpl/device.sgml + docs/reference/tmpl/itunesdb-db.sgml + docs/reference/tmpl/itunesdb-lowlevel.sgml + docs/reference/tmpl/photodb.sgml + docs/reference/tmpl/track.sgml + src/itdb.h + src/itdb_photoalbum.c: 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. + 2007-01-10 Jorg Schuler * bindings/python/Makefile.am: correct 'make dist' failure (patch diff --git a/README b/README index e899f1d..cfe05f8 100644 --- a/README +++ b/README @@ -98,7 +98,7 @@ Quick HOWTO use libgpod for photos memory). It is automatically added to the Photo Library Album (first album), which is created if it does not exist already. - itdb_photodb_photoalbum_craete(): + itdb_photodb_photoalbum_create(): Create and add a new photoalbum. itdb_photodb_photoalbum_add_photo(): diff --git a/docs/reference/libgpod-docs.xml b/docs/reference/libgpod-docs.xml index bb66747..d80fd43 100644 --- a/docs/reference/libgpod-docs.xml +++ b/docs/reference/libgpod-docs.xml @@ -52,25 +52,54 @@ - This manual documents the interfaces of the libgpod - library and has some short notes to help get you up to speed - with using the library. + + This manual documents the interfaces of the libgpod library and + has some short notes to help get you up to speed with using the + library. + + + Please see the programs in the tests/ + directory of the source distribution for some usage examples. A more + complete example can be found in the source for Gtkpod. You can also ask questions + on the developer's mailing list: gtkpod-devel@lists.sourceforge.net. + - + iPod database + + + The iPod database functions are used for adding audio and video + to the iPod. + + + - - - iPod database components - - - - - - + + iPod database components + + + + + + + + + + Photo database + + + The Photo database functions are used for adding pictures to + the iPod. + + + + diff --git a/docs/reference/libgpod-sections.txt b/docs/reference/libgpod-sections.txt index da8b518..83dbace 100644 --- a/docs/reference/libgpod-sections.txt +++ b/docs/reference/libgpod-sections.txt @@ -185,6 +185,24 @@ itdb_thumb_new itdb_thumb_get_filename +
+photodb +Photo database +Itdb_PhotoAlbum +Itdb_PhotoDB +itdb_photodb_add_photo +itdb_photodb_add_photo_from_data +itdb_photodb_create +itdb_photodb_free +itdb_photodb_parse +itdb_photodb_photoalbum_add_photo +itdb_photodb_photoalbum_by_name +itdb_photodb_photoalbum_create +itdb_photodb_photoalbum_remove +itdb_photodb_remove_photo +itdb_photodb_write +
+ diff --git a/docs/reference/tmpl/artwork.sgml b/docs/reference/tmpl/artwork.sgml index 023b0e1..32a7679 100644 --- a/docs/reference/tmpl/artwork.sgml +++ b/docs/reference/tmpl/artwork.sgml @@ -2,16 +2,18 @@ Artwork -Data structure to store iPod artwork (album covers and photos) +Data structure to store iPod artwork (album covers) -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 +Photo database section. - +Photo database @@ -102,6 +104,20 @@ These functions and structures are for adding, changing, and removing artwork. @Returns: + + + + + +@artwork: +@type: +@image_data: +@image_data_len: +@rotation: +@error: +@Returns: + + diff --git a/docs/reference/tmpl/device.sgml b/docs/reference/tmpl/device.sgml index 36d2778..d90303e 100644 --- a/docs/reference/tmpl/device.sgml +++ b/docs/reference/tmpl/device.sgml @@ -72,6 +72,98 @@ These functions are for reading and setting information about the iPod. @Returns: + + + + + +@device: +@field: +@value: + + + + + + + +@device: +@error: +@Returns: + + + + + + + +@device: +@Returns: + + + + + + + +@Returns: + + + + + + + +@generation: +@Returns: + + + + + + + +@model: +@Returns: + + + + + + + +@mountpoint: +@model_number: +@ipod_name: +@error: +@Returns: + + + + + + + +@ITDB_IPOD_GENERATION_UNKNOWN: +@ITDB_IPOD_GENERATION_FIRST: +@ITDB_IPOD_GENERATION_SECOND: +@ITDB_IPOD_GENERATION_THIRD: +@ITDB_IPOD_GENERATION_FOURTH: +@ITDB_IPOD_GENERATION_FIFTH: +@ITDB_IPOD_GENERATION_SIXTH: +@ITDB_IPOD_GENERATION_MOBILE: + + + + + + +@model_number: +@capacity: +@ipod_model: +@ipod_generation: +@musicdirs: + 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. + +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 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.) + + +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. + @@ -82,7 +162,7 @@ database and getting the total number of tracks and playlists. -@db: +@itdb: @error: @Returns: diff --git a/docs/reference/tmpl/itunesdb-lowlevel.sgml b/docs/reference/tmpl/itunesdb-lowlevel.sgml index 2f70b23..5db32dd 100644 --- a/docs/reference/tmpl/itunesdb-lowlevel.sgml +++ b/docs/reference/tmpl/itunesdb-lowlevel.sgml @@ -63,6 +63,15 @@ control over the iPod database. @Returns: + + + + + +@mountpoint: +@Returns: + + @@ -72,6 +81,15 @@ control over the iPod database. @Returns: + + + + + +@mountpoint: +@Returns: + + @@ -81,6 +99,24 @@ control over the iPod database. @Returns: + + + + + +@mountpoint: +@Returns: + + + + + + + +@mountpoint: +@Returns: + + diff --git a/docs/reference/tmpl/photodb.sgml b/docs/reference/tmpl/photodb.sgml new file mode 100644 index 0000000..24032bb --- /dev/null +++ b/docs/reference/tmpl/photodb.sgml @@ -0,0 +1,248 @@ + +Photo database + + +Functions to create, read, write the photo database + + + +These functions are for creating, reading, and writing the photo +database. + + +Overview of using the Photo database: + + +itdb_photodb_parse(): +Read an existing PhotoDB. + + +itdb_photodb_create(): +Create a new #Itdb_PhotoDB structure. The Photo Library Album is +(first album) is created automatically. + + +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. + + +itdb_photodb_photoalbum_create(): +Create and add a new photoalbum. + + +itdb_photodb_photoalbum_add_photo(): +Add a photo (#Itdb_Artwork) to an existing photoalbum. + + +itdb_photodb_photoalbum_remove(): +Remove an existing photoalbum. Pictures can be kept in the +Photo Library or automatically removed as well. + + +itdb_photodb_remove_photo(): +Remove a photo either from a photoalbum or completely from the database. + + +itdb_photodb_write(): +Write out your PhotoDB. + + +itdb_photodb_free(): +Free all memory taken by the PhotoDB. + + +itdb_photodb_photoalbum_by_name(): +Find the first photoalbum with a given name or the Photo +Library Album if called with no name. + + +If you cannot add photos because your iPod is not recognized, +you may have to set the iPod model by calling + + +itdb_device_set_sysinfo (db->device, "ModelNumStr", model); + + +For example, "MA450" would stand for an 80 GB 6th generation iPod Video. See +itdb_device.c +for a list of supported models. + + +This information will be written to the iPod when the PhotoDB is +saved (itdb_device_write_sysinfo() is called). + + +Have a look at the test-photos +test program in the tests/ +directory of the libgpod source for an example of how to use the interface. + + + + + + + + + + + + + + + +@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: + + + + + + +@photos: +@photoalbums: +@device: +@usertype: +@userdata: +@userdata_duplicate: +@userdata_destroy: + + + + + + +@db: +@filename: +@position: +@rotation: +@error: +@Returns: + + + + + + + +@db: +@image_data: +@image_data_len: +@position: +@rotation: +@error: +@Returns: + + + + + + + +@mountpoint: +@Returns: + + + + + + + +@photodb: + + + + + + + +@mp: +@error: +@Returns: + + + + + + + +@db: +@album: +@photo: +@position: + + + + + + + +@db: +@albumname: +@Returns: + + + + + + + +@db: +@albumname: +@pos: +@Returns: + + + + + + + +@db: +@album: +@remove_pics: + + + + + + + +@db: +@album: +@photo: + + + + + + + +@photodb: +@error: +@Returns: + + diff --git a/docs/reference/tmpl/track.sgml b/docs/reference/tmpl/track.sgml index 8ec4980..860c98c 100644 --- a/docs/reference/tmpl/track.sgml +++ b/docs/reference/tmpl/track.sgml @@ -227,6 +227,17 @@ information about an iPod track. @Returns: + + + + + +@track: +@image_data: +@image_data_len: +@Returns: + + diff --git a/src/itdb.h b/src/itdb.h index 66bbcac..af728fd 100644 --- a/src/itdb.h +++ b/src/itdb.h @@ -1033,7 +1033,7 @@ Itdb_PhotoAlbum *itdb_photodb_photoalbum_create (Itdb_PhotoDB *db, gint pos); Itdb_PhotoDB *itdb_photodb_create (const gchar *mountpoint); void itdb_photodb_free (Itdb_PhotoDB *photodb); -gboolean itdb_photodb_write (Itdb_PhotoDB *db, GError **error); +gboolean itdb_photodb_write (Itdb_PhotoDB *photodb, GError **error); void itdb_photodb_remove_photo (Itdb_PhotoDB *db, Itdb_PhotoAlbum *album, Itdb_Artwork *photo); diff --git a/src/itdb_photoalbum.c b/src/itdb_photoalbum.c index 3fd10c7..108ae76 100644 --- a/src/itdb_photoalbum.c +++ b/src/itdb_photoalbum.c @@ -51,7 +51,7 @@ memory). It is automatically added to the Photo Library Album (first album), which is created if it does not exist already. - itdb_photodb_photoalbum_craete(): + itdb_photodb_photoalbum_create(): Create and add a new photoalbum. itdb_photodb_photoalbum_add_photo(): @@ -198,12 +198,11 @@ gchar *itdb_get_photos_thumb_dir (const gchar *mountpoint) /** * itdb_photodb_parse: - * - * Parses the photo database of an iPod mounted at @mp. - * * @mp: mountpoint of the iPod * @error: will contain the error description when an error occured. * + * Parses the photo database of an iPod mounted at @mp. + * * Return value: the imported PhotoDB or NULL in case of an error. **/ Itdb_PhotoDB *itdb_photodb_parse (const gchar *mp, GError **error) @@ -229,7 +228,6 @@ Itdb_PhotoDB *itdb_photodb_parse (const gchar *mp, GError **error) /** * itdb_photodb_create: - * * @mountpoint: mountpoint or NULL. * * Creates a new Itdb_PhotoDB. If mountpoint is NULL, you will have to @@ -582,6 +580,9 @@ void itdb_photodb_remove_photo (Itdb_PhotoDB *db, * @albumname: the name of the photoalbum to get or NULL for the * master photoalbum. * + * Find the first photoalbum with a given name or the Photo Library + * Album if called with no name. + * * Return value: a pointer to the first photoalbum named @albumname, * else NULL */ @@ -603,7 +604,7 @@ Itdb_PhotoAlbum *itdb_photodb_photoalbum_by_name (Itdb_PhotoDB *db, const gchar } /** - * itdb_photodb_remove_photoalbum: + * itdb_photodb_photoalbum_remove: * @db: the #Itdb_PhotoDB to apply changes to * @album: the album to be removed from the database * @remove_pics: TRUE to remove pics in that album permanently from @@ -670,10 +671,12 @@ void itdb_photodb_photoalbum_add_photo (Itdb_PhotoDB *db, /** * itdb_photodb_photoalbum_create: * @db: The database to create a new album in - * @album_name: the name of the new album + * @albumname: the name of the new album * @pos: position where to insert the newly created album (-1 for * append to end). * + * Create and add a new photoalbum. + * * Return value: the album which was created and added. */ Itdb_PhotoAlbum *itdb_photodb_photoalbum_create (Itdb_PhotoDB *db, -- cgit