summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
Diffstat (limited to 'src')
-rw-r--r--src/itdb_artwork.c129
-rw-r--r--src/itdb_device.c46
-rw-r--r--src/itdb_itunesdb.c487
-rw-r--r--src/itdb_playlist.c364
-rw-r--r--src/itdb_track.c135
5 files changed, 909 insertions, 252 deletions
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-&gt;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-&gt;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-&gt;itdb-&gt;mountpoint.
+ *
+ * If @track-&gt;transferred is set to TRUE, nothing is done. Upon
+ * successful transfer @track-&gt;transferred is set to TRUE.
+ *
+ * For storage, the directories "f00 ... fnn" will be
+ * cycled through.
+ *
+ * The filename is constructed as "gtkpod"&lt;random number&gt; and copied
+ * to @track-&gt;ipod_path. If this file already exists, &lt;random number&gt;
+ * is adjusted until an unused filename is found.
+ *
+ * If @track-&gt;ipod_path is already set, this one will be used
+ * instead. If a file with this name already exists, it will be
+ * overwritten.
+ *
+ * @track-&gt;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-&gt;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-&gt;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-&gt;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-&gt;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-&gt;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);