Playlists

Playlists — Data structure to represent an iPod playlist

Functions

Types and Values

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.

Functions

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

Parameters

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 .

Parameters

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.

Parameters

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

Parameters

itdb

an Itdb_iTunesDB

 

pl

an Itdb_Playlist

 

pos

position to insert pl at

 

itdb_playlist_move ()

void
itdb_playlist_move (Itdb_Playlist *pl,
                    gint32 pos);

Moves playlist pl to position pos . -1 will append to the end of the list.

Parameters

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

Parameters

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

Parameters

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)

Parameters

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.

Parameters

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

Parameters

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)

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

pl

an Itdb_Playlist to randomize

 

Types and Values

struct Itdb_Playlist

struct Itdb_Playlist {
    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;
};

Structure representing an iTunes Playlist

Members

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;

Private data

 

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

 

Itdb_Playlist_Private

typedef struct {
    Itdb_Playlist_Mhsd5_Type mhsd5_type;
} Itdb_Playlist_Private;


enum ItdbPlaylistSortOrder

Playlist Sort Order

Members

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