diff options
Diffstat (limited to 'src')
| -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 |
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->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); |