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

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

gpointer reserved1;

Reserved for future use

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_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;

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_BIRATE

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