## 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;
        gchar *name;
        guint8 type;
        guint8 flag1;
        guint8 flag2;
        guint8 flag3;
        gint  num;
        GList *members;
        gboolean is_spl;
        time_t timestamp;
        guint64 id;
        guint32 sortorder;
        guint32 podcastflag;
        Itdb_SPLPref splpref;
        Itdb_SPLRules splrules;
        gpointer reserved100;
        gpointer reserved101;
        /* reserved for future use */
        gint32 reserved_int1;
        gint32 reserved_int2;
        Itdb_Playlist_Private *priv;
        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;

Structure representing an iTunes Playlist

Itdb_iTunesDB *`itdb`; | A pointer to the Itdb_iTunesDB (for convenience)
gchar *`name`; | The name of the playlist in UTF8
guint8 `type`; | The playlist type (normal or master)
guint8 `flag1`; | Unknown, usually set to 0
guint8 `flag2`; | Unknown, always set to 0
guint8 `flag3`; | Unknown, always set to 0
gint `num`; | The number of tracks in the playlist
GList *`members`; | A list of tracks in the playlist (Itdb_Track)
gboolean `is_spl`; | True if the playlist is a smart playlist, otherwise false
time_t `timestamp`; | When the playlist was created
guint64 `id`; | The playlist ID
guint32 `sortorder`; | The playlist sort order (ItdbPlaylistSortOrder)
guint32 `podcastflag`; | This is set to 0 on normal playlists and to 1 for the Podcast playlist. If set to 1, the playlist will not be shown under 'Playlists' on the iPod, but as 'Podcasts' under the Music menu. The actual title of the Playlist does not matter. If more than one playlist is set to 1, they don't show up at all.
Itdb_SPLPref `splpref`; | Smart playlist preferences (Itdb_SPLPref)
Itdb_SPLRules `splrules`; | Smart playlist rules (Itdb_SPLRules)
gpointer `reserved100`; | Reserved for MHOD100 implementation
gpointer `reserved101`; | Reserved for MHOD100 implementation
gint32 `reserved_int1`; | Reserved for future use
gint32 `reserved_int2`; | Reserved for future use
Itdb_Playlist_Private *`priv`; |
gpointer `reserved2`; | Reserved for future use
guint64 `usertype`; | For use by application
gpointer `userdata`; | For use by application
ItdbUserDataDuplicateFunc `userdata_duplicate`; | A function to duplicate userdata
ItdbUserDataDestroyFunc `userdata_destroy`; | A function to free userdata

### 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_BITRATE = 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;

Playlist Sort Order

`ITDB_PSO_MANUAL` | Sort by playlist order (manual sort)
`ITDB_PSO_TITLE` | Sort by track title
`ITDB_PSO_ALBUM` | Sort by album
`ITDB_PSO_ARTIST` | Sort by artist
`ITDB_PSO_BITRATE` | Sort by bitrate
`ITDB_PSO_GENRE` | Sort by genre
`ITDB_PSO_FILETYPE` | Sort by filetype
`ITDB_PSO_TIME_MODIFIED` | Sort by date modified
`ITDB_PSO_TRACK_NR` | Sort by track number
`ITDB_PSO_SIZE` | Sort by track size
`ITDB_PSO_TIME` | Sort by track time
`ITDB_PSO_YEAR` | Sort by year
`ITDB_PSO_SAMPLERATE` | Sort by samplerate
`ITDB_PSO_COMMENT` | Sort by comments
`ITDB_PSO_TIME_ADDED` | Sort by date added
`ITDB_PSO_EQUALIZER` | Sort by equilizer
`ITDB_PSO_COMPOSER` | Sort by composer
`ITDB_PSO_PLAYCOUNT` | Sort by playcount
`ITDB_PSO_TIME_PLAYED` | Sort by date last played
`ITDB_PSO_CD_NR` | Sort by disc number
`ITDB_PSO_RATING` | Sort by rating
`ITDB_PSO_RELEASE_DATE` | Sort by release date
`ITDB_PSO_BPM` | Sort by beats per minute
`ITDB_PSO_GROUPING` | Sort by grouping
`ITDB_PSO_CATEGORY` | Sort by category
`ITDB_PSO_DESCRIPTION` | Sort by description

Since 0.1.3

### 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 to append at the 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 : | the 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 : | the number of tracks in `pl`

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

Since 0.1.6

### itdb_playlist_set_mpl ()

    void                itdb_playlist_set_mpl               (Itdb_Playlist *pl);

Sets `pl` to be a master playlist

`pl` : | an Itdb_Playlist

Since 0.2.0

### 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 there is not one

Since 0.1.6

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

Since 0.1.6

### itdb_playlist_set_podcasts ()

    void                itdb_playlist_set_podcasts          (Itdb_Playlist *pl);

Set `pl` to be a podcasts playlist

`pl` : | an Itdb_Playlist

Since 0.2.0

### itdb_playlist_exists ()

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

Checks if `pl` is present in `itdb`

`itdb` : | an Itdb_iTunesDB
`pl` : | an Itdb_Playlist
Returns : | TRUE if `pl` exists in `itdb`, 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