diff options
| author | Christophe Fergeau <teuf@gnome.org> | 2006-04-10 18:17:25 +0000 |
|---|---|---|
| committer | Christophe Fergeau <teuf@gnome.org> | 2006-04-10 18:17:25 +0000 |
| commit | 94ca87f3e5f9a2de994893f4927bd374f36a8dc7 (patch) | |
| tree | 5129c69fdbd110e8c536ce0fc4082b4b1a90dbe1 | |
| parent | 7252444ca4b911507beaa9d62f6ddb28520b2284 (diff) | |
| download | libgpod-94ca87f3e5f9a2de994893f4927bd374f36a8dc7.tar.gz libgpod-94ca87f3e5f9a2de994893f4927bd374f36a8dc7.tar.xz libgpod-94ca87f3e5f9a2de994893f4927bd374f36a8dc7.zip | |
* docs/Makefile.am:
* docs/reference/Makefile.am:
* docs/reference/libgpod-docs.xml:
* docs/reference/libgpod-sections.txt:
* docs/reference/tmpl/Internal.sgml:
* docs/reference/tmpl/artwork.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/playlists.sgml:
* docs/reference/tmpl/smart-playlists.sgml:
* docs/reference/tmpl/track.sgml:
* docs/reference/version.xml.in: all the files below are new files
needed for gtk-doc support
* Makefile.am:
* configure.ac: add gtk-doc support to build system
* src/itdb_artwork.c:
* src/itdb_device.c:
* src/itdb_itunesdb.c:
* src/itdb_playlist.c:
* src/itdb_track.c: update inline comments in those files so that
gtk-doc can pick them up to build documentation
git-svn-id: https://gtkpod.svn.sf.net/svnroot/gtkpod/libgpod/trunk@1243 f01d2545-417e-4e96-918e-98f8d0dbbcb6
| -rw-r--r-- | ChangeLog | 28 | ||||
| -rw-r--r-- | Makefile.am | 5 | ||||
| -rw-r--r-- | configure.ac | 8 | ||||
| -rw-r--r-- | docs/Makefile.am | 1 | ||||
| -rw-r--r-- | docs/reference/Makefile.am | 78 | ||||
| -rw-r--r-- | docs/reference/libgpod-docs.xml | 75 | ||||
| -rw-r--r-- | docs/reference/libgpod-sections.txt | 266 | ||||
| -rw-r--r-- | docs/reference/tmpl/Internal.sgml | 19 | ||||
| -rw-r--r-- | docs/reference/tmpl/artwork.sgml | 160 | ||||
| -rw-r--r-- | docs/reference/tmpl/device.sgml | 129 | ||||
| -rw-r--r-- | docs/reference/tmpl/itunesdb-copying.sgml | 74 | ||||
| -rw-r--r-- | docs/reference/tmpl/itunesdb-db.sgml | 133 | ||||
| -rw-r--r-- | docs/reference/tmpl/itunesdb-lowlevel.sgml | 164 | ||||
| -rw-r--r-- | docs/reference/tmpl/itunesdb-time.sgml | 45 | ||||
| -rw-r--r-- | docs/reference/tmpl/libgpod-unused.sgml | 126 | ||||
| -rw-r--r-- | docs/reference/tmpl/playlists.sgml | 287 | ||||
| -rw-r--r-- | docs/reference/tmpl/smart-playlists.sgml | 269 | ||||
| -rw-r--r-- | docs/reference/tmpl/track.sgml | 232 | ||||
| -rw-r--r-- | docs/reference/version.xml.in | 4 | ||||
| -rw-r--r-- | src/itdb_artwork.c | 129 | ||||
| -rw-r--r-- | src/itdb_device.c | 46 | ||||
| -rw-r--r-- | src/itdb_itunesdb.c | 487 | ||||
| -rw-r--r-- | src/itdb_playlist.c | 364 | ||||
| -rw-r--r-- | src/itdb_track.c | 135 |
24 files changed, 3011 insertions, 253 deletions
@@ -1,3 +1,31 @@ +2006-04-10 Christophe Fergeau <teuf@gnome.org> + + * docs/Makefile.am: + * docs/reference/Makefile.am: + * docs/reference/libgpod-docs.xml: + * docs/reference/libgpod-sections.txt: + * docs/reference/tmpl/Internal.sgml: + * docs/reference/tmpl/artwork.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/playlists.sgml: + * docs/reference/tmpl/smart-playlists.sgml: + * docs/reference/tmpl/track.sgml: + * docs/reference/version.xml.in: all the files below are new files + needed for gtk-doc support + * Makefile.am: + * configure.ac: add gtk-doc support to build system + * src/itdb_artwork.c: + * src/itdb_device.c: + * src/itdb_itunesdb.c: + * src/itdb_playlist.c: + * src/itdb_track.c: update inline comments in those files so that + gtk-doc can pick them up to build documentation + 2006-04-08 Christophe Fergeau <teuf@gnome.org> * configure.ac: generate Makefile for bindings/python/examples diff --git a/Makefile.am b/Makefile.am index 7af1838..de9e100 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,4 +1,7 @@ -SUBDIRS=src tests po bindings m4 +SUBDIRS=src bindings tests po m4 docs + +# build documentation when doing a distcheck. +DISTCHECK_CONFIGURE_FLAGS = --enable-gtk-doc pkgconfigdir = $(libdir)/pkgconfig pkgconfig_DATA = libgpod-1.0.pc diff --git a/configure.ac b/configure.ac index d351fba..9b8a28d 100644 --- a/configure.ac +++ b/configure.ac @@ -87,6 +87,11 @@ AM_GLIB_GNU_GETTEXT dnl ************************************************** +dnl * gtk-doc +dnl ************************************************** +GTK_DOC_CHECK(1.0) + +dnl ************************************************** dnl * optional python bindings dnl ************************************************** @@ -148,6 +153,9 @@ Makefile bindings/Makefile bindings/python/Makefile bindings/python/examples/Makefile +docs/Makefile +docs/reference/Makefile +docs/reference/version.xml m4/Makefile po/Makefile.in src/Makefile diff --git a/docs/Makefile.am b/docs/Makefile.am new file mode 100644 index 0000000..b68c774 --- /dev/null +++ b/docs/Makefile.am @@ -0,0 +1 @@ +SUBDIRS=reference diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am new file mode 100644 index 0000000..138d70a --- /dev/null +++ b/docs/reference/Makefile.am @@ -0,0 +1,78 @@ +## Process this file with automake to produce Makefile.in + +# We require automake 1.6 at least. +AUTOMAKE_OPTIONS = 1.6 + +# This is a blank Makefile.am for using gtk-doc. +# Copy this to your project's API docs directory and modify the variables to +# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples +# of using the various options. + +# The name of the module, e.g. 'glib'. +DOC_MODULE=libgpod + +# The top-level SGML file. You can change this if you want to. +DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml + +# The directory containing the source code. Relative to $(srcdir). +# gtk-doc will search all .c & .h files beneath here for inline comments +# documenting the functions and macros. +# e.g. DOC_SOURCE_DIR=../../../gtk +DOC_SOURCE_DIR=../../src + +# Extra options to pass to gtkdoc-scangobj. Not normally needed. +SCANGOBJ_OPTIONS= + +# Extra options to supply to gtkdoc-scan. +# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" +SCAN_OPTIONS= + +# Extra options to supply to gtkdoc-mkdb. +# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml +MKDB_OPTIONS=--sgml-mode --output-format=xml + +# Extra options to supply to gtkdoc-mktmpl +# e.g. MKTMPL_OPTIONS=--only-section-tmpl +MKTMPL_OPTIONS= + +# Extra options to supply to gtkdoc-fixref. Not normally needed. +# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html +FIXXREF_OPTIONS= + +# Used for dependencies. The docs will be rebuilt if any of these change. +# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h +# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c +HFILE_GLOB=$(top_srcdir)/src/*.h +CFILE_GLOB=$(top_srcdir)/src/*.c + +# Header files to ignore when scanning. +# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h +IGNORE_HFILES= + +# Images to copy into HTML directory. +# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png +HTML_IMAGES= + +# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). +# e.g. content_files=running.sgml building.sgml changes-2.0.sgml +content_files= + +# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded +# These files must be listed here *and* in content_files +# e.g. expand_content_files=running.sgml +expand_content_files= + +# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. +# Only needed if you are using gtkdoc-scangobj to dynamically query widget +# signals and properties. +# e.g. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS) +# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib) +INCLUDES= +GTKDOC_LIBS= + +# This includes the standard gtk-doc make rules, copied by gtkdocize. +include $(top_srcdir)/gtk-doc.make + +# Other files to distribute +# e.g. EXTRA_DIST += version.xml.in +EXTRA_DIST += diff --git a/docs/reference/libgpod-docs.xml b/docs/reference/libgpod-docs.xml new file mode 100644 index 0000000..facff7b --- /dev/null +++ b/docs/reference/libgpod-docs.xml @@ -0,0 +1,75 @@ +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> + <bookinfo> + <title>libgpod Reference Manual</title> + <releaseinfo>for libgpod <xi:include href="version.xml"/></releaseinfo> + <authorgroup> + <author> + <firstname>Jorg</firstname> + <surname>Schuler</surname> + <affiliation> + <address> + <email>jorg.schuler@gmx.de</email> + </address> + </affiliation> + </author> + <author> + <firstname>Christophe</firstname> + <surname>Fergeau</surname> + <affiliation> + <address> + <email>teuf@gnome.org</email> + </address> + </affiliation> + </author> + </authorgroup> + <copyright> + <year>2006</year> + <holder>Christophe Fergeau</holder> + </copyright> + + <legalnotice> + <para>Permission is granted to copy, distribute and/or modify + this document under the terms of the <citetitle>GNU Free + Documentation License</citetitle>, Version 1.1 or any later + version published by the Free Software Foundation with no + Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. You may obtain a copy of the <citetitle>GNU Free + Documentation License</citetitle> from the Free Software + Foundation by visiting <ulink type="http" + url="http://www.fsf.org">their Web site</ulink> or by writing + to: Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA.</para> + + <para>Many of the names used by companies to distinguish their + products and services are claimed as trademarks. Where those + names appear in any GNOME documentation, and those trademarks + are made aware to the members of the GNOME Documentation + Project, the names have been printed in caps or initial + caps.</para> + </legalnotice> + + <abstract> + <para>This manual documents the interfaces of the libgpod + library and has some short notes to help get you up to speed + with using the library.</para> + </abstract> + </bookinfo> + + <chapter> + <title>iPod database</title> + <xi:include href="xml/itunesdb-db.xml"/> + <xi:include href="xml/itunesdb-copying.xml"/> + <xi:include href="xml/itunesdb-time.xml"/> + <xi:include href="xml/itunesdb-lowlevel.xml"/> + </chapter> + <chapter> + <title>iPod database components</title> + <xi:include href="xml/track.xml"/> + <xi:include href="xml/playlists.xml"/> + <xi:include href="xml/artwork.xml"/> + <xi:include href="xml/device.xml"/> + </chapter> +</book> diff --git a/docs/reference/libgpod-sections.txt b/docs/reference/libgpod-sections.txt new file mode 100644 index 0000000..676f4d6 --- /dev/null +++ b/docs/reference/libgpod-sections.txt @@ -0,0 +1,266 @@ +<SECTION> +<FILE>itunesdb-db</FILE> +<TITLE>The Itdb_iTunesDB structure</TITLE> +Itdb_iTunesDB +ItdbUserDataDestroyFunc +ItdbUserDataDuplicateFunc + +itdb_new +itdb_free +itdb_parse +itdb_write +itdb_set_mountpoint +itdb_get_mountpoint + +itdb_tracks_number +itdb_tracks_number_nontransferred +itdb_playlists_number +</SECTION> + +<SECTION> +<FILE>itunesdb-copying</FILE> +<TITLE>File handling functions</TITLE> +itdb_cp_track_to_ipod +itdb_filename_fs2ipod +itdb_filename_ipod2fs +itdb_filename_on_ipod +itdb_musicdirs_number +itdb_rename_files +</SECTION> + +<SECTION> +<FILE>itunesdb-lowlevel</FILE> +<TITLE>Low-level functions</TITLE> +itdb_get_control_dir +itdb_get_itunes_dir +itdb_get_music_dir +itdb_get_artwork_dir +itdb_get_device_dir +itdb_get_itunesdb_path +itdb_get_artworkdb_path +itdb_get_path + +itdb_resolve_path +itdb_shuffle_write +itdb_shuffle_write_file +itdb_cp +itdb_parse_file +itdb_write_file +itdb_duplicate +</SECTION> + +<SECTION> +<FILE>itunesdb-time</FILE> +<TITLE>Time handling</TITLE> +itdb_time_get_mac_time +itdb_time_mac_to_host +itdb_time_host_to_mac +</SECTION> + +<SECTION> +<FILE>track</FILE> +<TITLE>Tracks</TITLE> +Itdb_Track +itdb_track_new +itdb_track_free +itdb_track_add +itdb_track_remove +itdb_track_unlink +itdb_track_duplicate +itdb_track_by_id +itdb_track_id_tree_create +itdb_track_id_tree_destroy +itdb_track_id_tree_by_id +itdb_track_set_thumbnails +itdb_track_remove_thumbnails +ITDB_RATING_STEP +</SECTION> + + +<SECTION> +<FILE>playlists</FILE> +<TITLE>Playlists</TITLE> +Itdb_Playlist +ItdbPlaylistSortOrder +itdb_playlist_new +itdb_playlist_free +itdb_playlist_duplicate +itdb_playlist_add +itdb_playlist_move +itdb_playlist_remove +itdb_playlist_unlink + +itdb_playlist_add_track +itdb_playlist_remove_track +itdb_playlist_contains_track +itdb_playlist_contain_track_number +itdb_playlist_tracks_number + +itdb_playlist_mpl +itdb_playlist_is_mpl +itdb_playlist_set_mpl +itdb_playlist_podcasts +itdb_playlist_is_podcasts +itdb_playlist_set_podcasts +itdb_playlist_exists +itdb_playlist_by_id +itdb_playlist_by_nr +itdb_playlist_by_name + +itdb_playlist_randomize +</SECTION> + +<SECTION> +<FILE>smart-playlists</FILE> +<TITLE>Smart Playlists</TITLE> +SPLPref +SPLRule +SPLRules +SPLAction +SPLFieldType +SPLActionType +SPLField +SPLDATE_IDENTIFIER +SPL_MAXSTRINGLENGTH +SPL_STRING_MAXLEN +itdb_splr_get_field_type +itdb_splr_get_action_type +itdb_splr_validate +itdb_splr_remove +itdb_splr_new +itdb_splr_add +itdb_splr_add_new +itdb_spl_copy_rules +itdb_splr_eval +itdb_spl_update +itdb_spl_update_all +itdb_spl_update_live +</SECTION> + +<SECTION> +<FILE>device</FILE> +<TITLE>Device</TITLE> +Itdb_Device +itdb_device_new +itdb_device_free +itdb_device_set_mountpoint +itdb_device_read_sysinfo +itdb_device_get_sysinfo +Itdb_IpodModel +Itdb_ArtworkFormat +Itdb_Generation +Itdb_ModelType +</SECTION> + +<SECTION> +<FILE>artwork</FILE> +<TITLE>Artwork</TITLE> +Itdb_Artwork +Itdb_Thumb +ItdbThumbType +itdb_artwork_new +itdb_artwork_duplicate +itdb_artwork_free +itdb_artwork_add_thumbnail +itdb_artwork_remove_thumbnail +itdb_artwork_remove_thumbnails +itdb_artwork_get_thumb_by_type +itdb_thumb_get_gdk_pixbuf +itdb_thumb_duplicate +itdb_thumb_free +itdb_thumb_new +itdb_thumb_get_filename +</SECTION> + + + + +<SECTION> +<FILE>Internal</FILE> +<SUBSECTION Private> +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_mhii +dump_mhl +dump_mhsd +dump_mhfd +dump_mhba +ITUNESDB_MAX_SIZE +MHeader +MhlHeader +MhbdHeader +ArtworkDB_MhsdHeader +MhltHeader +MhlpHeader +MhypHeader +MhipHeader +MhitHeader +ArtworkDB_MhodHeader +MhfdHeader +MhliHeader +MhiiHeader +MhniHeader +MhlaHeader +MhbaHeader +MhlfHeader +MhifHeader +MhiaHeader +MhitHeader471 +ArtworkDB_MhodHeaderArtworkType3 +MhodHeaderString +MhodHeaderArtworkType1 +MhodHeaderSmartPlaylistData +MhodHeaderSmartPlaylistRuleString +MhodHeaderSmartPlaylistRuleNonString +MhodHeaderSmartPlaylistRule +iTunesDB_MhsdHeader +MhodHeader +_MhodHeaderArtworkType1 +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 + +SPLACTION_LAST_HOURS_VALUE +SPLACTION_LAST_MINUTES_VALUE +SPLACTION_LAST_YEARS_VALUE +SPLACTION_LAST_LUNARCYCLE_VALUE +SPLACTION_LAST_SIDEREAL_DAY +SPLACTION_LAST_SWATCH_BEAT +SPLACTION_LAST_MOMENT +SPLACTION_LAST_OSTENT +SPLACTION_LAST_FORTNIGHT +SPLACTION_LAST_VINAL +SPLACTION_LAST_QUARTER +SPLACTION_LAST_SOLAR_YEAR +SPLACTION_LAST_SIDEREAL_YEAR + +</SECTION> + diff --git a/docs/reference/tmpl/Internal.sgml b/docs/reference/tmpl/Internal.sgml new file mode 100644 index 0000000..5bae25a --- /dev/null +++ b/docs/reference/tmpl/Internal.sgml @@ -0,0 +1,19 @@ +<!-- ##### SECTION Title ##### --> +Internal + +<!-- ##### SECTION Short_Description ##### --> +Symbols to be hidden ;) + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + diff --git a/docs/reference/tmpl/artwork.sgml b/docs/reference/tmpl/artwork.sgml new file mode 100644 index 0000000..a7ce2a5 --- /dev/null +++ b/docs/reference/tmpl/artwork.sgml @@ -0,0 +1,160 @@ +<!-- ##### SECTION Title ##### --> +Artwork + +<!-- ##### SECTION Short_Description ##### --> +Data structure to store iPod artwork (cover and photos) + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### STRUCT Itdb_Artwork ##### --> +<para> + +</para> + +@thumbnails: +@artwork_size: +@id: + +<!-- ##### STRUCT Itdb_Thumb ##### --> +<para> + +</para> + +@type: +@filename: +@offset: +@size: +@width: +@height: + +<!-- ##### 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: + +<!-- ##### FUNCTION itdb_artwork_new ##### --> +<para> + +</para> + +@Returns: + + +<!-- ##### FUNCTION itdb_artwork_duplicate ##### --> +<para> + +</para> + +@artwork: +@Returns: + + +<!-- ##### FUNCTION itdb_artwork_free ##### --> +<para> + +</para> + +@artwork: + + +<!-- ##### FUNCTION itdb_artwork_add_thumbnail ##### --> +<para> + +</para> + +@artwork: +@type: +@filename: +@Returns: + + +<!-- ##### FUNCTION itdb_artwork_remove_thumbnail ##### --> +<para> + +</para> + +@artwork: +@thumb: + + +<!-- ##### FUNCTION itdb_artwork_remove_thumbnails ##### --> +<para> + +</para> + +@artwork: + + +<!-- ##### FUNCTION itdb_artwork_get_thumb_by_type ##### --> +<para> + +</para> + +@artwork: +@type: +@Returns: + + +<!-- ##### FUNCTION itdb_thumb_get_gdk_pixbuf ##### --> +<para> + +</para> + +@device: +@thumb: +@Returns: + + +<!-- ##### FUNCTION itdb_thumb_duplicate ##### --> +<para> + +</para> + +@thumb: +@Returns: + + +<!-- ##### FUNCTION itdb_thumb_free ##### --> +<para> + +</para> + +@thumb: + + +<!-- ##### FUNCTION itdb_thumb_new ##### --> +<para> + +</para> + +@Returns: + + +<!-- ##### FUNCTION itdb_thumb_get_filename ##### --> +<para> + +</para> + +@device: +@thumb: +@Returns: + + diff --git a/docs/reference/tmpl/device.sgml b/docs/reference/tmpl/device.sgml new file mode 100644 index 0000000..07090ed --- /dev/null +++ b/docs/reference/tmpl/device.sgml @@ -0,0 +1,129 @@ +<!-- ##### SECTION Title ##### --> +Device + +<!-- ##### SECTION Short_Description ##### --> +Data structure holding information about the iPod (model, mount point, ...) + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### STRUCT Itdb_Device ##### --> +<para> + +</para> + +@mountpoint: +@musicdirs: +@byte_order: +@endianess_reversed: + +<!-- ##### FUNCTION itdb_device_new ##### --> +<para> + +</para> + +@Returns: + + +<!-- ##### FUNCTION itdb_device_free ##### --> +<para> + +</para> + +@device: + + +<!-- ##### FUNCTION itdb_device_set_mountpoint ##### --> +<para> + +</para> + +@device: +@mp: + + +<!-- ##### FUNCTION itdb_device_read_sysinfo ##### --> +<para> + +</para> + +@device: +@Returns: + + +<!-- ##### FUNCTION itdb_device_get_sysinfo ##### --> +<para> + +</para> + +@device: +@field: +@Returns: + + +<!-- ##### STRUCT Itdb_IpodModel ##### --> +<para> + +</para> + +@model_number: +@capacity: +@model_type: +@generation: + +<!-- ##### STRUCT Itdb_ArtworkFormat ##### --> +<para> + +</para> + +@type: +@width: +@height: +@correlation_id: + +<!-- ##### ENUM Itdb_Generation ##### --> +<para> + +</para> + +@UNKNOWN_GENERATION: +@FIRST_GENERATION: +@SECOND_GENERATION: +@THIRD_GENERATION: +@FOURTH_GENERATION: +@FIFTH_GENERATION: +@MOBILE_GENERATION: + +<!-- ##### ENUM Itdb_ModelType ##### --> +<para> + +</para> + +@MODEL_TYPE_INVALID: +@MODEL_TYPE_UNKNOWN: +@MODEL_TYPE_COLOR: +@MODEL_TYPE_COLOR_U2: +@MODEL_TYPE_REGULAR: +@MODEL_TYPE_REGULAR_U2: +@MODEL_TYPE_MINI: +@MODEL_TYPE_MINI_BLUE: +@MODEL_TYPE_MINI_PINK: +@MODEL_TYPE_MINI_GREEN: +@MODEL_TYPE_MINI_GOLD: +@MODEL_TYPE_SHUFFLE: +@MODEL_TYPE_NANO_WHITE: +@MODEL_TYPE_NANO_BLACK: +@MODEL_TYPE_VIDEO_WHITE: +@MODEL_TYPE_VIDEO_BLACK: +@MODEL_TYPE_MOBILE_1: + diff --git a/docs/reference/tmpl/itunesdb-copying.sgml b/docs/reference/tmpl/itunesdb-copying.sgml new file mode 100644 index 0000000..82bfe94 --- /dev/null +++ b/docs/reference/tmpl/itunesdb-copying.sgml @@ -0,0 +1,74 @@ +<!-- ##### SECTION Title ##### --> +File handling functions + +<!-- ##### SECTION Short_Description ##### --> +Functions to copy new files to the iPod + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### FUNCTION itdb_cp_track_to_ipod ##### --> +<para> + +</para> + +@track: +@filename: +@error: +@Returns: + + +<!-- ##### FUNCTION itdb_filename_fs2ipod ##### --> +<para> + +</para> + +@filename: + + +<!-- ##### FUNCTION itdb_filename_ipod2fs ##### --> +<para> + +</para> + +@ipod_file: + + +<!-- ##### FUNCTION itdb_filename_on_ipod ##### --> +<para> + +</para> + +@track: +@Returns: + + +<!-- ##### FUNCTION itdb_musicdirs_number ##### --> +<para> + +</para> + +@itdb: +@Returns: + + +<!-- ##### FUNCTION itdb_rename_files ##### --> +<para> + +</para> + +@mp: +@error: +@Returns: + + diff --git a/docs/reference/tmpl/itunesdb-db.sgml b/docs/reference/tmpl/itunesdb-db.sgml new file mode 100644 index 0000000..37fc775 --- /dev/null +++ b/docs/reference/tmpl/itunesdb-db.sgml @@ -0,0 +1,133 @@ +<!-- ##### SECTION Title ##### --> +iPod database reading/writing + +<!-- ##### SECTION Short_Description ##### --> +Functions to create, read, write the iPod database + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### STRUCT Itdb_iTunesDB ##### --> +<para> + +</para> + +@tracks: +@playlists: +@filename: +@device: +@version: +@id: +@usertype: +@userdata: +@userdata_duplicate: +@userdata_destroy: + +<!-- ##### USER_FUNCTION ItdbUserDataDestroyFunc ##### --> +<para> + +</para> + +@userdata: + + +<!-- ##### USER_FUNCTION ItdbUserDataDuplicateFunc ##### --> +<para> + +</para> + +@userdata: +@Returns: + + +<!-- ##### FUNCTION itdb_new ##### --> +<para> + +</para> + +@Returns: + + +<!-- ##### FUNCTION itdb_free ##### --> +<para> + +</para> + +@itdb: + + +<!-- ##### FUNCTION itdb_parse ##### --> +<para> + +</para> + +@mp: +@error: +@Returns: + + +<!-- ##### FUNCTION itdb_write ##### --> +<para> + +</para> + +@itdb: +@error: +@Returns: + + +<!-- ##### FUNCTION itdb_set_mountpoint ##### --> +<para> + +</para> + +@itdb: +@mp: + + +<!-- ##### FUNCTION itdb_get_mountpoint ##### --> +<para> + +</para> + +@itdb: +@Returns: + + +<!-- ##### FUNCTION itdb_tracks_number ##### --> +<para> + +</para> + +@itdb: +@Returns: + + +<!-- ##### FUNCTION itdb_tracks_number_nontransferred ##### --> +<para> + +</para> + +@itdb: +@Returns: + + +<!-- ##### FUNCTION itdb_playlists_number ##### --> +<para> + +</para> + +@itdb: +@Returns: + + diff --git a/docs/reference/tmpl/itunesdb-lowlevel.sgml b/docs/reference/tmpl/itunesdb-lowlevel.sgml new file mode 100644 index 0000000..b91b65c --- /dev/null +++ b/docs/reference/tmpl/itunesdb-lowlevel.sgml @@ -0,0 +1,164 @@ +<!-- ##### SECTION Title ##### --> +Low-level functions + +<!-- ##### SECTION Short_Description ##### --> +Low-level functions which shouldn't be needed in normal situations + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### FUNCTION itdb_get_control_dir ##### --> +<para> + +</para> + +@mountpoint: +@Returns: + + +<!-- ##### FUNCTION itdb_get_itunes_dir ##### --> +<para> + +</para> + +@mountpoint: +@Returns: + + +<!-- ##### FUNCTION itdb_get_music_dir ##### --> +<para> + +</para> + +@mountpoint: +@Returns: + + +<!-- ##### FUNCTION itdb_get_artwork_dir ##### --> +<para> + +</para> + +@mountpoint: +@Returns: + + +<!-- ##### FUNCTION itdb_get_device_dir ##### --> +<para> + +</para> + +@mountpoint: +@Returns: + + +<!-- ##### FUNCTION itdb_get_itunesdb_path ##### --> +<para> + +</para> + +@mountpoint: +@Returns: + + +<!-- ##### FUNCTION itdb_get_artworkdb_path ##### --> +<para> + +</para> + +@mountpoint: +@Returns: + + +<!-- ##### FUNCTION itdb_get_path ##### --> +<para> + +</para> + +@dir: +@file: +@Returns: + + +<!-- ##### FUNCTION itdb_resolve_path ##### --> +<para> + +</para> + +@root: +@components: +@Returns: + + +<!-- ##### FUNCTION itdb_shuffle_write ##### --> +<para> + +</para> + +@itdb: +@error: +@Returns: + + +<!-- ##### FUNCTION itdb_shuffle_write_file ##### --> +<para> + +</para> + +@itdb: +@filename: +@error: +@Returns: + + +<!-- ##### FUNCTION itdb_cp ##### --> +<para> + +</para> + +@from_file: +@to_file: +@error: +@Returns: + + +<!-- ##### FUNCTION itdb_parse_file ##### --> +<para> + +</para> + +@filename: +@error: +@Returns: + + +<!-- ##### FUNCTION itdb_write_file ##### --> +<para> + +</para> + +@itdb: +@filename: +@error: +@Returns: + + +<!-- ##### FUNCTION itdb_duplicate ##### --> +<para> + +</para> + +@itdb: +@Returns: + + diff --git a/docs/reference/tmpl/itunesdb-time.sgml b/docs/reference/tmpl/itunesdb-time.sgml new file mode 100644 index 0000000..d06849e --- /dev/null +++ b/docs/reference/tmpl/itunesdb-time.sgml @@ -0,0 +1,45 @@ +<!-- ##### SECTION Title ##### --> +Time handling + +<!-- ##### SECTION Short_Description ##### --> +Helper functions to convert between Epoch time and Mac (iPod) time + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### FUNCTION itdb_time_get_mac_time ##### --> +<para> + +</para> + +@Returns: + + +<!-- ##### FUNCTION itdb_time_mac_to_host ##### --> +<para> + +</para> + +@mactime: +@Returns: + + +<!-- ##### FUNCTION itdb_time_host_to_mac ##### --> +<para> + +</para> + +@time: +@Returns: + + diff --git a/docs/reference/tmpl/libgpod-unused.sgml b/docs/reference/tmpl/libgpod-unused.sgml new file mode 100644 index 0000000..6fd94dc --- /dev/null +++ b/docs/reference/tmpl/libgpod-unused.sgml @@ -0,0 +1,126 @@ +<!-- ##### SECTION ./tmpl/itunesdb.sgml:Long_Description ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/itunesdb.sgml:See_Also ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/itunesdb.sgml:Short_Description ##### --> +Main data structure to manipulate an iPod content (songs, playlists, ...) + + +<!-- ##### SECTION ./tmpl/itunesdb.sgml:Stability_Level ##### --> + + + +<!-- ##### SECTION ./tmpl/itunesdb.sgml:Title ##### --> +iTunesDB + + +<!-- ##### MACRO ITDB_FILE_ERROR ##### --> +<para> + +</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: + +<!-- ##### MACRO SPLACTION_LAST_FORTNIGHT ##### --> +<para> + +</para> + + +<!-- ##### MACRO SPLACTION_LAST_HOURS_VALUE ##### --> +<para> + +</para> + + +<!-- ##### MACRO SPLACTION_LAST_LUNARCYCLE_VALUE ##### --> +<para> + +</para> + + +<!-- ##### MACRO SPLACTION_LAST_MINUTES_VALUE ##### --> +<para> + +</para> + + +<!-- ##### MACRO SPLACTION_LAST_MOMENT ##### --> +<para> + +</para> + + +<!-- ##### MACRO SPLACTION_LAST_OSTENT ##### --> +<para> + +</para> + + +<!-- ##### MACRO SPLACTION_LAST_QUARTER ##### --> +<para> + +</para> + + +<!-- ##### MACRO SPLACTION_LAST_SIDEREAL_DAY ##### --> +<para> + +</para> + + +<!-- ##### MACRO SPLACTION_LAST_SIDEREAL_YEAR ##### --> +<para> + +</para> + + +<!-- ##### MACRO SPLACTION_LAST_SOLAR_YEAR ##### --> +<para> + +</para> + + +<!-- ##### MACRO SPLACTION_LAST_SWATCH_BEAT ##### --> +<para> + +</para> + + +<!-- ##### MACRO SPLACTION_LAST_VINAL ##### --> +<para> + +</para> + + +<!-- ##### MACRO SPLACTION_LAST_YEARS_VALUE ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION itdb_file_error_quark ##### --> +<para> + +</para> + +@Returns: + diff --git a/docs/reference/tmpl/playlists.sgml b/docs/reference/tmpl/playlists.sgml new file mode 100644 index 0000000..70395be --- /dev/null +++ b/docs/reference/tmpl/playlists.sgml @@ -0,0 +1,287 @@ +<!-- ##### SECTION Title ##### --> +Playlists + +<!-- ##### SECTION Short_Description ##### --> +Data structure to represent an iPod playlist + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### STRUCT Itdb_Playlist ##### --> +<para> + +</para> + +@itdb: +@name: +@type: +@flag1: +@flag2: +@flag3: +@num: +@members: +@is_spl: +@timestamp: +@id: +@mhodcount: +@libmhodcount: +@sortorder: +@podcastflag: +@splpref: +@splrules: +@usertype: +@userdata: +@userdata_duplicate: +@userdata_destroy: + +<!-- ##### ENUM ItdbPlaylistSortOrder ##### --> +<para> + +</para> + +@ITDB_PSO_MANUAL: +@ITDB_PSO_TITLE: +@ITDB_PSO_ALBUM: +@ITDB_PSO_ARTIST: +@ITDB_PSO_BIRATE: +@ITDB_PSO_GENRE: +@ITDB_PSO_FILETYPE: +@ITDB_PSO_TIME_MODIFIED: +@ITDB_PSO_TRACK_NR: +@ITDB_PSO_SIZE: +@ITDB_PSO_TIME: +@ITDB_PSO_YEAR: +@ITDB_PSO_SAMPLERATE: +@ITDB_PSO_COMMENT: +@ITDB_PSO_TIME_ADDED: +@ITDB_PSO_EQUALIZER: +@ITDB_PSO_COMPOSER: +@ITDB_PSO_PLAYCOUNT: +@ITDB_PSO_TIME_PLAYED: +@ITDB_PSO_CD_NR: +@ITDB_PSO_RATING: +@ITDB_PSO_RELEASE_DATE: +@ITDB_PSO_BPM: +@ITDB_PSO_GROUPING: +@ITDB_PSO_CATEGORY: +@ITDB_PSO_DESCRIPTION: + +<!-- ##### FUNCTION itdb_playlist_new ##### --> +<para> + +</para> + +@title: +@spl: +@Returns: + + +<!-- ##### FUNCTION itdb_playlist_free ##### --> +<para> + +</para> + +@pl: + + +<!-- ##### FUNCTION itdb_playlist_duplicate ##### --> +<para> + +</para> + +@pl: +@Returns: + + +<!-- ##### FUNCTION itdb_playlist_add ##### --> +<para> + +</para> + +@itdb: +@pl: +@pos: + + +<!-- ##### FUNCTION itdb_playlist_move ##### --> +<para> + +</para> + +@pl: +@pos: + + +<!-- ##### FUNCTION itdb_playlist_remove ##### --> +<para> + +</para> + +@pl: + + +<!-- ##### FUNCTION itdb_playlist_unlink ##### --> +<para> + +</para> + +@pl: + + +<!-- ##### FUNCTION itdb_playlist_add_track ##### --> +<para> + +</para> + +@pl: +@track: +@pos: + + +<!-- ##### FUNCTION itdb_playlist_remove_track ##### --> +<para> + +</para> + +@pl: +@track: + + +<!-- ##### FUNCTION itdb_playlist_contains_track ##### --> +<para> + +</para> + +@pl: +@track: +@Returns: + + +<!-- ##### FUNCTION itdb_playlist_contain_track_number ##### --> +<para> + +</para> + +@tr: +@Returns: + + +<!-- ##### FUNCTION itdb_playlist_tracks_number ##### --> +<para> + +</para> + +@pl: +@Returns: + + +<!-- ##### FUNCTION itdb_playlist_mpl ##### --> +<para> + +</para> + +@itdb: +@Returns: + + +<!-- ##### FUNCTION itdb_playlist_is_mpl ##### --> +<para> + +</para> + +@pl: +@Returns: + + +<!-- ##### FUNCTION itdb_playlist_set_mpl ##### --> +<para> + +</para> + +@pl: + + +<!-- ##### FUNCTION itdb_playlist_podcasts ##### --> +<para> + +</para> + +@itdb: +@Returns: + + +<!-- ##### FUNCTION itdb_playlist_is_podcasts ##### --> +<para> + +</para> + +@pl: +@Returns: + + +<!-- ##### FUNCTION itdb_playlist_set_podcasts ##### --> +<para> + +</para> + +@pl: + + +<!-- ##### FUNCTION itdb_playlist_exists ##### --> +<para> + +</para> + +@itdb: +@pl: +@Returns: + + +<!-- ##### FUNCTION itdb_playlist_by_id ##### --> +<para> + +</para> + +@itdb: +@id: +@Returns: + + +<!-- ##### FUNCTION itdb_playlist_by_nr ##### --> +<para> + +</para> + +@itdb: +@num: +@Returns: + + +<!-- ##### FUNCTION itdb_playlist_by_name ##### --> +<para> + +</para> + +@itdb: +@name: +@Returns: + + +<!-- ##### FUNCTION itdb_playlist_randomize ##### --> +<para> + +</para> + +@pl: + + diff --git a/docs/reference/tmpl/smart-playlists.sgml b/docs/reference/tmpl/smart-playlists.sgml new file mode 100644 index 0000000..d910ccd --- /dev/null +++ b/docs/reference/tmpl/smart-playlists.sgml @@ -0,0 +1,269 @@ +<!-- ##### SECTION Title ##### --> +Smart Playlists + +<!-- ##### SECTION Short_Description ##### --> +Data structures used to manipulate iPod smart playlists + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### STRUCT SPLPref ##### --> +<para> + +</para> + +@liveupdate: +@checkrules: +@checklimits: +@limittype: +@limitsort: +@limitvalue: +@matchcheckedonly: + +<!-- ##### STRUCT SPLRule ##### --> +<para> + +</para> + +@field: +@action: +@string: +@fromvalue: +@fromdate: +@fromunits: +@tovalue: +@todate: +@tounits: +@unk052: +@unk056: +@unk060: +@unk064: +@unk068: + +<!-- ##### STRUCT SPLRules ##### --> +<para> + +</para> + +@unk004: +@match_operator: +@rules: + +<!-- ##### ENUM SPLAction ##### --> +<para> + +</para> + +@SPLACTION_IS_INT: +@SPLACTION_IS_GREATER_THAN: +@SPLACTION_IS_LESS_THAN: +@SPLACTION_IS_IN_THE_RANGE: +@SPLACTION_IS_IN_THE_LAST: +@SPLACTION_IS_STRING: +@SPLACTION_CONTAINS: +@SPLACTION_STARTS_WITH: +@SPLACTION_ENDS_WITH: +@SPLACTION_IS_NOT_INT: +@SPLACTION_IS_NOT_GREATER_THAN: +@SPLACTION_IS_NOT_LESS_THAN: +@SPLACTION_IS_NOT_IN_THE_RANGE: +@SPLACTION_IS_NOT_IN_THE_LAST: +@SPLACTION_IS_NOT: +@SPLACTION_DOES_NOT_CONTAIN: +@SPLACTION_DOES_NOT_START_WITH: +@SPLACTION_DOES_NOT_END_WITH: + +<!-- ##### ENUM SPLFieldType ##### --> +<para> + +</para> + +@splft_string: +@splft_int: +@splft_boolean: +@splft_date: +@splft_playlist: +@splft_unknown: + +<!-- ##### ENUM SPLActionType ##### --> +<para> + +</para> + +@splat_string: +@splat_int: +@splat_date: +@splat_range_int: +@splat_range_date: +@splat_inthelast: +@splat_playlist: +@splat_none: +@splat_invalid: +@splat_unknown: + +<!-- ##### ENUM SPLField ##### --> +<para> + +</para> + +@SPLFIELD_SONG_NAME: +@SPLFIELD_ALBUM: +@SPLFIELD_ARTIST: +@SPLFIELD_BITRATE: +@SPLFIELD_SAMPLE_RATE: +@SPLFIELD_YEAR: +@SPLFIELD_GENRE: +@SPLFIELD_KIND: +@SPLFIELD_DATE_MODIFIED: +@SPLFIELD_TRACKNUMBER: +@SPLFIELD_SIZE: +@SPLFIELD_TIME: +@SPLFIELD_COMMENT: +@SPLFIELD_DATE_ADDED: +@SPLFIELD_COMPOSER: +@SPLFIELD_PLAYCOUNT: +@SPLFIELD_LAST_PLAYED: +@SPLFIELD_DISC_NUMBER: +@SPLFIELD_RATING: +@SPLFIELD_COMPILATION: +@SPLFIELD_BPM: +@SPLFIELD_GROUPING: +@SPLFIELD_PLAYLIST: + +<!-- ##### MACRO SPLDATE_IDENTIFIER ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SPL_MAXSTRINGLENGTH ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SPL_STRING_MAXLEN ##### --> +<para> + +</para> + + + +<!-- ##### FUNCTION itdb_splr_get_field_type ##### --> +<para> + +</para> + +@splr: +@Returns: + + +<!-- ##### FUNCTION itdb_splr_get_action_type ##### --> +<para> + +</para> + +@splr: +@Returns: + + +<!-- ##### FUNCTION itdb_splr_validate ##### --> +<para> + +</para> + +@splr: + + +<!-- ##### FUNCTION itdb_splr_remove ##### --> +<para> + +</para> + +@pl: +@splr: + + +<!-- ##### FUNCTION itdb_splr_new ##### --> +<para> + +</para> + +@Returns: + + +<!-- ##### FUNCTION itdb_splr_add ##### --> +<para> + +</para> + +@pl: +@splr: +@pos: + + +<!-- ##### FUNCTION itdb_splr_add_new ##### --> +<para> + +</para> + +@pl: +@pos: +@Returns: + + +<!-- ##### FUNCTION itdb_spl_copy_rules ##### --> +<para> + +</para> + +@dest: +@src: + + +<!-- ##### FUNCTION itdb_splr_eval ##### --> +<para> + +</para> + +@splr: +@track: +@Returns: + + +<!-- ##### FUNCTION itdb_spl_update ##### --> +<para> + +</para> + +@spl: + + +<!-- ##### FUNCTION itdb_spl_update_all ##### --> +<para> + +</para> + +@itdb: + + +<!-- ##### FUNCTION itdb_spl_update_live ##### --> +<para> + +</para> + +@itdb: + + diff --git a/docs/reference/tmpl/track.sgml b/docs/reference/tmpl/track.sgml new file mode 100644 index 0000000..a96c52f --- /dev/null +++ b/docs/reference/tmpl/track.sgml @@ -0,0 +1,232 @@ +<!-- ##### SECTION Title ##### --> +Tracks + +<!-- ##### SECTION Short_Description ##### --> +Data structure to store metadata about an iPod track + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### STRUCT Itdb_Track ##### --> +<para> + +</para> + +@itdb: +@title: +@ipod_path: +@album: +@artist: +@genre: +@filetype: +@comment: +@category: +@composer: +@grouping: +@description: +@podcasturl: +@podcastrss: +@chapterdata: +@subtitle: +@id: +@size: +@tracklen: +@cd_nr: +@cds: +@track_nr: +@tracks: +@bitrate: +@samplerate: +@samplerate_low: +@year: +@volume: +@soundcheck: +@time_added: +@time_played: +@time_modified: +@bookmark_time: +@rating: +@playcount: +@playcount2: +@recent_playcount: +@transferred: +@BPM: +@app_rating: +@type1: +@type2: +@compilation: +@starttime: +@stoptime: +@checked: +@dbid: +@drm_userid: +@visible: +@filetype_marker: +@artwork_count: +@artwork_size: +@samplerate2: +@unk126: +@unk132: +@time_released: +@unk144: +@unk146: +@unk148: +@unk152: +@unk156: +@unk160: +@has_artwork: +@flag2: +@flag3: +@flag4: +@dbid2: +@lyrics_flag: +@movie_flag: +@mark_unplayed: +@unk179: +@unk180: +@unk184: +@samplecount: +@unk192: +@unk196: +@unk200: +@unk204: +@unk208: +@unk212: +@unk216: +@unk220: +@unk224: +@unk228: +@unk232: +@unk236: +@unk240: +@chapterdata_raw: +@chapterdata_raw_length: +@artwork: +@usertype: +@userdata: +@userdata_duplicate: +@userdata_destroy: + +<!-- ##### FUNCTION itdb_track_new ##### --> +<para> + +</para> + +@Returns: + + +<!-- ##### FUNCTION itdb_track_free ##### --> +<para> + +</para> + +@track: + + +<!-- ##### FUNCTION itdb_track_add ##### --> +<para> + +</para> + +@itdb: +@track: +@pos: + + +<!-- ##### FUNCTION itdb_track_remove ##### --> +<para> + +</para> + +@track: + + +<!-- ##### FUNCTION itdb_track_unlink ##### --> +<para> + +</para> + +@track: + + +<!-- ##### FUNCTION itdb_track_duplicate ##### --> +<para> + +</para> + +@tr: +@Returns: + + +<!-- ##### FUNCTION itdb_track_by_id ##### --> +<para> + +</para> + +@itdb: +@id: +@Returns: + + +<!-- ##### FUNCTION itdb_track_id_tree_create ##### --> +<para> + +</para> + +@itdb: +@Returns: + + +<!-- ##### FUNCTION itdb_track_id_tree_destroy ##### --> +<para> + +</para> + +@idtree: + + +<!-- ##### FUNCTION itdb_track_id_tree_by_id ##### --> +<para> + +</para> + +@idtree: +@id: +@Returns: + + +<!-- ##### FUNCTION itdb_track_set_thumbnails ##### --> +<para> + +</para> + +@track: +@filename: +@Returns: + + +<!-- ##### FUNCTION itdb_track_remove_thumbnails ##### --> +<para> + +</para> + +@track: + + +<!-- ##### MACRO ITDB_RATING_STEP ##### --> +<para> + +</para> + + + diff --git a/docs/reference/version.xml.in b/docs/reference/version.xml.in new file mode 100644 index 0000000..0426cae --- /dev/null +++ b/docs/reference/version.xml.in @@ -0,0 +1,4 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<phrase>@LIBGPOD_VERSION@</phrase> diff --git a/src/itdb_artwork.c b/src/itdb_artwork.c index 94b08b6..3c7d9d9 100644 --- a/src/itdb_artwork.c +++ b/src/itdb_artwork.c @@ -40,14 +40,26 @@ #endif #include <glib/gi18n-lib.h> - +/** + * itdb_artwork_new: + * + * Creates a new #Itdb_Artwork + * + * Return value: a new #Itdb_Artwork to be freed with itdb_artwork_free() when + * no longer needed + **/ Itdb_Artwork *itdb_artwork_new (void) { Itdb_Artwork *artwork = g_new0 (Itdb_Artwork, 1); return artwork; } - +/** + * itdb_artwork_free: + * @artwork: an #Itdb_Artwork + * + * Frees memory used by @artwork + **/ void itdb_artwork_free (Itdb_Artwork *artwork) { g_return_if_fail (artwork); @@ -78,6 +90,14 @@ static GList *dup_thumbnails (GList *thumbnails) return g_list_reverse (result); } +/** + * itdb_artwork_duplicate: + * @artwork: an #Itdb_Artwork + * + * Duplicates @artwork + * + * Return value: a new copy of @artwork + **/ Itdb_Artwork *itdb_artwork_duplicate (Itdb_Artwork *artwork) { Itdb_Artwork *dup; @@ -93,7 +113,13 @@ Itdb_Artwork *itdb_artwork_duplicate (Itdb_Artwork *artwork) } -/* Remove @thumb in @artwork */ +/** + * itdb_artwork_remove_thumbnail: + * @artwork: an #Itdb_Artwork + * @thumb: an #Itdb_Thumb + * + * Removes @thumb from @artwork. The memory used by @thumb isn't freed. + **/ void itdb_artwork_remove_thumbnail (Itdb_Artwork *artwork, Itdb_Thumb *thumb) { @@ -104,7 +130,12 @@ itdb_artwork_remove_thumbnail (Itdb_Artwork *artwork, Itdb_Thumb *thumb) } -/* Remove all thumbnails in @artwork */ +/** + * itdb_artwork_remove_thumbnails: + * @artwork: an #Itdb_Artwork + * + * Removes all thumbnails from @artwork + **/ void itdb_artwork_remove_thumbnails (Itdb_Artwork *artwork) { @@ -123,7 +154,19 @@ itdb_artwork_remove_thumbnails (Itdb_Artwork *artwork) -/* Append thumbnail of type @type to existing thumbnails in @artwork */ +/** + * itdb_artwork_add_thumbnail + * @artwork: an #Itdb_Thumbnail + * @type: thumbnail size + * @filename: image file to use to create the thumbnail + * + * 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. + * + * Return value: TRUE if the thumbnail could be successfully added, FALSE + * otherwise + **/ gboolean itdb_artwork_add_thumbnail (Itdb_Artwork *artwork, ItdbThumbType type, @@ -155,8 +198,16 @@ itdb_artwork_add_thumbnail (Itdb_Artwork *artwork, } -/* Return a pointer to the Itdb_Thumb of type @type or NULL when it - * does not exist */ +/** + * itdb_artwork_get_thumb_by_type: + * @artwork: an #Itdb_Artwork + * @type: type of the #Itdb_Thumb to retrieve + * + * Searches @artwork for an #Itdb_Thumb of type @type. + * + * Returns: an #Itdb_Thumb of type @type, or NULL if such a thumbnail couldn't + * be found + **/ Itdb_Thumb *itdb_artwork_get_thumb_by_type (Itdb_Artwork *artwork, ItdbThumbType type) { @@ -174,11 +225,18 @@ Itdb_Thumb *itdb_artwork_get_thumb_by_type (Itdb_Artwork *artwork, } -/* 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. - g_free() when not needed any more. -*/ +/** + * itdb_thumb_get_filename: + * @device: an #Itdb_Device + * @thumb: an #Itdb_Thumb + * + * 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 + * thumbnail file. + **/ gchar *itdb_thumb_get_filename (Itdb_Device *device, Itdb_Thumb *thumb) { gchar *artwork_dir, *filename=NULL; @@ -332,13 +390,20 @@ itdb_thumb_get_rgb_data (Itdb_Device *device, Itdb_Thumb *thumb) -/* Convert the pixeldata in @thumb to a GdkPixbuf. - Since we want to have gdk-pixbuf dependency optional, a generic - gpointer is returned which you have to cast to (GdkPixbuf *) - yourself. If gdk-pixbuf is not installed the NULL pointer is - returned. - The returned GdkPixbuf must be freed with gdk_pixbuf_unref() after - use. */ +/** + * itdb_thumb_get_gdk_pixbuf: + * @device: an #Itdb_Device + * @thumb: an #Itdb_Thumb + * + * Converts @thumb to a #GdkPixbuf. + * 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. + * + * Return value: 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. + **/ gpointer itdb_thumb_get_gdk_pixbuf (Itdb_Device *device, Itdb_Thumb *thumb) { @@ -448,14 +513,26 @@ itdb_thumb_get_gdk_pixbuf (Itdb_Device *device, Itdb_Thumb *thumb) #endif } - +/** + * itdb_thumb_new: + * + * Creates a new #Itdb_Thumb + * + * Return Value: newly allocated #Itdb_Thumb to be freed with itdb_thumb_free() + * after use + **/ Itdb_Thumb *itdb_thumb_new (void) { Itdb_Thumb *thumb = g_new0 (Itdb_Thumb, 1); return thumb; } - +/** + * itdb_thumb_free: + * @thumb: an #Itdb_Thumb + * + * Frees the memory used by @thumb + **/ void itdb_thumb_free (Itdb_Thumb *thumb) { g_return_if_fail (thumb); @@ -464,6 +541,16 @@ void itdb_thumb_free (Itdb_Thumb *thumb) g_free (thumb); } + +/** + * itdb_thumb_duplicate: + * @thumb: an #Itdb_Thumb + * + * Duplicates the data contained in @thumb + * + * Return value: a newly allocated copy of @thumb to be freed with + * itdb_thumb_free() after use + **/ Itdb_Thumb *itdb_thumb_duplicate (Itdb_Thumb *thumb) { Itdb_Thumb *new_thumb; diff --git a/src/itdb_device.c b/src/itdb_device.c index f8812e9..f475be3 100644 --- a/src/itdb_device.c +++ b/src/itdb_device.c @@ -228,7 +228,14 @@ static void itdb_device_reset_sysinfo (Itdb_Device *device) } -/* Create new Itdb_Device structure */ +/** + * itdb_device_new: + * + * Creates a new #Itdb_Device structure + * + * Return value: a newly allocated #Itdb_Device which must be freed with + * itdb_device_free() when no longer needed + **/ Itdb_Device *itdb_device_new () { Itdb_Device *dev; @@ -238,7 +245,12 @@ Itdb_Device *itdb_device_new () return dev; } -/* Free memory used by @device */ +/** + * itdb_device_free: + * @device: an #Itdb_Device + * + * Frees memory used by @device + **/ void itdb_device_free (Itdb_Device *device) { if (device) @@ -251,7 +263,14 @@ void itdb_device_free (Itdb_Device *device) } -/* Set mountpoint and read SysInfo file */ +/** + * itdb_device_set_mountpoint: + * @device: an #Itdb_Device + * @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) + **/ void itdb_device_set_mountpoint (Itdb_Device *device, const gchar *mp) { g_return_if_fail (device); @@ -263,10 +282,15 @@ void itdb_device_set_mountpoint (Itdb_Device *device, const gchar *mp) } -/* Read SysInfo file and store information in device->sysinfo for +/** + * itdb_device_read_sysinfo: + * @device: an #Itdb_Device + * + * Reads the SysInfo file and stores information in device->sysinfo for * later use. * - * Return value: TRUE if file could be read, FALSE otherwise */ + * Return value: TRUE if file could be read, FALSE otherwise + **/ gboolean itdb_device_read_sysinfo (Itdb_Device *device) { const gchar *p_sysinfo[] = {"SysInfo", NULL}; @@ -325,10 +349,16 @@ gboolean itdb_device_read_sysinfo (Itdb_Device *device) } -/* Retrieve specified field from the SysInfo file. +/** + * itdb_device_get_sysinfo: + * @device: an #Itdb_Device + * @field: field to retrive information from * - * Return value: g_free() after use - */ + * Retrieve specified field from the SysInfo file. + * + * Return value: the information associated with @field, or NULL if @field + * couldn't be found. g_free() after use + **/ gchar *itdb_device_get_sysinfo (Itdb_Device *device, const gchar *field) { g_return_val_if_fail (device, NULL); diff --git a/src/itdb_itunesdb.c b/src/itdb_itunesdb.c index 0665d7c..b35565e 100644 --- a/src/itdb_itunesdb.c +++ b/src/itdb_itunesdb.c @@ -261,12 +261,17 @@ static void fcontents_free (FContents *cts) component of the filename. If we can find such a match, we return it. Otherwise, we return NULL.*/ -/* 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 +/** + * itdb_resolve_path: + * @root: in local encoding + * @components: in utf8 + * + * 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 * 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. @root: in local encoding, - * @components: in utf8 */ + * Otherwise, we quit and return NULL. + **/ gchar * itdb_resolve_path (const gchar *root, const gchar * const * components) { @@ -1044,7 +1049,12 @@ static void itdb_free_fimp (FImport *fimp) } } -/* Free the memory taken by @itdb. */ +/** + * itdb_free: + * @itdb: an #Itdb_iTunesDB + * + * Free the memory taken by @itdb. + **/ void itdb_free (Itdb_iTunesDB *itdb) { if (itdb) @@ -1063,8 +1073,15 @@ void itdb_free (Itdb_iTunesDB *itdb) } } -/* Duplicate @itdb */ -/* FIXME: not implemented yet */ +/** + * itdb_duplicate: + * @itdb: an #Itdb_iTunesDB + * + * Duplicate @itdb + * FIXME: not implemented yet + * + * Return value: always return NULL since it's unimplemented + **/ Itdb_iTunesDB *itdb_duplicate (Itdb_iTunesDB *itdb) { g_return_val_if_fail (itdb, NULL); @@ -1072,7 +1089,15 @@ Itdb_iTunesDB *itdb_duplicate (Itdb_iTunesDB *itdb) g_return_val_if_reached (NULL); } -/* return number of playlists */ +/** + * itdb_playlists_number: + * @itdb: an #Itdb_iTunesDB + * + * Counts the number of playlists stored in @itdb + * + * Return value: the number of playlists in @itdb (including the master + * playlist) + **/ guint32 itdb_playlists_number (Itdb_iTunesDB *itdb) { g_return_val_if_fail (itdb, 0); @@ -1081,7 +1106,14 @@ guint32 itdb_playlists_number (Itdb_iTunesDB *itdb) } -/* return total number of tracks */ +/** + * itdb_tracks_number: + * @itdb: an #Itdb_iTunesDB + * + * Counts the number of tracks stored in @itdb + * + * Return value: the number of tracks in @itdb + **/ guint32 itdb_tracks_number (Itdb_iTunesDB *itdb) { g_return_val_if_fail (itdb, 0); @@ -1089,7 +1121,16 @@ guint32 itdb_tracks_number (Itdb_iTunesDB *itdb) return g_list_length (itdb->tracks); } - +/** + * itdb_tracks_number_nontransferred: + * @itdb: an #Itdb_iTunesDB + * + * Counts the number of non-transferred tracks in @itdb + * + * Return value: 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; @@ -1107,8 +1148,15 @@ guint32 itdb_tracks_number_nontransferred (Itdb_iTunesDB *itdb) -/* Creates a new Itdb_iTunesDB with the unknowns filled in to reasonable - values */ +/** + * itdb_new: + * + * 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() + * when it's no longer needed + **/ Itdb_iTunesDB *itdb_new (void) { static GOnce g_type_init_once = G_ONCE_INIT; @@ -2617,11 +2665,18 @@ static void error_no_control_dir (const gchar *mp, GError **error) } #endif -/* Parse the Itdb_iTunesDB. - Returns a pointer to the Itdb_iTunesDB struct holding the tracks and the - playlists. - "mp" should point to the mount point of the iPod, - e.g. "/mnt/ipod" and be in local encoding */ +/** + * itdb_parse: + * @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 + * 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; @@ -2686,7 +2741,18 @@ Itdb_iTunesDB *itdb_parse (const gchar *mp, GError **error) } -/* Same as itunesdb_parse(), but filename is specified directly. */ +/** + * itdb_parse_file: + * @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 + * 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_file (const gchar *filename, GError **error) { FImport *fimp; @@ -4101,9 +4167,17 @@ static void reassign_ids (FExport *fexp) } - -/* Do the actual writing to the iTunesDB */ -/* If @filename==NULL, itdb->filename is tried */ +/** + * itdb_write_file: + * @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. + * + * Return value: TRUE if all went well, FALSE otherwise + **/ gboolean itdb_write_file (Itdb_iTunesDB *itdb, const gchar *filename, GError **error) { @@ -4177,19 +4251,20 @@ gboolean itdb_write_file (Itdb_iTunesDB *itdb, const gchar *filename, return result; } -/* Write out an iTunesDB. - - 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. - - Returns TRUE on success, FALSE on error, in which case @error is - set accordingly. -*/ +/** + * itdb_write: + * @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 + * the export was successful. + * An existing "OTGPlaylistInfo" file is removed if the export was + * successful. + * + * Return value: 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; @@ -4335,23 +4410,23 @@ All integers in the iTunesSD file are in BIG endian form... */ -/* 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. - - Returns TRUE on success, FALSE on error, in which case @error is - set accordingly. - - itdb->mountpoint must point to the mount point of the iPod, - e.g. "/mnt/ipod" and be in local encoding. */ - - +/** + * itdb_shuffle_write: + * @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 + * set accordingly. + **/ gboolean itdb_shuffle_write (Itdb_iTunesDB *itdb, GError **error) { gchar *itunes_filename, *itunes_path; @@ -4393,8 +4468,17 @@ gboolean itdb_shuffle_write (Itdb_iTunesDB *itdb, GError **error) } -/* Do the actual writing to the iTunesSD */ -/* If @filename cannot be NULL */ +/** + * 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 + * + * Do the actual writing to the iTuneSsD + * + * Return value: 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) { @@ -4531,11 +4615,18 @@ gboolean itdb_shuffle_write_file (Itdb_iTunesDB *itdb, \*------------------------------------------------------------------*/ -/* (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. */ -/* Returns FALSE on error and sets @error accordingly */ +/** + * itdb_rename_files: + * @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 + **/ gboolean itdb_rename_files (const gchar *mp, GError **error) { const gchar *db_plc_o[] = {"Play Counts", NULL}; @@ -4623,17 +4714,27 @@ gboolean itdb_rename_files (const gchar *mp, GError **error) } -/* Convert string from casual PC file name to iPod iTunesDB format - * using ':' instead of slashes - */ +/** + * itdb_filename_fs2ipod: + * @filename: a filename 'PC-style' (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. + **/ void itdb_filename_fs2ipod (gchar *ipod_file) { g_strdelimit (ipod_file, G_DIR_SEPARATOR_S, ':'); } -/* Convert string from iPod iTunesDB format to casual PC file name - * using slashes instead of ':' - */ +/** + * itdb_filename_ipod2fs: + * @ipod_file: a filename 'PC-style' (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. + **/ void itdb_filename_ipod2fs (gchar *ipod_file) { g_strdelimit (ipod_file, ":", G_DIR_SEPARATOR); @@ -4641,11 +4742,16 @@ void itdb_filename_ipod2fs (gchar *ipod_file) -/* Set the mountpoint. +/** + * itdb_set_mountpoint: + * @itdb: an #Itdb_iTunesDB + * @mp: new mount point * - * Always use this function to set the mountpoint as it will reset the - * number of available /iPod_Control/Music/F.. dirs -*/ + * 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 + **/ void itdb_set_mountpoint (Itdb_iTunesDB *itdb, const gchar *mp) { g_return_if_fail (itdb); @@ -4655,7 +4761,15 @@ void itdb_set_mountpoint (Itdb_iTunesDB *itdb, const gchar *mp) itdb->device->musicdirs = 0; } -/* Retrieve a reference to the mountpoint */ +/** + * itdb_get_mountpoint: + * @itdb: an #Itdb_iTunesDB + * + * Retrieve a reference to the mountpoint of @itdb + * + * Return value: the @itdb mountpoint, this string shouldn't be freed nor + * modified + **/ const gchar *itdb_get_mountpoint (Itdb_iTunesDB *itdb) { g_return_val_if_fail (itdb, NULL); @@ -4664,11 +4778,18 @@ const gchar *itdb_get_mountpoint (Itdb_iTunesDB *itdb) } -/* Determine the number of F.. directories in iPod_Control/Music. - - If itdb->musicdirs is already set, simply return the previously - determined number. Otherwise count the directories first and set - itdb->musicdirs. */ +/** + * itdb_musicdirs_number: + * @itdb: an #Itdb_iTunesDB + * + * Determine the number of F.. directories in iPod_Control/Music. + * + * If itdb->musicdirs is already set, simply return the previously + * determined number. Otherwise count the directories first and set + * itdb->musicdirs. + * + * Return value: max number of directories in iPod_Control/Music + **/ gint itdb_musicdirs_number (Itdb_iTunesDB *itdb) { g_return_val_if_fail (itdb, 0); @@ -4679,28 +4800,37 @@ gint itdb_musicdirs_number (Itdb_iTunesDB *itdb) -/* Copy one track to the iPod. The PC filename is @filename - and is taken literally. - - The mountpoint of the iPod (in local encoding) is expected in - track->itdb->mountpoint. - - 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 - cycled through. - - The filename is constructed as "gtkpod"<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 - instead. If a file with this name already exists, it will be - overwritten. - - @track->filetype_marker is set according to the filename extension - */ +/** + * 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 + * + * Copy one track to the iPod. The PC filename is @filename + * and is taken literally. + * + * The mountpoint of the iPod (in local encoding) is expected in + * track->itdb->mountpoint. + * + * 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 + * cycled through. + * + * The filename is constructed as "gtkpod"<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 + * instead. If a file with this name already exists, it will be + * overwritten. + * + * @track->filetype_marker is set according to the filename extension + * + * Return value: TRUE on success, FALSE on error, in which case @error is + * set accordingly. + **/ gboolean itdb_cp_track_to_ipod (Itdb_Track *track, gchar *filename, GError **error) { @@ -4853,22 +4983,22 @@ gboolean itdb_cp_track_to_ipod (Itdb_Track *track, } -/* Return the full iPod filename as stored in @track. Return value - must be g_free()d after use. - - mount point of the iPod file system (in local encoding) is expected - in track->itdb->mountpoint - - @track: track - Return value: full filename to @track on the iPod or NULL if no - filename is set in @track. - - NOTE: NULL is returned when the file does not exist. - - 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 */ +/** + * itdb_filename_on_ipod: + * @track: an #Itdb_Track + * + * Return the full iPod filename as stored in @track. + * + * NOTE: NULL is returned when the file does not exist. + * + * 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 + * + * Return value: 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; @@ -4899,8 +5029,17 @@ gchar *itdb_filename_on_ipod (Itdb_Track *track) } -/* Copy file "from_file" to "to_file". - Returns TRUE on success, FALSE otherwise */ +/** + * itdb_cp: + * @from_file: source file + * @to_file: destination file + * @error: return location for a #GError or NULL + * + * Copy file "from_file" to "to_file". + * + * Return value: 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) { @@ -5009,18 +5148,17 @@ gboolean itdb_cp (const gchar *from_file, const gchar *to_file, -/* Get the i*_Control directory. Observed values are 'iPod_Control' +/** + * itdb_get_control_dir: + * @mountpoint: the iPod mountpoint + * + * Get the i*_Control directory. Observed values are 'iPod_Control' * for standard iPods and 'iTunes/iTunes_Control' for mobile * applications. * - * Parameters: @mountpoint: mountpoint of iPod - * (itdb->mountpoint). Note: I chose to pass the mountoint over - * passing a pointer to the itdb because this function may be used - * without relation to a particular itdb. - * * Return value: path to the control dir or NULL of non-existent. Must * g_free() after use. - */ + **/ gchar *itdb_get_control_dir (const gchar *mountpoint) { gchar *p_ipod[] = {"iPod_Control", NULL}; @@ -5040,12 +5178,17 @@ gchar *itdb_get_control_dir (const gchar *mountpoint) return result; } -/* Retrieve the directory @dir by first calling itdb_get_control_dir() +/** + * itdb_get_dir: + * mountpoint: the iPod mountpoint + * 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() * after use. - */ + **/ static gchar *itdb_get_dir (const gchar *mountpoint, const gchar *dir) { gchar *control_dir; @@ -5065,10 +5208,16 @@ static gchar *itdb_get_dir (const gchar *mountpoint, const gchar *dir) return result; } -/* Retrieve a path to the @file in @dir +/** + * itdb_get_path: + * @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. - */ + * Return value: path to the @file or NULL if non-existent. Must be g_free()'d + * after use. + **/ gchar *itdb_get_path (const gchar *dir, const gchar *file) { const gchar *p_file[] = {NULL, NULL}; @@ -5080,12 +5229,16 @@ gchar *itdb_get_path (const gchar *dir, const gchar *file) return itdb_resolve_path (dir, p_file); } -/* Retrieve the iTunes directory (containing the iTunesDB) by first +/** + * itdb_get_itunes_dir: + * @mountpoint: the iPod mountpoint + * + * 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 of non-existent. * Must g_free() after use. - */ + **/ gchar *itdb_get_itunes_dir (const gchar *mountpoint) { g_return_val_if_fail (mountpoint, NULL); @@ -5093,12 +5246,16 @@ gchar *itdb_get_itunes_dir (const gchar *mountpoint) return itdb_get_dir (mountpoint, "iTunes"); } -/* Retrieve the Music directory (containing the Fnn dirs) by first +/** + * itdb_get_music_dir: + * @mountpoint: the iPod 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 of * non-existent. Must g_free() after use. - */ + **/ gchar *itdb_get_music_dir (const gchar *mountpoint) { g_return_val_if_fail (mountpoint, NULL); @@ -5106,12 +5263,16 @@ gchar *itdb_get_music_dir (const gchar *mountpoint) return itdb_get_dir (mountpoint, "Music"); } -/* Retrieve the Device directory (containing the SysInfo file) by +/** + * itdb_get_device_dir: + * @mountpoint: the iPod 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 of * non-existent. Must g_free() after use. - */ + **/ gchar *itdb_get_device_dir (const gchar *mountpoint) { g_return_val_if_fail (mountpoint, NULL); @@ -5119,12 +5280,16 @@ gchar *itdb_get_device_dir (const gchar *mountpoint) return itdb_get_dir (mountpoint, "Device"); } -/* Retrieve the Artwork directory (containing the SysInfo file) by +/** + * itdb_get_artwork_dir: + * @mountpoint: the iPod mountpoint + * + * Retrieve the Artwork directory (containing the SysInfo file) by * first calling itdb_get_control_dir() and then adding 'Artwork' * * Return value: path to the Artwork directory or NULL of * non-existent. Must g_free() after use. - */ + **/ gchar *itdb_get_artwork_dir (const gchar *mountpoint) { g_return_val_if_fail (mountpoint, NULL); @@ -5132,10 +5297,15 @@ gchar *itdb_get_artwork_dir (const gchar *mountpoint) return itdb_get_dir (mountpoint, "Artwork"); } -/* Retrieve a path to the iTunesDB +/** + * itdb_get_itunesdb_path: + * @mountpoint: the iPod mountpoint + * + * Retrieve a path to the iTunesDB * - * Return value: path to the iTunesDB or NULL if non-existent. - */ + * Return value: path to the iTunesDB or NULL if non-existent. Must g_free() + * after use. + **/ gchar *itdb_get_itunesdb_path (const gchar *mountpoint) { gchar *itunes_dir, *path=NULL; @@ -5153,10 +5323,15 @@ gchar *itdb_get_itunesdb_path (const gchar *mountpoint) return path; } -/* Retrieve a path to the ArtworkDB +/** + * itdb_get_artworkdb_path: + * @mountpoint: the iPod mountpoint + * + * Retrieve a path to the ArtworkDB * - * Return value: path to the ArtworkDB or NULL if non-existent. - */ + * Return value: path to the ArtworkDB or NULL if non-existent. Must g_free() + * after use. + **/ gchar *itdb_get_artworkdb_path (const gchar *mountpoint) { gchar *itunes_dir, *path=NULL; @@ -5181,6 +5356,14 @@ gchar *itdb_get_artworkdb_path (const gchar *mountpoint) * * \*------------------------------------------------------------------*/ +/** + * itdb_time_get_mac_time: + * + * Gets the current time expressed in 'Mac' unit (ie in number of seconds since + * 1/1/1904). + * + * Return value: current time in 'Mac' unit. + **/ guint64 itdb_time_get_mac_time (void) { GTimeVal time; @@ -5190,10 +5373,17 @@ guint64 itdb_time_get_mac_time (void) } -/* convert Macintosh timestamp to host system time stamp -- modify +/** + * itdb_time_mac_to_host: + * @mactime: time expressed in 'Mac' unit + * + * Convert a Mac timestamp to host system time stamp -- modify * this function if necessary to port to host systems with different - * start of Epoch */ -/* A "0" time will not be converted */ + * start of Epoch. + * A "0" time will not be converted. + * + * Return value: timestamp for the host system + **/ time_t itdb_time_mac_to_host (guint64 mactime) { if (mactime != 0) return (time_t)(mactime - 2082844800); @@ -5201,9 +5391,16 @@ time_t itdb_time_mac_to_host (guint64 mactime) } -/* convert host system timestamp to Macintosh time stamp -- modify +/** + * itdb_time_host_to_mac: + * @time: time expressed in host unit + * + * Convert host system timestamp to Mac time stamp -- modify * this function if necessary to port to host systems with different - * start of Epoch */ + * start of Epoch + * + * Return value: a Mac timestamp + **/ guint64 itdb_time_host_to_mac (time_t time) { return (guint64)(((gint64)time) + 2082844800); diff --git a/src/itdb_playlist.c b/src/itdb_playlist.c index 89d77cb..4af2104 100644 --- a/src/itdb_playlist.c +++ b/src/itdb_playlist.c @@ -38,8 +38,15 @@ * for a complete copy of his original C++-classes. * */ -/* return TRUE if the smart playlist action @action is - known. Otherwise a warning is displayed and FALSE is returned. */ +/** + * itdb_spl_action_known: + * action: an #SPLAction + * + * 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. + **/ gboolean itdb_spl_action_known (SPLAction action) { gboolean result = FALSE; @@ -73,7 +80,15 @@ gboolean itdb_spl_action_known (SPLAction action) return result; } -/* return the logic type (string, int, date...) of the action field */ +/** + * itdb_splr_get_field_type: + * @splr: an #SPLRule + * + * Gets the type of the field of the @splr rule + * + * Return value: an #SPLFieldType corresponding to @splr field type + * (string, int, date, ...) + **/ SPLFieldType itdb_splr_get_field_type (const SPLRule *splr) { g_return_val_if_fail (splr != NULL, splft_unknown); @@ -114,7 +129,14 @@ SPLFieldType itdb_splr_get_field_type (const SPLRule *splr) } -/* return the type (range, date, string...) of the action field */ +/** + * itdb_splr_get_action_type: + * @splr: an #SPLRule + * + * Gets the type of the action associated with @splr. + * + * Return value: type (range, date, string...) of the action field + **/ SPLActionType itdb_splr_get_action_type (const SPLRule *splr) { SPLFieldType fieldType; @@ -268,8 +290,15 @@ SPLActionType itdb_splr_get_action_type (const SPLRule *splr) */ -/* function to evaluate a rule's truth against a track */ -/* track->itdb must be set. */ +/** + * itdb_splr_eval: + * @splr: an #SPLRule + * @track: an #Itdb_Track + * + * Evaluates @splr's truth against @track. track->itdb must be set. + * + * Return value: TRUE if @track matches @splr, FALSE otherwise. + **/ gboolean itdb_splr_eval (SPLRule *splr, Itdb_Track *track) { SPLFieldType ft; @@ -566,7 +595,12 @@ static GList *randomize_glist (GList *list) } -/* Randomizes a playlist */ +/** + * itdb_playlist_randomize: + * @pl: an #Itdb_Playlist to randomize + * + * Randomizes @pl + **/ void itdb_playlist_randomize (Itdb_Playlist *pl) { g_return_if_fail (pl); @@ -575,6 +609,15 @@ 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. + **/ void itdb_spl_update (Itdb_Playlist *spl) { GList *gl; @@ -790,7 +833,12 @@ void spl_update (Itdb_Playlist *playlist, gpointer data) } -/* update all smart playlists */ +/** + * itdb_spl_update_all: + * @itdb: an #Itdb_iTunesDB + * + * Updates all smart playlists contained in @itdb + **/ void itdb_spl_update_all (Itdb_iTunesDB *itdb) { g_return_if_fail (itdb); @@ -808,7 +856,13 @@ void spl_update2 (Itdb_Playlist *playlist, gpointer data) } -/* update all smart playlists with 'live updating' set*/ +/** + * 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 + **/ void itdb_spl_update_live (Itdb_iTunesDB *itdb) { g_return_if_fail (itdb); @@ -821,7 +875,12 @@ void itdb_spl_update_live (Itdb_iTunesDB *itdb) /* ------------------------------------------------------------------- */ -/* Validate a rule */ +/** + * itdb_splr_validate: + * @splr: an #SPLRule + * + * Validates a rule + **/ void itdb_splr_validate (SPLRule *splr) { SPLActionType at; @@ -873,7 +932,12 @@ void itdb_splr_validate (SPLRule *splr) } -/* Free memory of SPLRule @splr */ +/** + * itdb_splr_free: + * @splr: an #SPLRule + * + * Frees the memory used by @splr + **/ void itdb_splr_free (SPLRule *splr) { if (splr) @@ -883,7 +947,14 @@ void itdb_splr_free (SPLRule *splr) } } -/* remove @splr from playlist @pl */ +/** + * itdb_splr_remove: + * @pl: an #Itdb_Playlist + * @splr: an SPLRule + * + * Removes the smart playlist rule @splr from playlist @pl. The memory used by + * @splr is freed. + **/ void itdb_splr_remove (Itdb_Playlist *pl, SPLRule *splr) { g_return_if_fail (pl); @@ -893,7 +964,16 @@ void itdb_splr_remove (Itdb_Playlist *pl, SPLRule *splr) itdb_splr_free (splr); } -/* add smart rule @splr to playlist @pl at position @pos */ +/** + * itdb_splr_add: + * @pl: an #Itdb_Playlist + * @splr: an #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() + **/ void itdb_splr_add (Itdb_Playlist *pl, SPLRule *splr, gint pos) { g_return_if_fail (pl); @@ -904,7 +984,14 @@ void itdb_splr_add (Itdb_Playlist *pl, SPLRule *splr, gint pos) } -/* Create new default rule */ +/** + * itdb_splr_new: + * + * Creates a new default smart rule + * + * Return value: a new #SPLRule that must be freed with itdb_splr_free() when + * no longer needed + **/ SPLRule *itdb_splr_new (void) { SPLRule *splr = g_new0 (SPLRule, 1); @@ -922,8 +1009,17 @@ SPLRule *itdb_splr_new (void) } -/* create a new smart rule and insert it at position @pos of playlist - * @pl. A pointer to the newly created rule is returned. */ +/** + * itdb_splr_add_new: + * @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. + * + * Return value: pointer to the newly created #SPLRule. Its memory is handled + * by @pl though, so you don't need to explicitly call itdb_splr_free() on it + **/ SPLRule *itdb_splr_add_new (Itdb_Playlist *pl, gint pos) { SPLRule *splr; @@ -951,8 +1047,17 @@ static SPLRule *splr_duplicate (SPLRule *splr) } -/* Duplicate an existing playlist. pl_dup->id is set to zero, so that - * it will be set to a unique value when adding it to the itdb. */ +/** + * 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. + * + * Return value: 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; @@ -995,9 +1100,15 @@ Itdb_Playlist *itdb_playlist_duplicate (Itdb_Playlist *pl) } -/* copy all relevant information for smart playlist from playlist @src - to playlist @dest. Already available information is - overwritten/deleted. */ +/** + * itdb_spl_copy_rules: + * @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. + **/ void itdb_spl_copy_rules (Itdb_Playlist *dest, Itdb_Playlist *src) { GList *gl; @@ -1027,9 +1138,18 @@ void itdb_spl_copy_rules (Itdb_Playlist *dest, Itdb_Playlist *src) -/* Generate a new playlist structure. If @spl is TRUE, a smart - * playlist is generated. pl->id is set when adding to an itdb by - * itdb_playlist_add()*/ +/** + * 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 + * itdb_playlist_free() after use + **/ Itdb_Playlist *itdb_playlist_new (const gchar *title, gboolean spl) { Itdb_Playlist *pl = g_new0 (Itdb_Playlist, 1); @@ -1058,7 +1178,12 @@ Itdb_Playlist *itdb_playlist_new (const gchar *title, gboolean spl) } -/* Free the memory taken by playlist @pl. */ +/** + * itdb_playlist_free: + * @pl: an #Itdb_Playlist + * + * Frees the memory used by playlist @pl. + **/ void itdb_playlist_free (Itdb_Playlist *pl) { g_return_if_fail (pl); @@ -1074,10 +1199,17 @@ void itdb_playlist_free (Itdb_Playlist *pl) -/* add 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. */ -/* a critical message is logged if either itdb or pl is NULL */ +/** + * itdb_playlist_add: + * @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() + **/ void itdb_playlist_add (Itdb_iTunesDB *itdb, Itdb_Playlist *pl, gint32 pos) { g_return_if_fail (itdb); @@ -1115,7 +1247,13 @@ void itdb_playlist_add (Itdb_iTunesDB *itdb, Itdb_Playlist *pl, gint32 pos) -/* move playlist @pl to position @pos */ +/** + * itdb_playlist_move: + * @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; @@ -1129,7 +1267,13 @@ void itdb_playlist_move (Itdb_Playlist *pl, guint32 pos) } -/* Remove playlist @pl and free memory */ +/** + * itdb_playlist_remove: + * @pl: an #Itdb_Playlist + * + * Removes @pl from the #Itdb_iTunesDB it's associated with + * and frees memory + **/ void itdb_playlist_remove (Itdb_Playlist *pl) { Itdb_iTunesDB *itdb; @@ -1143,8 +1287,13 @@ void itdb_playlist_remove (Itdb_Playlist *pl) } -/* Remove playlist @pl but do not free memory */ -/* pl->itdb is set to NULL */ +/** + * 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 + **/ void itdb_playlist_unlink (Itdb_Playlist *pl) { Itdb_iTunesDB *itdb; @@ -1158,7 +1307,15 @@ void itdb_playlist_unlink (Itdb_Playlist *pl) } -/* Return TRUE if the playlist @pl exists, FALSE otherwise */ +/** + * itdb_playlist_exists: + * @itdb: an #Itdb_iTunesDB + * @pl: an #Itdb_Playlist + * + * Checks if @pl is present in @db + * + * Return value: TRUE if @pl exists in @db, FALSE otherwise + **/ gboolean itdb_playlist_exists (Itdb_iTunesDB *itdb, Itdb_Playlist *pl) { g_return_val_if_fail (itdb, FALSE); @@ -1169,10 +1326,15 @@ gboolean itdb_playlist_exists (Itdb_iTunesDB *itdb, Itdb_Playlist *pl) } -/* add @track to playlist @pl position @pos (-1 for "append to - * end") */ -/* a critical message is logged if either @itdb, @pl or @track is - NULL */ +/** + * itdb_playlist_add_track: + * @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") + **/ void itdb_playlist_add_track (Itdb_Playlist *pl, Itdb_Track *track, gint32 pos) { @@ -1188,8 +1350,16 @@ void itdb_playlist_add_track (Itdb_Playlist *pl, -/* Remove track @track from playlist *pl. If @pl == NULL remove from - * master playlist. */ +/** + * itdb_playlist_remove_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. + **/ void itdb_playlist_remove_track (Itdb_Playlist *pl, Itdb_Track *track) { g_return_if_fail (track); @@ -1203,8 +1373,16 @@ void itdb_playlist_remove_track (Itdb_Playlist *pl, Itdb_Track *track) } -/* Returns the playlist with the ID @id or NULL if the ID cannot be - * found. */ +/** + * itdb_playlist_by_id: + * @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. + **/ Itdb_Playlist *itdb_playlist_by_id (Itdb_iTunesDB *itdb, guint64 id) { GList *gl; @@ -1220,7 +1398,15 @@ Itdb_Playlist *itdb_playlist_by_id (Itdb_iTunesDB *itdb, guint64 id) } -/* Return playlist at position @num in @itdb */ +/** + * itdb_playlist_by_nr: + * @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 + **/ Itdb_Playlist *itdb_playlist_by_nr (Itdb_iTunesDB *itdb, guint32 num) { Itdb_Playlist *pl; @@ -1231,7 +1417,16 @@ Itdb_Playlist *itdb_playlist_by_nr (Itdb_iTunesDB *itdb, guint32 num) } -/* Return first playlist with name @name. */ +/** + * itdb_playlist_by_name: + * @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 + **/ Itdb_Playlist *itdb_playlist_by_name (Itdb_iTunesDB *itdb, gchar *name) { GList *gl; @@ -1249,7 +1444,14 @@ Itdb_Playlist *itdb_playlist_by_name (Itdb_iTunesDB *itdb, gchar *name) } -/* check if playlist is master playlist */ +/** + * itdb_playlist_is_mpl: + * @pl: an #Itdb_Playlist + * + * Checks if @pl is the master playlist + * + * Return value: TRUE if @pl is the master playlist, FALSE otherwise + **/ gboolean itdb_playlist_is_mpl (Itdb_Playlist *pl) { g_return_val_if_fail (pl, FALSE); @@ -1258,7 +1460,14 @@ gboolean itdb_playlist_is_mpl (Itdb_Playlist *pl) } -/* check if playlist is podcasts playlist */ +/** + * itdb_playlist_is_podcasts: + * @pl: an #Itdb_Playlist + * + * Checks if @pl is the podcasts playlist + * + * Return value: TRUE if @pl is the podcasts playlist, FALSE otherwise + **/ gboolean itdb_playlist_is_podcasts (Itdb_Playlist *pl) { g_return_val_if_fail (pl, FALSE); @@ -1267,7 +1476,12 @@ gboolean itdb_playlist_is_podcasts (Itdb_Playlist *pl) } -/* set playlist to MPL */ +/** + * itdb_playlist_set_mpl: + * @pl: an #Itdb_Playlist + * + * Sets @pl to be a master playlist + **/ void itdb_playlist_set_mpl (Itdb_Playlist *pl) { g_return_if_fail (pl); @@ -1276,7 +1490,12 @@ void itdb_playlist_set_mpl (Itdb_Playlist *pl) } -/* set playlist to Podcasts */ +/** + * itdb_playlist_set_podcasts: + * @pl: an #Itdb_Playlist + * + * Set @pl to be a podcasts playlist + **/ void itdb_playlist_set_podcasts (Itdb_Playlist *pl) { g_return_if_fail (pl); @@ -1285,7 +1504,14 @@ void itdb_playlist_set_podcasts (Itdb_Playlist *pl) } -/* return the master playlist of @itdb */ +/** + * itdb_playlist_mpl: + * @itdb: an #Itdb_iTunesDB + * + * Gets the master playlist of @itdb + * + * Return value: the master playlist of @itdb + **/ Itdb_Playlist *itdb_playlist_mpl (Itdb_iTunesDB *itdb) { Itdb_Playlist *pl; @@ -1302,7 +1528,14 @@ Itdb_Playlist *itdb_playlist_mpl (Itdb_iTunesDB *itdb) } -/* return the podcasts playlist of @itdb, if available */ +/** + * 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 + **/ Itdb_Playlist *itdb_playlist_podcasts (Itdb_iTunesDB *itdb) { GList *gl; @@ -1322,8 +1555,15 @@ Itdb_Playlist *itdb_playlist_podcasts (Itdb_iTunesDB *itdb) -/* checks if @track is in playlist @pl. TRUE, if yes, FALSE - otherwise. If @pl is NULL, the */ +/** + * itdb_playlist_contains_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 + **/ gboolean itdb_playlist_contains_track (Itdb_Playlist *pl, Itdb_Track *tr) { g_return_val_if_fail (tr, FALSE); @@ -1338,8 +1578,15 @@ gboolean itdb_playlist_contains_track (Itdb_Playlist *pl, Itdb_Track *tr) } -/* returns in how many playlists (other than the MPL) @track is a - member of */ +/** + * itdb_playlist_contain_track_number: + * @tr: an #Itdb_Track + * + * Counts the number of playlist @track is a member of (not including the + * master playlist) + * + * Return value: number of playlist containing @track + **/ guint32 itdb_playlist_contain_track_number (Itdb_Track *tr) { Itdb_iTunesDB *itdb; @@ -1363,7 +1610,14 @@ guint32 itdb_playlist_contain_track_number (Itdb_Track *tr) -/* return number of tracks in playlist */ +/** + * itdb_playlist_tracks_number: + * @pl: an #Itdb_Playlist + * + * Counts the number of tracks in @pl + * + * Return value: track count + **/ guint32 itdb_playlist_tracks_number (Itdb_Playlist *pl) { g_return_val_if_fail (pl, 0); diff --git a/src/itdb_track.c b/src/itdb_track.c index 51d0929..1e21866 100644 --- a/src/itdb_track.c +++ b/src/itdb_track.c @@ -51,7 +51,14 @@ static gboolean is_video_ipod (Itdb_Device *device) } -/* Generate a new Itdb_Track structure */ +/** + * itdb_track_new: + * + * Creates an empty #Itdb_Track + * + * Return Value: 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); @@ -206,9 +213,17 @@ static void itdb_track_set_defaults (Itdb_Track *tr) -/* Add @track to @itdb->tracks at position @pos (or at the end if pos - is -1). Application is responsible to also add it to the master - playlist. */ +/** + * itdb_track_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); @@ -223,7 +238,12 @@ void itdb_track_add (Itdb_iTunesDB *itdb, Itdb_Track *track, gint32 pos) else itdb->tracks = g_list_insert (itdb->tracks, track, pos); } -/* Free the memory taken by @track */ +/** + * itdb_track_free: + * @track: an #Itdb_Track + * + * Frees the memory used by @track + **/ void itdb_track_free (Itdb_Track *track) { g_return_if_fail (track); @@ -250,7 +270,14 @@ void itdb_track_free (Itdb_Track *track) g_free (track); } -/* Remove track @track and free memory */ +/** + * itdb_track_remove: + * @track: an #Itdb_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; @@ -263,8 +290,15 @@ void itdb_track_remove (Itdb_Track *track) itdb_track_free (track); } -/* Remove track @track but do not free memory */ -/* track->itdb is set to NULL */ +/** + * itdb_track_unlink: + * @track: an #Itdb_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. + **/ void itdb_track_unlink (Itdb_Track *track) { Itdb_iTunesDB *itdb; @@ -277,7 +311,14 @@ void itdb_track_unlink (Itdb_Track *track) track->itdb = NULL; } -/* Duplicate an existing track */ +/** + * itdb_track_duplicate: + * @tr: an #Itdb_Track + * + * Duplicates an existing track + * + * Return value: a newly allocated #Itdb_Track + **/ Itdb_Track *itdb_track_duplicate (Itdb_Track *tr) { Itdb_Track *tr_dup; @@ -325,6 +366,18 @@ Itdb_Track *itdb_track_duplicate (Itdb_Track *tr) } +/** + * itdb_track_set_thumbnails: + * @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 + * function is called. + * + * Return value: TRUE if the thumbnail could be added, FALSE otherwise. + **/ gboolean itdb_track_set_thumbnails (Itdb_Track *track, const gchar *filename) { @@ -365,7 +418,12 @@ gboolean itdb_track_set_thumbnails (Itdb_Track *track, return result; } - +/** + * itdb_track_remove_thumbnails: + * @track: an #Itdb_Track + * + * Removes the thumbnails associated with @track + **/ void itdb_track_remove_thumbnails (Itdb_Track *track) { g_return_if_fail (track); @@ -377,15 +435,23 @@ void itdb_track_remove_thumbnails (Itdb_Track *track) } -/* Returns the track with the ID @id or NULL if the ID cannot be - * found. */ -/* 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 -- if you need to lookup many IDs use - the functions itdb_track_id_tree_create(), - itdb_track_id_tree_destroy(), and itdb_track_id_tree_by_id() below. */ +/** + * itdb_track_by_id: + * @itdb: an #Itdb_iTunesDB + * @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 + * found. + **/ Itdb_Track *itdb_track_by_id (Itdb_iTunesDB *itdb, guint32 id) { GList *gl; @@ -410,8 +476,16 @@ static gint track_id_compare (gconstpointer a, gconstpointer b) } -/* Creates a balanced-binary tree for quick ID lookup that is used in - itdb_track_by_id_tree() function below */ +/** + * itdb_track_id_tree_create: + * @itdb: an #Itdb_iTunesDB + * + * Creates a balanced-binary tree for quick ID lookup that is used in + * itdb_track_by_id_tree() function below + * + * Return value: 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; @@ -430,7 +504,12 @@ GTree *itdb_track_id_tree_create (Itdb_iTunesDB *itdb) return idtree; } -/* free memory of @idtree */ +/** + * itdb_track_id_tree_destroy: + * @idtree: a #GTree + * + * Frees the memory used by @idtree + **/ void itdb_track_id_tree_destroy (GTree *idtree) { g_return_if_fail (idtree); @@ -438,7 +517,17 @@ void itdb_track_id_tree_destroy (GTree *idtree) g_tree_destroy (idtree); } -/* lookup track by @id using @idtree for quicker reference */ +/** + * 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 + * + * 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 + * couldn't be found + **/ Itdb_Track *itdb_track_id_tree_by_id (GTree *idtree, guint32 id) { g_return_val_if_fail (idtree, NULL); |