## rb-ext-db-key

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

## Functions

RBExtDBKey * | rb_ext_db_key_copy ()
void | rb_ext_db_key_free ()
RBExtDBKey * | rb_ext_db_key_create_lookup ()
RBExtDBKey * | rb_ext_db_key_create_storage ()
gboolean | rb_ext_db_key_is_lookup ()
void | rb_ext_db_key_add_field ()
char ** | rb_ext_db_key_get_field_names ()
const char * | rb_ext_db_key_get_field ()
char ** | rb_ext_db_key_get_field_values ()
gboolean | rb_ext_db_key_field_matches ()
void | rb_ext_db_key_add_info ()
char ** | rb_ext_db_key_get_info_names ()
const char * | rb_ext_db_key_get_info ()
gboolean | rb_ext_db_key_matches ()
gboolean | ( *RBExtDBKeyLookupCallback ) ()
void | rb_ext_db_key_lookups ()
TDB_DATA | rb_ext_db_key_to_store_key ()

## Types and Values

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

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