Playlists

Playlists — Data structure to represent an iPod playlist

Synopsis




                    Itdb_Playlist;
enum                ItdbPlaylistSortOrder;
Itdb_Playlist*      itdb_playlist_new                   (const gchar *title,
                                                         gboolean spl);
void                itdb_playlist_free                  (Itdb_Playlist *pl);
Itdb_Playlist*      itdb_playlist_duplicate             (Itdb_Playlist *pl);
void                itdb_playlist_add                   (Itdb_iTunesDB *itdb,
                                                         Itdb_Playlist *pl,
                                                         gint32 pos);
void                itdb_playlist_move                  (Itdb_Playlist *pl,
                                                         guint32 pos);
void                itdb_playlist_remove                (Itdb_Playlist *pl);
void                itdb_playlist_unlink                (Itdb_Playlist *pl);
void                itdb_playlist_add_track             (Itdb_Playlist *pl,
                                                         Itdb_Track *track,
                                                         gint32 pos);
void                itdb_playlist_remove_track          (Itdb_Playlist *pl,
                                                         Itdb_Track *track);
gboolean            itdb_playlist_contains_track        (Itdb_Playlist *pl,
                                                         Itdb_Track *track);
guint32             itdb_playlist_contain_track_number  (Itdb_Track *tr);
guint32             itdb_playlist_tracks_number         (Itdb_Playlist *pl);
Itdb_Playlist*      itdb_playlist_mpl                   (Itdb_iTunesDB *itdb);
gboolean            itdb_playlist_is_mpl                (Itdb_Playlist *pl);
void                itdb_playlist_set_mpl               (Itdb_Playlist *pl);
Itdb_Playlist*      itdb_playlist_podcasts              (Itdb_iTunesDB *itdb);
gboolean            itdb_playlist_is_podcasts           (Itdb_Playlist *pl);
void                itdb_playlist_set_podcasts          (Itdb_Playlist *pl);
gboolean            itdb_playlist_exists                (Itdb_iTunesDB *itdb,
                                                         Itdb_Playlist *pl);
Itdb_Playlist*      itdb_playlist_by_id                 (Itdb_iTunesDB *itdb,
                                                         guint64 id);
Itdb_Playlist*      itdb_playlist_by_nr                 (Itdb_iTunesDB *itdb,
                                                         guint32 num);
Itdb_Playlist*      itdb_playlist_by_name               (Itdb_iTunesDB *itdb,
                                                         gchar *name);
void                itdb_playlist_randomize             (Itdb_Playlist *pl);

Description

These functions and structures allow for adding and removing playlists, adding and removing tracks from playlists, sorting playlists, finding tracks in a playlist, etc.

Details

Itdb_Playlist

typedef struct {
    Itdb_iTunesDB *itdb;  /* pointer to iTunesDB (for convenience) */
    gchar *name;          /* name of playlist in UTF8              */
    guint8 type;          /* ITDB_PL_TYPE_NORM/_MPL                */
    guint8 flag1;         /* unknown, usually set to 0             */
    guint8 flag2;         /* unknown, always set to 0              */
    guint8 flag3;         /* unknown, always set to 0              */
    gint  num;            /* number of tracks in playlist          */
    GList *members;       /* tracks in playlist (Track *)          */
    gboolean is_spl;      /* smart playlist?                       */
    time_t timestamp;     /* timestamp of playlist creation        */
    guint64 id;           /* playlist ID                           */
    guint32 sortorder;    /* How to sort playlist -- see below     */
    guint32 podcastflag;  /* ITDB_PL_FLAG_NORM/_PODCAST            */
    Itdb_SPLPref splpref;      /* smart playlist prefs                  */
    Itdb_SPLRules splrules;    /* rules for smart playlists             */
    gpointer reserved100; /* reserved for MHOD100 implementation   */
    gpointer reserved101; /* reserved for MHOD100 implementation   */
    /* reserved for future use */
    gint32 reserved_int1;
    gint32 reserved_int2;
    gpointer reserved1;
    gpointer reserved2;
    /* below is for use by application */
    guint64 usertype;
    gpointer userdata;
    /* functions called to duplicate/free userdata */
    ItdbUserDataDuplicateFunc userdata_duplicate;
    ItdbUserDataDestroyFunc userdata_destroy;
} Itdb_Playlist;


