rb-ext-db-key

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

Types and Values

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

Functions

rb_ext_db_key_copy ()

RBExtDBKey *
rb_ext_db_key_copy (RBExtDBKey *key);

Copies a key.

Parameters

key

a RBExtDBKey

 

Returns

copied key


rb_ext_db_key_free ()

void
rb_ext_db_key_free (RBExtDBKey *key);

Frees a key

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

a

first RBExtDBKey

 

b

second RBExtDBKey

 

Returns

TRUE if the keys match


RBExtDBKeyLookupCallback ()

gboolean
(*RBExtDBKeyLookupCallback) (TDB_DATA data,
                             RBExtDBKey *key,
                             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.

Parameters

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.

[skip]

Parameters

key

a RBExtDBKey

 

Returns

TDB_DATA structure containing storage key

Types and Values

RBExtDBKey

typedef struct _RBExtDBKey RBExtDBKey;