struct iPodSong

struct iPodSong {

	gchar   *album;            /* album (utf8)          */
	gchar   *artist;           /* artist (utf8)         */
	gchar   *title;            /* title (utf8)          */
	gchar   *genre;            /* genre (utf8)          */
	gchar   *comment;          /* comment (utf8)        */
	gchar   *composer;         /* Composer (utf8)       */
	gchar   *fdesc;            /* ? (utf8)              */
	gchar   *ipod_path;        /* name of file on iPod: uses ":" instead of "/"*/
	gchar   *pc_path_utf8;     /* PC filename in utf8 encoding   */
	gchar   *pc_path_locale;   /* PC filename in locale encoding */
	guint32 ipod_id;           /* unique ID of track    */
	gint32  size;              /* size of file in bytes */
	gint32  oldsize;           /* used when updating tracks: size on iPod */
	gint32  tracklen;          /* Length of track in ms */
	gint32  cd_nr;             /* CD number             */
	gint32  cds;               /* number of CDs         */
	gint32  track_nr;          /* track number          */
	gint32  tracks;            /* number of tracks      */
	gint32  bitrate;           /* bitrate               */
	gint32  year;              /* year                  */
	gchar   *year_str;         /* year as string -- always identical to year */
	gint32  volume;            /* volume adjustment between -100 and +100    */
	guint32 time_played;       /* time of last play  (Mac type)              */
	guint32 time_modified;     /* time of last modification  (Mac type)      */
	guint32 rating;            /* star rating (stars * RATING_STEP (20))     */
	guint32 playcount;         /* number of times track was played           */
	guint32 recent_playcount;  /* times track was played since last sync     */
	gchar   *hostname;         /* name of host this file has been imported on*/
	gboolean transferred;      /* has file been transferred to iPod?         */
	gchar   *md5_hash;         /* md5 hash of file (or NULL)                 */
	gchar   *charset;          /* charset used for ID3 tags                  */
	/* FIXME: samplerate, start_time, stop_time are missing */
	/* FIXME: transparently handle conversions between mac time and unix time */
	guint ref_count;
};

ipod_song_new ()

iPodSong*   ipod_song_new                   (void);

Creates a new empty iPodSong.

ipod_song_ref ()

iPodSong*   ipod_song_ref                   (iPodSong *song);

Increases the reference count of song by 1.

ipod_song_unref ()

void        ipod_song_unref                 (iPodSong *song);

Decreases the reference count of song by 1. If it reaches 0, then song is destroyed (ie the memory it uses is freed).

ipod_song_dump ()

void        ipod_song_dump                  (iPodSong *song);

Pretty prints the content of song on stdout.

struct iPodPlaylist

struct iPodPlaylist {

	gchar *name;            /* name of playlist in UTF8 */
	guint32 type;           /* 1: master play list (PL_TYPE_MPL) */
	GList *songs;
	
	/* Private, used during loading of the database */
	GList *song_ids;
	guint ref_count;
};

ipod_playlist_new ()

iPodPlaylist* ipod_playlist_new             (const char *name);

Creates a new empty playlist whose name is name.

ipod_playlist_ref ()

iPodPlaylist* ipod_playlist_ref             (iPodPlaylist *playlist);

Increases the reference count of playlist by 1.

ipod_playlist_unref ()

void        ipod_playlist_unref             (iPodPlaylist *playlist);

Decreases the reference count of playlist by 1. If it reaches 0, then playlist is destroyed (ie the memory it uses is freed).

ipod_playlist_dump ()

void        ipod_playlist_dump              (iPodPlaylist *playlist);

Pretty prints the content of playlist on stdout.

struct iPodDB

struct iPodDB;

Opaque structure which represents the content of an iPod. It stores the mount point of the iPod associated with it, as well as all the songs and all the playlists stored on it. It lets you get information about those songs and playlists, add new ones, and remove existing one. You can then write your changes back to the iPod.

ipod_db_new ()

iPodDB*     ipod_db_new                     (const gchar *mount_point);