enum ItdbPlaylistSortOrder

typedef enum
{
    ITDB_PSO_MANUAL = 1,
/*    ITDB_PSO_UNKNOWN = 2, */
    ITDB_PSO_TITLE = 3,
    ITDB_PSO_ALBUM = 4,
    ITDB_PSO_ARTIST = 5,
    ITDB_PSO_BIRATE = 6,
    ITDB_PSO_GENRE = 7,
    ITDB_PSO_FILETYPE = 8,
    ITDB_PSO_TIME_MODIFIED = 9,
    ITDB_PSO_TRACK_NR = 10,
    ITDB_PSO_SIZE = 11,
    ITDB_PSO_TIME = 12,  /* ? */
    ITDB_PSO_YEAR = 13,
    ITDB_PSO_SAMPLERATE = 14,
    ITDB_PSO_COMMENT = 15,
    ITDB_PSO_TIME_ADDED = 16,
    ITDB_PSO_EQUALIZER = 17, /* ? */
    ITDB_PSO_COMPOSER = 18,
/*    ITDB_PSO_UNKNOWN = 19, */
    ITDB_PSO_PLAYCOUNT = 20,
    ITDB_PSO_TIME_PLAYED = 21,
    ITDB_PSO_CD_NR = 22,
    ITDB_PSO_RATING = 23,
    ITDB_PSO_RELEASE_DATE = 24, /* used by podcasts */
    ITDB_PSO_BPM = 25,
    ITDB_PSO_GROUPING = 26,
    ITDB_PSO_CATEGORY = 27,
    ITDB_PSO_DESCRIPTION = 28
} ItdbPlaylistSortOrder;


itdb_playlist_new ()

Itdb_Playlist*      itdb_playlist_new                   (const gchar *title,
                                                         gboolean spl);

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

title : playlist title
spl : smart playlist flag
Returns : a new Itdb_Playlist which must be freed with itdb_playlist_free() after use

itdb_playlist_free ()

void                itdb_playlist_free                  (Itdb_Playlist *pl);

Frees the memory used by playlist pl.

pl : an Itdb_Playlist

itdb_playlist_duplicate ()

Itdb_Playlist*      itdb_playlist_duplicate             (Itdb_Playlist *pl);

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.

pl : an Itdb_Playlist
Returns : a newly allocated Itdb_Playlist that you'll have to free with itdb_playlist_free() when you no longer need it.

itdb_playlist_add ()

void                itdb_playlist_add                   (Itdb_iTunesDB *itdb,
                                                         Itdb_Playlist *pl,
                                                         gint32 pos);

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()

itdb : an Itdb_iTunesDB
pl : an Itdb_Playlist
pos : position to insert pl at

itdb_playlist_move ()

void                itdb_playlist_move                  (Itdb_Playlist *pl,
                                                         guint32 pos);

Moves playlist pl to position pos

pl : an Itdb_Playlist
pos : new position

itdb_playlist_remove ()

void                itdb_playlist_remove                (Itdb_Playlist *pl);

Removes pl from the Itdb_iTunesDB it's associated with and frees memory

pl : an Itdb_Playlist

itdb_playlist_unlink ()

void                itdb_playlist_unlink                (Itdb_Playlist *pl);

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

pl : an Itdb_Playlist

itdb_playlist_add_track ()

void                itdb_playlist_add_track             (Itdb_Playlist *pl,
                                                         Itdb_Track *track,
                                                         gint32 pos);

Adds track to pl at position pos (-1 for "append to end")

pl : an Itdb_Playlist
track : an Itdb_Track
pos : position to insert track at

itdb_playlist_remove_track ()

