Smart Playlists

Smart Playlists — Data structure to represent an iPod smart playlist

Synopsis




            SPLPref;
            SPLRule;
            SPLRules;
enum        SPLAction;
enum        SPLFieldType;
enum        SPLActionType;
enum        SPLField;
#define     SPLDATE_IDENTIFIER
#define     SPL_MAXSTRINGLENGTH
#define     SPL_STRING_MAXLEN
SPLFieldType itdb_splr_get_field_type       (const SPLRule *splr);
SPLActionType itdb_splr_get_action_type     (const SPLRule *splr);
void        itdb_splr_validate              (SPLRule *splr);
void        itdb_splr_remove                (Itdb_Playlist *pl,
                                             SPLRule *splr);
SPLRule*    itdb_splr_new                   (void);
void        itdb_splr_add                   (Itdb_Playlist *pl,
                                             SPLRule *splr,
                                             gint pos);
SPLRule*    itdb_splr_add_new               (Itdb_Playlist *pl,
                                             gint pos);
void        itdb_spl_copy_rules             (Itdb_Playlist *dest,
                                             Itdb_Playlist *src);
gboolean    itdb_splr_eval                  (SPLRule *splr,
                                             Itdb_Track *track);
void        itdb_spl_update                 (Itdb_Playlist *spl);
void        itdb_spl_update_all             (Itdb_iTunesDB *itdb);
void        itdb_spl_update_live            (Itdb_iTunesDB *itdb);

Description

These functions and structures are for dealing with smart playlists.

Details

SPLPref

typedef struct {
    guint8  liveupdate;        /* "live Updating" check box */
    guint8  checkrules;        /* "Match X of the following
				  conditions" check box */
    guint8  checklimits;       /* "Limit To..." check box */
    guint32 limittype;         /* See types defined above */
    guint32 limitsort;         /* See types defined above */
    guint32 limitvalue;        /* The value typed next to "Limit
				  type" */
    guint8  matchcheckedonly;  /* "Match only checked songs" check
				  box */
} SPLPref;


SPLRule

typedef struct {
    guint32 field;
    guint32 action;
    gchar *string;             /* data in UTF8  */
    /* from and to are pretty stupid.. if it's a date type of field,
       then
         value = 0x2dae2dae2dae2dae,
         date = some number, like 2 or -2
         units = unit in seconds, like 604800 = a week
       but if this is actually some kind of integer comparison, like
       rating = 60 (3 stars)
         value = the value we care about
	 date = 0
	 units = 1 */
    guint64 fromvalue;
    gint64 fromdate;
    guint64 fromunits;
    guint64 tovalue;
    gint64 todate;
    guint64 tounits;
    guint32 unk052;
    guint32 unk056;
    guint32 unk060;
    guint32 unk064;
    guint32 unk068;
} SPLRule;


SPLRules

typedef struct {
    guint32 unk004;
    guint32 match_operator;  /* "All" (logical AND): SPLMATCH_AND,
				"Any" (logical OR): SPLMATCH_OR */
    GList *rules;
} SPLRules;


enum SPLAction