Creates a new empty iPodDB to handle the iPod mounted at mount_point. This function checks if mount_point corresponds to an actual iPod mount point, and it will fail if the given path doesn't look like one. If there is already an existing iPod database stored at mount_point, it won't be overwritten by the new database created using this function until ipod_db_write(- is called.

ipod_db_load ()

iPodDB*     ipod_db_load                    (const gchar *mount_point);

Creates a new iPodDB and initialize it with the content of the database present on the iPod mounted at mount_point. If there is no iPod database can be found at mount_point, an empty iPodDB is created.

ipod_db_save ()

gint        ipod_db_save                    (iPodDB *db);

Write a database file on the iPod corresponding to the information stored in db. WARNING: if this function returns an error, the iPod database may be damaged, and no backup files are currently created, so data losses can occur (a database may have to be recreated from scratch, and all the files may have to be readded to the iPod).

ipod_db_destroy ()

void        ipod_db_destroy                 (iPodDB *db);

Frees all the memory used by db. It also frees all the memory allocated for the iPodSong and iPodPlaylist it contains so make sure not to use any reference to those after calling this function.

ipod_db_add_song ()

int         ipod_db_add_song                (iPodDB *db,
                                             iPodSong *song);

Adds song to db content. It also adds the song to the master playlist. The file corresponding to song isn't copied to the iPod or anything, this must be handled separately. All this function does is to add song to the iPodDB so that the iPod database knows about song when db is synced to disk using ipod_db_save(). This function acquires its own reference to the song. If song is already known to db, ipod_db_add_song() reports failure.

ipod_db_get_songs ()

GList*      ipod_db_get_songs               (iPodDB *db);

Gets the list of all the songs available on the iPod corresponding to db.

ipod_db_add_song_to_playlist ()

int         ipod_db_add_song_to_playlist    (iPodDB *db,
                                             iPodPlaylist *playlist,
                                             iPodSong *song);

Adds song to playlist. If song or playlist are unknown to db, then ipod_db_add_song_to_playlist returns with a negative return value. The same thing happens if song is already present in playlist.

ipod_db_get_song_count ()

gint        ipod_db_get_song_count          (iPodDB *db);

Gets the number of songs stored in db.

ipod_db_add_playlist ()

int         ipod_db_add_playlist            (iPodDB *db,
                                             iPodPlaylist *playlist);

Adds playlist to db content. Nothing is changed on disk until ipod_db_sync() is called to update the database. This function acquires its own reference to the playlist, and to each song contained in the playlist.

ipod_db_get_playlists ()

GList*      ipod_db_get_playlists           (iPodDB *db);

Gets the list of all the playlists available on the iPod corresponding to db. This does not include the master playlist, if you want to get all the songs on the iPod, see ipod_db_get_songs().

ipod_db_get_playlist_count ()

gint        ipod_db_get_playlist_count      (iPodDB *db);

Gets the number of playlists stored in db including the master playlist. The master playlist always exists, it contains the list of all songs present in the database.

ipod_db_master_playlist_get_name ()

gchar*      ipod_db_master_playlist_get_name
                                            (iPodDB *db);

Gets the name of the iPod master playlist. The master playlist is a special playlist which contains a list of all the songs which will be displayed in the iPod user interface. Its name corresponds to the name of the iPod as displayed by iTunes for example.

ipod_db_master_playlist_set_name ()

void        ipod_db_master_playlist_set_name
                                            (iPodDB *db,
                                             const gchar *name);

Sets the name of the master playlist, see ipod_db_master_playlist_set_name() for more details about the master playlist.

ipod_db_get_mount_point ()

gchar*      ipod_db_get_mount_point         (iPodDB *db);

Gets the path where the iPod associated with the iPodDB is mounted.

ipod_path_to_unix_path ()

gchar*      ipod_path_to_unix_path          (const gchar *mount_point,
                                             const gchar *ipod_path);

The iPod references the files in contains using ':' as a dir separator, and its root directory (':') is obviously corresponding to the unix dir mount_point. This functions takes a path corresponding to a directory and an iPod path and converts it to an absolute unix path name.

ipod_path_from_unix_path ()

gchar*      ipod_path_from_unix_path        (const gchar *mount_point,
                                             const gchar *unix_path);

This functions takes a path corresponding to a directory and an absolute unix path and converts it to a path meaningful to the iPod. See ipod_path_to_unix_path() for more information.