void                itdb_playlist_remove_track          (Itdb_Playlist *pl,
                                                         Itdb_Track *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.

pl : an Itdb_Playlist
track : an Itdb_Track

itdb_playlist_contains_track ()

gboolean            itdb_playlist_contains_track        (Itdb_Playlist *pl,
                                                         Itdb_Track *track);

Checks if track is in pl.

pl : an Itdb_Playlist
track : an Itdb_Track
Returns : TRUE if track is in pl, FALSE otherwise

itdb_playlist_contain_track_number ()

guint32             itdb_playlist_contain_track_number  (Itdb_Track *tr);

Counts the number of playlist track is a member of (not including the master playlist)

tr : an Itdb_Track
Returns : number of playlist containing track

itdb_playlist_tracks_number ()

guint32             itdb_playlist_tracks_number         (Itdb_Playlist *pl);

Counts the number of tracks in pl

pl : an Itdb_Playlist
Returns : track count

itdb_playlist_mpl ()

Itdb_Playlist*      itdb_playlist_mpl                   (Itdb_iTunesDB *itdb);

Gets the master playlist of itdb

itdb : an Itdb_iTunesDB
Returns : the master playlist of itdb

itdb_playlist_is_mpl ()

gboolean            itdb_playlist_is_mpl                (Itdb_Playlist *pl);

Checks if pl is the master playlist

pl : an Itdb_Playlist
Returns : TRUE if pl is the master playlist, FALSE otherwise

itdb_playlist_set_mpl ()

void                itdb_playlist_set_mpl               (Itdb_Playlist *pl);

Sets pl to be a master playlist

pl : an Itdb_Playlist

itdb_playlist_podcasts ()

Itdb_Playlist*      itdb_playlist_podcasts              (Itdb_iTunesDB *itdb);

Gets the podcasts playlist of itdb

itdb : an Itdb_iTunesDB
Returns : the podcasts playlist of itdb, or NULL if it's there is none

itdb_playlist_is_podcasts ()

gboolean            itdb_playlist_is_podcasts           (Itdb_Playlist *pl);

Checks if pl is the podcasts playlist

pl : an Itdb_Playlist
Returns : TRUE if pl is the podcasts playlist, FALSE otherwise

itdb_playlist_set_podcasts ()

void                itdb_playlist_set_podcasts          (Itdb_Playlist *pl);

Set pl to be a podcasts playlist

pl : an Itdb_Playlist

itdb_playlist_exists ()

gboolean            itdb_playlist_exists                (Itdb_iTunesDB *itdb,
                                                         Itdb_Playlist *pl);

Checks if pl is present in db

itdb : an Itdb_iTunesDB
pl : an Itdb_Playlist
Returns : TRUE if pl exists in db, FALSE otherwise

itdb_playlist_by_id ()

Itdb_Playlist*      itdb_playlist_by_id                 (Itdb_iTunesDB *itdb,
                                                         guint64 id);

Looks up a playlist whose ID is id

itdb : an Itdb_iTunesDB
id : ID of the playlist to look for
Returns : the Itdb_Playlist with ID id or NULL if there is no such playlist.

itdb_playlist_by_nr ()

Itdb_Playlist*      itdb_playlist_by_nr                 (Itdb_iTunesDB *itdb,
                                                         guint32 num);

Gets the playlist at the given position in itdb

itdb : an Itdb_iTunesDB
num : the position of the playlist, counting from 0
Returns : the Itdb_Playlist, or NULL if there is no playlist at pos

itdb_playlist_by_name ()

Itdb_Playlist*      itdb_playlist_by_name               (Itdb_iTunesDB *itdb,
                                                         gchar *name);

Searches a playlist whose name is name in itdb

itdb : an Itdb_iTunesDB
name : name of the playlist to look for
Returns : the first Itdb_Playlist with name name, NULL if there is no such playlist

itdb_playlist_randomize ()

void                itdb_playlist_randomize             (Itdb_Playlist *pl);

Randomizes pl

pl : an Itdb_Playlist to randomize