rb-ext-db-key

rb-ext-db-key — key for external metadata lookups

Synopsis

RBExtDBKey *        rb_ext_db_key_copy                  (RBExtDBKey *key);
void                rb_ext_db_key_free                  (RBExtDBKey *key);
RBExtDBKey *        rb_ext_db_key_create_lookup         (const char *field,
                                                         const char *value);
RBExtDBKey *        rb_ext_db_key_create_storage        (const char *field,
                                                         const char *value);
gboolean            rb_ext_db_key_is_lookup             (RBExtDBKey *key);
void                rb_ext_db_key_add_field             (RBExtDBKey *key,
                                                         const char *field,
                                                         const char *value);
char **             rb_ext_db_key_get_field_names       (RBExtDBKey *key);
const char *        rb_ext_db_key_get_field             (RBExtDBKey *key,
                                                         const char *field);
char **             rb_ext_db_key_get_field_values      (RBExtDBKey *key,
                                                         const char *field);
gboolean            rb_ext_db_key_field_matches         (RBExtDBKey *key,
                                                         const char *field,
                                                         const char *value);
void                rb_ext_db_key_add_info              (RBExtDBKey *key,
                                                         const char *name,
                                                         const char *value);
char **             rb_ext_db_key_get_info_names        (RBExtDBKey *key);
const char *        rb_ext_db_key_get_info              (RBExtDBKey *key,
                                                         const char *name);
gboolean            rb_ext_db_key_matches               (RBExtDBKey *a,
                                                         RBExtDBKey *b);
gboolean            (*RBExtDBKeyLookupCallback)         (TDB_DATA data,
                                                         gpointer user_data);
void                rb_ext_db_key_lookups               (RBExtDBKey *key,
                                                         RBExtDBKeyLookupCallback callback,
                                                         gpointer user_data);
TDB_DATA            rb_ext_db_key_to_store_key          (RBExtDBKey *key);
                    RBExtDBKey;

Description

An external metadata key consists of one or more required fields (such as the album name for album art lookups), zero or more optional fields (such as the artist name), and zero or more informational fields (such as the musicbrainz album ID).

Details

rb_ext_db_key_copy ()

RBExtDBKey *        rb_ext_db_key_copy                  (RBExtDBKey *key);

Copies a key.

key :

a RBExtDBKey

Returns :

copied key

rb_ext_db_key_free ()

void                rb_ext_db_key_free                  (RBExtDBKey *key);

Frees a key

key :

a RBExtDBKey

rb_ext_db_key_create_lookup ()

RBExtDBKey *        rb_ext_db_key_create_lookup         (const char *field,
                                                         const char *value);

Creates a new metadata lookup key with a single field. Use rb_ext_db_key_add_field to add more.

field :

required field name

value :

value for field

Returns :

the new key

rb_ext_db_key_create_storage ()

RBExtDBKey *        rb_ext_db_key_create_storage        (const char *field,
                                                         const char *value);

Creates a new metadata storage key with a single field. Use rb_ext_db_key_add_field to add more.

field :

required field name

value :

value for field

Returns :

the new key

rb_ext_db_key_is_lookup ()

gboolean            rb_ext_db_key_is_lookup             (RBExtDBKey *key);

Returns TRUE if the key is a lookup key

key :

a RBExtDBKey

Returns :

whether the key is a lookup key

rb_ext_db_key_add_field ()

void                rb_ext_db_key_add_field             (RBExtDBKey *key,
                                                         const char *field,
                                                         const char *value);

Adds a field to the key, or an additional value to an existing field.

key :

a RBExtDBKey

field :

name of the field to add

value :

field value

rb_ext_db_key_get_field_names ()

char **             rb_ext_db_key_get_field_names       (RBExtDBKey *key);

Returns a NULL-terminated array containing the names of the fields present in the key.

key :

a RBExtDBKey

Returns :

array of field names. [transfer full]

rb_ext_db_key_get_field ()

const char *        rb_ext_db_key_get_field             (RBExtDBKey *key,
                                                         const char *field);

Extracts the value for a single-valued field.

key :

a RBExtDBKey

field :

field to retrieve

Returns :

field value, or NULL

rb_ext_db_key_get_field_values ()

char **             rb_ext_db_key_get_field_values      (RBExtDBKey *key,
                                                         const char *field);

Extracts the values for the specified field.

key :

a RBExtDBKey

field :

field to retrieve

Returns :

field values, or NULL. [transfer full]

rb_ext_db_key_field_matches ()

gboolean            rb_ext_db_key_field_matches         (RBExtDBKey *key,
                                                         const char *field,
                                                         const char *value);

Checks whether a specified field in key matches a value. This can be used to match keys against other types of data. To match keys against each other, use rb_ext_db_key_matches.

key :

an RBExtDBKey

field :

a field to check

value :

a value to match against

Returns :

TRUE if the field matches the value

rb_ext_db_key_add_info ()

void                rb_ext_db_key_add_info              (RBExtDBKey *key,
                                                         const char *name,
                                                         const char *value);

Adds an information field to the key.

key :

a RBExtDBKey

name :

name of the field to add

value :

field value

rb_ext_db_key_get_info_names ()

char **             rb_ext_db_key_get_info_names        (RBExtDBKey *key);

Returns a NULL-terminated array containing the names of the info fields * present in the key.

key :

a RBExtDBKey

Returns :

array of info field names. [transfer full]

rb_ext_db_key_get_info ()

const char *        rb_ext_db_key_get_info              (RBExtDBKey *key,
                                                         const char *name);

Extracts the value for the specified info field.

key :

a RBExtDBKey

name :

info field to retrieve

Returns :

field value, or NULL

rb_ext_db_key_matches ()

gboolean            rb_ext_db_key_matches               (RBExtDBKey *a,
                                                         RBExtDBKey *b);

Checks whether the fields specified in a match b. For keys to match, they must have the same set of required fields, and the values for all must match. Optional fields must have the same values if present in both. Informational fields are ignored.

a :

first RBExtDBKey

b :

second RBExtDBKey

Returns :

TRUE if the keys match

RBExtDBKeyLookupCallback ()

gboolean            (*RBExtDBKeyLookupCallback)         (TDB_DATA data,
                                                         gpointer user_data);


rb_ext_db_key_lookups ()

void                rb_ext_db_key_lookups               (RBExtDBKey *key,
                                                         RBExtDBKeyLookupCallback callback,
                                                         gpointer user_data);

Generates the set of possible lookup keys for key and passes them to callback in order. If the callback returns FALSE, processing will stop.

This should only be used by the metadata store itself. Metadata providers and consumers shouldn't need to do this.

key :

a RBExtDBKey

callback :

a callback to process lookup keys. [scope call]

user_data :

data to pass to callback

rb_ext_db_key_to_store_key ()

TDB_DATA            rb_ext_db_key_to_store_key          (RBExtDBKey *key);

Generates the storage key for key. This is the value that should be used to store an item identified by this key in the store. The storage key includes all optional fields, so keys passed to this function should be constructed using only the optional fields that were used to locate the item. The caller must free the data pointer inside data.

This should only be used by the metadata store itself. Metadata providers and consumers shouldn't need to do this.

key :

a RBExtDBKey

Returns :

TDB_DATA structure containing storage key

RBExtDBKey

typedef struct _RBExtDBKey RBExtDBKey;