rb-ext-db-key

## 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;