diff options
27 files changed, 2542 insertions, 1345 deletions
@@ -1,3 +1,37 @@ +2008-12-07 Todd Zullinger <tmzullinger at users.sourceforge.net> + + * docs/reference/libgpod-docs.xml + docs/reference/libgpod-sections.txt + docs/reference/tmpl/artwork.sgml + docs/reference/tmpl/chapterdata.sgml + docs/reference/tmpl/device.sgml + docs/reference/tmpl/itunesdb-copying.sgml + docs/reference/tmpl/itunesdb-db.sgml + docs/reference/tmpl/itunesdb-lowlevel.sgml + docs/reference/tmpl/itunesdb-time.sgml + docs/reference/tmpl/libgpod-unused.sgml + docs/reference/tmpl/photodb.sgml + docs/reference/tmpl/track.sgml + src/itdb.h + src/itdb_artwork.c + src/itdb_chapterdata.c + src/itdb_device.c + src/itdb_device.h + src/itdb_itunesdb.c + src/itdb_photoalbum.c + src/itdb_playlist.c + src/itdb_plist.c + src/itdb_sysinfo_extended_parser.c + src/itdb_thumb.c + src/itdb_thumb.h + src/itdb_track.c + src/ithumb-writer.c: + Update API documentation + + Add new functions and missing enums, macros, and structs to the proper + places in the documentation, remove old/unused functions, and clean up + various minor issues. + 2008-12-07 Jorg Schuler <jcsjcs at users.sourceforge.net> * itdb_itunesdb.c (jump_table_letter): don't terminate when diff --git a/docs/reference/libgpod-docs.xml b/docs/reference/libgpod-docs.xml index c6c46b6..4c999fe 100644 --- a/docs/reference/libgpod-docs.xml +++ b/docs/reference/libgpod-docs.xml @@ -26,7 +26,7 @@ </author> </authorgroup> <copyright> - <year>2006</year> + <year>2006-2008</year> <holder>Christophe Fergeau</holder> </copyright> @@ -88,6 +88,7 @@ <xi:include href="xml/playlists.xml"/> <xi:include href="xml/smart-playlists.xml"/> <xi:include href="xml/artwork.xml"/> + <xi:include href="xml/chapterdata.xml"/> <xi:include href="xml/device.xml"/> </chapter> </part> diff --git a/docs/reference/libgpod-sections.txt b/docs/reference/libgpod-sections.txt index 7b7e217..0db7680 100644 --- a/docs/reference/libgpod-sections.txt +++ b/docs/reference/libgpod-sections.txt @@ -2,8 +2,7 @@ <FILE>itunesdb-db</FILE> <TITLE>The Itdb_iTunesDB structure</TITLE> Itdb_iTunesDB -ItdbUserDataDestroyFunc -ItdbUserDataDuplicateFunc +ItdbFileError itdb_new itdb_free @@ -15,6 +14,9 @@ itdb_get_mountpoint itdb_tracks_number itdb_tracks_number_nontransferred itdb_playlists_number + +ItdbUserDataDestroyFunc +ItdbUserDataDuplicateFunc </SECTION> <SECTION> @@ -42,16 +44,17 @@ itdb_get_itunessd_path itdb_get_artworkdb_path itdb_get_photodb_path itdb_get_photos_thumb_dir -itdb_get_path +itdb_get_path itdb_resolve_path -itdb_shuffle_write -itdb_shuffle_write_file + itdb_cp itdb_cp_get_dest_filename itdb_cp_finalize itdb_parse_file itdb_write_file +itdb_shuffle_write +itdb_shuffle_write_file itdb_duplicate </SECTION> @@ -79,6 +82,8 @@ itdb_track_by_id itdb_track_id_tree_create itdb_track_id_tree_destroy itdb_track_id_tree_by_id +itdb_track_get_thumbnail +itdb_track_has_thumbnails itdb_track_set_thumbnails itdb_track_set_thumbnails_from_data itdb_track_set_thumbnails_from_pixbuf @@ -150,6 +155,22 @@ itdb_spl_update_live </SECTION> <SECTION> +<FILE>chapterdata</FILE> +<TITLE>Chapter Data</TITLE> +Itdb_Chapter +Itdb_Chapterdata +itdb_chapter_new +itdb_chapter_duplicate +itdb_chapter_free +itdb_chapterdata_new +itdb_chapterdata_add_chapter +itdb_chapterdata_duplicate +itdb_chapterdata_remove_chapter +itdb_chapterdata_remove_chapters +itdb_chapterdata_free +</SECTION> + +<SECTION> <FILE>device</FILE> <TITLE>Device</TITLE> Itdb_Device @@ -160,16 +181,17 @@ itdb_device_read_sysinfo itdb_device_get_sysinfo itdb_device_set_sysinfo itdb_device_write_sysinfo +Itdb_IpodInfo itdb_device_get_ipod_info itdb_device_supports_artwork itdb_device_supports_photo +itdb_device_supports_video itdb_info_get_ipod_info_table +Itdb_IpodGeneration itdb_info_get_ipod_generation_string +Itdb_IpodModel itdb_info_get_ipod_model_name_string itdb_init_ipod -Itdb_IpodGeneration -Itdb_IpodInfo -Itdb_IpodModel Itdb_ArtworkFormat </SECTION> @@ -177,57 +199,57 @@ Itdb_ArtworkFormat <FILE>artwork</FILE> <TITLE>Artwork</TITLE> Itdb_Artwork -Itdb_Thumb itdb_artwork_new itdb_artwork_duplicate itdb_artwork_free +itdb_artwork_get_pixbuf +itdb_artwork_set_thumbnail itdb_artwork_set_thumbnail_from_data itdb_artwork_set_thumbnail_from_pixbuf itdb_artwork_remove_thumbnails +Itdb_Thumb itdb_thumb_duplicate itdb_thumb_free +itdb_thumb_to_pixbuf_at_size +itdb_thumb_to_pixbufs </SECTION> <SECTION> <FILE>photodb</FILE> <TITLE>Photo database</TITLE> -Itdb_PhotoAlbum Itdb_PhotoDB -itdb_photodb_add_photo -itdb_photodb_add_photo_from_data -itdb_photodb_add_photo_from_pixbuf itdb_photodb_create itdb_photodb_free itdb_photodb_parse +itdb_photodb_write + +itdb_photodb_add_photo +itdb_photodb_add_photo_from_data +itdb_photodb_add_photo_from_pixbuf +itdb_photodb_remove_photo + +Itdb_PhotoAlbum +itdb_photodb_photoalbum_create 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 </SECTION> <SECTION> <FILE>Internal</FILE> <SUBSECTION Private> +DEBUG_ARTWORK G_GNUC_INTERNAL -g_stat -g_mkdir -g_rename -g_printf -G_IS_DIR_SEPARATOR dump_mhif dump_mhia -dump_mhod_type_1 -dump_mhod_type_3 dump_mhni dump_mhod +dump_mhod_string dump_mhii dump_mhl dump_mhsd dump_mhfd dump_mhba -ITUNESDB_MAX_SIZE MHeader MhlHeader MhbdHeader @@ -238,6 +260,7 @@ MhypHeader MhipHeader MhitHeader ArtworkDB_MhodHeader +ArtworkDB_MhodHeaderString MhfdHeader MhliHeader MhiiHeader @@ -248,39 +271,78 @@ MhlfHeader MhifHeader MhiaHeader MhitHeader471 -ArtworkDB_MhodHeaderArtworkType3 MhodHeaderString -MhodHeaderArtworkType1 MhodHeaderSmartPlaylistData MhodHeaderSmartPlaylistRuleString MhodHeaderSmartPlaylistRuleNonString MhodHeaderSmartPlaylistRule iTunesDB_MhsdHeader MhodHeader -MhodHeaderArtworkType3 -playcount NO_PLAYCOUNT WCONTENTS_STEPSIZE -RED_BITS -RED_SHIFT -RED_MASK -GREEN_BITS -GREEN_SHIFT -GREEN_MASK -BLUE_BITS -BLUE_SHIFT -BLUE_MASK DBParseContext db_parse_context_get_m_header iPodSong DB_TO_CPU_GET DB_TO_CPU_GET_DB -ItdbFileError ITDB_FILE_ERROR itdb_file_error_quark -itdb_get_artwork_info_from_type +ITDB_DEVICE_ERROR +ItdbDeviceError +itdb_device_error_quark DbType Itdb_DB +ItdbThumbDataType + +GChecksum +GChecksumType +g_checksum_copy +g_checksum_free +g_checksum_get_digest +g_checksum_get_string +g_checksum_new +g_checksum_type_get_length +g_checksum_update +g_compute_checksum_for_data +g_compute_checksum_for_string + +SysInfoIpodProperties +itdb_sysinfo_extended_parse +itdb_sysinfo_properties_free + +ALPHA_BITS_555 +ALPHA_BITS_888 +ALPHA_MASK_555 +ALPHA_MASK_888 +ALPHA_SHIFT_555 +ALPHA_SHIFT_888 +BLUE_BITS_555 +BLUE_BITS_565 +BLUE_BITS_888 +BLUE_MASK_555 +BLUE_MASK_565 +BLUE_MASK_888 +BLUE_SHIFT_555 +BLUE_SHIFT_565 +BLUE_SHIFT_888 +GREEN_BITS_555 +GREEN_BITS_565 +GREEN_BITS_888 +GREEN_MASK_555 +GREEN_MASK_565 +GREEN_MASK_888 +GREEN_SHIFT_555 +GREEN_SHIFT_565 +GREEN_SHIFT_888 +RED_BITS_555 +RED_BITS_565 +RED_BITS_888 +RED_MASK_555 +RED_MASK_565 +RED_MASK_888 +RED_SHIFT_555 +RED_SHIFT_565 +RED_SHIFT_888 ITDB_SPLACTION_LAST_HOURS_VALUE ITDB_SPLACTION_LAST_MINUTES_VALUE @@ -296,5 +358,15 @@ ITDB_SPLACTION_LAST_QUARTER ITDB_SPLACTION_LAST_SOLAR_YEAR ITDB_SPLACTION_LAST_SIDEREAL_YEAR +SHA_BLOCKSIZE +SHA_BYTE +SHA_BYTE_ORDER +SHA_DIGESTSIZE +SHA_INFO +SHA_LONG +SHA_VERSION +sha_final +sha_init +sha_update +itdb_compute_hash </SECTION> - diff --git a/docs/reference/tmpl/artwork.sgml b/docs/reference/tmpl/artwork.sgml index a93704b..00a87f3 100644 --- a/docs/reference/tmpl/artwork.sgml +++ b/docs/reference/tmpl/artwork.sgml @@ -42,37 +42,53 @@ album/track artwork. For working with photos, see the @userdata_duplicate: @userdata_destroy: -<!-- ##### STRUCT Itdb_Thumb ##### --> +<!-- ##### FUNCTION itdb_artwork_new ##### --> <para> </para> -@data_type: -@rotation: +@Returns: -<!-- ##### FUNCTION itdb_artwork_new ##### --> + +<!-- ##### FUNCTION itdb_artwork_duplicate ##### --> <para> </para> +@artwork: @Returns: -<!-- ##### FUNCTION itdb_artwork_duplicate ##### --> +<!-- ##### FUNCTION itdb_artwork_free ##### --> <para> </para> @artwork: + + +<!-- ##### FUNCTION itdb_artwork_get_pixbuf ##### --> +<para> + +</para> + +@device: +@artwork: +@width: +@height: @Returns: -<!-- ##### FUNCTION itdb_artwork_free ##### --> +<!-- ##### FUNCTION itdb_artwork_set_thumbnail ##### --> <para> </para> @artwork: +@filename: +@rotation: +@error: +@Returns: <!-- ##### FUNCTION itdb_artwork_set_thumbnail_from_data ##### --> @@ -108,6 +124,14 @@ album/track artwork. For working with photos, see the @artwork: +<!-- ##### STRUCT Itdb_Thumb ##### --> +<para> + +</para> + +@data_type: +@rotation: + <!-- ##### FUNCTION itdb_thumb_duplicate ##### --> <para> @@ -125,3 +149,25 @@ album/track artwork. For working with photos, see the @thumb: +<!-- ##### FUNCTION itdb_thumb_to_pixbuf_at_size ##### --> +<para> + +</para> + +@device: +@thumb: +@width: +@height: +@Returns: + + +<!-- ##### FUNCTION itdb_thumb_to_pixbufs ##### --> +<para> + +</para> + +@device: +@thumb: +@Returns: + + diff --git a/docs/reference/tmpl/chapterdata.sgml b/docs/reference/tmpl/chapterdata.sgml new file mode 100644 index 0000000..6c83b9b --- /dev/null +++ b/docs/reference/tmpl/chapterdata.sgml @@ -0,0 +1,124 @@ +<!-- ##### SECTION Title ##### --> +Chapter Data + +<!-- ##### SECTION Short_Description ##### --> +Data structure to store chapter data for tracks + +<!-- ##### SECTION Long_Description ##### --> +<para> +Chapters allow for a large file to be divided into sections. The start and stop +points in the track are defined here, as well as the title for each chapter. +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### STRUCT Itdb_Chapter ##### --> +<para> + +</para> + +@startpos: +@chaptertitle: +@reserved_int1: +@reserved_int2: +@reserved1: +@reserved2: + +<!-- ##### STRUCT Itdb_Chapterdata ##### --> +<para> + +</para> + +@chapters: +@unk024: +@unk028: +@unk032: +@reserved_int1: +@reserved_int2: +@reserved1: +@reserved2: + +<!-- ##### FUNCTION itdb_chapter_new ##### --> +<para> + +</para> + +@Returns: + + +<!-- ##### FUNCTION itdb_chapter_duplicate ##### --> +<para> + +</para> + +@chapter: +@Returns: + + +<!-- ##### FUNCTION itdb_chapter_free ##### --> +<para> + +</para> + +@chapter: + + +<!-- ##### FUNCTION itdb_chapterdata_new ##### --> +<para> + +</para> + +@Returns: + + +<!-- ##### FUNCTION itdb_chapterdata_add_chapter ##### --> +<para> + +</para> + +@chapterdata: +@startpos: +@chaptertitle: +@Returns: + + +<!-- ##### FUNCTION itdb_chapterdata_duplicate ##### --> +<para> + +</para> + +@chapterdata: +@Returns: + + +<!-- ##### FUNCTION itdb_chapterdata_remove_chapter ##### --> +<para> + +</para> + +@chapterdata: +@chapter: + + +<!-- ##### FUNCTION itdb_chapterdata_remove_chapters ##### --> +<para> + +</para> + +@chapterdata: + + +<!-- ##### FUNCTION itdb_chapterdata_free ##### --> +<para> + +</para> + +@chapterdata: + + diff --git a/docs/reference/tmpl/device.sgml b/docs/reference/tmpl/device.sgml index c4b69e6..391ee00 100644 --- a/docs/reference/tmpl/device.sgml +++ b/docs/reference/tmpl/device.sgml @@ -94,16 +94,22 @@ These functions are for reading and setting information about the iPod. @Returns: -<!-- ##### FUNCTION itdb_device_get_ipod_info ##### --> +<!-- ##### STRUCT Itdb_IpodInfo ##### --> <para> </para> -@device: -@Returns: - +@model_number: +@capacity: +@ipod_model: +@ipod_generation: +@musicdirs: +@reserved_int1: +@reserved_int2: +@reserved1: +@reserved2: -<!-- ##### FUNCTION itdb_device_supports_artwork ##### --> +<!-- ##### FUNCTION itdb_device_get_ipod_info ##### --> <para> </para> @@ -112,7 +118,7 @@ These functions are for reading and setting information about the iPod. @Returns: -<!-- ##### FUNCTION itdb_device_supports_photo ##### --> +<!-- ##### FUNCTION itdb_device_supports_artwork ##### --> <para> </para> @@ -121,41 +127,29 @@ These functions are for reading and setting information about the iPod. @Returns: -<!-- ##### FUNCTION itdb_info_get_ipod_info_table ##### --> -<para> - -</para> - -@Returns: - - -<!-- ##### FUNCTION itdb_info_get_ipod_generation_string ##### --> +<!-- ##### FUNCTION itdb_device_supports_photo ##### --> <para> </para> -@generation: +@device: @Returns: -<!-- ##### FUNCTION itdb_info_get_ipod_model_name_string ##### --> +<!-- ##### FUNCTION itdb_device_supports_video ##### --> <para> </para> -@model: +@device: @Returns: -<!-- ##### FUNCTION itdb_init_ipod ##### --> +<!-- ##### FUNCTION itdb_info_get_ipod_info_table ##### --> <para> </para> -@mountpoint: -@model_number: -@ipod_name: -@error: @Returns: @@ -179,26 +173,22 @@ These functions are for reading and setting information about the iPod. @ITDB_IPOD_GENERATION_NANO_1: @ITDB_IPOD_GENERATION_NANO_2: @ITDB_IPOD_GENERATION_NANO_3: +@ITDB_IPOD_GENERATION_NANO_4: @ITDB_IPOD_GENERATION_VIDEO_1: @ITDB_IPOD_GENERATION_VIDEO_2: @ITDB_IPOD_GENERATION_CLASSIC_1: +@ITDB_IPOD_GENERATION_CLASSIC_2: @ITDB_IPOD_GENERATION_TOUCH_1: @ITDB_IPOD_GENERATION_IPHONE_1: -<!-- ##### STRUCT Itdb_IpodInfo ##### --> +<!-- ##### FUNCTION itdb_info_get_ipod_generation_string ##### --> <para> </para> -@model_number: -@capacity: -@ipod_model: -@ipod_generation: -@musicdirs: -@reserved_int1: -@reserved_int2: -@reserved1: -@reserved2: +@generation: +@Returns: + <!-- ##### ENUM Itdb_IpodModel ##### --> <para> @@ -228,6 +218,9 @@ These functions are for reading and setting information about the iPod. @ITDB_IPOD_MODEL_NANO_GREEN: @ITDB_IPOD_MODEL_NANO_PINK: @ITDB_IPOD_MODEL_NANO_RED: +@ITDB_IPOD_MODEL_NANO_YELLOW: +@ITDB_IPOD_MODEL_NANO_PURPLE: +@ITDB_IPOD_MODEL_NANO_ORANGE: @ITDB_IPOD_MODEL_IPHONE_1: @ITDB_IPOD_MODEL_SHUFFLE_SILVER: @ITDB_IPOD_MODEL_SHUFFLE_PINK: @@ -240,6 +233,27 @@ These functions are for reading and setting information about the iPod. @ITDB_IPOD_MODEL_CLASSIC_BLACK: @ITDB_IPOD_MODEL_TOUCH_BLACK: +<!-- ##### FUNCTION itdb_info_get_ipod_model_name_string ##### --> +<para> + +</para> + +@model: +@Returns: + + +<!-- ##### FUNCTION itdb_init_ipod ##### --> +<para> + +</para> + +@mountpoint: +@model_number: +@ipod_name: +@error: +@Returns: + + <!-- ##### STRUCT Itdb_ArtworkFormat ##### --> <para> diff --git a/docs/reference/tmpl/itunesdb-copying.sgml b/docs/reference/tmpl/itunesdb-copying.sgml index 5b28c10..134362e 100644 --- a/docs/reference/tmpl/itunesdb-copying.sgml +++ b/docs/reference/tmpl/itunesdb-copying.sgml @@ -6,8 +6,8 @@ Managing files on the iPod <!-- ##### SECTION Long_Description ##### --> <para> -These functions are for copying, renaming, and getting information about the -files and directories on the iPod +These functions are for copying, renaming, and retrieving information +about the files and directories on the iPod. </para> <!-- ##### SECTION See_Also ##### --> diff --git a/docs/reference/tmpl/itunesdb-db.sgml b/docs/reference/tmpl/itunesdb-db.sgml index 27d3f52..9d4bcee 100644 --- a/docs/reference/tmpl/itunesdb-db.sgml +++ b/docs/reference/tmpl/itunesdb-db.sgml @@ -2,15 +2,15 @@ iPod database reading/writing <!-- ##### SECTION Short_Description ##### --> -Functions to create, read, write the iPod database +Functions to read, write, and create an iPod database <!-- ##### SECTION Long_Description ##### --> <para> -These functions are for creating, reading, writing, and deleting the iPod +These functions are for reading, writing, creating, and deleting an iPod database and getting the total number of tracks and playlists. </para> <para> -Overview of using the iPod database: +Overview of using an iPod database: </para> <para> itdb_parse(): read the iTunesDB and ArtworkDB @@ -20,72 +20,65 @@ 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). +containing all tracks the playlists in the database. Each track is +represented by an #Itdb_Track. Each playlist is represented by an +#Itdb_Playlist. See the <link linkend="libgpod-Tracks">Tracks</link> +and <link linkend="libgpod-Playlists">Playlists</link> sections for +details on tracks and playlists, respectively. </para> <para> -A number of functions for adding, removing, duplicating tracks -are available. Please see -<link linkend="libgpod-Tracks">Tracks</link> for details. +Each #Itdb_Playlist has a GList called @members which contains all of +the tracks in the playlist. Tracks referenced in a playlist must also +be present in the @tracks GList of the #Itdb_iTunesDB. </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. +The iPod must contain one master playlist (MPL) containing all tracks +accessible on the iPod through the Music->Tracks/Albums/Artists/etc. +menu. In addition to 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 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. 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 +@tracks GList of the #Itdb_iTunesDB, however. </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. +Each track may have a thumbnail associated with it. You can retrieve a +#GdkPixmap of the thumbnail using itdb_artwork_get_pixbuf(). A +thumbnail can be added with itdb_track_set_thumbnails(). A thumbnail +can be removed with itdb_track_remove_thumbnails(). Please see the +<link linkend="libgpod-Artwork">Artwork</link> section for more +details on artwork related functions and structures. </para> +<note> <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_artwork_get_pixbuf(). 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 +Be aware 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 +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.) +files. </para> +</note> <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. +have @userdata and @usertype fields that can be used by the +application to store additional application-specific 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 ##### --> @@ -116,22 +109,16 @@ to the library _duplicate()/_free() functions. @userdata_duplicate: @userdata_destroy: -<!-- ##### USER_FUNCTION ItdbUserDataDestroyFunc ##### --> +<!-- ##### ENUM ItdbFileError ##### --> <para> </para> -@userdata: - - -<!-- ##### USER_FUNCTION ItdbUserDataDuplicateFunc ##### --> -<para> - -</para> - -@userdata: -@Returns: - +@ITDB_FILE_ERROR_SEEK: +@ITDB_FILE_ERROR_CORRUPT: +@ITDB_FILE_ERROR_NOTFOUND: +@ITDB_FILE_ERROR_RENAME: +@ITDB_FILE_ERROR_ITDB_CORRUPT: <!-- ##### FUNCTION itdb_new ##### --> <para> @@ -214,3 +201,20 @@ to the library _duplicate()/_free() functions. @Returns: +<!-- ##### USER_FUNCTION ItdbUserDataDestroyFunc ##### --> +<para> + +</para> + +@userdata: + + +<!-- ##### USER_FUNCTION ItdbUserDataDuplicateFunc ##### --> +<para> + +</para> + +@userdata: +@Returns: + + diff --git a/docs/reference/tmpl/itunesdb-lowlevel.sgml b/docs/reference/tmpl/itunesdb-lowlevel.sgml index 9b8aaa8..9026d76 100644 --- a/docs/reference/tmpl/itunesdb-lowlevel.sgml +++ b/docs/reference/tmpl/itunesdb-lowlevel.sgml @@ -137,73 +137,73 @@ control over the iPod database. @Returns: -<!-- ##### FUNCTION itdb_shuffle_write ##### --> +<!-- ##### FUNCTION itdb_cp ##### --> <para> </para> -@itdb: +@from_file: +@to_file: @error: @Returns: -<!-- ##### FUNCTION itdb_shuffle_write_file ##### --> +<!-- ##### FUNCTION itdb_cp_get_dest_filename ##### --> <para> </para> -@itdb: +@track: +@mountpoint: @filename: @error: @Returns: -<!-- ##### FUNCTION itdb_cp ##### --> +<!-- ##### FUNCTION itdb_cp_finalize ##### --> <para> </para> -@from_file: -@to_file: +@track: +@mountpoint: +@dest_filename: @error: @Returns: -<!-- ##### FUNCTION itdb_cp_get_dest_filename ##### --> +<!-- ##### FUNCTION itdb_parse_file ##### --> <para> </para> -@track: -@mountpoint: @filename: @error: @Returns: -<!-- ##### FUNCTION itdb_cp_finalize ##### --> +<!-- ##### FUNCTION itdb_write_file ##### --> <para> </para> -@track: -@mountpoint: -@dest_filename: +@itdb: +@filename: @error: @Returns: -<!-- ##### FUNCTION itdb_parse_file ##### --> +<!-- ##### FUNCTION itdb_shuffle_write ##### --> <para> </para> -@filename: +@itdb: @error: @Returns: -<!-- ##### FUNCTION itdb_write_file ##### --> +<!-- ##### FUNCTION itdb_shuffle_write_file ##### --> <para> </para> diff --git a/docs/reference/tmpl/itunesdb-time.sgml b/docs/reference/tmpl/itunesdb-time.sgml index aeee4fb..c0e33a7 100644 --- a/docs/reference/tmpl/itunesdb-time.sgml +++ b/docs/reference/tmpl/itunesdb-time.sgml @@ -2,15 +2,19 @@ Time handling <!-- ##### SECTION Short_Description ##### --> -Helper functions to convert between Epoch time and Mac (iPod) time +[DEPRECATED] Helper functions to convert between Epoch time and Mac +(iPod) time <!-- ##### SECTION Long_Description ##### --> <para> -The functions provide conversion between Epoch time and Mac (iPod) time. These -functions are now obsolete and should no longer be used, libgpod automatically -converts to/from Epoch time and iPod time when writing/reading the iPod -databases +The functions provide conversion between Epoch time and Mac (iPod) +time. </para> +<note> +These functions are now obsolete and should no longer be used, libgpod +automatically converts to/from Epoch time and iPod time when +writing/reading the iPod databases. +</note> <!-- ##### SECTION See_Also ##### --> <para> diff --git a/docs/reference/tmpl/libgpod-unused.sgml b/docs/reference/tmpl/libgpod-unused.sgml index ccbb77d..2fae13d 100644 --- a/docs/reference/tmpl/libgpod-unused.sgml +++ b/docs/reference/tmpl/libgpod-unused.sgml @@ -118,35 +118,6 @@ iTunesDB </para> -<!-- ##### ENUM ItdbFileError ##### --> -<para> - -</para> - -@ITDB_FILE_ERROR_SEEK: -@ITDB_FILE_ERROR_CORRUPT: -@ITDB_FILE_ERROR_NOTFOUND: -@ITDB_FILE_ERROR_RENAME: -@ITDB_FILE_ERROR_ITDB_CORRUPT: - -<!-- ##### ENUM ItdbThumbType ##### --> -<para> - -</para> - -@ITDB_THUMB_COVER_SMALL: -@ITDB_THUMB_COVER_LARGE: -@ITDB_THUMB_PHOTO_SMALL: -@ITDB_THUMB_PHOTO_LARGE: -@ITDB_THUMB_PHOTO_FULL_SCREEN: -@ITDB_THUMB_PHOTO_TV_SCREEN: -@ITDB_THUMB_COVER_XLARGE: -@ITDB_THUMB_COVER_MEDIUM: -@ITDB_THUMB_COVER_SMEDIUM: -@ITDB_THUMB_COVER_XSMALL: -@ITDB_THUMB_CHAPTER_SMALL: -@ITDB_THUMB_CHAPTER_LARGE: - <!-- ##### ENUM Itdb_Generation ##### --> <para> diff --git a/docs/reference/tmpl/photodb.sgml b/docs/reference/tmpl/photodb.sgml index 59a7a4d..aded6bf 100644 --- a/docs/reference/tmpl/photodb.sgml +++ b/docs/reference/tmpl/photodb.sgml @@ -60,19 +60,20 @@ Library Album if called with no name. <para> 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(), e.g. for an 80 GB 6th generation +iPod Video, you would use: </para> +<programlisting> +itdb_device_set_sysinfo (db->device, "ModelNumStr", "MA450"); +</programlisting> <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" +See <ulink type="http" url="http://gtkpod.svn.sourceforge.net/svnroot/gtkpod/libgpod/trunk/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). +The model number will be saved on the iPod when the PhotoDB is +written (itdb_photodb_write() calls itdb_device_write_sysinfo()). </para> <para> Have a look at the <ulink type="http" @@ -90,28 +91,14 @@ directory of the libgpod source for an example of how to use the interface. <!-- ##### SECTION Stability_Level ##### --> -<!-- ##### STRUCT Itdb_PhotoAlbum ##### --> +<!-- ##### STRUCT Itdb_PhotoDB ##### --> <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: +@photos: +@photoalbums: +@device: @reserved_int1: @reserved_int2: @reserved1: @@ -121,22 +108,42 @@ directory of the libgpod source for an example of how to use the interface. @userdata_duplicate: @userdata_destroy: -<!-- ##### STRUCT Itdb_PhotoDB ##### --> +<!-- ##### FUNCTION itdb_photodb_create ##### --> <para> </para> -@photos: -@photoalbums: -@device: -@reserved_int1: -@reserved_int2: -@reserved1: -@reserved2: -@usertype: -@userdata: -@userdata_duplicate: -@userdata_destroy: +@mountpoint: +@Returns: + + +<!-- ##### FUNCTION itdb_photodb_free ##### --> +<para> + +</para> + +@photodb: + + +<!-- ##### FUNCTION itdb_photodb_parse ##### --> +<para> + +</para> + +@mp: +@error: +@Returns: + + +<!-- ##### FUNCTION itdb_photodb_write ##### --> +<para> + +</para> + +@photodb: +@error: +@Returns: + <!-- ##### FUNCTION itdb_photodb_add_photo ##### --> <para> @@ -178,30 +185,56 @@ directory of the libgpod source for an example of how to use the interface. @Returns: -<!-- ##### FUNCTION itdb_photodb_create ##### --> +<!-- ##### FUNCTION itdb_photodb_remove_photo ##### --> <para> </para> -@mountpoint: -@Returns: +@db: +@album: +@photo: -<!-- ##### FUNCTION itdb_photodb_free ##### --> +<!-- ##### STRUCT Itdb_PhotoAlbum ##### --> <para> </para> @photodb: +@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: +@reserved_int1: +@reserved_int2: +@reserved1: +@reserved2: +@usertype: +@userdata: +@userdata_duplicate: +@userdata_destroy: - -<!-- ##### FUNCTION itdb_photodb_parse ##### --> +<!-- ##### FUNCTION itdb_photodb_photoalbum_create ##### --> <para> </para> -@mp: -@error: +@db: +@albumname: +@pos: @Returns: @@ -226,17 +259,6 @@ directory of the libgpod source for an example of how to use the interface. @Returns: -<!-- ##### FUNCTION itdb_photodb_photoalbum_create ##### --> -<para> - -</para> - -@db: -@albumname: -@pos: -@Returns: - - <!-- ##### FUNCTION itdb_photodb_photoalbum_remove ##### --> <para> @@ -247,23 +269,3 @@ directory of the libgpod source for an example of how to use the interface. @remove_pics: -<!-- ##### FUNCTION itdb_photodb_remove_photo ##### --> -<para> - -</para> - -@db: -@album: -@photo: - - -<!-- ##### FUNCTION itdb_photodb_write ##### --> -<para> - -</para> - -@photodb: -@error: -@Returns: - - diff --git a/docs/reference/tmpl/track.sgml b/docs/reference/tmpl/track.sgml index 3a3c14f..a6ff7fb 100644 --- a/docs/reference/tmpl/track.sgml +++ b/docs/reference/tmpl/track.sgml @@ -252,6 +252,26 @@ information about an iPod track. @Returns: +<!-- ##### FUNCTION itdb_track_get_thumbnail ##### --> +<para> + +</para> + +@track: +@width: +@height: +@Returns: + + +<!-- ##### FUNCTION itdb_track_has_thumbnails ##### --> +<para> + +</para> + +@track: +@Returns: + + <!-- ##### FUNCTION itdb_track_set_thumbnails ##### --> <para> @@ -50,7 +50,22 @@ G_BEGIN_DECLS #define G_GNUC_INTERNAL #endif +/** + * ItdbUserDataDestroyFunc: + * @userdata: A #gpointer to user data + * + * Function called to free userdata + */ typedef void (* ItdbUserDataDestroyFunc) (gpointer userdata); + +/** + * ItdbUserDataDuplicateFunc: + * @userdata: A #gpointer to user data + * + * Function called to duplicate userdata + * + * Returns: A #gpointer + */ typedef gpointer (* ItdbUserDataDuplicateFunc) (gpointer userdata); /* public structures */ @@ -77,6 +92,38 @@ typedef struct _Itdb_Chapterdata Itdb_Chapterdata; * \* ------------------------------------------------------------ */ +/** + * Itdb_IpodGeneration: + * @ITDB_IPOD_GENERATION_UNKNOWN: Unknown iPod + * @ITDB_IPOD_GENERATION_FIRST: First Generation iPod + * @ITDB_IPOD_GENERATION_SECOND: Second Generation iPod + * @ITDB_IPOD_GENERATION_THIRD: Third Generation iPod + * @ITDB_IPOD_GENERATION_FOURTH: Fourth Generation iPod + * @ITDB_IPOD_GENERATION_PHOTO: Photo iPod + * @ITDB_IPOD_GENERATION_MOBILE: Mobile iPod + * @ITDB_IPOD_GENERATION_MINI_1: First Generation iPod Mini + * @ITDB_IPOD_GENERATION_MINI_2: Second Generation iPod Mini + * @ITDB_IPOD_GENERATION_SHUFFLE_1: First Generation iPod Shuffle + * @ITDB_IPOD_GENERATION_SHUFFLE_2: Second Generation iPod Shuffle + * @ITDB_IPOD_GENERATION_SHUFFLE_3: Third Generation iPod Shuffle + * @ITDB_IPOD_GENERATION_NANO_1: First Generation iPod Nano + * @ITDB_IPOD_GENERATION_NANO_2: Second Generation iPod Nano + * @ITDB_IPOD_GENERATION_NANO_3: Third Generation iPod Nano + * @ITDB_IPOD_GENERATION_NANO_4: Fourth Generation iPod Nano + * @ITDB_IPOD_GENERATION_VIDEO_1: First Generation iPod Video (aka 5g) + * @ITDB_IPOD_GENERATION_VIDEO_2: Second Generation iPod Video (aka 5.5g) + * @ITDB_IPOD_GENERATION_CLASSIC_1: First Generation iPod Classic + * @ITDB_IPOD_GENERATION_CLASSIC_2: Second Generation iPod Classic + * @ITDB_IPOD_GENERATION_TOUCH_1: First Generation iPod Touch + * @ITDB_IPOD_GENERATION_IPHONE_1: First Generation iPhone + * + * iPod generation information + * + * See http://support.apple.com/kb/HT1353 and http://en.wikipedia.org/wiki/IPod + * for more details. + * + * Since: 0.4.0 + */ typedef enum { ITDB_IPOD_GENERATION_UNKNOWN, ITDB_IPOD_GENERATION_FIRST, @@ -102,6 +149,50 @@ typedef enum { ITDB_IPOD_GENERATION_IPHONE_1, } Itdb_IpodGeneration; +/** + * Itdb_IpodModel: + * @ITDB_IPOD_MODEL_INVALID: Invalid model + * @ITDB_IPOD_MODEL_UNKNOWN: Unknown model + * @ITDB_IPOD_MODEL_COLOR: Color iPod + * @ITDB_IPOD_MODEL_COLOR_U2: Color iPod (U2) + * @ITDB_IPOD_MODEL_REGULAR: Regular iPod + * @ITDB_IPOD_MODEL_REGULAR_U2: Regular iPod (U2) + * @ITDB_IPOD_MODEL_MINI: iPod Mini + * @ITDB_IPOD_MODEL_MINI_BLUE: iPod Mini (Blue) + * @ITDB_IPOD_MODEL_MINI_PINK: iPod Mini (Pink) + * @ITDB_IPOD_MODEL_MINI_GREEN: iPod Mini (Green) + * @ITDB_IPOD_MODEL_MINI_GOLD: iPod Mini (Gold) + * @ITDB_IPOD_MODEL_SHUFFLE: iPod Shuffle + * @ITDB_IPOD_MODEL_NANO_WHITE: iPod Nano (White) + * @ITDB_IPOD_MODEL_NANO_BLACK: iPod Nano (Black) + * @ITDB_IPOD_MODEL_VIDEO_WHITE: iPod Video (White) + * @ITDB_IPOD_MODEL_VIDEO_BLACK: iPod Video (Black) + * @ITDB_IPOD_MODEL_MOBILE_1: Mobile iPod + * @ITDB_IPOD_MODEL_VIDEO_U2: iPod Video (U2) + * @ITDB_IPOD_MODEL_NANO_SILVER: iPod Nano (Silver) + * @ITDB_IPOD_MODEL_NANO_BLUE: iPod Nano (Blue) + * @ITDB_IPOD_MODEL_NANO_GREEN: iPod Nano (Green) + * @ITDB_IPOD_MODEL_NANO_PINK: iPod Nano (Pink) + * @ITDB_IPOD_MODEL_NANO_RED: iPod Nano (Red) + * @ITDB_IPOD_MODEL_NANO_YELLOW: iPod Nano (Yellow) + * @ITDB_IPOD_MODEL_NANO_PURPLE: iPod Nano (Purple) + * @ITDB_IPOD_MODEL_NANO_ORANGE: iPod Nano (Orange) + * @ITDB_IPOD_MODEL_IPHONE_1: iPhone + * @ITDB_IPOD_MODEL_SHUFFLE_SILVER: iPod Shuffle (Silver) + * @ITDB_IPOD_MODEL_SHUFFLE_PINK: iPod Shuffle (Pink) + * @ITDB_IPOD_MODEL_SHUFFLE_BLUE: iPod Shuffle (Blue) + * @ITDB_IPOD_MODEL_SHUFFLE_GREEN: iPod Shuffle (Green) + * @ITDB_IPOD_MODEL_SHUFFLE_ORANGE: iPod Shuffle (Orange) + * @ITDB_IPOD_MODEL_SHUFFLE_PURPLE: iPod Shuffle (Purple) + * @ITDB_IPOD_MODEL_SHUFFLE_RED: iPod Shuffle (Red) + * @ITDB_IPOD_MODEL_CLASSIC_SILVER: iPod Classic (Silver) + * @ITDB_IPOD_MODEL_CLASSIC_BLACK: iPod Classic (Black) + * @ITDB_IPOD_MODEL_TOUCH_BLACK: iPod Touch (Black) + * + * iPod model information + * + * Since: 0.4.0 + */ typedef enum { ITDB_IPOD_MODEL_INVALID, ITDB_IPOD_MODEL_UNKNOWN, @@ -142,19 +233,34 @@ typedef enum { ITDB_IPOD_MODEL_TOUCH_BLACK, } Itdb_IpodModel; +/** + * Itdb_IpodInfo: + * @model_number: The model number. This is abbreviated. If the first + * character is not numeric, it is ommited. e.g. + * "MA350 -> A350", "M9829 -> 9829" + * @capacity: The iPod's capacity in gigabytes + * @ipod_model: The iPod model + * @ipod_generation: The iPod generation + * @musicdirs: The number of music (Fnn) dirs created by iTunes. The + * exact number seems to be version dependent. Therefore, the + * numbers here represent a mixture of reported values and + * common sense. Note: this number does not necessarily + * represent the number of dirs present on a particular iPod. + * It is used when setting up a new iPod from scratch. + * @reserved_int1: Reserved for future use + * @reserved_int2: Reserved for future use + * @reserved1: Reserved for future use + * @reserved2: Reserved for future use + * + * Structure representing information about an iPod + * + * Since: 0.4.0 + */ struct _Itdb_IpodInfo { - /* model_number is abbreviated: if the first character is not - numeric, it is ommited. e.g. "MA350 -> A350", "M9829 -> 9829" */ const gchar *model_number; - const double capacity; /* in GB */ + const double capacity; const Itdb_IpodModel ipod_model; const Itdb_IpodGeneration ipod_generation; - /* Number of music (Fnn) dirs created by iTunes. The exact number - seems to be version dependent. Therefore, the numbers here - represent a mixture of reported values and common sense. Note: - this number does not necessarily represent the number of dirs - present on a particular iPod. It is used when setting up a new - iPod from scratch. */ const guint musicdirs; /* reserved for future use */ const gint32 reserved_int1; @@ -177,17 +283,51 @@ struct _Itdb_IpodInfo { copy. Further, all enums and #defines below, Itdb_SPLRule, Itdb_SPLRules, and Itdb_SPLPref may also be used under a FreeBSD license. */ +/** + * ITDB_SPL_STRING_MAXLEN: + * + * Maximum string length for smart playlists + * + * Since: 0.5.0 + */ #define ITDB_SPL_STRING_MAXLEN 255 + +/** + * ITDB_SPL_DATE_IDENTIFIER: + * + * Identifier for smart playlist date fields + * + * Since: 0.5.0 + */ #define ITDB_SPL_DATE_IDENTIFIER (G_GINT64_CONSTANT (0x2dae2dae2dae2daeU)) /* Definitions for smart playlists */ -typedef enum { /* types for match_operator */ - ITDB_SPLMATCH_AND = 0, /* AND rule - all of the rules must be true in - order for the combined rule to be applied */ - ITDB_SPLMATCH_OR = 1 /* OR rule */ + +/** + * ItdbSPLMatch: + * @ITDB_SPLMATCH_AND: Logical AND - all of the rules must be true in order for + * the combined rule to be applied + * @ITDB_SPLMATCH_OR: Logical OR - any of the rules may be true + * + * Types for smart playlist rules match_operator + */ +typedef enum { + ITDB_SPLMATCH_AND = 0, + ITDB_SPLMATCH_OR = 1 } ItdbSPLMatch; -/* Limit Types.. like limit playlist to 100 minutes or to 100 songs */ +/** + * ItdbLimitType: + * @ITDB_LIMITTYPE_MINUTES: Limit in minutes + * @ITDB_LIMITTYPE_MB: Limit in megabytes + * @ITDB_LIMITTYPE_SONGS: Limit in number of songs + * @ITDB_LIMITTYPE_HOURS: Limit in hours + * @ITDB_LIMITTYPE_GB: Limit in gigabytes + * + * The type of unit to use when limiting a playlist + * + * Since: 0.5.0 + */ typedef enum { ITDB_LIMITTYPE_MINUTES = 0x01, ITDB_LIMITTYPE_MB = 0x02, @@ -196,19 +336,39 @@ typedef enum { ITDB_LIMITTYPE_GB = 0x05 } ItdbLimitType; -/* Limit Sorts.. Like which songs to pick when using a limit type - Special note: the values for ITDB_LIMITSORT_LEAST_RECENTLY_ADDED, - ITDB_LIMITSORT_LEAST_OFTEN_PLAYED, ITDB_LIMITSORT_LEAST_RECENTLY_PLAYED, and - ITDB_LIMITSORT_LOWEST_RATING are really 0x10, 0x14, 0x15, 0x17, with the - 'limitsort_opposite' flag set. This is the same value as the - "positive" value (i.e. ITDB_LIMITSORT_LEAST_RECENTLY_ADDED), and is - really very terribly awfully weird, so we map the values to iPodDB - specific values with the high bit set. - - On writing, we check the high bit and write the limitsort_opposite - from that. That way, we don't have to deal with programs using the - class needing to set the wrong limit and then make it into the - "opposite", which would be frickin' annoying. */ +/** + * ItdbLimitSort: + * @ITDB_LIMITSORT_RANDOM: Sort randomly + * @ITDB_LIMITSORT_SONG_NAME: Sort by track name + * @ITDB_LIMITSORT_ALBUM: Sort by album name + * @ITDB_LIMITSORT_ARTIST: Sort by artist name + * @ITDB_LIMITSORT_GENRE: Sort by genre + * @ITDB_LIMITSORT_MOST_RECENTLY_ADDED: Sort by most recently added + * @ITDB_LIMITSORT_LEAST_RECENTLY_ADDED: Sort by least recently added + * @ITDB_LIMITSORT_MOST_OFTEN_PLAYED: Sort by most often played + * @ITDB_LIMITSORT_LEAST_OFTEN_PLAYED: Sort by least often played + * @ITDB_LIMITSORT_MOST_RECENTLY_PLAYED: Sort by most recently played + * @ITDB_LIMITSORT_LEAST_RECENTLY_PLAYED: Sort by least recently played + * @ITDB_LIMITSORT_HIGHEST_RATING: Sort by highest rating + * @ITDB_LIMITSORT_LOWEST_RATING: Sort by lowest rating + * + * Which songs to pick when using a limit type + * + * Note: the values for #ITDB_LIMITSORT_LEAST_RECENTLY_ADDED, + * #ITDB_LIMITSORT_LEAST_OFTEN_PLAYED, #ITDB_LIMITSORT_LEAST_RECENTLY_PLAYED, + * and #ITDB_LIMITSORT_LOWEST_RATING are really 0x10, 0x14, 0x15, 0x17, with the + * 'limitsort_opposite' flag set. This is the same value as the "positive" + * value (i.e. #ITDB_LIMITSORT_LEAST_RECENTLY_ADDED), and is really very + * terribly awfully weird, so we map the values to iPodDB specific values with + * the high bit set. + * + * On writing, we check the high bit and write the limitsort_opposite from that. + * That way, we don't have to deal with programs using the class needing to set + * the wrong limit and then make it into the "opposite", which would be frickin' + * annoying. + * + * Since: 0.5.0 + */ typedef enum { ITDB_LIMITSORT_RANDOM = 0x02, ITDB_LIMITSORT_SONG_NAME = 0x03, @@ -225,28 +385,57 @@ typedef enum { ITDB_LIMITSORT_LOWEST_RATING = 0x80000017, /* See note above */ } ItdbLimitSort; -/* Smartlist Actions - Used in the rules. -Note by Otto (Samuel Wood): - really this is a bitmapped field... - high byte - bit 0 = "string" values if set, "int" values if not set - bit 1 = "not", or to negate the check. - lower 2 bytes - bit 0 = simple "IS" query - bit 1 = contains - bit 2 = begins with - bit 3 = ends with - bit 4 = greater than - bit 5 = unknown, but probably greater than or equal to - bit 6 = less than - bit 7 = unknown, but probably less than or equal to - bit 8 = a range selection - bit 9 = "in the last" +/** + * ItdbSPLAction: + * @ITDB_SPLACTION_IS_INT: is integer ("Is Set" in iTunes) + * @ITDB_SPLACTION_IS_GREATER_THAN: is greater than ("Is after" in iTunes) + * @ITDB_SPLACTION_IS_LESS_THAN: is less than ("Is Before" in iTunes) + * @ITDB_SPLACTION_IS_IN_THE_RANGE: is in the range + * @ITDB_SPLACTION_IS_IN_THE_LAST: is in the last + * @ITDB_SPLACTION_BINARY_AND: binary AND + * @ITDB_SPLACTION_IS_STRING: is a string + * @ITDB_SPLACTION_CONTAINS: contains + * @ITDB_SPLACTION_STARTS_WITH: starts with + * @ITDB_SPLACTION_ENDS_WITH: ends with + * @ITDB_SPLACTION_IS_NOT_INT: is not an integer ("Is Not Set" in iTunes) + * @ITDB_SPLACTION_IS_NOT_GREATER_THAN: is not greater than (not in iTunes) + * @ITDB_SPLACTION_IS_NOT_LESS_THAN: is not less than (not in iTunes) + * @ITDB_SPLACTION_IS_NOT_IN_THE_RANGE: is not in the range (not in iTunes) + * @ITDB_SPLACTION_IS_NOT_IN_THE_LAST: is not in the last + * @ITDB_SPLACTION_IS_NOT: is not + * @ITDB_SPLACTION_DOES_NOT_CONTAIN: does not contain + * @ITDB_SPLACTION_DOES_NOT_START_WITH: does not start with (not in iTunes) + * @ITDB_SPLACTION_DOES_NOT_END_WITH: does not end with (not in iTunes) + * + * Smartlist Actions used in smart playlist rules. + * + * Note by Otto (Samuel Wood): + * <informalexample> + * <programlisting> + * really this is a bitmapped field... + * high byte + * bit 0 = "string" values if set, "int" values if not set + * bit 1 = "not", or to negate the check. + * lower 2 bytes + * bit 0 = simple "IS" query + * bit 1 = contains + * bit 2 = begins with + * bit 3 = ends with + * bit 4 = greater than + * bit 5 = unknown, but probably greater than or equal to + * bit 6 = less than + * bit 7 = unknown, but probably less than or equal to + * bit 8 = a range selection + * bit 9 = "in the last" + * </programlisting> + * </informalexample> + * + * Since: 0.5.0 */ typedef enum { - ITDB_SPLACTION_IS_INT = 0x00000001, /* "Is Set" in iTunes */ - ITDB_SPLACTION_IS_GREATER_THAN = 0x00000010, /* "Is After" in iTunes */ - ITDB_SPLACTION_IS_LESS_THAN = 0x00000040, /* "Is Before" in iTunes */ + ITDB_SPLACTION_IS_INT = 0x00000001, + ITDB_SPLACTION_IS_GREATER_THAN = 0x00000010, + ITDB_SPLACTION_IS_LESS_THAN = 0x00000040, ITDB_SPLACTION_IS_IN_THE_RANGE = 0x00000100, ITDB_SPLACTION_IS_IN_THE_LAST = 0x00000200, ITDB_SPLACTION_BINARY_AND = 0x00000400, @@ -256,25 +445,32 @@ typedef enum { ITDB_SPLACTION_STARTS_WITH = 0x01000004, ITDB_SPLACTION_ENDS_WITH = 0x01000008, - ITDB_SPLACTION_IS_NOT_INT = 0x02000001, /* "Is Not Set" in iTunes */ - - /* Note: Not available in iTunes 4.5 (untested on iPod) */ + ITDB_SPLACTION_IS_NOT_INT = 0x02000001, ITDB_SPLACTION_IS_NOT_GREATER_THAN = 0x02000010, - /* Note: Not available in iTunes 4.5 (untested on iPod) */ ITDB_SPLACTION_IS_NOT_LESS_THAN = 0x02000040, - /* Note: Not available in iTunes 4.5 (seems to work on iPod) */ ITDB_SPLACTION_IS_NOT_IN_THE_RANGE = 0x02000100, - ITDB_SPLACTION_IS_NOT_IN_THE_LAST = 0x02000200, + ITDB_SPLACTION_IS_NOT = 0x03000001, ITDB_SPLACTION_DOES_NOT_CONTAIN = 0x03000002, - - /* Note: Not available in iTunes 4.5 (seems to work on iPod) */ ITDB_SPLACTION_DOES_NOT_START_WITH = 0x03000004, - /* Note: Not available in iTunes 4.5 (seems to work on iPod) */ ITDB_SPLACTION_DOES_NOT_END_WITH = 0x03000008, } ItdbSPLAction; +/** + * ItdbSPLFieldType: + * @ITDB_SPLFT_STRING: string + * @ITDB_SPLFT_INT: integer + * @ITDB_SPLFT_BOOLEAN: boolean + * @ITDB_SPLFT_DATE: date + * @ITDB_SPLFT_PLAYLIST: playlist + * @ITDB_SPLFT_UNKNOWN: unknown + * @ITDB_SPLFT_BINARY_AND: binary AND + * + * Smart Playlist Field Types + * + * Since: 0.5.0 + */ typedef enum { ITDB_SPLFT_STRING = 1, @@ -286,6 +482,24 @@ typedef enum ITDB_SPLFT_BINARY_AND } ItdbSPLFieldType; +/** + * ItdbSPLActionType: + * @ITDB_SPLAT_STRING: string + * @ITDB_SPLAT_INT: from integer + * @ITDB_SPLAT_DATE: from date ... + * @ITDB_SPLAT_RANGE_INT: an integer range ... + * @ITDB_SPLAT_RANGE_DATE: a date range ... + * @ITDB_SPLAT_INTHELAST: in the last ... + * @ITDB_SPLAT_PLAYLIST: in playlist + * @ITDB_SPLAT_NONE: none + * @ITDB_SPLAT_INVALID: invalid + * @ITDB_SPLAT_UNKNOWN: unknown + * @ITDB_SPLAT_BINARY_AND: is / is not (binary AND) + * + * Smart Playlist Action Types + * + * Since: 0.5.0 + */ typedef enum { ITDB_SPLAT_STRING = 1, @@ -302,14 +516,23 @@ typedef enum } ItdbSPLActionType; -/* These are to pass to AddRule() when you need a unit for the two "in - the last" action types Or, in theory, you can use any time - range... iTunes might not like it, but the iPod shouldn't care. */ +/** + * ItdbSPLActionLast: + * @ITDB_SPLACTION_LAST_DAYS_VALUE: Seconds in 24 hours + * @ITDB_SPLACTION_LAST_WEEKS_VALUE: Seconds in 7 days + * @ITDB_SPLACTION_LAST_MONTHS_VALUE: Seconds in 1 month (approximately) + * + * These are to pass to AddRule() when you need a unit for the two "in the last" + * action types. In theory, you can use any time range. iTunes might not + * like it, but the iPod shouldn't care. + * + * Since: 0.5.0 + */ typedef enum { ITDB_SPLACTION_LAST_DAYS_VALUE = 86400, /* nr of secs in 24 hours */ ITDB_SPLACTION_LAST_WEEKS_VALUE = 604800, /* nr of secs in 7 days */ ITDB_SPLACTION_LAST_MONTHS_VALUE = 2628000,/* nr of secs in 30.4167 - days ~= 1 month */ + days ~= 1 month */ } ItdbSPLActionLast; #if 0 @@ -331,84 +554,161 @@ typedef enum { #define ITDB_SPLACTION_LAST_SIDEREAL_YEAR 31558150 // a "sidereal year" is the time it takes the earth to reach the same point in space again, compared to the stars #endif -/* Smartlist fields - Used for rules. */ +/** + * ItdbSPLField: + * @ITDB_SPLFIELD_SONG_NAME: Song name (string) + * @ITDB_SPLFIELD_ALBUM: Album (string) + * @ITDB_SPLFIELD_ARTIST: Artist (string) + * @ITDB_SPLFIELD_BITRATE: Bitrate (integer, e.g. from/to = 128) + * @ITDB_SPLFIELD_SAMPLE_RATE: Sample rate (integer, e.g. from/to = 44100) + * @ITDB_SPLFIELD_YEAR: Year (integer, e.g. from/to = 2004) + * @ITDB_SPLFIELD_GENRE: Genre (string) + * @ITDB_SPLFIELD_KIND: File type (string, e.g. MP3-File) + * @ITDB_SPLFIELD_DATE_MODIFIED: Date modified (integer, e.g. + * from/to = bcf93280 == is before 6/19/2004) + * @ITDB_SPLFIELD_TRACKNUMBER: Track number (integer, e.g. from/to = 2) + * @ITDB_SPLFIELD_SIZE: Size (integer, e.g. + * from/to = 0x00600000 for 6MB) + * @ITDB_SPLFIELD_TIME: Time (integer, e.g. + * from/to = 83999 for 1:23/83 seconds) + * @ITDB_SPLFIELD_COMMENT: Comment (string) + * @ITDB_SPLFIELD_DATE_ADDED: Date added (integer, e.g. + * from/to = bcfa83ff == is after 6/19/2004) + * @ITDB_SPLFIELD_COMPOSER: Composer (string) + * @ITDB_SPLFIELD_PLAYCOUNT: Playcount (integer, e.g. from/to = 1) + * @ITDB_SPLFIELD_LAST_PLAYED: Date last played (integer, e.g. + * from = bcfa83ff (6/19/2004) + * to = 0xbcfbd57f (6/20/2004)) + * @ITDB_SPLFIELD_DISC_NUMBER: Disc number (integer, e.g. from/to = 1) + * @ITDB_SPLFIELD_RATING: Rating (integer, e.g. + * from/to = 60 (3 stars)) + * @ITDB_SPLFIELD_COMPILATION: Compilation (integer, e.g. + * is set -> ITDB_SPLACTION_IS_INT/from=1, + * not set -> ITDB_SPLACTION_IS_NOT_INT/from=1) + * @ITDB_SPLFIELD_BPM: Beats per minute (integer, e.g. + * from/to = 60) + * @ITDB_SPLFIELD_GROUPING: Grouping (string) + * @ITDB_SPLFIELD_PLAYLIST: FIXME Unknown...not parsed correctly... + * from/to = 0xb6fbad5f for "Purchased Music". + * Extra data after "to"... + * @ITDB_SPLFIELD_VIDEO_KIND: Logical integer (works on mediatype) + * @ITDB_SPLFIELD_TVSHOW: TV Show (string) + * @ITDB_SPLFIELD_SEASON_NR: Season number (integer) + * @ITDB_SPLFIELD_SKIPCOUNT: Skipcount (integer) + * @ITDB_SPLFIELD_LAST_SKIPPED: Last skipped (integer) + * @ITDB_SPLFIELD_ALBUMARTIST: Album artist (string) + * + * Smart Playlist Fields, used for Smart Playlist Rules (#Itdb_SPLRule). + * + * Since: 0.5.0 + */ typedef enum { - ITDB_SPLFIELD_SONG_NAME = 0x02, /* String */ - ITDB_SPLFIELD_ALBUM = 0x03, /* String */ - ITDB_SPLFIELD_ARTIST = 0x04, /* String */ - ITDB_SPLFIELD_BITRATE = 0x05, /* Int (e.g. from/to = 128) */ - ITDB_SPLFIELD_SAMPLE_RATE = 0x06, /* Int (e.g. from/to = 44100) */ - ITDB_SPLFIELD_YEAR = 0x07, /* Int (e.g. from/to = 2004) */ - ITDB_SPLFIELD_GENRE = 0x08, /* String */ - ITDB_SPLFIELD_KIND = 0x09, /* String */ - ITDB_SPLFIELD_DATE_MODIFIED = 0x0a,/* Int (e.g. from/to = bcf93280 == - is before 6/19/2004)*/ - ITDB_SPLFIELD_TRACKNUMBER = 0x0b, /* Int (e.g. from = 1, to = 2) */ - ITDB_SPLFIELD_SIZE = 0x0c, /* Int (e.g. from/to = 0x00600000 - for 6MB) */ - ITDB_SPLFIELD_TIME = 0x0d, /* Int (e.g. from/to = 83999 for - 1:23/83 seconds) */ - ITDB_SPLFIELD_COMMENT = 0x0e, /* String */ - ITDB_SPLFIELD_DATE_ADDED = 0x10, /* Int (e.g. from/to = bcfa83ff == - is after 6/19/2004) */ - ITDB_SPLFIELD_COMPOSER = 0x12, /* String */ - ITDB_SPLFIELD_PLAYCOUNT = 0x16, /* Int (e.g. from/to = 1) */ - ITDB_SPLFIELD_LAST_PLAYED = 0x17, /* Int/ (e.g. from = bcfa83ff (6/19/2004) - to = 0xbcfbd57f (6/20/2004)) */ - ITDB_SPLFIELD_DISC_NUMBER = 0x18, /* Int (e.g. from/to = 1) */ - ITDB_SPLFIELD_RATING = 0x19, /* Int/Stars Rating (e.g. from/to = - 60 (3 stars)) */ - ITDB_SPLFIELD_COMPILATION = 0x1f, /* Int (e.g. is set -> - ITDB_SPLACTION_IS_INT/from=1, - is not set -> - ITDB_SPLACTION_IS_NOT_INT/from=1) */ - ITDB_SPLFIELD_BPM = 0x23, /* Int (e.g. from/to = 60) */ - ITDB_SPLFIELD_GROUPING = 0x27, /* String */ - ITDB_SPLFIELD_PLAYLIST = 0x28, /* FIXME - Unknown...not parsed - correctly...from/to = 0xb6fbad5f - for "Purchased Music". Extra - data after "to"... */ - ITDB_SPLFIELD_VIDEO_KIND = 0x3c, /* Logic Int */ - ITDB_SPLFIELD_TVSHOW = 0x3e, /* String */ - ITDB_SPLFIELD_SEASON_NR = 0x3f, /* Int */ - ITDB_SPLFIELD_SKIPCOUNT = 0x44, /* Int */ - ITDB_SPLFIELD_LAST_SKIPPED = 0x45, /* Int */ - ITDB_SPLFIELD_ALBUMARTIST = 0x47 /* String */ + ITDB_SPLFIELD_SONG_NAME = 0x02, + ITDB_SPLFIELD_ALBUM = 0x03, + ITDB_SPLFIELD_ARTIST = 0x04, + ITDB_SPLFIELD_BITRATE = 0x05, + ITDB_SPLFIELD_SAMPLE_RATE = 0x06, + ITDB_SPLFIELD_YEAR = 0x07, + ITDB_SPLFIELD_GENRE = 0x08, + ITDB_SPLFIELD_KIND = 0x09, + ITDB_SPLFIELD_DATE_MODIFIED = 0x0a, + ITDB_SPLFIELD_TRACKNUMBER = 0x0b, + ITDB_SPLFIELD_SIZE = 0x0c, + ITDB_SPLFIELD_TIME = 0x0d, + ITDB_SPLFIELD_COMMENT = 0x0e, + ITDB_SPLFIELD_DATE_ADDED = 0x10, + ITDB_SPLFIELD_COMPOSER = 0x12, + ITDB_SPLFIELD_PLAYCOUNT = 0x16, + ITDB_SPLFIELD_LAST_PLAYED = 0x17, + ITDB_SPLFIELD_DISC_NUMBER = 0x18, + ITDB_SPLFIELD_RATING = 0x19, + ITDB_SPLFIELD_COMPILATION = 0x1f, + ITDB_SPLFIELD_BPM = 0x23, + ITDB_SPLFIELD_GROUPING = 0x27, + ITDB_SPLFIELD_PLAYLIST = 0x28, + ITDB_SPLFIELD_VIDEO_KIND = 0x3c, + ITDB_SPLFIELD_TVSHOW = 0x3e, + ITDB_SPLFIELD_SEASON_NR = 0x3f, + ITDB_SPLFIELD_SKIPCOUNT = 0x44, + ITDB_SPLFIELD_LAST_SKIPPED = 0x45, + ITDB_SPLFIELD_ALBUMARTIST = 0x47 } ItdbSPLField; +/** + * Itdb_SPLPref: + * @liveupdate: Live Updating + * @checkrules: Match this number of rules. If set to 0, ignore rules. + * @checklimits: Limit to this number of @limittype. If 0, no limits. + * @limittype: an #ItdbLimitType + * @limitsort: an #ItdbLimitSort + * @limitvalue: The value typed next to "Limit type" + * @matchcheckedonly: Match only checked songs + * @reserved_int1: Reserved for future use + * @reserved_int2: Reserved for future use + * @reserved1: Reserved for future use + * @reserved2: Reserved for future use + * + * Smart Playlist preferences are for various flags that are not strictly smart + * playlist "rules." + * + * Since: 0.5.0 + */ struct _Itdb_SPLPref { - guint8 liveupdate; /* "live Updating" check box */ - guint8 checkrules; /* "Match X of the following - conditions" check box */ - guint8 checklimits; /* "Limit To..." check box */ - guint32 limittype; /* See types defined above */ - guint32 limitsort; /* See types defined above */ - guint32 limitvalue; /* The value typed next to "Limit - type" */ - guint8 matchcheckedonly; /* "Match only checked songs" check box */ - /* reserved for future use */ + guint8 liveupdate; + guint8 checkrules; + guint8 checklimits; + guint32 limittype; + guint32 limitsort; + guint32 limitvalue; + guint8 matchcheckedonly; gint32 reserved_int1; gint32 reserved_int2; gpointer reserved1; gpointer reserved2; }; +/** + * Itdb_SPLRule: + * @field: an #ItdbSPLFieldType + * @action: an #ItdbSPLActionType + * @string: data in UTF8 + * @fromvalue: from value + * @fromdate: from date + * @fromunits: from units + * @tovalue: to value + * @todate: to date + * @tounits: to units + * @unk052: Unknown + * @unk056: Unknown + * @unk060: Unknown + * @unk064: Unknown + * @unk068: Unknown + * @reserved_int1: Reserved for future use + * @reserved_int2: Reserved for future use + * @reserved1: Reserved for future use + * @reserved2: Reserved for future use + * + * Smart Playlist Rule + * + * The from and to fields require some explanation. If @field is a date type, + * then @value would be set to 0x2dae2dae2dae2dae, @date would be a number, + * (e.g. 2 or -2), and @units would be a time unit in seconds (e.g. one week + * would be 604800). If @field is an integer comparison, like rating = 60 (i.e. + * 3 stars), then @value would be the value we care about (e.g. 60), @date would + * be 0, and @units would be 1. Binary AND types are similar, @value is the + * important part, with @date = 0 and @units = 1. Clear as mud, right? + * + * For more details see <ulink + * url="http://ipodlinux.org/ITunesDB.html#Smart_Playlist_Rule_Values">ipodlinux.org</ulink>. + * + * Since: 0.5.0 + */ struct _Itdb_SPLRule { guint32 field; guint32 action; - gchar *string; /* data in UTF8 */ - /* from and to are pretty stupid.. if it's a date type of field, - then - value = 0x2dae2dae2dae2dae, - date = some number, like 2 or -2 - units = unit in seconds, like 604800 = a week - but if this is actually some kind of integer comparison, like - rating = 60 (3 stars) - value = the value we care about - date = 0 - units = 1 */ + gchar *string; guint64 fromvalue; gint64 fromdate; guint64 fromunits; @@ -427,12 +727,25 @@ struct _Itdb_SPLRule gpointer reserved2; }; - +/** + * Itdb_SPLRules: + * @unk004: Unknown + * @match_operator: Whether all rules must match (#ITDB_SPLMATCH_AND) or any + * rules may match (#ITDB_SPLMATCH_OR) + * @rules: list of #Itdb_SPLRule's + * @reserved_int1: Reserved for future use + * @reserved_int2: Reserved for future use + * @reserved1: Reserved for future use + * @reserved2: Reserved for future use + * + * Smart Playlist Rules + * + * Since: 0.5.0 + */ struct _Itdb_SPLRules { guint32 unk004; - guint32 match_operator; /* "All" (logical AND): Itdb_SPLMATCH_AND, - "Any" (logical OR): Itdb_SPLMATCH_OR */ + guint32 match_operator; GList *rules; /* reserved for future use */ gint32 reserved_int1; @@ -448,10 +761,24 @@ struct _Itdb_SPLRules * \* ------------------------------------------------------------ */ +/** + * Itdb_Chapter: + * @startpos: The start position of the chapter in ms. The first chapter + * begins at 1. + * @chaptertitle: The chapter title in UTF8 + * @reserved_int1: Reserved for future use + * @reserved_int2: Reserved for future use + * @reserved1: Reserved for future use + * @reserved2: Reserved for future use + * + * Structure representing an iTunesDB Chapter + * + * Since: 0.7.0 + */ struct _Itdb_Chapter { guint32 startpos; - gchar *chaptertitle; /* data in UTF8 */ + gchar *chaptertitle; /* reserved for future use */ gint32 reserved_int1; gint32 reserved_int2; @@ -459,7 +786,21 @@ struct _Itdb_Chapter gpointer reserved2; }; - +/** + * Itdb_Chapterdata: + * @chapters: A list of chapters (#Itdb_Chapter) + * @unk024: Unknown + * @unk028: Unknown + * @unk032: Unknown + * @reserved_int1: Reserved for future use + * @reserved_int2: Reserved for future use + * @reserved1: Reserved for future use + * @reserved2: Reserved for future use + * + * Structure representing iTunesDB Chapter data + * + * Since: 0.7.0 + */ struct _Itdb_Chapterdata { GList *chapters; @@ -480,25 +821,52 @@ struct _Itdb_Chapterdata * \* ------------------------------------------------------------ */ -/* one star is how much (track->rating) */ +/** + * ITDB_RATING_STEP: + * + * The multiplier for each star in #track->rating + */ #define ITDB_RATING_STEP 20 +/** + * Itdb_Artwork: + * @thumbnail: An #Itdb_Thumb + * @id: Artwork id used by photoalbums. This starts at 0x40 and + * is set automatically when the ArtworkDB or PhotoDB is + * written + * @dbid: The dbid of associated track. Used internally by + * libgpod. + * @unk028: Unknown + * @rating: Rating from iPhoto * 20 (PhotoDB only) + * @unk036: Unknown + * @creation_date: Date the image file was created (PhotoDB only) + * @digitized_date: Date the image was taken (EXIF information, PhotoDB + * only) + * @artwork_size: Size in bytes of the original source image (PhotoDB + * only -- don't touch in case of ArtworkDB!) + * @reserved_int1: Reserved for future use + * @reserved_int2: Reserved for future use + * @reserved1: Reserved for future use + * @reserved2: Reserved for future use + * @usertype: For use by application + * @userdata: For use by application + * @userdata_duplicate: A function to duplicate #userdata + * @userdata_destroy: A function to free #userdata + * + * Structure representing artwork in an #Itdb_iTunesDB or #Itdb_PhotoDB + * + * Since: 0.3.0 + */ struct _Itdb_Artwork { Itdb_Thumb *thumbnail; - guint32 id; /* Artwork id used by photoalbums, starts at - * 0x40... libgpod will set this on sync. */ - guint64 dbid; /* dbid of associated track. used - internally by libgpod */ + guint32 id; + guint64 dbid; gint32 unk028; - guint32 rating; /* Rating from iPhoto * 20 (PhotoDB only) */ + guint32 rating; gint32 unk036; - time_t creation_date; /* Date the image file was created - (creation date of image file (PhotoDB only) */ - time_t digitized_date;/* Date the image was taken (EXIF information, - PhotoDB only) */ - guint32 artwork_size; /* Size in bytes of the original source - image (PhotoDB only -- don't touch in - case of ArtworkDB!) */ + time_t creation_date; + time_t digitized_date; + guint32 artwork_size; /* reserved for future use */ gint32 reserved_int1; gint32 reserved_int2; @@ -512,12 +880,29 @@ struct _Itdb_Artwork { ItdbUserDataDestroyFunc userdata_destroy; }; - +/** + * Itdb_PhotoDB: + * @photos: A list of photos in the database (#Itdb_Artwork) + * @photoalbums: A list of albums in the database (#Itdb_PhotoAlbum) + * @device: iPod device info (#Itdb_Device) + * @reserved_int1: Reserved for future use + * @reserved_int2: Reserved for future use + * @reserved1: Reserved for future use + * @reserved2: Reserved for future use + * @usertype: For use by application + * @userdata: For use by application + * @userdata_duplicate: A function to duplicate #userdata + * @userdata_destroy: A function to free #userdata + * + * Structure representing an iTunes Photo database + * + * Since: 0.4.0 + */ struct _Itdb_PhotoDB { - GList *photos; /* (Itdb_Artwork *) */ - GList *photoalbums; /* (Itdb_PhotoAlbum *) */ - Itdb_Device *device;/* iPod device info */ + GList *photos; + GList *photoalbums; + Itdb_Device *device; /* reserved for future use */ gint32 reserved_int1; gint32 reserved_int2; @@ -531,12 +916,31 @@ struct _Itdb_PhotoDB ItdbUserDataDestroyFunc userdata_destroy; }; +/** + * Itdb_iTunesDB: + * @tracks: A list of tracks in the database (#Itdb_Track) + * @playlists: A list of playlists in the database (#Itdb_Playlist) + * @filename: The filename of the iTunesDB + * @device: iPod device info (#Itdb_Device) + * @version: The version number of the iTunesDB + * @id: A 64 bit id value for the iTunesDB + * @reserved_int1: Reserved for future use + * @reserved_int2: Reserved for future use + * @reserved1: Reserved for future use + * @reserved2: Reserved for future use + * @usertype: For use by application + * @userdata: For use by application + * @userdata_duplicate: A function to duplicate #userdata + * @userdata_destroy: A function to free #userdata + * + * Structure representing an iTunes database + */ struct _Itdb_iTunesDB { GList *tracks; GList *playlists; - gchar *filename; /* filename of iTunesDB */ - Itdb_Device *device;/* iPod device info */ + gchar *filename; + Itdb_Device *device; guint32 version; guint64 id; /* reserved for future use */ @@ -552,32 +956,62 @@ struct _Itdb_iTunesDB ItdbUserDataDestroyFunc userdata_destroy; }; +/** + * Itdb_PhotoAlbum: + * @photodb: A pointer to the #Itdb_PhotoDB (for convenience) + * @name: The name of photoalbum in UTF8 + * @members: A list of photos in album (#Itdb_Artwork) + * @album_type: The album type. 0x01 for master (Photo Library), + * 0x02 for a normal album. (4 and 5 have also been + * seen.) + * @playmusic: Play music during slideshow + * @repeat: Repeat the slideshow + * @random: Show slides in random order + * @show_titles: Show slide captions + * @transition_direction: Transition direction. 0=none, 1=left-to-right, + * 2=right-to-left, 3=top-to-bottom, 4=bottom-to-top + * @slide_duration: Slide duration in seconds + * @transition_duration: Transition duration, in milliseconds + * @song_id: The @dbid2 of a track to play during slideshow + * @unk024: Unknown, seems to be always 0 + * @unk028: Unknown, seems to be always 0 + * @unk044: Unknown, seems to always be 0 + * @unk048: Unknown, seems to always be 0 + * @album_id: The id of the album. This is set automatically when + * the PhotoDB is written. + * @prev_album_id: The id of the previous playlist. This is set + * automatically when the PhotoDB is written. + * @reserved_int1: Reserved for future use + * @reserved_int2: Reserved for future use + * @reserved1: Reserved for future use + * @reserved2: Reserved for future use + * @usertype: For use by application + * @userdata: For use by application + * @userdata_duplicate: A function to duplicate #userdata + * @userdata_destroy: A function to free #userdata + * + * Structure representing an iTunes Photo Album + * + * Since: 0.4.0 + */ struct _Itdb_PhotoAlbum { - Itdb_PhotoDB *photodb; /* database to which this album belongs */ - gchar *name; /* name of photoalbum in UTF8 */ - GList *members; /* photos in album (Itdb_Artwork *) */ - guint8 album_type; /* 0x01 for master (Photo Library), - 0x02 otherwise (sometimes 4 and 5) */ - guint8 playmusic; /* play music during slideshow (from - iPhoto setting) */ - guint8 repeat; /* repeat the slideshow (from iPhoto - setting) */ - guint8 random; /* show the slides in random order - (from iPhoto setting) */ - guint8 show_titles; /* show slide captions (from iPhoto - setting) */ - guint8 transition_direction; /* 0=none, 1=left-to-right, - 2=right-to-left, 3=top-to-bottom, - 4=bottom-to-top (from iPhoto setting) */ - gint32 slide_duration; /* in seconds (from iPhoto setting) */ - gint32 transition_duration; /* in milliseconds (from iPhoto setting) */ - gint64 song_id; /* dbid2 of track in iTunesDB to play - during slideshow (from iPhoto setting)*/ - gint32 unk024; /* unknown, seems to be always 0 */ - gint16 unk028; /* unknown, seems to be always 0 */ - gint32 unk044; /* unknown, seems to always be 0 */ - gint32 unk048; /* unknown, seems to always be 0 */ + Itdb_PhotoDB *photodb; + gchar *name; + GList *members; + guint8 album_type; + guint8 playmusic; + guint8 repeat; + guint8 random; + guint8 show_titles; + guint8 transition_direction; + gint32 slide_duration; + gint32 transition_duration; + gint64 song_id; + gint32 unk024; + gint16 unk028; + gint32 unk044; + gint32 unk048; /* set automatically at time of writing the PhotoDB */ gint32 album_id; gint32 prev_album_id; @@ -594,25 +1028,61 @@ struct _Itdb_PhotoAlbum ItdbUserDataDestroyFunc userdata_destroy; }; +/** + * Itdb_Playlist: + * @itdb: A pointer to the #Itdb_iTunesDB (for convenience) + * @name: The name of the playlist in UTF8 + * @type: The playlist type (normal or master) + * @flag1: Unknown, usually set to 0 + * @flag2: Unknown, always set to 0 + * @flag3: Unknown, always set to 0 + * @num: The number of tracks in the playlist + * @members: A list of tracks in the playlist (#Itdb_Track) + * @is_spl: True if the playlist is a smart playlist, otherwise + * false + * @timestamp: When the playlist was created + * @id: The playlist ID + * @sortorder: The playlist sort order (#ItdbPlaylistSortOrder) + * @podcastflag: This is set to 0 on normal playlists and to 1 for the + * Podcast playlist. If set to 1, the playlist will not be + * shown under 'Playlists' on the iPod, but as 'Podcasts' + * under the Music menu. The actual title of the Playlist + * does not matter. If more than one playlist is set to 1, + * they don't show up at all. + * @splpref: Smart playlist preferences (#Itdb_SPLPref) + * @splrules: Smart playlist rules (#Itdb_SPLRules) + * @reserved100: Reserved for MHOD100 implementation + * @reserved101: Reserved for MHOD100 implementation + * @reserved_int1: Reserved for future use + * @reserved_int2: Reserved for future use + * @reserved1: Reserved for future use + * @reserved2: Reserved for future use + * @usertype: For use by application + * @userdata: For use by application + * @userdata_duplicate: A function to duplicate #userdata + * @userdata_destroy: A function to free #userdata + * + * Structure representing an iTunes Playlist + */ struct _Itdb_Playlist { - Itdb_iTunesDB *itdb; /* pointer to iTunesDB (for convenience) */ - gchar *name; /* name of playlist in UTF8 */ - guint8 type; /* ITDB_PL_TYPE_NORM/_MPL */ - guint8 flag1; /* unknown, usually set to 0 */ - guint8 flag2; /* unknown, always set to 0 */ - guint8 flag3; /* unknown, always set to 0 */ - gint num; /* number of tracks in playlist */ - GList *members; /* tracks in playlist (Track *) */ - gboolean is_spl; /* smart playlist? */ - time_t timestamp; /* timestamp of playlist creation */ - guint64 id; /* playlist ID */ - guint32 sortorder; /* How to sort playlist -- see below */ - guint32 podcastflag; /* ITDB_PL_FLAG_NORM/_PODCAST */ - Itdb_SPLPref splpref; /* smart playlist prefs */ - Itdb_SPLRules splrules; /* rules for smart playlists */ - gpointer reserved100; /* reserved for MHOD100 implementation */ - gpointer reserved101; /* reserved for MHOD100 implementation */ + Itdb_iTunesDB *itdb; + gchar *name; + guint8 type; + guint8 flag1; + guint8 flag2; + guint8 flag3; + gint num; + GList *members; + gboolean is_spl; + time_t timestamp; + guint64 id; + guint32 sortorder; + guint32 podcastflag; + Itdb_SPLPref splpref; + Itdb_SPLRules splrules; + gpointer reserved100; + gpointer reserved101; /* reserved for future use */ gint32 reserved_int1; gint32 reserved_int2; @@ -627,39 +1097,39 @@ struct _Itdb_Playlist }; -/* -Playlist Sort Order - -1 - playlist order (manual sort order) -2 - ??? -3 - songtitle -4 - album -5 - artist -6 - bitrate -7 - genre -8 - kind -9 - date modified -10 - track nr -11 - size -12 - time -13 - year -14 - sample rate -15 - comment -16 - date added -17 - equalizer -18 - composer -19 - ??? -20 - play count -21 - last played -22 - disc nr -23 - my rating -24 - release date (I guess, it's the value for the "Podcasts" list) -25 - BPM -26 - grouping -27 - category -28 - description -*/ - +/** + * ItdbPlaylistSortOrder: + * @ITDB_PSO_MANUAL: Sort by playlist order (manual sort) + * @ITDB_PSO_TITLE: Sort by track title + * @ITDB_PSO_ALBUM: Sort by album + * @ITDB_PSO_ARTIST: Sort by artist + * @ITDB_PSO_BIRATE: Sort by bitrate + * @ITDB_PSO_GENRE: Sort by genre + * @ITDB_PSO_FILETYPE: Sort by filetype + * @ITDB_PSO_TIME_MODIFIED: Sort by date modified + * @ITDB_PSO_TRACK_NR: Sort by track number + * @ITDB_PSO_SIZE: Sort by track size + * @ITDB_PSO_TIME: Sort by track time + * @ITDB_PSO_YEAR: Sort by year + * @ITDB_PSO_SAMPLERATE: Sort by samplerate + * @ITDB_PSO_COMMENT: Sort by comments + * @ITDB_PSO_TIME_ADDED: Sort by date added + * @ITDB_PSO_EQUALIZER: Sort by equilizer + * @ITDB_PSO_COMPOSER: Sort by composer + * @ITDB_PSO_PLAYCOUNT: Sort by playcount + * @ITDB_PSO_TIME_PLAYED: Sort by date last played + * @ITDB_PSO_CD_NR: Sort by disc number + * @ITDB_PSO_RATING: Sort by rating + * @ITDB_PSO_RELEASE_DATE: Sort by release date + * @ITDB_PSO_BPM: Sort by beats per minute + * @ITDB_PSO_GROUPING: Sort by grouping + * @ITDB_PSO_CATEGORY: Sort by category + * @ITDB_PSO_DESCRIPTION: Sort by description + * + * Playlist Sort Order + * + * Since: 0.1.3 + */ typedef enum { ITDB_PSO_MANUAL = 1, @@ -693,7 +1163,23 @@ typedef enum } ItdbPlaylistSortOrder; -/* Mediatype definitions */ +/** + * Itdb_Mediatype: + * @ITDB_MEDIATYPE_AUDIO: Audio files + * @ITDB_MEDIATYPE_MOVIE: Movies + * @ITDB_MEDIATYPE_PODCAST: Podcasts + * @ITDB_MEDIATYPE_AUDIOBOOK: Audio books + * @ITDB_MEDIATYPE_MUSICVIDEO: Music videos + * @ITDB_MEDIATYPE_TVSHOW: TV Shows + * + * Mediatype definitions + * + * The mediatype is used to determine what menu a track appears under. For + * example, setting the mediatype to #ITDB_MEDIATYPE_PODCAST makes the track + * appear on the Podcast menu. + * + * Since: 0.5.0 + */ typedef enum { ITDB_MEDIATYPE_AUDIO = 0x0001, @@ -704,35 +1190,331 @@ typedef enum ITDB_MEDIATYPE_TVSHOW = 0x0040, } Itdb_Mediatype; -/* some of the descriptive comments below are copied verbatim from - http://ipodlinux.org/ITunesDB. - http://ipodlinux.org/ITunesDB is the best source for information - about the iTunesDB and related files. */ +/** + * Itdb_Track: + * @itdb: A pointer to the #Itdb_iTunesDB (for convenience) + * @title: The title of the track in UTF8 + * @ipod_path: The file path on the iPod. Directories are + * separated with ":" instead of "/". The path is + * relative to the iPod mountpoint. + * @album: The album name in UTF8 + * @artist: The artist name in UTF8 + * @genre: The genre in UTF8 + * @filetype: A UTF8 string describing the file type. E.g. + * "MP3-File". + * @comment: A comment in UTF8 + * @category: The category ("Technology", "Music", etc.) + * where the podcast was located. (Added in + * dbversion 0x0d) + * @composer: The composer name in UTF8 + * @grouping: ??? (UTF8) + * @description: Description text (such as podcast show notes). + * (Added in dbversion 0x0d) + * @podcasturl: Podcast Enclosure URL in UTF-8 or ASCII. + * (Added in dbversion 0x0d) + * @podcastrss: Podcast RSS URL in UTF-8 or ASCII. + * (Added in dbversion 0x0d) + * @chapterdata: This is an m4a-style entry that is used to + * display subsongs within a mhit. (Added in + * dbversion 0x0d) + * @subtitle: Subtitle (usually the same as Description). + * (Added in dbversion 0x0d) + * @tvshow: Name of the TV show (only used for TV Shows). + * (Added in dbversion 0x0d?) (Since libgpod-0.4.2) + * @tvepisode: The episode number (only used for TV Shows). + * (Added in dbversion 0x0d?) (Since libgpod-0.4.2) + * @tvnetwork: The TV network (only used for TV Shows). + * (Added in dbversion 0x0d?) (Since libgpod-0.4.2) + * @albumartist: The album artist (Added in dbversion 0x13?) + * (Since libgpod-0.4.2) + * @keywords: List of keywords pertaining to the track. + * (Added in dbversion 0x13?) (Since libgpod-0.4.2) + * @sort_artist: The artist name used for sorting. Artists with + * names like "The Artist" would have "Artist, + * The" here. If you do not set this field, + * libgpod will pre-sort the lists displayed by + * the iPod according to "Artist, The", without + * setting this field. + * (Added in dbversion 0x13?) (Since libgpod-0.5.0) + * @sort_title: The track title used for sorting. See + * @sort_artist. (Since libgpod-0.5.0) + * @sort_album: The album name used for sorting. See + * @sort_artist. (Since libgpod-0.5.0) + * @sort_albumartist: The album artist used for sorting. See + * @sort_artist. (Since libgpod-0.5.0) + * @sort_composer: The composer used for sorting. See + * @sort_artist. (Since libgpod-0.5.0) + * @sort_tvshow: The name of the TV show used for sorting. See + * @sort_artist. (Since libgpod-0.5.0) + * @id: Unique ID of track + * @size: The size of the file in bytes + * @tracklen: The length of the track in ms + * @cd_nr: The CD number the track comes from. + * @cds: The total number of CDs. + * @track_nr: The track number. + * @tracks: The total number of tracks. + * @bitrate: The bitrate at which the file is encoded. + * @samplerate: The samplerate of the track (e.g. CD = 44100) + * @samplerate_low: In the iTunesDB the samplerate is + * multiplied by 0x10000 -- these are the + * lower 16 bit, which are usually 0 + * @year: The year the track was released + * @volume: Volume adjustment field. This is a value from + * -255 to 255 that will be applied to the track + * on playback. + * @soundcheck: The SoundCheck value to apply to the song, when + * SoundCheck is switched on in the iPod settings. + * The value for this field can be determined by + * the equation: X = 1000 * 10 ^ (-.1 * Y) where Y + * is the adjustment value in dB and X is the + * value that goes into the SoundCheck field. The + * value 0 is special, the equation is not used + * and it is treated as "no Soundcheck" (basically + * the same as the value 1000). This equation + * works perfectly well with ReplayGain derived + * data instead of the iTunes SoundCheck derived + * information. + * @time_added: The time the track was added. + * @time_modified: The time the track was last modified + * @time_played: The time the track was last played + * @bookmark_time: The time, in milliseconds, that the track will + * start playing at. This is used for AudioBook + * filetypes (.aa and .m4b). Note that there is + * also a bookmark value in the play counts file + * that will be set by the iPod and can be used + * instead of this value. + * @rating: The track rating (stars * #ITDB_RATING_STEP) + * @playcount: The number of times the track has been played + * @playcount2: This also stores the play count of the + * track. It is unclear if this ever differs + * from the above value. During sync, this is set + * to the same value as @playcount. + * @recent_playcount: The number of times the track was played since + * the last sync. + * @transferred: Whether the file been transferred to iPod. + * @BPM: BPM (beats per minute) of the track + * @app_rating: The last rating set by an application (e.g. + * iTunes). If the rating on the iPod and the + * @rating field above differ, the original + * rating is copied here and the new rating is + * stored in @rating. + * @type1: CBR MP3s and AAC are 0x00, VBR MP3s are 0x01 + * @type2: MP3s are 0x01, AAC are 0x00 + * @compilation: Flag to mark the track as a compilation. True + * if set to 0x1, false if set to 0x0. + * @starttime: The time, in milliseconds, at which the song + * will start playing. + * @stoptime: The time, in milliseconds, at which the song + * will stop playing. + * @checked: Flag for whether the track is checked. True if + * set to 0x0, false if set to 0x1 + * @dbid: Unique database ID that identifies this song + * across the databases on the iPod. For example, + * this id joins an iTunesDB mhit with an + * ArtworkDB mhii. + * @drm_userid: Apple Store/Audible User ID (for DRM'ed files + * only, set to 0 otherwise). + * @visible: If this value is 1, the song is visible on the + * iPod. All other values cause the file to be + * hidden. + * @filetype_marker: This appears to always be 0 on hard drive based + * iPods, but for the iTunesDB that is written to + * an iPod Shuffle, iTunes 4.7.1 writes out the + * file's type as an ANSI string(!). For example, + * a MP3 file has a filetype of 0x4d503320 -> + * 0x4d = 'M', 0x50 = 'P', 0x33 = '3', 0x20 = + * <space>. This is set to the filename + * extension by libgpod when copying the track to + * the iPod. + * @artwork_count: The number of album artwork items associated + * with this song. libgpod updates this value + * when syncing. + * @artwork_size: The total size of artwork (in bytes) attached + * to this song, when it is converted to JPEG + * format. Observed in dbversion 0x0b and with + * an iPod Photo. libgpod updates this value when + * syncing. + * @samplerate2: The sample rate of the song expressed as an + * IEEE 32 bit floating point number. It is + * uncertain why this is here. libgpod will set + * this when adding a track. + * @unk126: Unknown, but always seems to be 0xffff for + * MP3/AAC songs, 0x0 for uncompressed songs + * (like WAVE format), 0x1 for Audible. libgpod + * will try to set this when adding a new track. + * @unk132: Unknown + * @time_released: The date/time the track was added to the iTunes + * music store? For podcasts this is the release + * date that is displayed next to the title in the + * Podcast playlist. + * @unk144: Unknown, but MP3 songs appear to be always + * 0x000c, AAC songs are always 0x0033, Audible + * files are 0x0029, WAV files are 0x0. libgpod + * will attempt to set this value when adding a + * track. + * @explicit_flag: Flag to mark a track as "explicit" in iTunes. + * True if to 0x1, false if set to 0x0. + * @unk148: Unknown - used for Apple Store DRM songs + * (always 0x01010100?), zero otherwise + * @unk152: Unknown + * @skipcount: The number of times the track has been skipped. + * (Added in dbversion 0x0c) + * @recent_skipcount: The number of times the track was skipped since + * the last sync. + * @last_skipped: The time the track was last skipped. (Added in + * dbversion 0x0c) + * @has_artwork: Whether the track has artwork. + * True if set to 0x01, false if set to 0x02. + * @skip_when_shuffling: Flag to skip the track when shuffling. True if + * set to 0x01, false if set to 0x00. Audiobooks + * (.aa and .m4b) always seem to be skipped when + * shuffling, regardless of this flag. + * @remember_playback_position: Flag to remember playback position. + * True when set to 0x01, false when set to 0x00. + * Audiobooks (.aa and .m4b) always seem to + * remember the playback position, regardless of + * this flag. + * @flag4: Used for podcasts, 0x00 otherwise. If set to + * 0x01 the "Now Playing" page will show + * Title/Album, when set to 0x00 it will also show + * the Artist. When set to 0x02 a sub-page + * (middle button) with further information about + * the track will be shown. + * @dbid2: The purpose of the field is unclear. If not + * set, libgpod will set this to the same value as + * @dbid when adding a track. (With iTunes, since + * dbversion 0x12, this field value differs from + * @dbid.) + * @lyrics_flag: Whether the track has lyrics (e.g. it has a + * USLT ID3 tag in an MP3 or a @lyr atom in an + * MP4). True if set to 0x01, false if set to + * 0x00. + * @movie_flag: Whether the track is a movie. True if set to + * 0x01, false if set to 0x00. + * @mark_unplayed: A value of 0x02 marks a podcast as unplayed on + * the iPod, with a bullet. Once played it is set + * to 0x01. Non-podcasts have this set to 0x01. + * (Added in dbversion 0x0c) + * @unk179: Unknown, always 0x00 so far. (Added in + * dbversion 0x0c) + * @unk180: Unknown. (Added in dbversion 0x0c) + * @pregap: The number of samples of silence before the + * track starts (for gapless playback). + * @samplecount: The number of samples in the track (for gapless + * playback). + * @unk196: Unknown. (Added in dbversion 0x0c) + * @postgap: The number of samples of silence at the end of + * the track (for gapless playback). + * @unk204: Unknown. Appears to be 0x1 for files encoded + * using the MP3 encoder, 0x0 otherwise. (Added + * in dbversion 0x0c, first values observed in + * 0x0d.) + * @mediatype: The type of file. It must be set to 0x00000001 + * for audio files, and set to 0x00000002 for + * video files. If set to 0x00, the files show up + * in both, the audio menus ("Songs", "Artists", + * etc.) and the video menus ("Movies", "Music + * Videos", etc.). It appears to be set to 0x20 + * for music videos, and if set to 0x60 the file + * shows up in "TV Shows" rather than "Movies". + * <para> + * The following list summarizes all observed types: + * </para> + * <itemizedlist> + * <listitem>0x00 00 00 00 - Audio/Video</listitem> + * <listitem>0x00 00 00 01 - Audio</listitem> + * <listitem>0x00 00 00 02 - Video</listitem> + * <listitem>0x00 00 00 04 - Podcast</listitem> + * <listitem>0x00 00 00 06 - Video Podcast</listitem> + * <listitem>0x00 00 00 08 - Audiobook</listitem> + * <listitem>0x00 00 00 20 - Music Video</listitem> + * <listitem>0x00 00 00 40 - TV Show (shows up ONLY + * in TV Shows)</listitem> + * <listitem>0x00 00 00 60 - TV Show (shows up in + * the Music lists as well)</listitem> + * </itemizedlist> + * @season_nr: The season number of the track (only used for + * TV Shows). + * @episode_nr: The episode number of the track (only used for + * TV Shows). Although this is not displayed on + * the iPod, the episodes are sorted by episode + * number. + * @unk220: Unknown. This has something to do with + * protected files. It is set to 0x0 for + * non-protected files. + * @unk224: Unknown. (Added in dbversion 0x0c) + * @unk228: Unknown. (Added in dbversion 0x0c) + * @unk232: Unknown. (Added in dbversion 0x0c) + * @unk236: Unknown. (Added in dbversion 0x0c) + * @unk240: Unknown. (Added in dbversion 0x0c) + * @unk244: Unknown. (Added in dbversion 0x13) + * @gapless_data: The size in bytes from first Synch Frame + * (which is usually the XING frame that + * includes the LAME tag) until the 8th before + * the last frame. The gapless playback does not + * work for MP3 files if this is set to zero. For + * AAC tracks, this may be zero. (Added in + * dbversion 0x13) + * @unk252: Unknown. (Added in dbversion 0x0c) + * @gapless_track_flag: If set to 1, this track has gapless playback + * data. (Added in dbversion 0x13) + * @gapless_album_flag: If set to 1, this track does not use + * crossfading in iTunes. (Added in dbversion + * 0x13) + * @artwork: An #Itdb_Artwork for cover art + * @mhii_link: This is set to the id of the corresponding + * ArtworkDB mhii, used for sparse artwork + * support. (Since libgpod-0.7.0) + * @reserved_int1: Reserved for future use + * @reserved_int2: Reserved for future use + * @reserved_int3: Reserved for future use + * @reserved_int4: Reserved for future use + * @reserved_int5: Reserved for future use + * @reserved_int6: Reserved for future use + * @reserved1: Reserved for future use + * @reserved2: Reserved for future use + * @reserved3: Reserved for future use + * @reserved4: Reserved for future use + * @reserved5: Reserved for future use + * @reserved6: Reserved for future use + * @usertype: For use by application + * @userdata: For use by application + * @userdata_duplicate: A function to duplicate #userdata + * @userdata_destroy: A function to free #userdata + * + * Structure representing a track in an iTunesDB + * + * <note><para>When adding string fields don't forget to add them in + * itdb_track_duplicate() as well.</para></note> + * + * Many of the parameter descriptions are copied verbatim from + * http://ipodlinux.org/ITunesDB, which is the best source for information about + * the iTunesDB and related files. + */ struct _Itdb_Track { - Itdb_iTunesDB *itdb; /* pointer to iTunesDB (for convenience) */ - gchar *title; /* title (utf8) */ - gchar *ipod_path; /* name of file on iPod: uses ":" instead - of "/" and is relative to mountpoint */ - gchar *album; /* album (utf8) */ - gchar *artist; /* artist (utf8) */ - gchar *genre; /* genre (utf8) */ - gchar *filetype; /* eg. "MP3-File"...(utf8) */ - gchar *comment; /* comment (utf8) */ - gchar *category; /* Category for podcast */ - gchar *composer; /* Composer (utf8) */ - gchar *grouping; /* ? (utf8) */ - gchar *description; /* see note for MHOD_ID in itdb_itunesdb.c */ - gchar *podcasturl; /* see note for MHOD_ID in itdb_itunesdb.c */ - gchar *podcastrss; /* see note for MHOD_ID in itdb_itunesdb.c */ - Itdb_Chapterdata *chapterdata; /* see note for MHOD_ID in itdb_itunesdb.c */ - gchar *subtitle; /* see note for MHOD_ID in itdb_itunesdb.c */ -/* the following 6 are new in libgpod 0.4.2... */ - gchar *tvshow; /* see note for MHOD_ID in itdb_itunesdb.c */ - gchar *tvepisode; /* see note for MHOD_ID in itdb_itunesdb.c */ - gchar *tvnetwork; /* see note for MHOD_ID in itdb_itunesdb.c */ - gchar *albumartist; /* see note for MHOD_ID in itdb_itunesdb.c */ - gchar *keywords; /* see note for MHOD_ID in itdb_itunesdb.c */ + Itdb_iTunesDB *itdb; + gchar *title; + gchar *ipod_path; + gchar *album; + gchar *artist; + gchar *genre; + gchar *filetype; + gchar *comment; + gchar *category; + gchar *composer; + gchar *grouping; + gchar *description; + gchar *podcasturl; + gchar *podcastrss; + Itdb_Chapterdata *chapterdata; + gchar *subtitle; +/* the following 5 are new in libgpod 0.4.2... */ + gchar *tvshow; + gchar *tvepisode; + gchar *tvnetwork; + gchar *albumartist; + gchar *keywords; /* the following 6 are new in libgpod 0.5.0... */ /* You can set these strings to override the standard sortorder. When set they take precedence over the default @@ -747,199 +1529,90 @@ struct _Itdb_Track the lists displayed by the iPod according to "Artist, The", without setting the field. */ - gchar *sort_artist; /* artist (for sorting) */ - gchar *sort_title; /* title (for sorting) */ - gchar *sort_album; /* album (for sorting) */ - gchar *sort_albumartist; /* album artist (for sorting) */ - gchar *sort_composer; /* composer (for sorting) */ - gchar *sort_tvshow; /* tv show (for sorting) */ -/* new fields in libgpod 0.5.0 up to here */ - guint32 id; /* unique ID of track */ - gint32 size; /* size of file in bytes */ - gint32 tracklen; /* Length of track in ms */ - gint32 cd_nr; /* CD number */ - gint32 cds; /* number of CDs */ - gint32 track_nr; /* track number */ - gint32 tracks; /* number of tracks */ - gint32 bitrate; /* bitrate */ - guint16 samplerate; /* samplerate (CD: 44100) */ - guint16 samplerate_low; /* in the iTunesDB the samplerate is - multiplied by 0x10000 -- these are the - lower 16 bit, which are usually 0 */ - gint32 year; /* year */ - gint32 volume; /* volume adjustment */ - guint32 soundcheck; /* volume adjustment "soundcheck" */ - time_t time_added; /* time when added */ - time_t time_modified; /* time of last modification */ - time_t time_played; /* time of last play */ - guint32 bookmark_time; /* bookmark set for (AudioBook) in ms */ - guint32 rating; /* star rating (stars * RATING_STEP (20)) */ - guint32 playcount; /* number of times track was played */ - guint32 playcount2; /* Also stores the play count of the - song. Don't know if it ever differs - from the above value. During sync itdb - sets playcount2 to the same value as - playcount. */ - guint32 recent_playcount; /* times track was played since last sync */ - gboolean transferred; /* has file been transferred to iPod? */ - gint16 BPM; /* BPM (beats per minute) of this track */ - guint8 app_rating; /* star rating set by appl. (not - * iPod). If the rating set on the iPod - and the rating field above differ, the - original rating is copied here and the - new rating is stored above. */ - guint8 type1; /* CBR MP3s and AAC are 0x00, VBR MP3s are - 0x01 */ - guint8 type2; /* MP3s are 0x01, AAC are 0x00 */ + gchar *sort_artist; + gchar *sort_title; + gchar *sort_album; + gchar *sort_albumartist; + gchar *sort_composer; + gchar *sort_tvshow; +/* end of new fields in libgpod 0.5.0 */ + guint32 id; + gint32 size; + gint32 tracklen; + gint32 cd_nr; + gint32 cds; + gint32 track_nr; + gint32 tracks; + gint32 bitrate; + guint16 samplerate; + guint16 samplerate_low; + gint32 year; + gint32 volume; + guint32 soundcheck; + time_t time_added; + time_t time_modified; + time_t time_played; + guint32 bookmark_time; + guint32 rating; + guint32 playcount; + guint32 playcount2; + guint32 recent_playcount; + gboolean transferred; + gint16 BPM; + guint8 app_rating; + guint8 type1; + guint8 type2; guint8 compilation; guint32 starttime; guint32 stoptime; - guint8 checked; /* 0x0: checkmark on track is set 0x1: not set */ - guint64 dbid; /* unique database ID */ - guint32 drm_userid; /* Apple Store/Audible User ID (for DRM'ed - files only, set to 0 otherwise). */ - guint32 visible; /* If this value is 1, the song is visible - on the iPod. All other values cause - the file to be hidden. */ - guint32 filetype_marker; /* This appears to always be 0 on hard - drive based iPods, but for the - iTunesDB that is written to an iPod - Shuffle, iTunes 4.7.1 writes out the - file's type as an ANSI string(!). For - example, a MP3 file has a filetype of - 0x4d503320 -> 0x4d = 'M', 0x50 = 'P', - 0x33 = '3', 0x20 = <space>. (set to - the filename extension by itdb when - copying track to iPod) */ - guint16 artwork_count; /* The number of album artwork items - associated with this song. libgpod - updates this value when syncing */ - guint32 artwork_size; /* The total size of artwork (in bytes) - attached to this song, when it is - converted to JPEG format. Observed in - iPodDB version 0x0b and with an iPod - Photo. libgpod updates this value when - syncing */ - float samplerate2; /* The sample rate of the song expressed - as an IEEE 32 bit floating point - number. It's uncertain why this is - here. itdb will set this when adding - a track */ - - guint16 unk126; /* unknown, but always seems to be 0xffff for - MP3/AAC songs, 0x0 for uncompressed songs - (like WAVE format), 0x1 for Audible. itdb - will try to set this when adding a new track */ - guint32 unk132; /* unknown */ - time_t time_released;/* date/time added to music store? - For podcasts: release date as displayed next to the - title in the Podcast playlist */ - guint16 unk144; /* unknown, but MP3 songs appear to be always - 0x000c, AAC songs are always 0x0033, Audible - files are 0x0029, WAV files are 0x0. itdb - will attempt to set this value when adding a - track. */ - guint16 explicit_flag;/* If this flag is set to 1, the track is shown as - explicit content in iTunes. Otherwise set this flag - to 0.*/ - guint32 unk148; /* unknown - used for Apple Store DRM songs - (always 0x01010100?), zero otherwise */ - guint32 unk152; /* unknown */ - guint32 skipcount; /* Number of times the track has been skipped. - Formerly unk156 (added in dbversion 0x0c) */ - guint32 recent_skipcount; /* number of times track was skipped since - last sync */ - guint32 last_skipped;/* Date/time last skipped. Formerly unk160 - (added in dbversion 0x0c) */ - guint8 has_artwork; /* 0x01: artwork is present. 0x02: no artwork is - present for this track (used by the iPod to - decide whether to display Artwork or not) */ - guint8 skip_when_shuffling;/* "Skip when shuffling" when set to - 0x01, set to 0x00 otherwise. .m4b and .aa - files always seem to be skipped when - shuffling, however */ - guint8 remember_playback_position;/* "Remember playback position" - when set to 0x01, set to 0x00 otherwise. .m4b - and .aa files always seem to remember the - playback position, however. */ - guint8 flag4; /* Used for podcasts, 0x00 otherwise. If set to - 0x01 the "Now Playing" page will show - Title/Album, when set to 0x00 it will also - show the Artist. When set to 0x02 a sub-page - (middle button) with further information - about the track will be shown. */ - guint64 dbid2; /* not clear. if not set, itdb will set this to - the same value as dbid when adding a - track. (With iTunes, since V0x12, this field - value differs from the dbid one.) */ - guint8 lyrics_flag; /* set to 0x01 if lyrics are present in MP3 tag - ("ULST"), 0x00 otherwise */ - guint8 movie_flag; /* set to 0x01 if it's a movie file, 0x00 - otherwise */ - guint8 mark_unplayed; /* A value of 0x02 marks a podcast as unplayed - on the iPod (bullet) once played it is set to - 0x01. Non-podcasts have this set to 0x01. */ - guint8 unk179; /* unknown (always 0x00 so far) */ + guint8 checked; + guint64 dbid; + guint32 drm_userid; + guint32 visible; + guint32 filetype_marker; + guint16 artwork_count; + guint32 artwork_size; + float samplerate2; + guint16 unk126; + guint32 unk132; + time_t time_released; + guint16 unk144; + guint16 explicit_flag; + guint32 unk148; + guint32 unk152; + guint32 skipcount; + guint32 recent_skipcount; + guint32 last_skipped; + guint8 has_artwork; + guint8 skip_when_shuffling; + guint8 remember_playback_position; + guint8 flag4; + guint64 dbid2; + guint8 lyrics_flag; + guint8 movie_flag; + guint8 mark_unplayed; + guint8 unk179; guint32 unk180; - guint32 pregap; /* Number of samples of silence before the songs - starts (for gapless playback). */ - guint64 samplecount;/* Number of samples in the song. First observed - in dbversion 0x0d, and only for AAC and WAV - files (for gapless playback). */ + guint32 pregap; + guint64 samplecount; guint32 unk196; - guint32 postgap; /* Number of samples of silence at the end of - the song (for gapless playback). */ - guint32 unk204; /* unknown - added in dbversion 0x0c, first - values observed in 0x0d. Observed to be 0x0 - or 0x1. */ - guint32 mediatype; /* It seems that this field denotes the type of - the file on (e.g.) the 5g video iPod. It must - be set to 0x00000001 for audio files, and set - to 0x00000002 for video files. If set to - 0x00, the files show up in both, the audio - menus ("Songs", "Artists", etc.) and the - video menus ("Movies", "Music Videos", - etc.). It appears to be set to 0x20 for music - videos, and if set to 0x60 the file shows up - in "TV Shows" rather than "Movies". - - The following list summarizes all observed types: - - * 0x00 00 00 00 - Audio/Video - * 0x00 00 00 01 - Audio - * 0x00 00 00 02 - Video - * 0x00 00 00 04 - Podcast - * 0x00 00 00 06 - Video Podcast - * 0x00 00 00 08 - Audiobook - * 0x00 00 00 20 - Music Video - * 0x00 00 00 40 - TV Show (shows up ONLY in TV Shows - * 0x00 00 00 60 - TV Show (shows up in the - Music lists as well) */ - guint32 season_nr; /* the season number of the track, for TV shows only. */ - guint32 episode_nr; /* the episode number of the track, for TV shows - only - although not displayed on the iPod, - the episodes are sorted by episode number. */ - guint32 unk220; /* Has something to do with protected files - - set to 0x0 for non-protected files. */ + guint32 postgap; + guint32 unk204; + guint32 mediatype; + guint32 season_nr; + guint32 episode_nr; + guint32 unk220; guint32 unk224; guint32 unk228, unk232, unk236, unk240, unk244; - guint32 gapless_data;/* some magic number needed for gapless playback - (added in dbversion 0x13) It has been observed - that gapless playback does not work if this is - set to zero. This number is related to the the - filesize in bytes, but it is a couple of bytes - less than the filesize. Maybe ID3 tags - etc... taken off? */ + guint32 gapless_data; guint32 unk252; - guint16 gapless_track_flag; /* if 1, this track has gapless playback data - (added in dbversion 0x13) */ - guint16 gapless_album_flag; /* if 1, this track does not use crossfading - in iTunes (added in dbversion 0x13) */ + guint16 gapless_track_flag; + guint16 gapless_album_flag; /* This is for Cover Art support */ struct _Itdb_Artwork *artwork; - /* 200805 */ + /* This is for sparse artwork support, new in libgpod-0.7.0 */ guint32 mhii_link; /* reserved for future use */ @@ -977,13 +1650,24 @@ struct _Itdb_Track * Error codes * \* ------------------------------------------------------------ */ + +/** + * ItdbFileError: + * @ITDB_FILE_ERROR_SEEK: file corrupt: illegal seek occured + * @ITDB_FILE_ERROR_CORRUPT: file corrupt + * @ITDB_FILE_ERROR_NOTFOUND: file not found + * @ITDB_FILE_ERROR_RENAME: file could not be renamed + * @ITDB_FILE_ERROR_ITDB_CORRUPT: iTunesDB in memory corrupt + * + * Error codes for iTunesDB file + */ typedef enum { - ITDB_FILE_ERROR_SEEK, /* file corrupt: illegal seek occured */ - ITDB_FILE_ERROR_CORRUPT, /* file corrupt */ - ITDB_FILE_ERROR_NOTFOUND, /* file not found */ - ITDB_FILE_ERROR_RENAME, /* file could not be renamed */ - ITDB_FILE_ERROR_ITDB_CORRUPT /* iTunesDB in memory corrupt */ + ITDB_FILE_ERROR_SEEK, + ITDB_FILE_ERROR_CORRUPT, + ITDB_FILE_ERROR_NOTFOUND, + ITDB_FILE_ERROR_RENAME, + ITDB_FILE_ERROR_ITDB_CORRUPT } ItdbFileError; @@ -1197,9 +1881,9 @@ gpointer itdb_artwork_get_pixbuf (Itdb_Device *device, Itdb_Artwork *artwork, /* itdb_thumb_... */ Itdb_Thumb *itdb_thumb_duplicate (Itdb_Thumb *thumb); -gpointer itdb_thumb_to_pixbuf_at_size (Itdb_Device *dev, Itdb_Thumb *thumb, - gint width, gint height); -GList *itdb_thumb_to_pixbufs (Itdb_Device *dev, Itdb_Thumb *thumb); +gpointer itdb_thumb_to_pixbuf_at_size (Itdb_Device *device, Itdb_Thumb *thumb, + gint width, gint height); +GList *itdb_thumb_to_pixbufs (Itdb_Device *device, Itdb_Thumb *thumb); void itdb_thumb_free (Itdb_Thumb *thumb); /* itdb_chapterdata_... */ diff --git a/src/itdb_artwork.c b/src/itdb_artwork.c index db895d7..dd6c4ca 100644 --- a/src/itdb_artwork.c +++ b/src/itdb_artwork.c @@ -48,9 +48,11 @@ * * Creates a new #Itdb_Artwork * - * Return value: a new #Itdb_Artwork to be freed with itdb_artwork_free() when + * Returns: a new #Itdb_Artwork to be freed with itdb_artwork_free() when * no longer needed - **/ + * + * Since: 0.3.0 + */ Itdb_Artwork *itdb_artwork_new (void) { Itdb_Artwork *artwork = g_new0 (Itdb_Artwork, 1); @@ -62,7 +64,9 @@ Itdb_Artwork *itdb_artwork_new (void) * @artwork: an #Itdb_Artwork * * Frees memory used by @artwork - **/ + * + * Since: 0.3.0 + */ void itdb_artwork_free (Itdb_Artwork *artwork) { g_return_if_fail (artwork); @@ -78,8 +82,10 @@ void itdb_artwork_free (Itdb_Artwork *artwork) * * Duplicates @artwork * - * Return value: a new copy of @artwork - **/ + * Returns: a new copy of @artwork + * + * Since: 0.3.0 + */ Itdb_Artwork *itdb_artwork_duplicate (Itdb_Artwork *artwork) { Itdb_Artwork *dup; @@ -101,7 +107,9 @@ Itdb_Artwork *itdb_artwork_duplicate (Itdb_Artwork *artwork) * @artwork: an #Itdb_Artwork * * Removes all thumbnails from @artwork - **/ + * + * Since: 0.3.0 + */ void itdb_artwork_remove_thumbnails (Itdb_Artwork *artwork) { @@ -117,24 +125,25 @@ itdb_artwork_remove_thumbnails (Itdb_Artwork *artwork) /** * itdb_artwork_set_thumbnail - * @artwork: an #Itdb_Thumbnail - * @type: thumbnail size - * @filename: image file to use to create the thumbnail - * @rotation: angle by which the image should be rotated - * counterclockwise. Valid values are 0, 90, 180 and 270. - * @error: return location for a #GError or NULL + * @artwork: an #Itdb_Artwork + * @filename: image file to use to create the thumbnail + * @rotation: angle by which the image should be rotated + * counterclockwise. Valid values are 0, 90, 180 and 270. + * @error: return location for a #GError or NULL * * Appends a thumbnail of type @type to existing thumbnails in @artwork. No * data is read from @filename yet, the file will be when @artwork is saved to * disk. @filename must still exist when that happens. * * For the rotation angle you can also use the gdk constants - * GDK_PIXBUF_ROTATE_NONE, ..._COUNTERCLOCKWISE, ..._UPSIDEDOWN AND - * ..._CLOCKWISE. + * %GDK_PIXBUF_ROTATE_NONE, %GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE, + * %GDK_PIXBUF_ROTATE_UPSIDEDOWN, AND %GDK_PIXBUF_ROTATE_CLOCKWISE. * - * Return value: TRUE if the thumbnail could be successfully added, FALSE + * Returns: TRUE if the thumbnail could be successfully added, FALSE * otherwise. @error is set appropriately. - **/ + * + * Since: 0.7.0 + */ gboolean itdb_artwork_set_thumbnail (Itdb_Artwork *artwork, const gchar *filename, @@ -176,24 +185,25 @@ itdb_artwork_set_thumbnail (Itdb_Artwork *artwork, /** * itdb_artwork_set_thumbnail_from_pixbuf - * @artwork: an #Itdb_Thumbnail - * @pixbuf: #GdkPixbuf to use to create the thumbnail - * @rotation: angle by which the image should be rotated - * counterclockwise. Valid values are 0, 90, 180 and 270. - * @error: return location for a #GError or NULL + * @artwork: an #Itdb_Artwork + * @pixbuf: #GdkPixbuf to use to create the thumbnail + * @rotation: angle by which the image should be rotated + * counterclockwise. Valid values are 0, 90, 180 and 270. + * @error: return location for a #GError or NULL * - * Appends a thumbnail of type @type to existing thumbnails in @artwork. No - * data is generated from @pixbuf yet, it will be done when @artwork is saved - * to disk. @pixbuf is ref'ed by this function, but is not copied, so it should - * not be modified before the database is saved. + * Set a thumbnail in @artwork. No data is generated from @pixbuf yet, it will + * be done when @artwork is saved to disk. @pixbuf is ref'ed by this function, + * but is not copied, so it should not be modified before the database is saved. * * For the rotation angle you can also use the gdk constants - * GDK_PIXBUF_ROTATE_NONE, ..._COUNTERCLOCKWISE, ..._UPSIDEDOWN AND - * ..._CLOCKWISE. + * %GDK_PIXBUF_ROTATE_NONE, %GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE, + * %GDK_PIXBUF_ROTATE_UPSIDEDOWN, AND %GDK_PIXBUF_ROTATE_CLOCKWISE. * - * Return value: TRUE if the thumbnail could be successfully added, FALSE + * Returns: TRUE if the thumbnail could be successfully added, FALSE * otherwise. @error is set appropriately. - **/ + * + * Since: 0.7.0 + */ gboolean itdb_artwork_set_thumbnail_from_pixbuf (Itdb_Artwork *artwork, gpointer pixbuf, @@ -235,25 +245,26 @@ itdb_artwork_set_thumbnail_from_pixbuf (Itdb_Artwork *artwork, /** * itdb_artwork_set_thumbnail_from_data - * @artwork: an #Itdb_Thumbnail - * @image_data: data used to create the thumbnail (the raw contents of - * an image file) + * @artwork: an #Itdb_Artwork + * @image_data: data used to create the thumbnail (the raw contents of + * an image file) * @image_data_len: length of above data block - * @rotation: angle by which the image should be rotated - * counterclockwise. Valid values are 0, 90, 180 and 270. - * @error: return location for a #GError or NULL + * @rotation: angle by which the image should be rotated + * counterclockwise. Valid values are 0, 90, 180 and 270. + * @error: return location for a #GError or NULL * - * Appends a thumbnail of type @type to existing thumbnails in - * @artwork. No data is processed yet. This will be done when @artwork - * is saved to disk. + * Set a thumbnail in @artwork. No data is processed yet. This will be done when + * @artwork is saved to disk. * * For the rotation angle you can also use the gdk constants - * GDK_PIXBUF_ROTATE_NONE, ..._COUNTERCLOCKWISE, ..._UPSIDEDOWN AND - * ..._CLOCKWISE. + * %GDK_PIXBUF_ROTATE_NONE, %GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE, + * %GDK_PIXBUF_ROTATE_UPSIDEDOWN, AND %GDK_PIXBUF_ROTATE_CLOCKWISE. * - * Return value: TRUE if the thumbnail could be successfully added, FALSE + * Returns: TRUE if the thumbnail could be successfully added, FALSE * otherwise. @error is set appropriately. - **/ + * + * Since: 0.7.0 + */ gboolean itdb_artwork_set_thumbnail_from_data (Itdb_Artwork *artwork, const guchar *image_data, @@ -881,23 +892,25 @@ gpointer itdb_thumb_ipod_item_to_pixbuf (Itdb_Device *device, #endif /** - * itdb_artwork_get_thumbnail! - * @artwork: an #Itdb_Artwork - * - * @width: width of the pixbuf to retrieve, -1 for the biggest - * possible size and 0 for the smallest possible size (with no scaling) - * - * @height: height of the pixbuf to retrieve, -1 for the biggest possible size - * and 0 for the smallest possible size (with no scaling) + * itdb_artwork_get_pixbuf: + * @artwork: an #Itdb_Artwork + * @device: an #Itdb_Device + * @width: width of the pixbuf to retrieve, -1 for the biggest + * possible size and 0 for the smallest possible size (with no + * scaling) + * @height: height of the pixbuf to retrieve, -1 for the biggest possible + * size and 0 for the smallest possible size (with no scaling) * * Returns a #GdkPixbuf representing the thumbnail stored in @artwork * scaling it if appropriate. If either height or width is -1, then the * biggest unscaled thumbnail available will be returned * - * Return value: a #GdkPixbuf that must be unreffed when no longer used, NULL + * Returns: a #GdkPixbuf that must be unreffed when no longer used, NULL * if no artwork could be found or if libgpod is compiled without GdkPixbuf * support - **/ + * + * Since: 0.7.0 + */ gpointer itdb_artwork_get_pixbuf (Itdb_Device *device, Itdb_Artwork *artwork, gint width, gint height) { diff --git a/src/itdb_chapterdata.c b/src/itdb_chapterdata.c index 131f66e..c74e6d6 100644 --- a/src/itdb_chapterdata.c +++ b/src/itdb_chapterdata.c @@ -41,9 +41,11 @@ * * Creates a new #Itdb_Chapterdata * - * Return value: a new #Itdb_Chapterdata to be freed with itdb_chapterdata_free() when - * no longer needed - **/ + * Returns: a new #Itdb_Chapterdata to be freed with + * itdb_chapterdata_free() when no longer needed + * + * Since: 0.7.0 + */ Itdb_Chapterdata *itdb_chapterdata_new (void) { Itdb_Chapterdata *chapterdata = g_new0 (Itdb_Chapterdata, 1); @@ -55,7 +57,9 @@ Itdb_Chapterdata *itdb_chapterdata_new (void) * @chapterdata: an #Itdb_Chapterdata * * Frees memory used by @chapterdata - **/ + * + * Since: 0.7.0 + */ void itdb_chapterdata_free (Itdb_Chapterdata *chapterdata) { g_return_if_fail (chapterdata); @@ -92,8 +96,10 @@ static GList *dup_chapters (GList *chapters) * * Duplicates @chapterdata * - * Return value: a new copy of @chapterdata - **/ + * Returns: a new copy of @chapterdata + * + * Since: 0.7.0 + */ Itdb_Chapterdata *itdb_chapterdata_duplicate (Itdb_Chapterdata *chapterdata) { Itdb_Chapterdata *dup; @@ -116,10 +122,12 @@ Itdb_Chapterdata *itdb_chapterdata_duplicate (Itdb_Chapterdata *chapterdata) /** * itdb_chapterdata_remove_chapter: * @chapterdata: an #Itdb_Chapterdata - * @chapeer: an #Itdb_Chapter + * @chapter: an #Itdb_Chapter * * Removes @chapter from @chapterdata. The memory used by @chapter is freed. - **/ + * + * Since: 0.7.0 + */ void itdb_chapterdata_remove_chapter (Itdb_Chapterdata *chapterdata, Itdb_Chapter *chapter) { @@ -135,7 +143,9 @@ itdb_chapterdata_remove_chapter (Itdb_Chapterdata *chapterdata, Itdb_Chapter *ch * @chapterdata: an #Itdb_Chapterdata * * Removes all chapters from @chapterdata - **/ + * + * Since: 0.7.0 + */ void itdb_chapterdata_remove_chapters (Itdb_Chapterdata *chapterdata) { @@ -154,9 +164,11 @@ itdb_chapterdata_remove_chapters (Itdb_Chapterdata *chapterdata) * * Creates a new #Itdb_Chapter * - * Return Value: newly allocated #Itdb_Chapter to be freed with itdb_chapter_free() + * Returns: newly allocated #Itdb_Chapter to be freed with itdb_chapter_free() * after use - **/ + * + * Since: 0.7.0 + */ Itdb_Chapter *itdb_chapter_new (void) { Itdb_Chapter *chapter = g_new0 (Itdb_Chapter, 1); @@ -168,7 +180,9 @@ Itdb_Chapter *itdb_chapter_new (void) * @chapter: an #Itdb_Chapter * * Frees the memory used by @chapter - **/ + * + * Since: 0.7.0 + */ void itdb_chapter_free (Itdb_Chapter *chapter) { g_return_if_fail (chapter); @@ -183,9 +197,11 @@ void itdb_chapter_free (Itdb_Chapter *chapter) * * Duplicates the data contained in @chapter * - * Return value: a newly allocated copy of @chapter to be freed with + * Returns: a newly allocated copy of @chapter to be freed with * itdb_chapter_free() after use - **/ + * + * Since: 0.7.0 + */ Itdb_Chapter *itdb_chapter_duplicate (Itdb_Chapter *chapter) { Itdb_Chapter *new_chapter; @@ -201,15 +217,17 @@ Itdb_Chapter *itdb_chapter_duplicate (Itdb_Chapter *chapter) /** * itdb_chapterdata_add_chapter - * @chapterdata: an #Itdb_Chapterdata - * @startpos: chapter start time in milliseconds + * @chapterdata: an #Itdb_Chapterdata + * @startpos: chapter start time in milliseconds * @chaptertitle: chapter title * * Appends a chapter to existing chapters in @chapterdata. * - * Return value: TRUE if the chapter could be successfully added, FALSE + * Returns: TRUE if the chapter could be successfully added, FALSE * otherwise. - **/ + * + * Since: 0.7.0 + */ gboolean itdb_chapterdata_add_chapter (Itdb_Chapterdata *chapterdata, gint32 startpos, diff --git a/src/itdb_device.c b/src/itdb_device.c index 6261711..b035c30 100644 --- a/src/itdb_device.c +++ b/src/itdb_device.c @@ -649,9 +649,11 @@ static void itdb_device_reset_sysinfo (Itdb_Device *device) * * Creates a new #Itdb_Device structure * - * Return value: a newly allocated #Itdb_Device which must be freed with + * Returns: a newly allocated #Itdb_Device which must be freed with * itdb_device_free() when no longer needed - **/ + * + * Since: 0.4.0 + */ Itdb_Device *itdb_device_new () { Itdb_Device *dev; @@ -666,7 +668,9 @@ Itdb_Device *itdb_device_new () * @device: an #Itdb_Device * * Frees memory used by @device - **/ + * + * Since: 0.4.0 + */ void itdb_device_free (Itdb_Device *device) { if (device) @@ -684,11 +688,13 @@ void itdb_device_free (Itdb_Device *device) /** * itdb_device_set_mountpoint: * @device: an #Itdb_Device - * @mp: the new mount point + * @mp: the new mount point * * Sets the mountpoint of @device to @mp and update the cached device * information (in particular, re-read the SysInfo file) - **/ + * + * Since: 0.4.0 + */ void itdb_device_set_mountpoint (Itdb_Device *device, const gchar *mp) { g_return_if_fail (device); @@ -753,8 +759,10 @@ static void itdb_device_read_sysinfo_extended (Itdb_Device *device) * Reads the SysInfo file and stores information in device->sysinfo for * later use. * - * Return value: TRUE if file could be read, FALSE otherwise - **/ + * Returns: TRUE if file could be read, FALSE otherwise + * + * Since: 0.4.0 + */ gboolean itdb_device_read_sysinfo (Itdb_Device *device) { const gchar *p_sysinfo[] = {"SysInfo", NULL}; @@ -827,13 +835,15 @@ static void write_sysinfo_entry (const gchar *key, /** * itdb_device_write_sysinfo: * @device: an #Itdb_Device - * @error: return location for a #GError or NULL + * @error: return location for a #GError or NULL * * Fills the SysInfo file with information in device->sysinfo. Note: * no directories are created if not already existent. * - * Return value: TRUE if file could be read, FALSE otherwise - **/ + * Returns: TRUE if file could be read, FALSE otherwise + * + * Since: 0.4.0 + */ gboolean itdb_device_write_sysinfo (Itdb_Device *device, GError **error) { gchar *devicedir; @@ -883,13 +893,15 @@ gboolean itdb_device_write_sysinfo (Itdb_Device *device, GError **error) /** * itdb_device_get_sysinfo: * @device: an #Itdb_Device - * @field: field to retrive information from + * @field: field to retrive information from * * Retrieve specified field from the SysInfo file. * - * Return value: the information associated with @field, or NULL if @field + * Returns: the information associated with @field, or NULL if @field * couldn't be found. g_free() after use - **/ + * + * Since: 0.4.0 + */ gchar *itdb_device_get_sysinfo (const Itdb_Device *device, const gchar *field) { g_return_val_if_fail (device, NULL); @@ -902,13 +914,14 @@ gchar *itdb_device_get_sysinfo (const Itdb_Device *device, const gchar *field) /** * itdb_device_set_sysinfo: * @device: an #Itdb_Device - * @field: field to set - * @value: value to set (or NULL to remove the field). + * @field: field to set + * @value: value to set (or NULL to remove the field). * * Set specified field. It can later be written to the iPod using * itdb_device_write_sysinfo() * - **/ + * Since: 0.4.0 + */ void itdb_device_set_sysinfo (Itdb_Device *device, const gchar *field, const gchar *value) { @@ -935,8 +948,10 @@ void itdb_device_set_sysinfo (Itdb_Device *device, * * Retrieve the #Itdb_IpodInfo entry for this iPod * - * Return value: the #Itdb_IpodInfo entry for this iPod - **/ + * Returns: the #Itdb_IpodInfo entry for this iPod + * + * Since: 0.4.0 + */ const Itdb_IpodInfo * itdb_device_get_ipod_info (const Itdb_Device *device) { @@ -1154,16 +1169,14 @@ itdb_device_musicdirs_number (Itdb_Device *device) return device->musicdirs; } -/** +/* * endianess_check_path: + * @path: the file to look at. + * @hdr: the header string (4 bytes) in case of LITTLE_ENDIAN * * Check if endianess can be determined by looking at header of @path. * - * @path: the file to look at. - * @hdr: the header string (4 bytes) in case of LITTLE_ENDIAN - * - * Return value: - * G_LITTLE_ENDIAN, G_BIG_ENDIAN or 0 if endianess could not be + * Returns: G_LITTLE_ENDIAN, G_BIG_ENDIAN or 0 if endianess could not be * determined. */ static guint endianess_check_path (const gchar *path, const gchar *hdr) @@ -1273,8 +1286,10 @@ itdb_device_autodetect_endianess (Itdb_Device *device) * Return a pointer to the start of valid iPod model descriptions, * which is an array of #Itdb_IpodInfo entries. * - * Return value: a pointer to the array of #Itdb_IpodInfo entries. - **/ + * Returns: a pointer to the array of #Itdb_IpodInfo entries. + * + * Since: 0.4.0 + */ const Itdb_IpodInfo *itdb_info_get_ipod_info_table (void) { return &ipod_info_table[2]; @@ -1287,9 +1302,11 @@ const Itdb_IpodInfo *itdb_info_get_ipod_info_table (void) * * Return the iPod's generic model name, like "Color", "Nano"... * - * Return value: a pointer to the model name. This is a static string + * Returns: a pointer to the model name. This is a static string * and must not be g_free()d. - **/ + * + * Since: 0.4.0 + */ const gchar *itdb_info_get_ipod_model_name_string (Itdb_IpodModel model) { gint i=0; @@ -1312,9 +1329,11 @@ const gchar *itdb_info_get_ipod_model_name_string (Itdb_IpodModel model) * Return the iPod's generic generation name, like "First Generation", * "Mobile Phone"... * - * Return value: a pointer to the generation name. This is a static + * Returns: a pointer to the generation name. This is a static * string and must not be g_free()d. - **/ + * + * Since: 0.4.0 + */ const gchar *itdb_info_get_ipod_generation_string (Itdb_IpodGeneration generation) { gint i=0; @@ -1339,7 +1358,9 @@ const gchar *itdb_info_get_ipod_generation_string (Itdb_IpodGeneration generatio * with a non-art capable iPod, no artwork data will be written to the * iPod so you can spare calls to the artwork handling methods. * - * Return value: true if @device can display artwork. + * Returns: true if @device can display artwork. + * + * Since: 0.5.0 */ gboolean itdb_device_supports_artwork (const Itdb_Device *device) { @@ -1359,7 +1380,9 @@ gboolean itdb_device_supports_artwork (const Itdb_Device *device) * * Indicates whether @device can play videos or not. * - * Return value: true if @device can play videos. + * Returns: true if @device can play videos. + * + * Since: 0.7.0 */ gboolean itdb_device_supports_video (const Itdb_Device *device) { @@ -1405,7 +1428,9 @@ gboolean itdb_device_supports_video (const Itdb_Device *device) * * Indicates whether @device can display photos or not. * - * Return value: true if @device can display photos. + * Returns: true if @device can display photos. + * + * Since: 0.5.0 */ gboolean itdb_device_supports_photo (const Itdb_Device *device) { @@ -1597,8 +1622,10 @@ static void itdb_device_set_timezone_info (Itdb_Device *device) * iTunesDB checksum which is expected by newer iPod models * (iPod classic/fat nanos) * - * Return value: the guint64 firewire id, or 0 if we don't know it - **/ + * Returns: the guint64 firewire id, or 0 if we don't know it + * + * Since: 0.6.0 + */ guint64 itdb_device_get_firewire_id (const Itdb_Device *device) { gchar *fwid; @@ -1664,14 +1691,14 @@ G_GNUC_INTERNAL gboolean itdb_device_requires_checksum (Itdb_Device *device) /** * itdb_device_get_storage_info: * - * @device: an #Itdb_Device + * @device: an #Itdb_Device * @capacity: returned capacity in bytes - * @free: returned free space in bytes + * @free: returned free space in bytes * * Return the storage info for this iPod * - * Return value: TRUE if storage info could be obtained, FALSE otherwise - **/ + * Returns: TRUE if storage info could be obtained, FALSE otherwise + */ gboolean itdb_device_get_storage_info (Itdb_Device *device, guint64 *capacity, guint64 *free) { #ifdef WIN32 diff --git a/src/itdb_device.h b/src/itdb_device.h index 1888a27..7a37177 100644 --- a/src/itdb_device.h +++ b/src/itdb_device.h @@ -74,33 +74,68 @@ enum _ItdbThumbFormat THUMB_FORMAT_EXPERIMENTAL_BE, }; +/** + * Itdb_Device: + * @mountpoint: The mountpoint of the iPod + * @musicdirs: The number of /iPod_Control/Music/F.. dirs + * @byte_order: G_LITTLE_ENDIAN "regular" endianness G_BIG_ENDIAN + * "reversed" endianness (e.g. mobile phone iTunesDBs) + * @sysinfo: A hash with key/value pairs of all entries in + * Device/SysInfo + * @sysinfo_extended: The parsed content of SysInfoExtended, which can be NULL + * @sysinfo_changed: True if the sysinfo hash been changed by the user, false + * otherwise. (see itdb_set_sysinfo()) + * @timezone_shift: The difference in seconds between the current timezone + * and UTC + * + * Structure representing an iPod device + * + * Since: 0.4.0 + */ struct _Itdb_Device { - gchar *mountpoint; /* mountpoint of the iPod */ - gint musicdirs; /* number of /iPod_Control/Music/F.. dirs */ - guint byte_order; /* G_LITTLE_ENDIAN "regular" endianness - * G_BIG_ENDIAN "reversed" endianness (e.g. mobile - * phone iTunesDBs) - */ - GHashTable *sysinfo; /* hash with value/key pairs of all entries - * in Device/SysInfo */ - SysInfoIpodProperties *sysinfo_extended; /* parsed content of - * SysInfoExtended, can be NULL */ - gboolean sysinfo_changed; /* Has the sysinfo hash been changed by - the user (itdb_set_sysinfo) */ - gint timezone_shift; /* difference in seconds between the current - * timezone and UTC - */ - + gchar *mountpoint; + gint musicdirs; + guint byte_order; + GHashTable *sysinfo; + SysInfoIpodProperties *sysinfo_extended; + gboolean sysinfo_changed; + gint timezone_shift; }; +/** + * Itdb_ArtworkFormat: + * @format_id: Unique ID for the format (generally a 4 digit int) + * @width: Width of the thumbnail + * @height: Height of the thumbnail + * @format: Pixel format of the thumbnail (RGB, YUV, ...) + * @padding: Number of bytes of padding to add after the thumbnail + * (not found in SysInfoExtended -- added for + * compatibility with hardcoded artwork formats) + * @crop: Indicates if the thumbnail is to be cropped + * @rotation: Degrees to rotate the thumbnail + * @back_color: Background color for the thumbnail + * @display_width: Width at which the thumbnail will be displayed + * (not currently used) + * @interlaced: If TRUE, the thumbnails are interlaced + * (not currently used) + * @align_row_bytes: If TRUE, each pixel row must be aligned a 2-byte boundary + * @color_adjustment: Color adjustment for the thumbnails + * (not currently used) + * @gamma: Gamma value for the thumbails + * (not currently used) + * @associated_format: Unknown (not currently used) + * + * Structure representing the characteristics of the thumbnails to + * write to a given .ithmb file. The format of the structure is based + * on the way artwork formats are written to SysInfoExtended. + */ struct _Itdb_ArtworkFormat { gint format_id; gint width; gint height; ItdbThumbFormat format; - gint32 padding; /* not found in SysInfoExtended, added - * for compatibility with hardcoded artwork formats */ + gint32 padding; gboolean crop; gint rotation; guchar back_color[4]; diff --git a/src/itdb_itunesdb.c b/src/itdb_itunesdb.c index 8cdffc6..f30ac0f 100644 --- a/src/itdb_itunesdb.c +++ b/src/itdb_itunesdb.c @@ -354,13 +354,13 @@ static void fcontents_free (FContents *cts) * Resolve the path to a track on the iPod * * We start by assuming that the iPod mount point exists. Then, for - * each component c of track->ipod_path, we try to find an entry d in + * each component c of @track->ipod_path, we try to find an entry d in * good_path that is case-insensitively equal to c. If we find d, we * append d to good_path and make the result the new good_path. * Otherwise, we quit and return NULL. * - * Return value: path to track on the iPod or NULL. - **/ + * Returns: path to track on the iPod or NULL. + */ gchar * itdb_resolve_path (const gchar *root, const gchar * const * components) { @@ -1147,7 +1147,7 @@ static void itdb_free_fimp (FImport *fimp) * @itdb: an #Itdb_iTunesDB * * Free the memory taken by @itdb. - **/ + */ void itdb_free (Itdb_iTunesDB *itdb) { if (itdb) @@ -1173,8 +1173,8 @@ void itdb_free (Itdb_iTunesDB *itdb) * Duplicate @itdb * FIXME: not implemented yet * - * Return value: always return NULL since it's unimplemented - **/ + * Returns: always return NULL since it's unimplemented + */ Itdb_iTunesDB *itdb_duplicate (Itdb_iTunesDB *itdb) { g_return_val_if_fail (itdb, NULL); @@ -1188,9 +1188,9 @@ Itdb_iTunesDB *itdb_duplicate (Itdb_iTunesDB *itdb) * * Counts the number of playlists stored in @itdb * - * Return value: the number of playlists in @itdb (including the master + * Returns: the number of playlists in @itdb (including the master * playlist) - **/ + */ guint32 itdb_playlists_number (Itdb_iTunesDB *itdb) { g_return_val_if_fail (itdb, 0); @@ -1204,8 +1204,8 @@ guint32 itdb_playlists_number (Itdb_iTunesDB *itdb) * * Counts the number of tracks stored in @itdb * - * Return value: the number of tracks in @itdb - **/ + * Returns: the number of tracks in @itdb + */ guint32 itdb_tracks_number (Itdb_iTunesDB *itdb) { g_return_val_if_fail (itdb, 0); @@ -1219,10 +1219,10 @@ guint32 itdb_tracks_number (Itdb_iTunesDB *itdb) * * Counts the number of non-transferred tracks in @itdb * - * Return value: the number of tracks in @itdb that haven't been transferred + * 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_tracks_number_nontransferred (Itdb_iTunesDB *itdb) { guint n = 0; @@ -1244,9 +1244,9 @@ guint32 itdb_tracks_number_nontransferred (Itdb_iTunesDB *itdb) * Creates a new Itdb_iTunesDB with the unknowns filled in to reasonable * values. * - * Return value: a newly created Itdb_iTunesDB to be freed with itdb_free() + * Returns: a newly created Itdb_iTunesDB to be freed with itdb_free() * when it's no longer needed - **/ + */ Itdb_iTunesDB *itdb_new (void) { static GOnce g_type_init_once = G_ONCE_INIT; @@ -2956,16 +2956,16 @@ itdb_parse_internal (Itdb_iTunesDB *itdb, GError **error) /** * itdb_parse: - * @mp: mount point of the iPod (eg "/mnt/ipod) in local encoding - * @error: return location for a #GError or NULL + * @mp: mount point of the iPod (eg "/mnt/ipod") in local encoding + * @error: return location for a #GError or NULL * * Parse the Itdb_iTunesDB of the iPod located at @mp * - * Return value: a newly allocated #Itdb_iTunesDB struct holding the tracks and + * 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 - **/ + */ Itdb_iTunesDB *itdb_parse (const gchar *mp, GError **error) { gchar *filename; @@ -3043,16 +3043,16 @@ Itdb_iTunesDB *itdb_parse (const gchar *mp, GError **error) /** * itdb_parse_file: - * @filename: path to a file in iTunesDB format - * @error: return location for a #GError or NULL + * @filename: path to a file in iTunesDB format + * @error: return location for a #GError or NULL * * Same as itunesdb_parse(), but filename is specified directly. * - * Return value: a newly allocated #Itdb_iTunesDB struct holding the tracks and + * Returns: a newly allocated #Itdb_iTunesDB struct holding the tracks and * the playlists present in @filename, NULL if @filename isn't a parsable * iTunesDB file. If non-NULL, the #Itdb_iTunesDB is to be freed with * itdb_free() when it's no longer needed - **/ + */ Itdb_iTunesDB *itdb_parse_file (const gchar *filename, GError **error) { Itdb_iTunesDB *itdb; @@ -5116,15 +5116,15 @@ static gboolean write_db_checksum (FExport *fexp, GError **error) /** * itdb_write_file: - * @itdb: the #Itdb_iTunesDB to save - * @filename: filename to save @itdb to - * @error: return location for a #GError or NULL + * @itdb: the #Itdb_iTunesDB to save + * @filename: filename to save @itdb to + * @error: return location for a #GError or NULL * * Write the content of @itdb to @filename. If @filename is NULL, it attempts - * to write to itdb->filename. + * to write to @itdb->filename. * - * Return value: TRUE if all went well, FALSE otherwise - **/ + * Returns: TRUE if all went well, FALSE otherwise + */ gboolean itdb_write_file (Itdb_iTunesDB *itdb, const gchar *filename, GError **error) { @@ -5211,8 +5211,8 @@ gboolean itdb_write_file (Itdb_iTunesDB *itdb, const gchar *filename, /** * itdb_write: - * @itdb: the #Itdb_iTunesDB to write to disk - * @error: return location for a #GError or NULL + * @itdb: the #Itdb_iTunesDB to write to disk + * @error: return location for a #GError or NULL * * Write out an iTunesDB. It reassigns unique IDs to all tracks. * An existing "Play Counts" file is renamed to "Play Counts.bak" if @@ -5220,9 +5220,9 @@ gboolean itdb_write_file (Itdb_iTunesDB *itdb, const gchar *filename, * An existing "OTGPlaylistInfo" file is removed if the export was * successful. * - * Return value: TRUE on success, FALSE on error, in which case @error is + * Returns: TRUE on success, FALSE on error, in which case @error is * set accordingly. - **/ + */ gboolean itdb_write (Itdb_iTunesDB *itdb, GError **error) { gchar *itunes_filename, *itunes_path; @@ -5376,21 +5376,20 @@ All integers in the iTunesSD file are in BIG endian form... /** * itdb_shuffle_write: - * @itdb: the #Itdb_iTunesDB to write to disk - * @error: return location for a #GError or NULL + * @itdb: the #Itdb_iTunesDB to write to disk + * @error: return location for a #GError or NULL * * Write out an iTunesSD for the Shuffle. - * First 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->mountpoint must point to the mount point of the iPod, - * e.g. "/mnt/ipod" and be in local encoding. * - * Return value: TRUE on success, FALSE on error, in which case @error is + * First 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->mountpoint must point to the mount + * point of the iPod, e.g. "/mnt/ipod" and be in local encoding. + * + * Returns: TRUE on success, FALSE on error, in which case @error is * set accordingly. - **/ + */ gboolean itdb_shuffle_write (Itdb_iTunesDB *itdb, GError **error) { gchar *itunes_filename, *itunes_path; @@ -5445,15 +5444,15 @@ static gboolean haystack (gchar *filetype, gchar **desclist) /** * itdb_shuffle_write_file: - * @itdb: the #Itdb_iTunesDB to write to disk - * @filename: file to write to, cannot be NULL - * @error: return location for a #GError or NULL + * @itdb: the #Itdb_iTunesDB to write to disk + * @filename: file to write to, cannot be NULL + * @error: return location for a #GError or NULL * * Do the actual writing to the iTunesSD * - * Return value: TRUE on success, FALSE on error, in which case @error is + * Returns: TRUE on success, FALSE on error, in which case @error is * set accordingly. - **/ + */ gboolean itdb_shuffle_write_file (Itdb_iTunesDB *itdb, const gchar *filename, GError **error) { @@ -5568,16 +5567,16 @@ gboolean itdb_shuffle_write_file (Itdb_iTunesDB *itdb, /** * itdb_rename_files: - * @mp: mount point of the iPod - * @error: return location for a #GError or NULL + * @mp: mount point of the iPod + * @error: return location for a #GError or NULL * * Renames/removes some files on the iPod (Playcounts, OTG * semaphore). May have to be called if you write the iTunesDB not * directly to the iPod but to some other location and then manually * copy the file from there to the iPod. * - * Return value: FALSE on error and sets @error accordingly - **/ + * Returns: FALSE on error and sets @error accordingly + */ gboolean itdb_rename_files (const gchar *mp, GError **error) { const gchar *db_plc_o[] = {"Play Counts", NULL}; @@ -5667,12 +5666,12 @@ gboolean itdb_rename_files (const gchar *mp, GError **error) /** * itdb_filename_fs2ipod: - * @filename: a filename 'PC-style' (eg /iPod_Control/Music/f00/test.mp3) + * @filename: a 'PC-style' filename (eg /iPod_Control/Music/f00/test.mp3) * - * Convert string from casual PC file name to iPod iTunesDB format using ':' - * instead of G_DIR_SEPARATOR_S (ie slashes on Unix-like systems). @ipod_file - * is modified in place. - **/ + * Convert string from casual PC file name to iPod iTunesDB format + * using ':' instead of G_DIR_SEPARATOR_S (i.e. slashes on Unix-like + * systems). @ipod_file is modified in place. + */ void itdb_filename_fs2ipod (gchar *ipod_file) { g_strdelimit (ipod_file, G_DIR_SEPARATOR_S, ':'); @@ -5680,12 +5679,12 @@ void itdb_filename_fs2ipod (gchar *ipod_file) /** * itdb_filename_ipod2fs: - * @ipod_file: a filename 'PC-style' (eg /iPod_Control/Music/f00/test.mp3) + * @ipod_file: a 'PC-style' filename (eg /iPod_Control/Music/f00/test.mp3) * - * Convert string from from iPod iTunesDB format to casual PC file name - * using G_DIR_SEPARATOR (ie slashes on Unix-like systems) instead of ':'. - * @ipod_file is modified in place. - **/ + * Convert string from from iPod iTunesDB format to casual PC file + * name using G_DIR_SEPARATOR (ie slashes on Unix-like systems) + * instead of ':'. @ipod_file is modified in place. + */ void itdb_filename_ipod2fs (gchar *ipod_file) { g_strdelimit (ipod_file, ":", G_DIR_SEPARATOR); @@ -5693,14 +5692,16 @@ void itdb_filename_ipod2fs (gchar *ipod_file) /** * itdb_set_mountpoint: - * @itdb: an #Itdb_iTunesDB - * @mp: new mount point + * @itdb: an #Itdb_iTunesDB + * @mp: new mount point * - * 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 - **/ + * Sets the mountpoint of @itdb. 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. + * + * Since: 0.1.3 + */ void itdb_set_mountpoint (Itdb_iTunesDB *itdb, const gchar *mp) { g_return_if_fail (itdb); @@ -5716,9 +5717,11 @@ void itdb_set_mountpoint (Itdb_iTunesDB *itdb, const gchar *mp) * * Retrieve a reference to the mountpoint of @itdb * - * Return value: the @itdb mountpoint, this string shouldn't be freed nor - * modified - **/ + * Returns: the @itdb mountpoint, this string shouldn't be freed + * nor modified + * + * Since: 0.4.0 + */ const gchar *itdb_get_mountpoint (Itdb_iTunesDB *itdb) { g_return_val_if_fail (itdb, NULL); @@ -5740,12 +5743,14 @@ const gchar *itdb_photodb_get_mountpoint (Itdb_PhotoDB *photodb) * * Determine the number of F.. directories in iPod_Control/Music. * - * If itdb->musicdirs is already set, simply return the previously + * If @itdb->musicdirs is already set, simply return the previously * determined number. Otherwise count the directories first and set - * itdb->musicdirs. + * @itdb->musicdirs. + * + * Returns: max number of directories in iPod_Control/Music * - * Return value: max number of directories in iPod_Control/Music - **/ + * Since: 0.1.3 + */ gint itdb_musicdirs_number (Itdb_iTunesDB *itdb) { g_return_val_if_fail (itdb, 0); @@ -5756,29 +5761,31 @@ gint itdb_musicdirs_number (Itdb_iTunesDB *itdb) /** * itdb_cp_get_dest_filename: - * @track: track to transfer or NULL + * @track: track to transfer or NULL * @mountpoint: mountpoint of your iPod or NULL - * @filename: the source file - * @error: return location for a #GError or NULL + * @filename: the source file + * @error: return location for a #GError or NULL * - * Creates a valid filename on the iPod where to copy @filename. + * Creates a valid filename on the iPod where @filename can be copied. * - * You must either provide @track or @mountpoint. Providing @track is + * You must provide either @track or @mountpoint. Providing @track is * not thread-safe (accesses track->itdb->device and may even write to * track->itdb->device). Providing @mountpoint is thread-safe but * slightly slower because the number of music directories is counted * each time the function is called. * - * You can use #itdb_cp() to copy the track to the iPod or implement + * You can use itdb_cp() to copy the track to the iPod or implement * your own copy function. After the file was copied you have to call - * #itdb_cp_finalize() to obtain relevant update information for + * itdb_cp_finalize() to obtain relevant update information for * #Itdb_Track. * - * Return value: a valid filename on the iPod to where @filename can - * be copied or NULL in case of an error. In that case @error is set + * Returns: a valid filename on the iPod where @filename can be + * copied or NULL in case of an error. In that case @error is set * accordingly. You must free the filename when it is no longer * needed. - **/ + * + * Since: 0.5.0 + */ gchar *itdb_cp_get_dest_filename (Itdb_Track *track, const gchar *mountpoint, const gchar *filename, @@ -5912,30 +5919,43 @@ gchar *itdb_cp_get_dest_filename (Itdb_Track *track, /** * itdb_cp_finalize: - * @track: track to update or NULL - * @mountpoint: mountpoint of your iPod or NULL - * @dest_filename: the name of the file on the iPod copied to - * @error: return location for a #GError or NULL + * @track: track to update or NULL + * @mountpoint: mountpoint of your iPod or NULL + * @dest_filename: the name of the file on the iPod copied to + * @error: return location for a #GError or NULL + * + * Updates information in @track necessary for the iPod. * - * Updates information in @track necessary for the iPod. You must - * either supply @track or @mountpoint. If @track == NULL, a new track - * structure is created that must be freed with #itdb_track_free() - * when it is no longer needed. + * You must supply either @track or @mountpoint. If @track == NULL, a + * new track structure is created that must be freed with + * itdb_track_free() when it is no longer needed. * - * The following fields are updated: + * The following @track fields are updated: * - * - ipod_path - * - filetype_marker - * - transferred - * - size + * <itemizedlist> + * <listitem> + * ipod_path + * </listitem> + * <listitem> + * filetype_marker + * </listitem> + * <listitem> + * transferred + * </listitem> + * <listitem> + * size + * </listitem> + * </itemizedlist> * - * Return value: on success a pointer to the #Itdb_Track item passed + * Returns: on success a pointer to the #Itdb_Track item passed * or a new #Itdb_Track item if @track was NULL. In the latter case - * you must free the memory using #itdb_track_free() when the item is + * you must free the memory using itdb_track_free() when the item is * no longer used. If an error occurs NULL is returned and @error is * set accordingly. Errors occur when @dest_filename cannot be * accessed or the mountpoint is not set. - **/ + * + * Since: 0.5.0 + */ Itdb_Track *itdb_cp_finalize (Itdb_Track *track, const gchar *mountpoint, const gchar *dest_filename, @@ -6037,9 +6057,9 @@ Itdb_Track *itdb_cp_finalize (Itdb_Track *track, /** * itdb_cp_track_to_ipod: - * @track: the #Itdb_Track to copy (containing @filename metadata) - * @filename: the source file - * @error: return location for a #GError or NULL + * @track: the #Itdb_Track to copy (containing @filename metadata) + * @filename: the source file + * @error: return location for a #GError or NULL * * Copy one track to the iPod. The PC filename is @filename * and is taken literally. @@ -6048,24 +6068,24 @@ Itdb_Track *itdb_cp_finalize (Itdb_Track *track, * with itdb_set_mountpoint() (done automatically when reading an * iTunesDB). * - * If @track->transferred is set to TRUE, nothing is done. Upon - * successful transfer @track->transferred is set to TRUE. + * If @track->transferred is set to TRUE, nothing is done. Upon + * successful transfer @track->transferred is set to TRUE. * - * For storage, the directories "f00 ... fnn" will be used randomly. + * For storage, the directories "F00 ... Fnn" will be used randomly. * - * The filename is constructed as "libgpod"<random number> and copied - * to @track->ipod_path. If this file already exists, <random number> + * The filename is constructed as "libgpod@random_number" and copied + * to @track->ipod_path. If this file already exists, @random_number * is adjusted until an unused filename is found. * - * If @track->ipod_path is already set, this one will be used + * If @track->ipod_path is already set, this one will be used * instead. If a file with this name already exists, it will be * overwritten. * - * @track->filetype_marker is set according to the filename extension + * @track->filetype_marker is set according to the filename extension * - * Return value: TRUE on success, FALSE on error, in which case @error is + * Returns: TRUE on success, FALSE on error, in which case @error is * set accordingly. - **/ + */ gboolean itdb_cp_track_to_ipod (Itdb_Track *track, const gchar *filename, GError **error) { @@ -6100,18 +6120,22 @@ gboolean itdb_cp_track_to_ipod (Itdb_Track *track, * itdb_filename_on_ipod: * @track: an #Itdb_Track * - * Return the full iPod filename as stored in @track. + * Get the full iPod filename as stored in @track. * - * NOTE: NULL is returned when the file does not exist. + * <note> + * NULL is returned when the file does not exist. + * </note> * - * NOTE: this code works around a problem on some systems (see - * itdb_resolve_path() ) and might return a filename with different - * case than the original filename. Don't copy it back to @track - * unless you must + * <note> + * This code works around a problem on some systems (see + * itdb_resolve_path()) and might return a filename with different + * case than the original filename. Don't copy it back to @track if + * you can avoid it. + * </note> * - * Return value: full filename to @track on the iPod or NULL if no + * Returns: full filename to @track on the iPod or NULL if no * filename is set in @track. Must be freed with g_free() after use. - **/ + */ gchar *itdb_filename_on_ipod (Itdb_Track *track) { gchar *result = NULL; @@ -6150,15 +6174,15 @@ gchar *itdb_filename_on_ipod (Itdb_Track *track) /* Use open instead of fopen. fwrite is really slow on the Mac. */ /** * itdb_cp: - * @from_file: source file - * @to_file: destination file - * @error: return location for a #GError or NULL + * @from_file: source file + * @to_file: destination file + * @error: return location for a #GError or NULL * - * Copy file "from_file" to "to_file". + * Copy file @from_file to @to_file. * - * Return value: TRUE on success, FALSE on error, in which case @error is + * Returns: TRUE on success, FALSE on error, in which case @error is * set accordingly. - **/ + */ gboolean itdb_cp (const gchar *from_file, const gchar *to_file, GError **error) { @@ -6319,9 +6343,11 @@ itdb_file_set_contents (const char *filename, * for standard iPods and 'iTunes/iTunes_Control' for mobile * applications. * - * Return value: path to the control dir or NULL if non-existent. Must + * Returns: path to the control dir or NULL if non-existent. Must * g_free() after use. - **/ + * + * Since: 0.4.0 + */ gchar *itdb_get_control_dir (const gchar *mountpoint) { gchar *p_ipod[] = {"iPod_Control", NULL}; @@ -6345,14 +6371,14 @@ gchar *itdb_get_control_dir (const gchar *mountpoint) /** * itdb_get_dir: * @mountpoint: the iPod mountpoint - * @dir: a directory + * @dir: a directory * * Retrieve the directory @dir by first calling itdb_get_control_dir() * and then adding @dir * - * Return value: path to @dir or NULL if non-existent. Must g_free() + * Returns: path to @dir or NULL if non-existent. Must g_free() * after use. - **/ + */ static gchar *itdb_get_dir (const gchar *mountpoint, const gchar *dir) { gchar *control_dir; @@ -6374,14 +6400,16 @@ static gchar *itdb_get_dir (const gchar *mountpoint, const gchar *dir) /** * itdb_get_path: - * @dir: a directory - * @file: a file + * @dir: a directory + * @file: a file * * Retrieve a path to the @file in @dir * - * Return value: path to the @file or NULL if non-existent. Must be g_free()'d + * Returns: path to the @file or NULL if non-existent. Must g_free() * after use. - **/ + * + * Since: 0.4.0 + */ gchar *itdb_get_path (const gchar *dir, const gchar *file) { const gchar *p_file[] = {NULL, NULL}; @@ -6400,9 +6428,11 @@ gchar *itdb_get_path (const gchar *dir, const gchar *file) * Retrieve the iTunes directory (containing the iTunesDB) by first * calling itdb_get_control_dir() and then adding 'iTunes' * - * Return value: path to the iTunes directory or NULL if non-existent. + * Returns: path to the iTunes directory or NULL if non-existent. * Must g_free() after use. - **/ + * + * Since: 0.4.0 + */ gchar *itdb_get_itunes_dir (const gchar *mountpoint) { g_return_val_if_fail (mountpoint, NULL); @@ -6417,9 +6447,9 @@ gchar *itdb_get_itunes_dir (const gchar *mountpoint) * Retrieve the Music directory (containing the Fnn dirs) by first * calling itdb_get_control_dir() and then adding 'Music' * - * Return value: path to the Music directory or NULL if + * Returns: path to the Music directory or NULL if * non-existent. Must g_free() after use. - **/ + */ gchar *itdb_get_music_dir (const gchar *mountpoint) { g_return_val_if_fail (mountpoint, NULL); @@ -6434,9 +6464,11 @@ gchar *itdb_get_music_dir (const gchar *mountpoint) * Retrieve the Device directory (containing the SysInfo file) by * first calling itdb_get_control_dir() and then adding 'Device' * - * Return value: path to the Device directory or NULL if + * Returns: path to the Device directory or NULL if * non-existent. Must g_free() after use. - **/ + * + * Since: 0.4.0 + */ gchar *itdb_get_device_dir (const gchar *mountpoint) { g_return_val_if_fail (mountpoint, NULL); @@ -6451,9 +6483,11 @@ gchar *itdb_get_device_dir (const gchar *mountpoint) * Retrieve the Artwork directory (containing the ArtworDB) by * first calling itdb_get_control_dir() and then adding 'Artwork' * - * Return value: path to the Artwork directory or NULL if + * Returns: path to the Artwork directory or NULL if * non-existent. Must g_free() after use. - **/ + * + * Since: 0.4.0 + */ gchar *itdb_get_artwork_dir (const gchar *mountpoint) { g_return_val_if_fail (mountpoint, NULL); @@ -6467,9 +6501,11 @@ gchar *itdb_get_artwork_dir (const gchar *mountpoint) * * Retrieve a path to the iTunesDB * - * Return value: path to the iTunesDB or NULL if non-existent. Must g_free() + * Returns: path to the iTunesDB or NULL if non-existent. Must g_free() * after use. - **/ + * + * Since: 0.4.0 + */ gchar *itdb_get_itunesdb_path (const gchar *mountpoint) { gchar *itunes_dir, *path=NULL; @@ -6493,9 +6529,11 @@ gchar *itdb_get_itunesdb_path (const gchar *mountpoint) * * Retrieve a path to the iTunesSD * - * Return value: path to the iTunesSD or NULL if non-existent. Must g_free() + * Returns: path to the iTunesSD or NULL if non-existent. Must g_free() * after use. - **/ + * + * Since: 0.4.0 + */ gchar *itdb_get_itunessd_path (const gchar *mountpoint) { gchar *itunes_dir, *path=NULL; @@ -6519,9 +6557,11 @@ gchar *itdb_get_itunessd_path (const gchar *mountpoint) * * Retrieve a path to the ArtworkDB * - * Return value: path to the ArtworkDB or NULL if non-existent. Must g_free() + * Returns: path to the ArtworkDB or NULL if non-existent. Must g_free() * after use. - **/ + * + * Since: 0.4.0 + */ gchar *itdb_get_artworkdb_path (const gchar *mountpoint) { gchar *itunes_dir, *path=NULL; @@ -6552,11 +6592,11 @@ gchar *itdb_get_artworkdb_path (const gchar *mountpoint) * Gets the current time in a format appropriate for storing in the libgpod * data structures * - * Return value: current time + * Returns: current time * * Deprecated: kept for compatibility with older code, directly use * g_get_current_time() or time(NULL) instead - **/ + */ time_t itdb_time_get_mac_time (void) { GTimeVal time; @@ -6572,11 +6612,11 @@ time_t itdb_time_get_mac_time (void) * * Converts a timestamp from libgpod format to host system timestamp. * - * Return value: timestamp for the host system + * Returns: timestamp for the host system * * Deprecated: It's been kept for compatibility with older code, but this * function is now a no-op - **/ + */ time_t itdb_time_mac_to_host (time_t time) { return time; @@ -6588,11 +6628,11 @@ time_t itdb_time_mac_to_host (time_t time) * * Convert host system timestamp to libgpod format timestamp * - * Return value: a libgpod timestamp + * Returns: a libgpod timestamp * * Deprecated: It's been kept for compatibility with older code, but this * function is now a no-op - **/ + */ time_t itdb_time_host_to_mac (time_t time) { return time; @@ -6611,9 +6651,10 @@ time_t itdb_time_host_to_mac (time_t time) * information as well as the directory structure required for the * type of iPod. * - * Return value: TRUE when successful, FALSE if a failure has occurred. - * - **/ + * Returns: TRUE when successful, FALSE if a failure has occurred. + * + * Since: 0.4.0 + */ gboolean itdb_init_ipod (const gchar *mountpoint, const gchar *model_number, const gchar *ipod_name, diff --git a/src/itdb_photoalbum.c b/src/itdb_photoalbum.c index 2e6168b..84febf7 100644 --- a/src/itdb_photoalbum.c +++ b/src/itdb_photoalbum.c @@ -121,8 +121,10 @@ static void error_no_photos_dir (const gchar *mp, GError **error) * Retrieve the Photo directory by * first calling itdb_get_control_dir() and then adding 'Photos' * - * Return value: path to the Artwork directory or NULL if + * Returns: path to the Artwork directory or NULL if * non-existent. Must g_free() after use. + * + * Since: 0.4.0 */ gchar *itdb_get_photos_dir (const gchar *mountpoint) { @@ -149,9 +151,11 @@ gchar *itdb_get_photos_dir (const gchar *mountpoint) * * Retrieve a path to the Photo DB * - * Return value: path to the PhotoDB or NULL if non-existent. Must + * Returns: path to the PhotoDB or NULL if non-existent. Must * g_free() after use. - **/ + * + * Since: 0.4.0 + */ gchar *itdb_get_photodb_path (const gchar *mountpoint) { gchar *photo_dir, *path=NULL; @@ -176,8 +180,10 @@ gchar *itdb_get_photodb_path (const gchar *mountpoint) * Retrieve the Photo Thumbnail directory by * first calling itdb_get_control_dir() and then adding 'Photos/Thumbs' * - * Return value: path to the Artwork directory or NULL if + * Returns: path to the Artwork directory or NULL if * non-existent. Must g_free() after use. + * + * Since: 0.4.0 */ gchar *itdb_get_photos_thumb_dir (const gchar *mountpoint) { @@ -201,13 +207,15 @@ gchar *itdb_get_photos_thumb_dir (const gchar *mountpoint) /** * itdb_photodb_parse: - * @mp: mountpoint of the iPod - * @error: will contain the error description when an error occured. + * @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. - **/ + * Returns: the imported PhotoDB or NULL in case of an error. + * + * Since: 0.4.0 + */ Itdb_PhotoDB *itdb_photodb_parse (const gchar *mp, GError **error) { gchar *photos_dir; @@ -244,10 +252,12 @@ Itdb_PhotoDB *itdb_photodb_parse (const gchar *mp, GError **error) * Creates a new Itdb_PhotoDB. If mountpoint is NULL, you will have to * set it manually later by calling itdb_device_set_mountpoint(). * - * Return value: a newly created Itdb_PhotoDB to be freed with + * Returns: a newly created Itdb_PhotoDB to be freed with * itdb_photodb_free() when it's no longer needed. The Photo Library * Album is created automatically. - **/ + * + * Since: 0.4.2 + */ Itdb_PhotoDB *itdb_photodb_create (const gchar *mountpoint) { Itdb_PhotoDB *photodb = itdb_photodb_new (); @@ -280,7 +290,9 @@ static Itdb_PhotoDB *itdb_photodb_new (void) * @photodb: an #Itdb_PhotoDB * * Free the memory taken by @photodb. - **/ + * + * Since: 0.4.0 + */ void itdb_photodb_free (Itdb_PhotoDB *photodb) { if (photodb) @@ -460,24 +472,26 @@ static Itdb_Artwork *itdb_photodb_add_photo_internal (Itdb_PhotoDB *db, /** * itdb_photodb_add_photo: - * @db: the #Itdb_PhotoDB to add the photo to. - * @filename: file with the photo to add. - * @position: position where to insert the new photo (-1 to append at - * the end) - * @rotation: angle by which the image should be rotated - * counterclockwise. Valid values are 0, 90, 180 and 270. - * @error: return location for a #GError or NULL - * + * @db: the #Itdb_PhotoDB to add the photo to + * @filename: path of the photo to add. + * @position: position where to insert the new photo (-1 to append + * at the end) + * @rotation: angle by which the image should be rotated + * counterclockwise. Valid values are 0, 90, 180 and 270. + * @error: return location for a #GError or NULL + * * Add a photo to the PhotoDB. The photo is automatically added to the * first Photoalbum, which by default contains a list of all photos in * the database. If no Photoalbums exist one is created automatically. * * For the rotation angle you can also use the gdk constants - * GDK_PIXBUF_ROTATE_NONE, ..._COUNTERCLOCKWISE, ..._UPSIDEDOWN AND - * ..._CLOCKWISE. + * %GDK_PIXBUF_ROTATE_NONE, %GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE, + * %GDK_PIXBUF_ROTATE_UPSIDEDOWN, AND %GDK_PIXBUF_ROTATE_CLOCKWISE. * - * Return value: a pointer to the added photo. - **/ + * Returns: a pointer to the added photo. + * + * Since: 0.4.0 + */ Itdb_Artwork *itdb_photodb_add_photo (Itdb_PhotoDB *db, const gchar *filename, gint position, @@ -493,26 +507,28 @@ Itdb_Artwork *itdb_photodb_add_photo (Itdb_PhotoDB *db, /** * itdb_photodb_add_photo_from_data: - * @db: the #Itdb_PhotoDB to add the photo to. - * @image_data: chunk of memory containing the image data (for example - * a jpg file) + * @db: the #Itdb_PhotoDB to add the photo to + * @image_data: chunk of memory containing the image data (for + * example a jpg file) * @image_data_len: length of above chunk of memory - * @position: position where to insert the new photo (-1 to append at - * the end) - * @rotation: angle by which the image should be rotated - * counterclockwise. Valid values are 0, 90, 180 and 270. - * @error: return location for a #GError or NULL - * + * @position: position where to insert the new photo (-1 to + * append at the end) + * @rotation: angle by which the image should be rotated + * counterclockwise. Valid values are 0, 90, 180 and 270. + * @error: return location for a #GError or NULL + * * Add a photo to the PhotoDB. The photo is automatically added to the * first Photoalbum, which by default contains a list of all photos in * the database. If no Photoalbums exist one is created automatically. * * For the rotation angle you can also use the gdk constants - * GDK_PIXBUF_ROTATE_NONE, ..._COUNTERCLOCKWISE, ..._UPSIDEDOWN AND - * ..._CLOCKWISE. + * %GDK_PIXBUF_ROTATE_NONE, %GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE, + * %GDK_PIXBUF_ROTATE_UPSIDEDOWN, AND %GDK_PIXBUF_ROTATE_CLOCKWISE. * - * Return value: a pointer to the added photo. - **/ + * Returns: a pointer to the added photo. + * + * Since: 0.4.0 + */ Itdb_Artwork *itdb_photodb_add_photo_from_data (Itdb_PhotoDB *db, const guchar *image_data, gsize image_data_len, @@ -530,24 +546,26 @@ Itdb_Artwork *itdb_photodb_add_photo_from_data (Itdb_PhotoDB *db, /** * itdb_photodb_add_photo_from_pixbuf: - * @db: the #Itdb_PhotoDB to add the photo to. - * @pixbuf: a #GdkPixbuf to use as the image data - * @position: position where to insert the new photo (-1 to append at - * the end) - * @rotation: angle by which the image should be rotated - * counterclockwise. Valid values are 0, 90, 180 and 270. - * @error: return location for a #GError or NULL - * + * @db: the #Itdb_PhotoDB to add the photo to + * @pixbuf: a #GdkPixbuf to use as the image data + * @position: position where to insert the new photo (-1 to append + * at the end) + * @rotation: angle by which the image should be rotated + * counterclockwise. Valid values are 0, 90, 180 and 270. + * @error: return location for a #GError or NULL + * * Add a photo to the PhotoDB. The photo is automatically added to the * first Photoalbum, which by default contains a list of all photos in * the database. If no Photoalbums exist one is created automatically. * * For the rotation angle you can also use the gdk constants - * GDK_PIXBUF_ROTATE_NONE, ..._COUNTERCLOCKWISE, ..._UPSIDEDOWN AND - * ..._CLOCKWISE. + * %GDK_PIXBUF_ROTATE_NONE, %GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE, + * %GDK_PIXBUF_ROTATE_UPSIDEDOWN, AND %GDK_PIXBUF_ROTATE_CLOCKWISE. + * + * Returns: a pointer to the added photo. * - * Return value: a pointer to the added photo. - **/ + * Since: 0.5.0 + */ Itdb_Artwork *itdb_photodb_add_photo_from_pixbuf (Itdb_PhotoDB *db, gpointer pixbuf, gint position, @@ -563,19 +581,23 @@ Itdb_Artwork *itdb_photodb_add_photo_from_pixbuf (Itdb_PhotoDB *db, /** * itdb_photodb_remove_photo: - * @db: the #Itdb_PhotoDB to remove the photo from - * @album: the album to remove the photo from. If album is NULL, then - * it will first be removed from all photoalbums and then from the - * photo database as well. - * @photo: #Itdb_Artwork (photo) to remove. + * @db: the #Itdb_PhotoDB to remove the photo from + * @album: the album to remove the photo from. If album is NULL, then + * it will first be removed from all photoalbums and then + * from the photo database as well. + * @photo: #Itdb_Artwork (photo) to remove. * - * Remove photo. If @album is not the first photoalbum, the photo will - * be removed from that album only. If @album is NULL or the first - * photoalbum (Photo Library), the photo will be removed from all - * albums and the #Itdb_PhotoDB. + * Removes a photo. If @album is not the first photoalbum, the photo + * will be removed from that album only. If @album is NULL or the + * first photoalbum (Photo Library), the photo will be removed from + * all albums and the #Itdb_PhotoDB. * + * <note> * @photo will be freed and can no longer be used if removed from the * first photoalbum. + * </note> + * + * Since: 0.4.0 */ void itdb_photodb_remove_photo (Itdb_PhotoDB *db, Itdb_PhotoAlbum *album, @@ -609,15 +631,17 @@ void itdb_photodb_remove_photo (Itdb_PhotoDB *db, /** * itdb_photodb_photoalbum_by_name: - * @db: the #Itdb_PhotoDB to retrieve the album from - * @albumname: the name of the photoalbum to get or NULL for the - * master photoalbum. + * @db: the #Itdb_PhotoDB to retrieve the album from + * @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, + * Returns: a pointer to the first photoalbum named @albumname, * else NULL + * + * Since: 0.4.2 */ Itdb_PhotoAlbum *itdb_photodb_photoalbum_by_name (Itdb_PhotoDB *db, const gchar *albumname) { @@ -638,17 +662,21 @@ Itdb_PhotoAlbum *itdb_photodb_photoalbum_by_name (Itdb_PhotoDB *db, const gchar /** * 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 - * the database. + * @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 the database. * - * Remove @album from the Photo Database. If remove_pics is TRUE, + * Remove @album from the Photo Database. If @remove_pics is TRUE, * remove all photos contained in @album from the Photo Database. * + * <note> * Memory used by the removed album will be freed and the album cannot * be accessed any more. - **/ + * </note> + * + * Since: 0.4.2 + */ void itdb_photodb_photoalbum_remove (Itdb_PhotoDB *db, Itdb_PhotoAlbum *album, gboolean remove_pics) @@ -677,11 +705,12 @@ void itdb_photodb_photoalbum_remove (Itdb_PhotoDB *db, /** * itdb_photodb_photoalbum_add_photo: - * @db: the #Itdb_PhotoDB to act on - * @album: the #Itdb_PhotoAlbum to add the photo to - * @photo: a pointer to the photo (#Itdb_Artwork) to add to the album - * @position: position where to insert the new photo (-1 to append at - * the end) + * @db: the #Itdb_PhotoDB to act on + * @album: the #Itdb_PhotoAlbum to add the photo to + * @photo: a pointer to the photo (#Itdb_Artwork) to add to the + * album + * @position: position where to insert the new photo (-1 to append + * at the end) * * Adds a photo already in the library to the specified album * @album. Photos are automatically added to the first album (Photo @@ -689,8 +718,8 @@ void itdb_photodb_photoalbum_remove (Itdb_PhotoDB *db, * itdb_photodb_add_photo_from_data(), so you don't have to use this * function to add them there. * + * Since: 0.4.2 */ - void itdb_photodb_photoalbum_add_photo (Itdb_PhotoDB *db, Itdb_PhotoAlbum *album, Itdb_Artwork *photo, @@ -705,14 +734,16 @@ void itdb_photodb_photoalbum_add_photo (Itdb_PhotoDB *db, /** * itdb_photodb_photoalbum_create: - * @db: The database to create a new album in - * @albumname: the name of the new album - * @pos: position where to insert the newly created album (-1 for - * append to end). + * @db: The database to create a new album in + * @albumname: the name of the new album + * @pos: position where to insert the newly created album (-1 + * to append at the end). * * Create and add a new photoalbum. * - * Return value: the album which was created and added. + * Returns: the album which was created and added. + * + * Since: 0.4.2 */ Itdb_PhotoAlbum *itdb_photodb_photoalbum_create (Itdb_PhotoDB *db, const gchar *albumname, @@ -734,16 +765,18 @@ Itdb_PhotoAlbum *itdb_photodb_photoalbum_create (Itdb_PhotoDB *db, /** * itdb_photodb_write: - * @photodb: the #Itdb_PhotoDB to write to disk - * @error: return location for a #GError or NULL + * @photodb: the #Itdb_PhotoDB to write to disk + * @error: return location for a #GError or NULL * * Write out a PhotoDB. * * FIXME: error is not set yet. * - * Return value: TRUE on success, FALSE on error, in which case @error is + * Returns: TRUE on success, FALSE on error, in which case @error is * set accordingly. - **/ + * + * Since: 0.4.0 + */ gboolean itdb_photodb_write (Itdb_PhotoDB *photodb, GError **error) { gint result; diff --git a/src/itdb_playlist.c b/src/itdb_playlist.c index 9acd695..e5c9e6b 100644 --- a/src/itdb_playlist.c +++ b/src/itdb_playlist.c @@ -39,13 +39,13 @@ /** * itdb_spl_action_known: - * @action: an #SPLAction + * @action: an #ItdbSPLAction * * Checks if @action is a known (to libgpod) smart playlist action. * - * Return value: TRUE if @action is known. Otherwise a warning is displayed - * and FALSE is returned. - **/ + * Returns: TRUE if @action is known. Otherwise a warning is + * displayed and FALSE is returned. + */ gboolean itdb_spl_action_known (ItdbSPLAction action) { gboolean result = FALSE; @@ -86,9 +86,9 @@ gboolean itdb_spl_action_known (ItdbSPLAction action) * * Gets the type of the field of the @splr rule * - * Return value: an #Itdb_SPLFieldType corresponding to @splr field type - * (string, int, date, ...) - **/ + * Returns: an #Itdb_SPLFieldType corresponding to @splr field + * type (string, int, date, ...) + */ ItdbSPLFieldType itdb_splr_get_field_type (const Itdb_SPLRule *splr) { g_return_val_if_fail (splr != NULL, ITDB_SPLFT_UNKNOWN); @@ -141,8 +141,8 @@ ItdbSPLFieldType itdb_splr_get_field_type (const Itdb_SPLRule *splr) * * Gets the type of the action associated with @splr. * - * Return value: type (range, date, string...) of the action field - **/ + * Returns: type (range, date, string...) of the action field + */ ItdbSPLActionType itdb_splr_get_action_type (const Itdb_SPLRule *splr) { ItdbSPLFieldType fieldType; @@ -320,13 +320,13 @@ ItdbSPLActionType itdb_splr_get_action_type (const Itdb_SPLRule *splr) /** * itdb_splr_eval: - * @splr: an #Itdb_SPLRule - * @track: an #Itdb_Track + * @splr: an #Itdb_SPLRule + * @track: an #Itdb_Track * - * Evaluates @splr's truth against @track. track->itdb must be set. + * Evaluates @splr's truth against @track. @track->itdb must be set. * - * Return value: TRUE if @track matches @splr, FALSE otherwise. - **/ + * Returns: TRUE if @track matches @splr, FALSE otherwise. + */ gboolean itdb_splr_eval (Itdb_SPLRule *splr, Itdb_Track *track) { ItdbSPLFieldType ft; @@ -681,7 +681,7 @@ static GList *randomize_glist (GList *list) * @pl: an #Itdb_Playlist to randomize * * Randomizes @pl - **/ + */ void itdb_playlist_randomize (Itdb_Playlist *pl) { g_return_if_fail (pl); @@ -693,11 +693,12 @@ void itdb_playlist_randomize (Itdb_Playlist *pl) * itdb_spl_update: * @spl: an #Itdb_Playlist * - * Updates the content of the smart playlist @spl (meant to be called if the - * tracks stored in the #Itdb_iTunesDB associated with @spl have changed - * somehow and you want spl->members to be accurate with regards to those - * changes. Does nothing if @spl isn't a smart playlist. - **/ + * Updates the content of the smart playlist @spl (meant to be called + * if the tracks stored in the #Itdb_iTunesDB associated with @spl + * have changed somehow and you want @spl->members to be accurate + * with regards to those changes. Does nothing if @spl isn't a smart + * playlist. + */ void itdb_spl_update (Itdb_Playlist *spl) { GList *gl; @@ -909,7 +910,7 @@ void itdb_spl_update (Itdb_Playlist *spl) * @itdb: an #Itdb_iTunesDB * * Updates all smart playlists contained in @itdb - **/ + */ void itdb_spl_update_all (Itdb_iTunesDB *itdb) { g_return_if_fail (itdb); @@ -929,9 +930,11 @@ static void spl_update2 (Itdb_Playlist *playlist, gpointer data) * itdb_spl_update_live: * @itdb: an #Itdb_iTunesDB * - * Updates all 'live' smart playlists contained in @itdb, ie those which have - * the 'live updating' flag set - **/ + * Updates all smart playlists contained in @itdb which have the + * @liveupdate flag set. + * + * Since: 0.2.0 + */ void itdb_spl_update_live (Itdb_iTunesDB *itdb) { g_return_if_fail (itdb); @@ -947,8 +950,8 @@ void itdb_spl_update_live (Itdb_iTunesDB *itdb) * itdb_splr_validate: * @splr: an #Itdb_SPLRule * - * Validates a rule - **/ + * Validates a smart playlist rule + */ void itdb_splr_validate (Itdb_SPLRule *splr) { ItdbSPLActionType at; @@ -1005,7 +1008,7 @@ void itdb_splr_validate (Itdb_SPLRule *splr) * @splr: an #Itdb_SPLRule * * Frees the memory used by @splr - **/ + */ void itdb_splr_free (Itdb_SPLRule *splr) { if (splr) @@ -1020,9 +1023,9 @@ void itdb_splr_free (Itdb_SPLRule *splr) * @pl: an #Itdb_Playlist * @splr: an Itdb_SPLRule * - * Removes the smart playlist rule @splr from playlist @pl. The memory used by - * @splr is freed. - **/ + * Removes the smart playlist rule @splr from playlist @pl. The memory + * used by @splr is freed. + */ void itdb_splr_remove (Itdb_Playlist *pl, Itdb_SPLRule *splr) { g_return_if_fail (pl); @@ -1034,14 +1037,14 @@ void itdb_splr_remove (Itdb_Playlist *pl, Itdb_SPLRule *splr) /** * itdb_splr_add: - * @pl: an #Itdb_Playlist - * @splr: an #Itdb_SPLRule - * @pos: position of the rule + * @pl: an #Itdb_Playlist + * @splr: an #Itdb_SPLRule + * @pos: position of the rule * - * Adds the smart rule @splr to @pl at position @pos. If @pos is -1, @splr gets - * appended to the end. After this call, @splr memory is managed by @pl, so - * you no longer need to call itdb_splr_free() - **/ + * Adds the smart rule @splr to @pl at position @pos. If @pos is -1, + * @splr gets appended to the end. After this call, @splr memory is + * managed by @pl, so you no longer need to call itdb_splr_free() + */ void itdb_splr_add (Itdb_Playlist *pl, Itdb_SPLRule *splr, gint pos) { g_return_if_fail (pl); @@ -1056,9 +1059,9 @@ void itdb_splr_add (Itdb_Playlist *pl, Itdb_SPLRule *splr, gint pos) * * Creates a new default smart rule * - * Return value: a new #Itdb_SPLRule that must be freed with itdb_splr_free() when + * Returns: a new #Itdb_SPLRule that must be freed with itdb_splr_free() when * no longer needed - **/ + */ Itdb_SPLRule *itdb_splr_new (void) { Itdb_SPLRule *splr = g_new0 (Itdb_SPLRule, 1); @@ -1077,15 +1080,16 @@ Itdb_SPLRule *itdb_splr_new (void) /** * itdb_splr_add_new: - * @pl: an #Itdb_Playlist - * @pos: position to insert the rule at + * @pl: an #Itdb_Playlist + * @pos: position to insert the rule at * - * Creates a new smart rule and inserts it at position @pos in @pl. If @pos is - * -1, the new rule gets appended to the end. + * Creates a new smart rule and inserts it at position @pos in @pl. If + * @pos is -1, the new rule gets appended to the end. * - * Return value: pointer to the newly created #Itdb_SPLRule. Its memory is handled - * by @pl though, so you don't need to explicitly call itdb_splr_free() on it - **/ + * Returns: pointer to the newly created #Itdb_SPLRule. Its + * memory is handled by @pl though, so you don't need to explicitly + * call itdb_splr_free() on it + */ Itdb_SPLRule *itdb_splr_add_new (Itdb_Playlist *pl, gint pos) { Itdb_SPLRule *splr; @@ -1116,13 +1120,14 @@ static Itdb_SPLRule *splr_duplicate (Itdb_SPLRule *splr) * itdb_playlist_duplicate: * @pl: an #Itdb_Playlist * - * Duplicates an existing playlist. pl_dup->id is set to zero, so that - * it will be set to a unique value when adding it to an #Itdb_iTunesDB. The - * returned playlist won't be associated with an #Itdb_iTunesDB. + * Duplicates an existing playlist. @pl_dup->id is set to zero, so + * that it will be set to a unique value when adding it to an + * #Itdb_iTunesDB. The returned playlist won't be associated with an + * #Itdb_iTunesDB. * - * Return value: a newly allocated #Itdb_Playlist that you'll have to free - * with itdb_playlist_free() when you no longer need it. - **/ + * Returns: a newly allocated #Itdb_Playlist that you'll have to + * free with itdb_playlist_free() when you no longer need it. + */ Itdb_Playlist *itdb_playlist_duplicate (Itdb_Playlist *pl) { Itdb_Playlist *pl_dup; @@ -1166,13 +1171,13 @@ Itdb_Playlist *itdb_playlist_duplicate (Itdb_Playlist *pl) /** * itdb_spl_copy_rules: - * @dest: destination #Itdb_Playlist - * @src: source #Itdb_Playlist + * @dest: destination #Itdb_Playlist + * @src: source #Itdb_Playlist * * Copy all relevant information for smart playlist from playlist @src - * to playlist @dest. If @dest is already a smart playlist, the existing data - * is overwritten/deleted. - **/ + * to playlist @dest. If @dest is already a smart playlist, the + * existing data is overwritten/deleted. + */ void itdb_spl_copy_rules (Itdb_Playlist *dest, Itdb_Playlist *src) { GList *gl; @@ -1202,16 +1207,16 @@ void itdb_spl_copy_rules (Itdb_Playlist *dest, Itdb_Playlist *src) /** * itdb_playlist_new: - * @title: playlist title - * @spl: smart playlist flag - * - * Creates a new playlist. If @spl is TRUE, a smart - * playlist is generated. pl->id is set by itdb_playlist_add() when the - * playlist is added to an #Itdb_iTunesDB - * - * Return value: a new #Itdb_Playlist which must be freed with + * @title: playlist title + * @spl: smart playlist flag + * + * Creates a new playlist. If @spl is TRUE, a smart playlist is + * generated. pl->id is set by itdb_playlist_add() when the playlist + * is added to an #Itdb_iTunesDB + * + * Returns: a new #Itdb_Playlist which must be freed with * itdb_playlist_free() after use - **/ + */ Itdb_Playlist *itdb_playlist_new (const gchar *title, gboolean spl) { Itdb_Playlist *pl = g_new0 (Itdb_Playlist, 1); @@ -1244,7 +1249,7 @@ Itdb_Playlist *itdb_playlist_new (const gchar *title, gboolean spl) * @pl: an #Itdb_Playlist * * Frees the memory used by playlist @pl. - **/ + */ void itdb_playlist_free (Itdb_Playlist *pl) { g_return_if_fail (pl); @@ -1260,15 +1265,16 @@ void itdb_playlist_free (Itdb_Playlist *pl) /** * itdb_playlist_add: - * @itdb: an #Itdb_iTunesDB - * @pl: an #Itdb_Playlist - * @pos: position to insert @pl at + * @itdb: an #Itdb_iTunesDB + * @pl: an #Itdb_Playlist + * @pos: position to insert @pl at * * Adds playlist @pl to the database @itdb at position @pos (-1 for - * "append to end"). A unique id is created if pl->id is equal to - * zero. After calling this function, @itdb manages the memory of @pl, which - * means you no longer need to explicitly call itdb_playlist_free() - **/ + * "append to end"). A unique id is created if @pl->id is equal to + * zero. After calling this function, @itdb manages the memory of @pl, + * which means you no longer need to explicitly call + * itdb_playlist_free() + */ void itdb_playlist_add (Itdb_iTunesDB *itdb, Itdb_Playlist *pl, gint32 pos) { g_return_if_fail (itdb); @@ -1307,11 +1313,11 @@ void itdb_playlist_add (Itdb_iTunesDB *itdb, Itdb_Playlist *pl, gint32 pos) /** * itdb_playlist_move: - * @pl: an #Itdb_Playlist - * @pos: new position + * @pl: an #Itdb_Playlist + * @pos: new position * * Moves playlist @pl to position @pos - **/ + */ void itdb_playlist_move (Itdb_Playlist *pl, guint32 pos) { Itdb_iTunesDB *itdb; @@ -1330,7 +1336,7 @@ void itdb_playlist_move (Itdb_Playlist *pl, guint32 pos) * * Removes @pl from the #Itdb_iTunesDB it's associated with * and frees memory - **/ + */ void itdb_playlist_remove (Itdb_Playlist *pl) { Itdb_iTunesDB *itdb; @@ -1347,9 +1353,9 @@ void itdb_playlist_remove (Itdb_Playlist *pl) * itdb_playlist_unlink: * @pl: an #Itdb_Playlist * - * Remove @pl from the #Itdb_iTunesDB it's associated with but do not free - * memory. pl->itdb is set to NULL after this function returns - **/ + * Remove @pl from the #Itdb_iTunesDB it's associated with but do not + * free memory. @pl->itdb is set to NULL after this function returns + */ void itdb_playlist_unlink (Itdb_Playlist *pl) { Itdb_iTunesDB *itdb; @@ -1364,13 +1370,13 @@ void itdb_playlist_unlink (Itdb_Playlist *pl) /** * itdb_playlist_exists: - * @itdb: an #Itdb_iTunesDB - * @pl: an #Itdb_Playlist + * @itdb: an #Itdb_iTunesDB + * @pl: an #Itdb_Playlist * - * Checks if @pl is present in @db + * Checks if @pl is present in @itdb * - * Return value: TRUE if @pl exists in @db, FALSE otherwise - **/ + * Returns: TRUE if @pl exists in @itdb, FALSE otherwise + */ gboolean itdb_playlist_exists (Itdb_iTunesDB *itdb, Itdb_Playlist *pl) { g_return_val_if_fail (itdb, FALSE); @@ -1382,13 +1388,12 @@ gboolean itdb_playlist_exists (Itdb_iTunesDB *itdb, Itdb_Playlist *pl) /** * itdb_playlist_add_track: - * @pl: an #Itdb_Playlist - * @track: an #Itdb_Track - * @pos: position to insert @track at + * @pl: an #Itdb_Playlist + * @track: an #Itdb_Track + * @pos: position to insert @track at * - * Adds @track to @pl at position @pos (-1 for "append to - * end") - **/ + * Adds @track to @pl at position @pos (-1 to append at the end) + */ void itdb_playlist_add_track (Itdb_Playlist *pl, Itdb_Track *track, gint32 pos) { @@ -1403,14 +1408,14 @@ void itdb_playlist_add_track (Itdb_Playlist *pl, /** * itdb_playlist_remove_track: - * @pl: an #Itdb_Playlist - * @track: an #Itdb_Track + * @pl: an #Itdb_Playlist + * @track: an #Itdb_Track * * Removes @track from @pl. If @pl is NULL, removes @track from the - * master playlist. If @track can't be found in @pl, nothing happens. If after - * removing @track, @pl is empty, it's not removed from the database - * The memory used by @track isn't freed. - **/ + * master playlist. If @track can't be found in @pl, nothing happens. + * If after removing @track, @pl is empty, it's not removed from the + * database The memory used by @track isn't freed. + */ void itdb_playlist_remove_track (Itdb_Playlist *pl, Itdb_Track *track) { g_return_if_fail (track); @@ -1425,14 +1430,14 @@ void itdb_playlist_remove_track (Itdb_Playlist *pl, Itdb_Track *track) /** * itdb_playlist_by_id: - * @itdb: an #Itdb_iTunesDB - * @id: ID of the playlist to look for + * @itdb: an #Itdb_iTunesDB + * @id: ID of the playlist to look for * * Looks up a playlist whose ID is @id * - * Return value: the #Itdb_Playlist with ID @id or NULL if there is no such - * playlist. - **/ + * Returns: the #Itdb_Playlist with ID @id or NULL if there is no + * such playlist. + */ Itdb_Playlist *itdb_playlist_by_id (Itdb_iTunesDB *itdb, guint64 id) { GList *gl; @@ -1449,13 +1454,14 @@ Itdb_Playlist *itdb_playlist_by_id (Itdb_iTunesDB *itdb, guint64 id) /** * itdb_playlist_by_nr: - * @itdb: an #Itdb_iTunesDB - * @num: the position of the playlist, counting from 0 + * @itdb: an #Itdb_iTunesDB + * @num: the position of the playlist, counting from 0 * * Gets the playlist at the given position in @itdb * - * Return value: the #Itdb_Playlist, or NULL if there is no playlist at @pos - **/ + * Returns: the #Itdb_Playlist, or NULL if there is no playlist + * at @pos + */ Itdb_Playlist *itdb_playlist_by_nr (Itdb_iTunesDB *itdb, guint32 num) { Itdb_Playlist *pl; @@ -1467,14 +1473,14 @@ Itdb_Playlist *itdb_playlist_by_nr (Itdb_iTunesDB *itdb, guint32 num) /** * itdb_playlist_by_name: - * @itdb: an #Itdb_iTunesDB - * @name: name of the playlist to look for + * @itdb: an #Itdb_iTunesDB + * @name: name of the playlist to look for * * Searches a playlist whose name is @name in @itdb * - * Return value: the first #Itdb_Playlist with name @name, NULL if there is no - * such playlist - **/ + * Returns: the first #Itdb_Playlist with name @name, NULL if + * there is no such playlist + */ Itdb_Playlist *itdb_playlist_by_name (Itdb_iTunesDB *itdb, gchar *name) { GList *gl; @@ -1497,8 +1503,10 @@ Itdb_Playlist *itdb_playlist_by_name (Itdb_iTunesDB *itdb, gchar *name) * * Checks if @pl is the master playlist * - * Return value: TRUE if @pl is the master playlist, FALSE otherwise - **/ + * Returns: TRUE if @pl is the master playlist, FALSE otherwise + * + * Since: 0.1.6 + */ gboolean itdb_playlist_is_mpl (Itdb_Playlist *pl) { g_return_val_if_fail (pl, FALSE); @@ -1512,8 +1520,10 @@ gboolean itdb_playlist_is_mpl (Itdb_Playlist *pl) * * Checks if @pl is the podcasts playlist * - * Return value: TRUE if @pl is the podcasts playlist, FALSE otherwise - **/ + * Returns: TRUE if @pl is the podcasts playlist, FALSE otherwise + * + * Since: 0.1.6 + */ gboolean itdb_playlist_is_podcasts (Itdb_Playlist *pl) { g_return_val_if_fail (pl, FALSE); @@ -1526,7 +1536,9 @@ gboolean itdb_playlist_is_podcasts (Itdb_Playlist *pl) * @pl: an #Itdb_Playlist * * Sets @pl to be a master playlist - **/ + * + * Since: 0.2.0 + */ void itdb_playlist_set_mpl (Itdb_Playlist *pl) { g_return_if_fail (pl); @@ -1539,7 +1551,9 @@ void itdb_playlist_set_mpl (Itdb_Playlist *pl) * @pl: an #Itdb_Playlist * * Set @pl to be a podcasts playlist - **/ + * + * Since: 0.2.0 + */ void itdb_playlist_set_podcasts (Itdb_Playlist *pl) { g_return_if_fail (pl); @@ -1553,8 +1567,8 @@ void itdb_playlist_set_podcasts (Itdb_Playlist *pl) * * Gets the master playlist of @itdb * - * Return value: the master playlist of @itdb - **/ + * Returns: the master playlist of @itdb + */ Itdb_Playlist *itdb_playlist_mpl (Itdb_iTunesDB *itdb) { Itdb_Playlist *pl; @@ -1570,15 +1584,17 @@ Itdb_Playlist *itdb_playlist_mpl (Itdb_iTunesDB *itdb) return pl; } - /** * itdb_playlist_podcasts: * @itdb: an #Itdb_iTunesDB * * Gets the podcasts playlist of @itdb * - * Return value: the podcasts playlist of @itdb, or NULL if it's there is none - **/ + * Returns: the podcasts playlist of @itdb, or NULL if there is + * not one + * + * Since: 0.1.6 + */ Itdb_Playlist *itdb_playlist_podcasts (Itdb_iTunesDB *itdb) { GList *gl; @@ -1598,13 +1614,13 @@ Itdb_Playlist *itdb_playlist_podcasts (Itdb_iTunesDB *itdb) /** * itdb_playlist_contains_track: - * @pl: an #Itdb_Playlist - * @track: an #Itdb_Track + * @pl: an #Itdb_Playlist + * @track: an #Itdb_Track * - * Checks if @track is in @pl. - * - * Return value: TRUE if @track is in @pl, FALSE otherwise - **/ + * Checks if @track is in @pl + * + * Returns: TRUE if @track is in @pl, FALSE otherwise + */ gboolean itdb_playlist_contains_track (Itdb_Playlist *pl, Itdb_Track *tr) { g_return_val_if_fail (tr, FALSE); @@ -1622,11 +1638,11 @@ gboolean itdb_playlist_contains_track (Itdb_Playlist *pl, Itdb_Track *tr) * itdb_playlist_contain_track_number: * @tr: an #Itdb_Track * - * Counts the number of playlist @track is a member of (not including the - * master playlist) + * Counts the number of playlist @track is a member of (not including + * the master playlist) * - * Return value: number of playlist containing @track - **/ + * Returns: the number of playlist containing @track + */ guint32 itdb_playlist_contain_track_number (Itdb_Track *tr) { Itdb_iTunesDB *itdb; @@ -1654,8 +1670,8 @@ guint32 itdb_playlist_contain_track_number (Itdb_Track *tr) * * Counts the number of tracks in @pl * - * Return value: track count - **/ + * Returns: the number of tracks in @pl + */ guint32 itdb_playlist_tracks_number (Itdb_Playlist *pl) { g_return_val_if_fail (pl, 0); diff --git a/src/itdb_plist.c b/src/itdb_plist.c index 2bd1dca..6595401 100644 --- a/src/itdb_plist.c +++ b/src/itdb_plist.c @@ -373,15 +373,16 @@ itdb_plist_parse (xmlNode * a_node, GError **error) /** * itdb_plist_parse: - * @filename: name of the XML plist file to parse - * @error: return location for a #GError + * @filename: name of the XML plist file to parse + * @error: return location for a #GError * - * Returns: NULL on error (@error will be set), a newly allocated GValue - * containing a GHashTable otherwise. + * Parses the XML plist file stored in @filename. If an error occurs + * during the parsing, itdb_plist_parse will return NULL and @error + * will be set * - * Parses the XML plist file stored in @filename. If an error occurs during - * the parsing, itdb_plist_parse will return NULL and @error will be set - **/ + * Returns: NULL on error (@error will be set), a newly allocated + * #GValue containing a #GHashTable otherwise. + */ GValue * itdb_plist_parse_from_file (const char *filename, GError **error) { @@ -409,17 +410,18 @@ itdb_plist_parse_from_file (const char *filename, GError **error) /** * itdb_plist_parse_from_memory: - * @data: memory location containing XML plist data to parse - * @len: length in bytes of the string to parse - * @error: return location for a #GError + * @data: memory location containing XML plist data to parse + * @len: length in bytes of the string to parse + * @error: return location for a #GError * - * Returns: NULL on error (@error will be set), a newly allocated GValue - * containing a GHashTable otherwise. + * Parses the XML plist file stored in @data which length is @len + * bytes. If an error occurs during the parsing, + * itdb_plist_parse_from_memory() will return NULL and @error will be + * set. * - * Parses the XML plist file stored in @data which length is @len bytes. If - * an error occurs during the parsing, itdb_plist_parse_from_memory will - * return NULL and @error will be set - **/ + * Returns: NULL on error (@error will be set), a newly allocated + * #GValue containing a #GHashTable otherwise. + */ GValue * itdb_plist_parse_from_memory (const char *data, gsize len, GError **error) { diff --git a/src/itdb_sysinfo_extended_parser.c b/src/itdb_sysinfo_extended_parser.c index 5408c91..a373b8b 100644 --- a/src/itdb_sysinfo_extended_parser.c +++ b/src/itdb_sysinfo_extended_parser.c @@ -501,16 +501,18 @@ static SysInfoIpodProperties *g_value_to_ipod_properties (GValue *value) /** * itdb_sysinfo_extended_parse: - * @filename: name of the SysInfoExtended file to parse - * @error: return location for a #GError - * Returns: a newly allocated #SysInfoIpodProperties which must be freed - * after use, or NULL if an error occurred during the parsing + * @filename: name of the SysInfoExtended file to parse + * @error: return location for a #GError * * itdb_sysinfo_extended_parse() parses a SysInfoExtended file into a * #SysInfoIpodProperties structure. This structure contains a lot of - * information about the iPod properties (artwork format supported, podcast - * capabilities, ...) which can be queried using the appropriate accessors - **/ + * information about the iPod properties (artwork format supported, + * podcast capabilities, ...) which can be queried using the + * appropriate accessors. + * + * Returns: a newly allocated #SysInfoIpodProperties which must be + * freed after use, or NULL if an error occurred during the parsing + */ SysInfoIpodProperties *itdb_sysinfo_extended_parse (const char *filename, GError **error) { @@ -534,9 +536,6 @@ SysInfoIpodProperties *itdb_sysinfo_extended_parse (const char *filename, * itdb_sysinfo_properties_get_serial_number: * @props: a #SysInfoIpodProperties structure * - * Returns: the iPod serial number, NULL if the serial number wasn't set in - * @props. The returned string must not be modified nor freed. - * * Gets the iPod serial number from @props if it was found while parsing * @props. The serial number uniquely identify an ipod and it can be used * to determine when it was produced and its model/color, see @@ -545,7 +544,10 @@ SysInfoIpodProperties *itdb_sysinfo_extended_parse (const char *filename, * correspond to. Please avoid parsing this serial number by yourself and * ask for additionnal API in libgpod if you find yourself needing to parse * that serial number :) - **/ + * + * Returns: the iPod serial number, NULL if the serial number wasn't set in + * @props. The returned string must not be modified nor freed. + */ const char * itdb_sysinfo_properties_get_serial_number (const SysInfoIpodProperties *props) { @@ -557,16 +559,16 @@ itdb_sysinfo_properties_get_serial_number (const SysInfoIpodProperties *props) * itdb_sysinfo_properties_get_firewire_id: * @props: a #SysInfoIpodProperties structure * - * Returns: the iPod firewire ID, NULL if the serial number wasn't set in - * @props. The returned string must not be modified nor freed. - * * Gets the iPod firewire ID from @props if it was found while parsing * @props. Contrary to what its name implies, the firewire ID is also set * on USB iPods and is especially important on iPod Classic and Nano Video * since this ID (which is unique on each iPod) is needed to generate the * checksum that is required to write a valid iPod database on these * models. - **/ + * + * Returns: the iPod firewire ID, NULL if the serial number wasn't set in + * @props. The returned string must not be modified nor freed. + */ const char * itdb_sysinfo_properties_get_firewire_id (const SysInfoIpodProperties *props) { @@ -578,11 +580,10 @@ itdb_sysinfo_properties_get_firewire_id (const SysInfoIpodProperties *props) * itdb_sysinfo_properties_get_cover_art_formats: * @props: a #SysInfoIpodProperties structure * - * Returns: a #GList of #Itdb_ArtworkFormat describing the cover art formats - * supported by the iPod described in @props. The returned list must not be + * Returns: a #GList of #Itdb_ArtworkFormat describing the cover art formats + * supported by the iPod described in @props. The returned list must not be * modified nor freed. - * - **/ + */ const GList * itdb_sysinfo_properties_get_cover_art_formats (const SysInfoIpodProperties *props) { @@ -594,11 +595,10 @@ itdb_sysinfo_properties_get_cover_art_formats (const SysInfoIpodProperties *prop * itdb_sysinfo_properties_get_photo_formats: * @props: a #SysInfoIpodProperties structure * - * Returns: a #GList of #Itdb_ArtworkFormat describing the photo formats - * supported by the iPod described in @props. The returned list must not be + * Returns: a #GList of #Itdb_ArtworkFormat describing the photo formats + * supported by the iPod described in @props. The returned list must not be * modified nor freed. - * - **/ + */ const GList * itdb_sysinfo_properties_get_photo_formats (const SysInfoIpodProperties *props) { @@ -610,11 +610,10 @@ itdb_sysinfo_properties_get_photo_formats (const SysInfoIpodProperties *props) * itdb_sysinfo_properties_get_chapter_image_formats: * @props: a #SysInfoIpodProperties structure * - * Returns: a #GList of #Itdb_ArtworkFormat describing the chapter image - * formats supported by the iPod described in @props. The returned list must + * Returns: a #GList of #Itdb_ArtworkFormat describing the chapter image + * formats supported by the iPod described in @props. The returned list must * not be modified nor freed. - * - **/ + */ const GList * itdb_sysinfo_properties_get_chapter_image_formats (const SysInfoIpodProperties *props) { @@ -626,13 +625,13 @@ itdb_sysinfo_properties_get_chapter_image_formats (const SysInfoIpodProperties * * itdb_sysinfo_properties_supports_sparse_artwork: * @props: a #SysInfoIpodProperties structure * - * Returns: TRUE if the iPod supports sparse artwork, FALSE if it does not - * or if @props doesn't contain any information about sparse artwork - * * Sparse artwork is a way to share artwork between different iPod tracks * which make things more efficient space-wise. This function can be used * to check if the more space-efficient artwork storage can be used. - **/ + * + * Returns: TRUE if the iPod supports sparse artwork, FALSE if it does not + * or if @props doesn't contain any information about sparse artwork + */ G_GNUC_INTERNAL gboolean itdb_sysinfo_properties_supports_sparse_artwork (const SysInfoIpodProperties *props) { diff --git a/src/itdb_thumb.c b/src/itdb_thumb.c index 201dfb1..0f9a394 100644 --- a/src/itdb_thumb.c +++ b/src/itdb_thumb.c @@ -115,7 +115,9 @@ static void itdb_thumb_ipod_item_free (Itdb_Thumb_Ipod_Item *item) * @thumb: an #Itdb_Thumb * * Frees the memory used by @thumb - **/ + * + * Since: 0.3.0 + */ void itdb_thumb_free (Itdb_Thumb *thumb) { g_return_if_fail (thumb); @@ -183,9 +185,11 @@ itdb_thumb_ipod_item_duplicate (Itdb_Thumb_Ipod_Item *item) * * Duplicates the data contained in @thumb * - * Return value: a newly allocated copy of @thumb to be freed with + * Returns: a newly allocated copy of @thumb to be freed with * itdb_thumb_free() after use - **/ + * + * Since: 0.3.0 + */ Itdb_Thumb *itdb_thumb_duplicate (Itdb_Thumb *thumb) { switch (thumb->data_type) { @@ -298,17 +302,17 @@ Itdb_Thumb_Ipod_Item *itdb_thumb_ipod_get_item_by_type (Itdb_Thumb *thumbs, } /** - * itdb_thumb_get_filename: + * itdb_thumb_ipod_get_filename: * @device: an #Itdb_Device - * @thumb: an #Itdb_Thumb + * @thumb: an #Itdb_Thumb_Ipod_Item * * Get filename of thumbnail. If it's a thumbnail on the iPod, return * the full path to the ithmb file. Otherwise return the full path to * the original file. * - * Return value: newly allocated string containing the absolute path to the + * Returns: newly allocated string containing the absolute path to the * thumbnail file. - **/ + */ gchar *itdb_thumb_ipod_get_filename (Itdb_Device *device, Itdb_Thumb_Ipod_Item *item) { gchar *artwork_dir; @@ -356,23 +360,26 @@ const GList *itdb_thumb_ipod_get_thumbs (Itdb_Thumb_Ipod *thumbs) /** * itdb_thumb_to_pixbuf_at_size: * @device: an #Itdb_Device - * @thumb: an #Itdb_Thumb - * + * @thumb: an #Itdb_Thumb + * @width: width of the pixbuf to retrieve, -1 for the biggest + * possible size and 0 for the smallest possible size (with no scaling) + * @height: height of the pixbuf to retrieve, -1 for the biggest possible size + * and 0 for the smallest possible size (with no scaling) + * * Converts @thumb to a #GdkPixbuf. + * + * <note> * Since we want to have gdk-pixbuf dependency optional, a generic * gpointer is returned which you have to cast to a #GdkPixbuf using * GDK_PIXBUF() yourself. + * </note> * - * @width: width of the pixbuf to retrieve, -1 for the biggest - * possible size and 0 for the smallest possible size (with no scaling) - * - * @height: height of the pixbuf to retrieve, -1 for the biggest possible size - * and 0 for the smallest possible size (with no scaling) - * - * Return value: a #GdkPixbuf that must be unreffed with gdk_pixbuf_unref() + * Returns: a #GdkPixbuf that must be unreffed with gdk_pixbuf_unref() * after use, or NULL if the creation of the gdk-pixbuf failed or if * libgpod was compiled without gdk-pixbuf support. - **/ + * + * Since: 0.7.0 + */ gpointer itdb_thumb_to_pixbuf_at_size (Itdb_Device *device, Itdb_Thumb *thumb, gint width, gint height) { @@ -504,7 +511,8 @@ gpointer itdb_thumb_to_pixbuf_at_size (Itdb_Device *device, Itdb_Thumb *thumb, return pixbuf; } -static GList *itdb_thumb_ipod_to_pixbufs (Itdb_Device *dev, Itdb_Thumb_Ipod *thumb) +static GList *itdb_thumb_ipod_to_pixbufs (Itdb_Device *device, + Itdb_Thumb_Ipod *thumb) { const GList *items; GList *pixbufs = NULL; @@ -516,7 +524,7 @@ static GList *itdb_thumb_ipod_to_pixbufs (Itdb_Device *dev, Itdb_Thumb_Ipod *thu items != NULL; items = items->next) { GdkPixbuf *pixbuf; - pixbuf = itdb_thumb_ipod_item_to_pixbuf (dev, items->data); + pixbuf = itdb_thumb_ipod_item_to_pixbuf (device, items->data); if (pixbuf != NULL) { pixbufs = g_list_prepend (pixbufs, pixbuf); } @@ -528,12 +536,7 @@ static GList *itdb_thumb_ipod_to_pixbufs (Itdb_Device *dev, Itdb_Thumb_Ipod *thu /** * itdb_thumb_to_pixbufs: * @device: an #Itdb_Device - * @thumb: an #Itdb_Thumb - * - * Return value: a #GList of #GdkPixbuf which are associated with @thumb, NULL - * if the pixbuf was invalid or if libgpod is compiled without gdk-pixbuf - * support. The #GdkPixbuf must be unreffed with gdk_pixbuf_unref() after use - * and the #GList must be freed with g_list_free(). + * @thumb: an #Itdb_Thumb * * Converts @thumb to a #GList of #GdkPixbuf. The returned #GList will * generally contain only 1 element, the full-size pixbuf associated with @@ -541,20 +544,27 @@ static GList *itdb_thumb_ipod_to_pixbufs (Itdb_Device *dev, Itdb_Thumb_Ipod *thu * modified from the library, then the returned #GList will contain several * #GdkPixbuf corresponding to the various thumbnail sizes that were * written to the iPod database. - **/ -GList *itdb_thumb_to_pixbufs (Itdb_Device *dev, Itdb_Thumb *thumb) + * + * Returns: a #GList of #GdkPixbuf which are associated with @thumb, NULL + * if the pixbuf was invalid or if libgpod is compiled without gdk-pixbuf + * support. The #GdkPixbuf must be unreffed with gdk_pixbuf_unref() after use + * and the #GList must be freed with g_list_free(). + * + * Since: 0.7.0 + */ +GList *itdb_thumb_to_pixbufs (Itdb_Device *device, Itdb_Thumb *thumb) { GList *pixbufs = NULL; GdkPixbuf *pixbuf; switch (thumb->data_type) { case ITDB_THUMB_TYPE_IPOD: - pixbufs = itdb_thumb_ipod_to_pixbufs (dev, (Itdb_Thumb_Ipod *)thumb); + pixbufs = itdb_thumb_ipod_to_pixbufs (device, (Itdb_Thumb_Ipod *)thumb); break; case ITDB_THUMB_TYPE_FILE: case ITDB_THUMB_TYPE_MEMORY: case ITDB_THUMB_TYPE_PIXBUF: - pixbuf = itdb_thumb_to_pixbuf_at_size (dev, thumb, -1, -1); + pixbuf = itdb_thumb_to_pixbuf_at_size (device, thumb, -1, -1); pixbufs = g_list_append (pixbufs, pixbuf); break; case ITDB_THUMB_TYPE_INVALID: @@ -564,14 +574,14 @@ GList *itdb_thumb_to_pixbufs (Itdb_Device *dev, Itdb_Thumb *thumb) return pixbufs; } #else -gpointer itdb_thumb_to_pixbuf_at_size (Itdb_Device *dev, Itdb_Thumb *thumb, +gpointer itdb_thumb_to_pixbuf_at_size (Itdb_Device *device, Itdb_Thumb *thumb, gint width, gint height) { return NULL; } -GList *itdb_thumb_to_pixbufs (Itdb_Device *dev, Itdb_Thumb *thumb) +GList *itdb_thumb_to_pixbufs (Itdb_Device *device, Itdb_Thumb *thumb) { return NULL; } diff --git a/src/itdb_thumb.h b/src/itdb_thumb.h index 7c2806c..9170945 100644 --- a/src/itdb_thumb.h +++ b/src/itdb_thumb.h @@ -27,14 +27,13 @@ #include "itdb_device.h" /* Types of thumbnails in Itdb_Image */ -enum _ItdbThumbDataType { +typedef enum { ITDB_THUMB_TYPE_INVALID, ITDB_THUMB_TYPE_FILE, ITDB_THUMB_TYPE_MEMORY, ITDB_THUMB_TYPE_PIXBUF, ITDB_THUMB_TYPE_IPOD -}; -typedef enum _ItdbThumbDataType ItdbThumbDataType; +} ItdbThumbDataType; /* The Itdb_Thumb structure can represent two slightly different thumbnails: @@ -51,11 +50,22 @@ typedef enum _ItdbThumbDataType ItdbThumbDataType; filename point to a 'real' image file OR image_data and image_data_len are set. - + b) a thumbnail (big or small) stored on a database in the iPod. In these cases, id corresponds to the ID originally used in the database, filename points to a .ithmb file on the iPod */ + +/** + * Itdb_Thumb: + * @data_type: The type of data (file, memory, pixbuf, ipod, etc.) + * @rotation: Angle by which the image is rotated counterclockwise + * + * This is an opaque structure representing a thumbnail to be + * transferred to the ipod or read from the ipod. + * + * Since: 0.3.0 + */ struct _Itdb_Thumb { ItdbThumbDataType data_type; guint rotation; diff --git a/src/itdb_track.c b/src/itdb_track.c index dbe427e..16a07d8 100644 --- a/src/itdb_track.c +++ b/src/itdb_track.c @@ -38,9 +38,9 @@ * * Creates an empty #Itdb_Track * - * Return Value: the new #Itdb_Track, free it with itdb_track_free() when no + * Returns: the new #Itdb_Track, free it with itdb_track_free() when no * longer needed - **/ + */ Itdb_Track *itdb_track_new (void) { Itdb_Track *track = g_new0 (Itdb_Track, 1); @@ -195,15 +195,15 @@ static void itdb_track_set_defaults (Itdb_Track *tr) /** * itdb_track_add: - * @itdb: an #Itdb_iTunesDB - * @track: an #Itdb_Track - * @pos: position of the track to add + * @itdb: an #Itdb_iTunesDB + * @track: an #Itdb_Track + * @pos: position of the track to add * * Adds @track to @itdb->tracks at position @pos (or at the end if pos * is -1). The application is responsible to also add it to the master * playlist. The @itdb gets ownership of the @track and will take care of * freeing the memory it uses when it's no longer necessary. - **/ + */ void itdb_track_add (Itdb_iTunesDB *itdb, Itdb_Track *track, gint32 pos) { g_return_if_fail (itdb); @@ -222,7 +222,7 @@ void itdb_track_add (Itdb_iTunesDB *itdb, Itdb_Track *track, gint32 pos) * @track: an #Itdb_Track * * Frees the memory used by @track - **/ + */ void itdb_track_free (Itdb_Track *track) { g_return_if_fail (track); @@ -270,7 +270,7 @@ void itdb_track_free (Itdb_Track *track) * Removes @track from the #Itdb_iTunesDB it's associated with, and frees the * memory it uses. It doesn't remove the track from the playlists it may have * been added to, in particular it won't be removed from the master playlist. - **/ + */ void itdb_track_remove (Itdb_Track *track) { Itdb_iTunesDB *itdb; @@ -290,8 +290,8 @@ void itdb_track_remove (Itdb_Track *track) * Removes @track from the #Itdb_iTunesDB it's associated with, but do not free * memory. It doesn't remove the track from the playlists it may have been * added to, in particular it won't be removed from the master playlist. - * track->itdb is set to NULL. - **/ + * @track->itdb is set to NULL. + */ void itdb_track_unlink (Itdb_Track *track) { Itdb_iTunesDB *itdb; @@ -310,8 +310,8 @@ void itdb_track_unlink (Itdb_Track *track) * * Duplicates an existing track * - * Return value: a newly allocated #Itdb_Track - **/ + * Returns: a newly allocated #Itdb_Track + */ Itdb_Track *itdb_track_duplicate (Itdb_Track *tr) { Itdb_Track *tr_dup; @@ -431,16 +431,18 @@ static gboolean itdb_track_set_thumbnails_internal (Itdb_Track *track, /** * itdb_track_set_thumbnails: - * @track: an #Itdb_Track + * @track: an #Itdb_Track * @filename: image file to use as a thumbnail * * Uses the image contained in @filename to generate iPod thumbnails. The image * can be in any format supported by gdk-pixbuf. To save memory, the thumbnails - * will only be generated when necessary, ie when itdb_save() or a similar + * will only be generated when necessary, i.e. when itdb_save() or a similar * function is called. * - * Return value: TRUE if the thumbnail could be added, FALSE otherwise. - **/ + * Returns: TRUE if the thumbnail could be added, FALSE otherwise. + * + * Since: 0.3.0 + */ gboolean itdb_track_set_thumbnails (Itdb_Track *track, const gchar *filename) { @@ -453,18 +455,20 @@ gboolean itdb_track_set_thumbnails (Itdb_Track *track, /** * itdb_track_set_thumbnails_from_data: - * @track: an #Itdb_Track - * @image_data: data used to create the thumbnail (the raw contents of - * an image file) + * @track: an #Itdb_Track + * @image_data: data used to create the thumbnail (the raw contents of + * an image file) * @image_data_len: length of above data block * * Uses @image_data to generate iPod thumbnails. The image can be in * any format supported by gdk-pixbuf. To save memory, the thumbnails - * will only be generated when necessary, ie when itdb_save() or a + * will only be generated when necessary, i.e. when itdb_save() or a * similar function is called. * - * Return value: TRUE if the thumbnail could be added, FALSE otherwise. - **/ + * Returns: TRUE if the thumbnail could be added, FALSE otherwise. + * + * Since: 0.4.0 + */ gboolean itdb_track_set_thumbnails_from_data (Itdb_Track *track, const guchar *image_data, gsize image_data_len) @@ -479,15 +483,17 @@ gboolean itdb_track_set_thumbnails_from_data (Itdb_Track *track, /** * itdb_track_set_thumbnails_from_pixbuf: - * @track: an #Itdb_Track + * @track: an #Itdb_Track * @pixbuf: a #GdkPixbuf used to generate the thumbnail * * Uses @pixbuf to generate iPod thumbnails. To save memory, the thumbnails - * will only be generated when necessary, ie when itdb_save() or a + * will only be generated when necessary, i.e. when itdb_save() or a * similar function is called. * - * Return value: TRUE if the thumbnail could be added, FALSE otherwise. - **/ + * Returns: TRUE if the thumbnail could be added, FALSE otherwise. + * + * Since: 0.5.0 + */ gboolean itdb_track_set_thumbnails_from_pixbuf (Itdb_Track *track, gpointer pixbuf) { @@ -503,7 +509,9 @@ gboolean itdb_track_set_thumbnails_from_pixbuf (Itdb_Track *track, * @track: an #Itdb_Track * * Removes the thumbnails associated with @track - **/ + * + * Since: 0.3.0 + */ void itdb_track_remove_thumbnails (Itdb_Track *track) { g_return_if_fail (track); @@ -518,20 +526,23 @@ void itdb_track_remove_thumbnails (Itdb_Track *track) /** * itdb_track_by_id: * @itdb: an #Itdb_iTunesDB - * @id: ID of the track to look for + * @id: ID of the track to look for * * Looks up a track using its ID in @itdb. + * * Looking up tracks by ID is not really a good idea because the IDs * are created by itdb just before export. The functions are here * because they are needed during import of the iTunesDB which is * referencing tracks by IDs. - * This function is very slow (linear in the number of tracks contained in the - * database). If you need to lookup many IDs use itdb_track_id_tree_create(), - * itdb_track_id_tree_destroy(), and itdb_track_id_tree_by_id(). * - * Return value: #Itdb_Track with the ID @id or NULL if the ID cannot be + * This function is very slow (linear in the number of tracks + * contained in the database). If you need to lookup many IDs use + * itdb_track_id_tree_create(), itdb_track_id_tree_destroy(), and + * itdb_track_id_tree_by_id(). + * + * Returns: #Itdb_Track with the ID @id or NULL if the ID cannot be * found. - **/ + */ Itdb_Track *itdb_track_by_id (Itdb_iTunesDB *itdb, guint32 id) { GList *gl; @@ -560,11 +571,11 @@ static gint track_id_compare (gconstpointer a, gconstpointer b) * @itdb: an #Itdb_iTunesDB * * Creates a balanced-binary tree for quick ID lookup that is used in - * itdb_track_by_id_tree() function below + * itdb_track_by_id_tree() * - * Return value: a #GTree indexed by track IDs to be freed with + * Returns: a #GTree indexed by track IDs to be freed with * itdb_track_id_tree_destroy() when no longer used - **/ + */ GTree *itdb_track_id_tree_create (Itdb_iTunesDB *itdb) { GTree *idtree; @@ -588,7 +599,7 @@ GTree *itdb_track_id_tree_create (Itdb_iTunesDB *itdb) * @idtree: a #GTree * * Frees the memory used by @idtree - **/ + */ void itdb_track_id_tree_destroy (GTree *idtree) { g_return_if_fail (idtree); @@ -599,14 +610,14 @@ void itdb_track_id_tree_destroy (GTree *idtree) /** * itdb_track_id_tree_by_id: * @idtree: a #GTree created using itdb_track_id_tree_create() - * @id: the ID of the track to search for + * @id: the ID of the track to search for * - * Lookup an #Itdb_Track by @id using @idtree for faster lookup (compared to - * itdb_track_by_id) + * Lookup an #Itdb_Track by @id using @idtree for faster lookup + * (compared to itdb_track_by_id()) * - * Return value: the #Itdb_Track whose ID is @id, or NULL if such a track + * Returns: the #Itdb_Track whose ID is @id, or NULL if such a track * couldn't be found - **/ + */ Itdb_Track *itdb_track_id_tree_by_id (GTree *idtree, guint32 id) { g_return_val_if_fail (idtree, NULL); @@ -618,8 +629,12 @@ Itdb_Track *itdb_track_id_tree_by_id (GTree *idtree, guint32 id) * itdb_track_has_thumbnails: * @track: an #Itdb_Track * - * Return value: TRUE if @track has artwork available, FALSE otherwise - **/ + * Determine if a @track has thumbnails + * + * Returns: TRUE if @track has artwork available, FALSE otherwise + * + * Since: 0.7.0 + */ gboolean itdb_track_has_thumbnails (Itdb_Track *track) { g_return_val_if_fail (track != NULL, FALSE); @@ -628,20 +643,22 @@ gboolean itdb_track_has_thumbnails (Itdb_Track *track) /** * itdb_track_get_thumbnail: - * @track: an #Itdb_Track - * @width: width of the pixbuf to retrieve, -1 for the biggest possible size - * (with no scaling) + * @track: an #Itdb_Track + * @width: width of the pixbuf to retrieve, -1 for the biggest possible size + * (with no scaling) * @height: height of the pixbuf to retrieve, -1 for the biggest possible size - * (with no scaling) + * (with no scaling) * - * Returns a #GdkPixbuf representing the cover associated with the current - * track, scaling it if appropriate. If either height or width is -1, then the - * biggest unscaled thumbnail available will be returned + * Get a thumbnail representing the cover associated with the current track, + * scaling it if appropriate. If either height or width is -1, then the biggest + * unscaled thumbnail available will be returned. * - * Return value: a #GdkPixbuf that must be unreffed when no longer used, NULL + * Returns: a #GdkPixbuf that must be unreffed when no longer used, NULL * if no artwork could be found or if libgpod is compiled without GdkPixbuf * support - **/ + * + * Since: 0.7.0 + */ gpointer itdb_track_get_thumbnail (Itdb_Track *track, gint width, gint height) { g_return_val_if_fail (track != NULL, NULL); diff --git a/src/ithumb-writer.c b/src/ithumb-writer.c index c29151e..9fbe9c6 100644 --- a/src/ithumb-writer.c +++ b/src/ithumb-writer.c @@ -1391,7 +1391,7 @@ static gboolean ithumb_rearrange_thumbnail_file (gpointer _key, If a thumbnail has been removed, a slot in the file is opened. This slot is filled by copying data from the end of the file and - adjusting the corresponding Itdb_Image offset pointer. When all + adjusting the corresponding Itdb_Thumb offset pointer. When all slots are filled, the file is truncated to the new length. */ static gboolean |