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 <[EMAIL PROTECTED]>
+ * src/itdb_sysinfo_extended_parser.c:
+ * src/itdb_plist.c: add gtk-doc documentation
+
+2008-07-27 Christophe Fergeau <[EMAIL PROTECTED]>
+
* 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.
-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
gtkpod-cvs2 mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/gtkpod-cvs2
