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

## 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?                       */
        guint32 timestamp;    /* some timestamp                        */
        guint64 id;           /* playlist ID                           */
        guint32 mhodcount;    /* This appears to be the number of string
    			     MHODs (type < 50) associated with this
    			     playlist (typically 0x01). Doesn't seem
    			     to be signficant unless you include Type
    			     52 MHODs. libgpod sets this to 1 when
    			     syncing */
        guint16 libmhodcount; /* The number of Type 52 MHODs associated
    			     with this playlist. If you don't create
    			     Type 52 MHODs, this can be
    			     zero. Otherwise, if you have Type 52
    			     MHODs associated with this playlist and
    			     set this to zero, no songs appear on the
    			     iPod. jcsjcs: with iTunes 4.9 this seems
    			     to be set to 1 even without any Type 52
    			     MHODs present. libgpod sets this to 1
    			     when syncing */
        guint32 sortorder;    /* How to sort playlist -- see below     */
        guint32 podcastflag;  /* ITDB_PL_FLAG_NORM/_PODCAST            */
        SPLPref splpref;      /* smart playlist prefs                  */
        SPLRules splrules;    /* rules for smart playlists             */
        /* below is for use by application */
        guint64 usertype;
        gpointer userdata;
        /* function called to duplicate userdata */
        ItdbUserDataDuplicateFunc userdata_duplicate;
        /* function called to free userdata */
        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