typedef enum {
    SPLACTION_IS_INT = 0x00000001,          /* "Is Set" in iTunes */
    SPLACTION_IS_GREATER_THAN = 0x00000010, /* "Is After" in iTunes */
    SPLACTION_IS_LESS_THAN = 0x00000040,    /* "Is Before" in iTunes */
    SPLACTION_IS_IN_THE_RANGE = 0x00000100,
    SPLACTION_IS_IN_THE_LAST = 0x00000200,

    SPLACTION_IS_STRING = 0x01000001,
    SPLACTION_CONTAINS = 0x01000002,
    SPLACTION_STARTS_WITH = 0x01000004,
    SPLACTION_ENDS_WITH = 0x01000008,

    SPLACTION_IS_NOT_INT = 0x02000001,     /* "Is Not Set" in iTunes */

    /* Note: Not available in iTunes 4.5 (untested on iPod) */
    SPLACTION_IS_NOT_GREATER_THAN = 0x02000010,
    /* Note: Not available in iTunes 4.5 (untested on iPod) */
    SPLACTION_IS_NOT_LESS_THAN = 0x02000040,
    /* Note: Not available in iTunes 4.5 (seems to work on iPod) */
    SPLACTION_IS_NOT_IN_THE_RANGE = 0x02000100,

    SPLACTION_IS_NOT_IN_THE_LAST = 0x02000200,
    SPLACTION_IS_NOT = 0x03000001,
    SPLACTION_DOES_NOT_CONTAIN = 0x03000002,

    /* Note: Not available in iTunes 4.5 (seems to work on iPod) */
    SPLACTION_DOES_NOT_START_WITH = 0x03000004,
    /* Note: Not available in iTunes 4.5 (seems to work on iPod) */
    SPLACTION_DOES_NOT_END_WITH = 0x03000008,
} SPLAction;


enum SPLFieldType

typedef enum
{
    splft_string = 1,
    splft_int,
    splft_boolean,
    splft_date,
    splft_playlist,
    splft_unknown
} SPLFieldType;


enum SPLActionType

typedef enum
{
    splat_string = 1,
    splat_int,
    splat_date,
    splat_range_int,
    splat_range_date,
    splat_inthelast,
    splat_playlist,
    splat_none,
    splat_invalid,
    splat_unknown
} SPLActionType;


enum SPLField

typedef enum {
    SPLFIELD_SONG_NAME = 0x02,    /* String */
    SPLFIELD_ALBUM = 0x03,        /* String */
    SPLFIELD_ARTIST = 0x04,       /* String */
    SPLFIELD_BITRATE = 0x05,      /* Int (e.g. from/to = 128) */
    SPLFIELD_SAMPLE_RATE = 0x06,  /* Int  (e.g. from/to = 44100) */
    SPLFIELD_YEAR = 0x07,         /* Int  (e.g. from/to = 2004) */
    SPLFIELD_GENRE = 0x08,        /* String */
    SPLFIELD_KIND = 0x09,         /* String */
    SPLFIELD_DATE_MODIFIED = 0x0a,/* Int/Mac Timestamp (e.g. from/to =
                                     bcf93280 == is before 6/19/2004)*/
    SPLFIELD_TRACKNUMBER = 0x0b,  /* Int (e.g. from = 1, to = 2) */
    SPLFIELD_SIZE = 0x0c,         /* Int (e.g. from/to = 0x00600000
				     for 6MB) */
    SPLFIELD_TIME = 0x0d,         /* Int (e.g. from/to = 83999 for
				     1:23/83 seconds) */
    SPLFIELD_COMMENT = 0x0e,      /* String */
    SPLFIELD_DATE_ADDED = 0x10,   /* Int/Mac Timestamp (e.g. from/to =
                                     bcfa83ff == is after 6/19/2004) */
    SPLFIELD_COMPOSER = 0x12,     /* String */
    SPLFIELD_PLAYCOUNT = 0x16,    /* Int  (e.g. from/to = 1) */
    SPLFIELD_LAST_PLAYED = 0x17,  /* Int/Mac Timestamp (e.g. from =
                                     bcfa83ff (6/19/2004) to =
                                     0xbcfbd57f (6/20/2004)) */
    SPLFIELD_DISC_NUMBER = 0x18,  /* Int  (e.g. from/to = 1) */
    SPLFIELD_RATING = 0x19,       /* Int/Stars Rating (e.g. from/to =
                                     60 (3 stars)) */
    SPLFIELD_COMPILATION = 0x1f,  /* Int (e.g. is set ->
				     SPLACTION_IS_INT/from=1,
				     is not set ->
				     SPLACTION_IS_NOT_INT/from=1) */
    SPLFIELD_BPM = 0x23,          /* Int  (e.g. from/to = 60) */
    SPLFIELD_GROUPING = 0x27,     /* String */
    SPLFIELD_PLAYLIST = 0x28,     /* XXX - Unknown...not parsed
				     correctly...from/to = 0xb6fbad5f
				     for * "Purchased Music".  Extra
				     data after * "to"... */
} SPLField;


SPLDATE_IDENTIFIER

#define SPLDATE_IDENTIFIER (G_GINT64_CONSTANT (0x2dae2dae2dae2daeU))


SPL_MAXSTRINGLENGTH

#define SPL_MAXSTRINGLENGTH 255


SPL_STRING_MAXLEN

#define SPL_STRING_MAXLEN 255


itdb_splr_get_field_type ()

SPLFieldType itdb_splr_get_field_type       (const SPLRule *splr);

Gets the type of the field of the splr rule

splr : an SPLRule
Returns : an SPLFieldType corresponding to splr field type (string, int, date, ...)

itdb_splr_get_action_type ()

SPLActionType itdb_splr_get_action_type     (const SPLRule *splr);

Gets the type of the action associated with splr.

splr : an SPLRule
Returns : type (range, date, string...) of the action field

itdb_splr_validate ()

void        itdb_splr_validate              (SPLRule *splr);

Validates a rule

splr : an SPLRule

itdb_splr_remove ()

void        itdb_splr_remove                (Itdb_Playlist *pl,
                                             SPLRule *splr);

Removes the smart playlist rule splr from playlist pl. The memory used by splr is freed.

pl : an Itdb_Playlist
splr : an SPLRule

itdb_splr_new ()

SPLRule*    itdb_splr_new                   (void);

Creates a new default smart rule

Returns : a new SPLRule that must be freed with itdb_splr_free() when no longer needed

itdb_splr_add ()

void        itdb_splr_add                   (Itdb_Playlist *pl,
                                             SPLRule *splr,
                                             gint pos);

Adds the smart rule splr to pl at position pos. If pos is -1, splr gets appended to the end. After this call, splr memory is managed by pl, so you no longer need to call itdb_splr_free()

pl : an Itdb_Playlist
splr : an SPLRule
pos : position of the rule

itdb_splr_add_new ()

SPLRule*    itdb_splr_add_new               (Itdb_Playlist *pl,
                                             gint pos);

Creates a new smart rule and inserts it at position pos in pl. If pos is -1, the new rule gets appended to the end.

pl : an Itdb_Playlist
pos : position to insert the rule at
Returns : pointer to the newly created SPLRule. Its memory is handled by pl though, so you don't need to explicitly call itdb_splr_free() on it

itdb_spl_copy_rules ()

void        itdb_spl_copy_rules             (Itdb_Playlist *dest,
                                             Itdb_Playlist *src);

Copy all relevant information for smart playlist from playlist src to playlist dest. If dest is already a smart playlist, the existing data is overwritten/deleted.

dest : destination Itdb_Playlist
src : source Itdb_Playlist

itdb_splr_eval ()

gboolean    itdb_splr_eval                  (SPLRule *splr,
                                             Itdb_Track *track);

Evaluates splr's truth against track. track->itdb must be set.

splr : an SPLRule
track : an Itdb_Track
Returns : TRUE if track matches splr, FALSE otherwise.

itdb_spl_update ()

void        itdb_spl_update                 (Itdb_Playlist *spl);

Updates the content of the smart playlist spl (meant to be called if the tracks stored in the Itdb_iTunesDB associated with spl have changed somehow and you want spl->members to be accurate with regards to those changes. Does nothing if spl isn't a smart playlist.

spl : an Itdb_Playlist

itdb_spl_update_all ()

void        itdb_spl_update_all             (Itdb_iTunesDB *itdb);

Updates all smart playlists contained in itdb

itdb : an Itdb_iTunesDB

itdb_spl_update_live ()

void        itdb_spl_update_live            (Itdb_iTunesDB *itdb);

Updates all 'live' smart playlists contained in itdb, ie those which have the 'live updating' flag set

itdb : an Itdb_iTunesDB

See Also

Playlists