Playlists

## 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