|
|
|
libgpod Reference Manual | |
|---|---|---|---|---|
Itdb_SPLPref;
Itdb_SPLRule;
Itdb_SPLRules;
enum ItdbLimitSort;
enum ItdbLimitType;
enum ItdbSPLAction;
enum ItdbSPLActionLast;
enum ItdbSPLActionType;
enum ItdbSPLField;
enum ItdbSPLFieldType;
enum ItdbSPLMatch;
#define ITDB_SPL_DATE_IDENTIFIER
#define ITDB_SPL_STRING_MAXLEN
ItdbSPLFieldType itdb_splr_get_field_type (const Itdb_SPLRule *splr);
ItdbSPLActionType itdb_splr_get_action_type (const Itdb_SPLRule *splr);
void itdb_splr_validate (Itdb_SPLRule *splr);
void itdb_splr_remove (Itdb_Playlist *pl,
Itdb_SPLRule *splr);
Itdb_SPLRule* itdb_splr_new (void);
void itdb_splr_add (Itdb_Playlist *pl,
Itdb_SPLRule *splr,
gint pos);
Itdb_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 (Itdb_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);
typedef struct {
guint8 liveupdate;
guint8 checkrules;
guint8 checklimits;
guint32 limittype;
guint32 limitsort;
guint32 limitvalue;
guint8 matchcheckedonly;
gint32 reserved_int1;
gint32 reserved_int2;
gpointer reserved1;
gpointer reserved2;
} Itdb_SPLPref;
Smart Playlist preferences are for various flags that are not strictly smart playlist "rules."
guint8 |
Live Updating |
guint8 |
Match this number of rules. If set to 0, ignore rules. |
guint8 |
Limit to this number of limittype. If 0, no limits.
|
guint32 |
an ItdbLimitType |
guint32 |
an ItdbLimitSort |
guint32 |
The value typed next to "Limit type" |
guint8 |
Match only checked songs |
gint32 |
Reserved for future use |
gint32 |
Reserved for future use |
gpointer |
Reserved for future use |
gpointer |
Reserved for future use |
Since 0.5.0
typedef struct {
guint32 field;
guint32 action;
gchar *string;
guint64 fromvalue;
gint64 fromdate;
guint64 fromunits;
guint64 tovalue;
gint64 todate;
guint64 tounits;
guint32 unk052;
guint32 unk056;
guint32 unk060;
guint32 unk064;
guint32 unk068;
/* reserved for future use */
gint32 reserved_int1;
gint32 reserved_int2;
gpointer reserved1;
gpointer reserved2;
} Itdb_SPLRule;
Smart Playlist Rule
The from and to fields require some explanation. If field is a date type,
then value would be set to 0x2dae2dae2dae2dae, date would be a number,
(e.g. 2 or -2), and units would be a time unit in seconds (e.g. one week
would be 604800). If field is an integer comparison, like rating = 60 (i.e.
3 stars), then value would be the value we care about (e.g. 60), date would
be 0, and units would be 1. Binary AND types are similar, value is the
important part, with date = 0 and units = 1. Clear as mud, right?
For more details see ipodlinux.org.
guint32 |
an ItdbSPLFieldType |
guint32 |
an ItdbSPLActionType |
gchar * |
data in UTF8 |
guint64 |
from value |
gint64 |
from date |
guint64 |
from units |
guint64 |
to value |
gint64 |
to date |
guint64 |
to units |
guint32 |
Unknown |
guint32 |
Unknown |
guint32 |
Unknown |
guint32 |
Unknown |
guint32 |
Unknown |
gint32 |
Reserved for future use |
gint32 |
Reserved for future use |
gpointer |
Reserved for future use |
gpointer |
Reserved for future use |
Since 0.5.0
typedef struct {
guint32 unk004;
guint32 match_operator;
GList *rules;
/* reserved for future use */
gint32 reserved_int1;
gint32 reserved_int2;
gpointer reserved1;
gpointer reserved2;
} Itdb_SPLRules;
Smart Playlist Rules
guint32 |
Unknown |
guint32 |
Whether all rules must match (ITDB_SPLMATCH_AND) or any rules may match (ITDB_SPLMATCH_OR) |
GList * |
list of Itdb_SPLRule's |
gint32 |
Reserved for future use |
gint32 |
Reserved for future use |
gpointer |
Reserved for future use |
gpointer |
Reserved for future use |
Since 0.5.0
typedef enum {
ITDB_LIMITSORT_RANDOM = 0x02,
ITDB_LIMITSORT_SONG_NAME = 0x03,
ITDB_LIMITSORT_ALBUM = 0x04,
ITDB_LIMITSORT_ARTIST = 0x05,
ITDB_LIMITSORT_GENRE = 0x07,
ITDB_LIMITSORT_MOST_RECENTLY_ADDED = 0x10,
ITDB_LIMITSORT_LEAST_RECENTLY_ADDED = 0x80000010, /* See note above */
ITDB_LIMITSORT_MOST_OFTEN_PLAYED = 0x14,
ITDB_LIMITSORT_LEAST_OFTEN_PLAYED = 0x80000014, /* See note above */
ITDB_LIMITSORT_MOST_RECENTLY_PLAYED = 0x15,
ITDB_LIMITSORT_LEAST_RECENTLY_PLAYED = 0x80000015,/* See note above */
ITDB_LIMITSORT_HIGHEST_RATING = 0x17,
ITDB_LIMITSORT_LOWEST_RATING = 0x80000017, /* See note above */
} ItdbLimitSort;
Which songs to pick when using a limit type
Note: the values for ITDB_LIMITSORT_LEAST_RECENTLY_ADDED, ITDB_LIMITSORT_LEAST_OFTEN_PLAYED, ITDB_LIMITSORT_LEAST_RECENTLY_PLAYED, and ITDB_LIMITSORT_LOWEST_RATING are really 0x10, 0x14, 0x15, 0x17, with the 'limitsort_opposite' flag set. This is the same value as the "positive" value (i.e. ITDB_LIMITSORT_LEAST_RECENTLY_ADDED), and is really very terribly awfully weird, so we map the values to iPodDB specific values with the high bit set.
On writing, we check the high bit and write the limitsort_opposite from that. That way, we don't have to deal with programs using the class needing to set the wrong limit and then make it into the "opposite", which would be frickin' annoying.
| Sort randomly | |
| Sort by track name | |
| Sort by album name | |
| Sort by artist name | |
| Sort by genre | |
| Sort by most recently added | |
| Sort by least recently added | |
| Sort by most often played | |
| Sort by least often played | |
| Sort by most recently played | |
| Sort by least recently played | |
| Sort by highest rating | |
| Sort by lowest rating |
Since 0.5.0
typedef enum {
ITDB_LIMITTYPE_MINUTES = 0x01,
ITDB_LIMITTYPE_MB = 0x02,
ITDB_LIMITTYPE_SONGS = 0x03,
ITDB_LIMITTYPE_HOURS = 0x04,
ITDB_LIMITTYPE_GB = 0x05
} ItdbLimitType;
The type of unit to use when limiting a playlist
| Limit in minutes | |
| Limit in megabytes | |
| Limit in number of songs | |
| Limit in hours | |
| Limit in gigabytes |
Since 0.5.0
typedef enum {
ITDB_SPLACTION_IS_INT = 0x00000001,
ITDB_SPLACTION_IS_GREATER_THAN = 0x00000010,
ITDB_SPLACTION_IS_LESS_THAN = 0x00000040,
ITDB_SPLACTION_IS_IN_THE_RANGE = 0x00000100,
ITDB_SPLACTION_IS_IN_THE_LAST = 0x00000200,
ITDB_SPLACTION_BINARY_AND = 0x00000400,
ITDB_SPLACTION_IS_STRING = 0x01000001,
ITDB_SPLACTION_CONTAINS = 0x01000002,
ITDB_SPLACTION_STARTS_WITH = 0x01000004,
ITDB_SPLACTION_ENDS_WITH = 0x01000008,
ITDB_SPLACTION_IS_NOT_INT = 0x02000001,
ITDB_SPLACTION_IS_NOT_GREATER_THAN = 0x02000010,
ITDB_SPLACTION_IS_NOT_LESS_THAN = 0x02000040,
ITDB_SPLACTION_IS_NOT_IN_THE_RANGE = 0x02000100,
ITDB_SPLACTION_IS_NOT_IN_THE_LAST = 0x02000200,
ITDB_SPLACTION_IS_NOT = 0x03000001,
ITDB_SPLACTION_DOES_NOT_CONTAIN = 0x03000002,
ITDB_SPLACTION_DOES_NOT_START_WITH = 0x03000004,
ITDB_SPLACTION_DOES_NOT_END_WITH = 0x03000008,
} ItdbSPLAction;
Smartlist Actions used in smart playlist rules.
Note by Otto (Samuel Wood):
really this is a bitmapped field... high byte bit 0 = "string" values if set, "int" values if not set bit 1 = "not", or to negate the check. lower 2 bytes bit 0 = simple "IS" query bit 1 = contains bit 2 = begins with bit 3 = ends with bit 4 = greater than bit 5 = unknown, but probably greater than or equal to bit 6 = less than bit 7 = unknown, but probably less than or equal to bit 8 = a range selection bit 9 = "in the last"
| is integer ("Is Set" in iTunes) | |
| is greater than ("Is after" in iTunes) | |
| is less than ("Is Before" in iTunes) | |
| is in the range | |
| is in the last | |
| binary AND | |
| is a string | |
| contains | |
| starts with | |
| ends with | |
| is not an integer ("Is Not Set" in iTunes) | |
| is not greater than (not in iTunes) | |
| is not less than (not in iTunes) | |
| is not in the range (not in iTunes) | |
| is not in the last | |
| is not | |
| does not contain | |
| does not start with (not in iTunes) | |
| does not end with (not in iTunes) |
Since 0.5.0
typedef enum {
ITDB_SPLACTION_LAST_DAYS_VALUE = 86400, /* nr of secs in 24 hours */
ITDB_SPLACTION_LAST_WEEKS_VALUE = 604800, /* nr of secs in 7 days */
ITDB_SPLACTION_LAST_MONTHS_VALUE = 2628000,/* nr of secs in 30.4167
days ~= 1 month */
} ItdbSPLActionLast;
These are to pass to AddRule() when you need a unit for the two "in the last"
action types. In theory, you can use any time range. iTunes might not
like it, but the iPod shouldn't care.
| Seconds in 24 hours | |
| Seconds in 7 days | |
| Seconds in 1 month (approximately) |
Since 0.5.0
typedef enum
{
ITDB_SPLAT_STRING = 1,
ITDB_SPLAT_INT,
ITDB_SPLAT_DATE,
ITDB_SPLAT_RANGE_INT,
ITDB_SPLAT_RANGE_DATE,
ITDB_SPLAT_INTHELAST,
ITDB_SPLAT_PLAYLIST,
ITDB_SPLAT_NONE,
ITDB_SPLAT_INVALID,
ITDB_SPLAT_UNKNOWN,
ITDB_SPLAT_BINARY_AND
} ItdbSPLActionType;
Smart Playlist Action Types
| string | |
| from integer | |
| from date ... | |
| an integer range ... | |
| a date range ... | |
| in the last ... | |
| in playlist | |
| none | |
| invalid | |
| unknown | |
| is / is not (binary AND) |
Since 0.5.0
typedef enum {
ITDB_SPLFIELD_SONG_NAME = 0x02,
ITDB_SPLFIELD_ALBUM = 0x03,
ITDB_SPLFIELD_ARTIST = 0x04,
ITDB_SPLFIELD_BITRATE = 0x05,
ITDB_SPLFIELD_SAMPLE_RATE = 0x06,
ITDB_SPLFIELD_YEAR = 0x07,
ITDB_SPLFIELD_GENRE = 0x08,
ITDB_SPLFIELD_KIND = 0x09,
ITDB_SPLFIELD_DATE_MODIFIED = 0x0a,
ITDB_SPLFIELD_TRACKNUMBER = 0x0b,
ITDB_SPLFIELD_SIZE = 0x0c,
ITDB_SPLFIELD_TIME = 0x0d,
ITDB_SPLFIELD_COMMENT = 0x0e,
ITDB_SPLFIELD_DATE_ADDED = 0x10,
ITDB_SPLFIELD_COMPOSER = 0x12,
ITDB_SPLFIELD_PLAYCOUNT = 0x16,
ITDB_SPLFIELD_LAST_PLAYED = 0x17,
ITDB_SPLFIELD_DISC_NUMBER = 0x18,
ITDB_SPLFIELD_RATING = 0x19,
ITDB_SPLFIELD_COMPILATION = 0x1f,
ITDB_SPLFIELD_BPM = 0x23,
ITDB_SPLFIELD_GROUPING = 0x27,
ITDB_SPLFIELD_PLAYLIST = 0x28,
ITDB_SPLFIELD_VIDEO_KIND = 0x3c,
ITDB_SPLFIELD_TVSHOW = 0x3e,
ITDB_SPLFIELD_SEASON_NR = 0x3f,
ITDB_SPLFIELD_SKIPCOUNT = 0x44,
ITDB_SPLFIELD_LAST_SKIPPED = 0x45,
ITDB_SPLFIELD_ALBUMARTIST = 0x47
} ItdbSPLField;
Smart Playlist Fields, used for Smart Playlist Rules (Itdb_SPLRule).
| Song name (string) | |
| Album (string) | |
| Artist (string) | |
| Bitrate (integer, e.g. from/to = 128) | |
| Sample rate (integer, e.g. from/to = 44100) | |
| Year (integer, e.g. from/to = 2004) | |
| Genre (string) | |
| File type (string, e.g. MP3-File) | |
| Date modified (integer, e.g. from/to = bcf93280 == is before 6/19/2004) | |
| Track number (integer, e.g. from/to = 2) | |
| Size (integer, e.g. from/to = 0x00600000 for 6MB) | |
| Time (integer, e.g. from/to = 83999 for 1:23/83 seconds) | |
| Comment (string) | |
| Date added (integer, e.g. from/to = bcfa83ff == is after 6/19/2004) | |
| Composer (string) | |
| Playcount (integer, e.g. from/to = 1) | |
| Date last played (integer, e.g. from = bcfa83ff (6/19/2004) to = 0xbcfbd57f (6/20/2004)) | |
| Disc number (integer, e.g. from/to = 1) | |
| Rating (integer, e.g. from/to = 60 (3 stars)) | |
| Compilation (integer, e.g. is set -> ITDB_SPLACTION_IS_INT/from=1, not set -> ITDB_SPLACTION_IS_NOT_INT/from=1) | |
| Beats per minute (integer, e.g. from/to = 60) | |
| Grouping (string) | |
| FIXME Unknown...not parsed correctly... from/to = 0xb6fbad5f for "Purchased Music". Extra data after "to"... | |
| Logical integer (works on mediatype) | |
| TV Show (string) | |
| Season number (integer) | |
| Skipcount (integer) | |
| Last skipped (integer) | |
| Album artist (string) |
Since 0.5.0
typedef enum
{
ITDB_SPLFT_STRING = 1,
ITDB_SPLFT_INT,
ITDB_SPLFT_BOOLEAN,
ITDB_SPLFT_DATE,
ITDB_SPLFT_PLAYLIST,
ITDB_SPLFT_UNKNOWN,
ITDB_SPLFT_BINARY_AND
} ItdbSPLFieldType;
Smart Playlist Field Types
| string | |
| integer | |
| boolean | |
| date | |
| playlist | |
| unknown | |
| binary AND |
Since 0.5.0
typedef enum {
ITDB_SPLMATCH_AND = 0,
ITDB_SPLMATCH_OR = 1
} ItdbSPLMatch;
Types for smart playlist rules match_operator
#define ITDB_SPL_DATE_IDENTIFIER (G_GINT64_CONSTANT (0x2dae2dae2dae2daeU))
Identifier for smart playlist date fields
Since 0.5.0
#define ITDB_SPL_STRING_MAXLEN 255
Maximum string length for smart playlists
Since 0.5.0
ItdbSPLFieldType itdb_splr_get_field_type (const Itdb_SPLRule *splr);
Gets the type of the field of the splr rule
|
an Itdb_SPLRule |
Returns : |
an Itdb_SPLFieldType corresponding to splr field
type (string, int, date, ...)
|
ItdbSPLActionType itdb_splr_get_action_type (const Itdb_SPLRule *splr);
Gets the type of the action associated with splr.
|
an Itdb_SPLRule |
Returns : |
type (range, date, string...) of the action field |
void itdb_splr_validate (Itdb_SPLRule *splr);
Validates a smart playlist rule
|
an Itdb_SPLRule |
void itdb_splr_remove (Itdb_Playlist *pl, Itdb_SPLRule *splr);
Removes the smart playlist rule splr from playlist pl. The memory
used by splr is freed.
|
an Itdb_Playlist |
|
an Itdb_SPLRule |
Itdb_SPLRule* itdb_splr_new (void);
Creates a new default smart rule
Returns : |
a new Itdb_SPLRule that must be freed with itdb_splr_free() when
no longer needed
|
void itdb_splr_add (Itdb_Playlist *pl, Itdb_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()
|
an Itdb_Playlist |
|
an Itdb_SPLRule |
|
position of the rule |
Itdb_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.
|
an Itdb_Playlist |
|
position to insert the rule at |
Returns : |
pointer to the newly created Itdb_SPLRule. Its
memory is handled by pl though, so you don't need to explicitly
call itdb_splr_free() on it
|
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.
|
destination Itdb_Playlist |
|
source Itdb_Playlist |
gboolean itdb_splr_eval (Itdb_SPLRule *splr, Itdb_Track *track);
Evaluates splr's truth against track. track->itdb must be set.
|
an Itdb_SPLRule |
|
an Itdb_Track |
Returns : |
TRUE if track matches splr, FALSE otherwise.
|
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.
|
an Itdb_Playlist |
void itdb_spl_update_all (Itdb_iTunesDB *itdb);
Updates all smart playlists contained in itdb
|
an Itdb_iTunesDB |
void itdb_spl_update_live (Itdb_iTunesDB *itdb);
Updates all smart playlists contained in itdb which have the
liveupdate flag set.
|
an Itdb_iTunesDB |
Since 0.2.0