From: <te...@us...> - 2008-07-29 20:10:30
|
Revision: 2068 http://gtkpod.svn.sourceforge.net/gtkpod/?rev=2068&view=rev Author: teuf Date: 2008-07-29 20:10:39 +0000 (Tue, 29 Jul 2008) Log Message: ----------- Add gtk-doc documentation Modified Paths: -------------- libgpod/trunk/ChangeLog libgpod/trunk/src/itdb_plist.c libgpod/trunk/src/itdb_sysinfo_extended_parser.c Modified: libgpod/trunk/ChangeLog =================================================================== --- libgpod/trunk/ChangeLog 2008-07-29 20:10:13 UTC (rev 2067) +++ libgpod/trunk/ChangeLog 2008-07-29 20:10:39 UTC (rev 2068) @@ -1,5 +1,10 @@ 2008-07-27 Christophe Fergeau <te...@gn...> + * src/itdb_sysinfo_extended_parser.c: + * src/itdb_plist.c: add gtk-doc documentation + +2008-07-27 Christophe Fergeau <te...@gn...> + * src/itdb_sysinfo_extended_parser.c: * src/itdb_sysinfo_extended_parser.h: add a GError argument to SysInfoExtended parsing functions Modified: libgpod/trunk/src/itdb_plist.c =================================================================== --- libgpod/trunk/src/itdb_plist.c 2008-07-29 20:10:13 UTC (rev 2067) +++ libgpod/trunk/src/itdb_plist.c 2008-07-29 20:10:39 UTC (rev 2068) @@ -311,6 +311,17 @@ return NULL; } +/** + * itdb_plist_parse: + * @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 + **/ GValue * itdb_plist_parse_from_file (const char *filename, GError **error) { @@ -336,6 +347,19 @@ return parsed_doc; } +/** + * 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 + * + * 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 + **/ GValue * itdb_plist_parse_from_memory (const char *data, gsize len, GError **error) { Modified: libgpod/trunk/src/itdb_sysinfo_extended_parser.c =================================================================== --- libgpod/trunk/src/itdb_sysinfo_extended_parser.c 2008-07-29 20:10:13 UTC (rev 2067) +++ libgpod/trunk/src/itdb_sysinfo_extended_parser.c 2008-07-29 20:10:39 UTC (rev 2068) @@ -501,6 +501,18 @@ return props; } +/** + * 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 + * + * 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 + **/ SysInfoIpodProperties *itdb_sysinfo_extended_parse (const char *filename, GError **error) { @@ -520,6 +532,22 @@ return props; } +/** + * 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 + * http://svn.gnome.org/viewvc/podsleuth/trunk/src/PodSleuth/PodSleuth/SerialNumber.cs?view=markup + * for more details about what the various parts of the serial number + * 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 :) + **/ const char * itdb_sysinfo_properties_get_serial_number (const SysInfoIpodProperties *props) { @@ -527,6 +555,20 @@ return props->serial_number; } +/** + * 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. + **/ const char * itdb_sysinfo_properties_get_firewire_id (const SysInfoIpodProperties *props) { @@ -534,6 +576,15 @@ return props->firewire_guid; } +/** + * 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 + * modified nor freed. + * + **/ const GList * itdb_sysinfo_properties_get_cover_art_formats (const SysInfoIpodProperties *props) { @@ -541,6 +592,15 @@ return props->artwork_formats; } +/** + * 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 + * modified nor freed. + * + **/ const GList * itdb_sysinfo_properties_get_photo_formats (const SysInfoIpodProperties *props) { @@ -548,6 +608,15 @@ return props->photo_formats; } +/** + * 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 + * not be modified nor freed. + * + **/ const GList * itdb_sysinfo_properties_get_chapter_image_formats (const SysInfoIpodProperties *props) { @@ -555,6 +624,17 @@ return props->chapter_image_formats; } +/** + * 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. + **/ G_GNUC_INTERNAL gboolean itdb_sysinfo_properties_supports_sparse_artwork (const SysInfoIpodProperties *props) { This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |