GrlRelatedKeys: Grilo Reference Manual

## GrlRelatedKeys GrlRelatedKeys — A class where to store related metadata keys. |

## Functions

GrlRelatedKeys * | grl_related_keys_new ()
GrlRelatedKeys * | grl_related_keys_new_valist ()
GrlRelatedKeys * | grl_related_keys_new_with_keys ()
GrlRelatedKeys * | grl_related_keys_dup ()
const GValue * | grl_related_keys_get ()
const guint8 * | grl_related_keys_get_binary ()
gboolean | grl_related_keys_get_boolean ()
gconstpointer | grl_related_keys_get_boxed ()
gfloat | grl_related_keys_get_float ()
gint | grl_related_keys_get_int ()
gint64 | grl_related_keys_get_int64 ()
GList * | grl_related_keys_get_keys ()
const gchar * | grl_related_keys_get_string ()
gboolean | grl_related_keys_has_key ()
void | grl_related_keys_set ()
void | grl_related_keys_set_binary ()
void | grl_related_keys_set_boolean ()
void | grl_related_keys_set_boxed ()
void | grl_related_keys_set_float ()
gboolean | grl_related_keys_set_for_id ()
void | grl_related_keys_set_int ()
void | grl_related_keys_set_int64 ()
void | grl_related_keys_set_string ()
void | grl_related_keys_remove ()

## Types and Values

struct | GrlRelatedKeys
struct | GrlRelatedKeysClass

## Object Hierarchy

        GObject
        ╰── GrlRelatedKeys

## Includes

    #include <grilo.h>

## Description

When handling media keys, like artist, URI, mime-type, and so on, some of these keys are somewhat related: they do not make sense if they are not accompanied by other keys.

For instance, media URI and and mime-type are related keys: mime-type does not make sense if it is not accompanied by an URI. Moreover, for each URI value, there is a corresponding mime-type value.

GrlRelatedKeys stores related keys and their values in one place, so user can handle them in one shot.

## Functions

### grl_related_keys_new ()

    GrlRelatedKeys *
    grl_related_keys_new (void);

Creates a new GrlRelatedKeys instance that can be used to store related keys and their values.

#### Returns

a new object.

Since: 0.1.10

### grl_related_keys_new_valist ()

    GrlRelatedKeys *
    grl_related_keys_new_valist (GrlKeyID key,
                                 va_list args);

Creates a new GrlRelatedKeys containing pairs of (key, value). Finish the list with `NULL`.

In case of a binary-type key, the expected element is (key, value, size).

value type will be extracted from key information.

#### Parameters

key | first key |
args | va_list of value, followed by (key,value) pairs to insert |

#### Returns

a new GrlRelatedKeys

Since: 0.1.10

### grl_related_keys_new_with_keys ()

    GrlRelatedKeys *
    grl_related_keys_new_with_keys (GrlKeyID key,
                                    ...);

Creates a initial GrlRelatedKeys containing the list of (key, value) pairs. Finish the list with `NULL`.

For more information see grl_related_keys_new_valist.

[skip]

#### Parameters

key | first key |
... | value, following by list of (key, value) |

#### Returns

a new GrlRelatedKeys

Since: 0.1.10

### grl_related_keys_dup ()

    GrlRelatedKeys *
    grl_related_keys_dup (GrlRelatedKeys *relkeys);

Makes a deep copy of `relkeys` and its contents.

#### Parameters

relkeys | set of related keys to duplicate |

#### Returns

a new GrlRelatedKeys. Free it with g_object_unref.

[transfer full]

Since: 0.1.10

### grl_related_keys_get ()

    const GValue *
    grl_related_keys_get (GrlRelatedKeys *relkeys,
                          GrlKeyID key);

Get the value associated with `key` from `relkeys` . If it does not contain any value, `NULL` will be returned.

#### Parameters

relkeys | set of related keys to retrieve value |
key | key to look up. | [type GrlKeyID]

#### Returns

a GValue. This value should not be modified nor freed by user.

[transfer none]

Since: 0.1.10

### grl_related_keys_get_binary ()

    const guint8 *
    grl_related_keys_get_binary (GrlRelatedKeys *relkeys,
                                 GrlKeyID key,
                                 gsize *size);

Returns the value associated with `key` from `relkeys` . If `key` has no value, or value is not a binary, or `key` is not in `relkeys` , then 0 is returned.

#### Parameters

relkeys | set of related keys to inspect |
key | key to use. | [type GrlKeyID]
size | location to store the buffer size. | [out]

#### Returns

buffer location associated with `key` , or `NULL` in other case. If successful `size` will be set to the buffer size.

Since: 0.1.10

### grl_related_keys_get_boolean ()

    gboolean
    grl_related_keys_get_boolean (GrlRelatedKeys *relkeys,
                                  GrlKeyID key);

Returns the value associated with `key` from `relkeys` . If `key` has no value, or value is not a gboolean, or `key` is not in `relkeys` , then `FALSE` is returned.

#### Parameters

relkeys | set of related keys to inspect |
key | key to use. | [type GrlKeyID]

#### Returns

float value associated with `key` , or `FALSE` in other case.

Since: 0.2.3

### grl_related_keys_get_boxed ()

    gconstpointer
    grl_related_keys_get_boxed (GrlRelatedKeys *relkeys,
                                GrlKeyID key);

Returns the value associated with `key` from `relkeys` . If `key` has no value, the value is not of a boxed type, or `key` is not in `relkeys` , then `NULL` is returned.

#### Parameters

relkeys | set of related keys to inspect |
key | key to use |

#### Returns

the GBoxed value associated with `key` if possible, or `NULL` in other case. The caller should not change nor free the value.

[transfer none]

Since: 0.2.0

### grl_related_keys_get_float ()

    gfloat
    grl_related_keys_get_float (GrlRelatedKeys *relkeys,
                                GrlKeyID key);

Returns the value associated with `key` from `relkeys` . If `key` has no value, or value is not a gfloat, or `key` is not in `relkeys` , then 0 is returned.

#### Parameters

relkeys | set of related keys to inspect |
key | key to use. | [type GrlKeyID]

#### Returns

float value associated with `key` , or 0 in other case.

Since: 0.1.10

### grl_related_keys_get_int ()

    gint
    grl_related_keys_get_int (GrlRelatedKeys *relkeys,
                              GrlKeyID key);

Returns the value associated with `key` from `relkeys` . If `key` has no value, or value is not a gint, or `key` is not in `relkeys` , then 0 is returned.

#### Parameters

relkeys | set of related keys to inspect |
key | key to use. | [type GrlKeyID]

#### Returns

int value associated with `key` , or 0 in other case.

Since: 0.1.10

### grl_related_keys_get_int64 ()

    gint64
    grl_related_keys_get_int64 (GrlRelatedKeys *relkeys,
                                GrlKeyID key);

Returns the value associated with `key` from `relkeys` . If `key` has no value, or value is not a gint64, or `key` is not in `relkeys` , then 0 is returned.

#### Parameters

relkeys | set of related keys to inspect |
key | key to use. | [type GrlKeyID]

#### Returns

int64 value associated with `key` , or 0 in other case.

Since: 0.2.12

### grl_related_keys_get_keys ()

    GList *
    grl_related_keys_get_keys (GrlRelatedKeys *relkeys);

Returns a list with keys contained in `relkeys` .

#### Parameters

relkeys | set of related keys to inspect |

#### Returns

a list with the keys. The content of the list should not be modified or freed. Use `g_list_free()` when done using the list.

[transfer container][element-type GrlKeyID]

Since: 0.1.13

### grl_related_keys_get_string ()

    const gchar *
    grl_related_keys_get_string (GrlRelatedKeys *relkeys,
                                 GrlKeyID key);

Returns the value associated with `key` from `relkeys` . If `key` has no value, or value is not string, or `key` is not in `relkeys` , then `NULL` is returned.

#### Parameters

relkeys | set of related keys to inspect |
key | key to use. | [type GrlKeyID]

#### Returns

string associated with `key` , or `NULL` in other case. Caller should not change nor free the value.

Since: 0.1.10

### grl_related_keys_has_key ()

    gboolean
    grl_related_keys_has_key (GrlRelatedKeys *relkeys,
                              GrlKeyID key);

Checks if `key` is in `relkeys` .

#### Parameters

relkeys | set of related keys to inspect |
key | key to search. | [type GrlKeyID]

#### Returns

`TRUE` if `key` is in `relkeys` , `FALSE` in other case.

Since: 0.1.10

### grl_related_keys_set ()

    void
    grl_related_keys_set (GrlRelatedKeys *relkeys,
                          GrlKeyID key,
                          const GValue *value);

Sets the value associated with `key` into `relkeys` . Old value is freed and the new one is set.

Also, checks that `value` is compliant with `key` specification, modifying it accordingly. For instance, if `key` requires a number between 0 and 10, but value is outside this range, it will be adapted accordingly.

#### Parameters

relkeys | set of related keys to modify |
key | key to change or add. | [type GrlKeyID]
value | the new value |

Since: 0.1.10

### grl_related_keys_set_binary ()

    void
    grl_related_keys_set_binary (GrlRelatedKeys *relkeys,
                                 GrlKeyID key,
                                 const guint8 *buf,
                                 gsize size);

Sets the value associated with `key` into `relkeys` . `key` must have been registered as a binary-type key. Old value is replaced by the new one.

#### Parameters

relkeys | set of related keys to change |
key | key to change or add. | [type GrlKeyID]
buf | buffer holding the relkeys |
size | size of the buffer |

Since: 0.1.10

### grl_related_keys_set_boolean ()

    void
    grl_related_keys_set_boolean (GrlRelatedKeys *relkeys,
                                  GrlKeyID key,
                                  gboolean booleanvalue);

Sets the value associated with `key` into `relkeys` . `key` must have been registered as a boolean-type key. Old value is replaced by the new one.

#### Parameters

relkeys | set of related keys to change |
key | key to change or add. | [type GrlKeyID]
booleanvalue | the new value |

Since: 0.2.3

### grl_related_keys_set_boxed ()

    void
    grl_related_keys_set_boxed (GrlRelatedKeys *relkeys,
                                GrlKeyID key,
                                gconstpointer boxed);

Sets the value associated with `key` into `relkeys` . `key` must have been registered as a boxed-type key. Old value is freed and the new one is set.

#### Parameters

relkeys | set of related keys to modify |
key | key to change or add |
boxed | the new value |

Since: 0.2.0

### grl_related_keys_set_float ()

    void
    grl_related_keys_set_float (GrlRelatedKeys *relkeys,
                                GrlKeyID key,
                                gfloat floatvalue);

Sets the value associated with `key` into `relkeys` . `key` must have been registered as a float-type key. Old value is replaced by the new one.

#### Parameters

relkeys | set of related keys to change |
key | key to change or add. | [type GrlKeyID]
floatvalue | the new value |

Since: 0.1.10

### grl_related_keys_set_for_id ()

    gboolean
    grl_related_keys_set_for_id (GrlRelatedKeys *relkeys,
                                 const gchar *key_name,
                                 const GValue *value);

Sets the value associated with `key_name` in `relkeys` . This `key_name` is used to create a new GParamSpec instance, which is further used to create and register a key using `grl_registry_register_metadata_key()`. If `key_name` already has a `value` , old value is replaced by the new one.

A property key_name consists of segments consisting of ASCII letters and digits, separated by either the '-' or '_' character. The first character of a property key_name must be a letter. Key_names which violate these rules lead to undefined behaviour.

#### Parameters

relkeys | set of related keys to modify |
key_name | name of the key to change or add |
value | the new value |

#### Returns

TRUE if `value` was set to `key_name` , FALSE otherwise.

Since: 0.3.13

### grl_related_keys_set_int ()

    void
    grl_related_keys_set_int (GrlRelatedKeys *relkeys,
                              GrlKeyID key,
                              gint intvalue);

Sets the value associated with `key` into `relkeys` . `key` must have been registered as an int-type key. Old value is replaced by the new one.

#### Parameters

relkeys | set of related keys to change |
key | key to change or add. | [type GrlKeyID]
intvalue | the new value |

Since: 0.1.10

### grl_related_keys_set_int64 ()

    void
    grl_related_keys_set_int64 (GrlRelatedKeys *relkeys,
                                GrlKeyID key,
                                gint64 intvalue);

Sets the value associated with `key` into `relkeys` . `key` must have been registered as a int64-type key. Old value is replaced by the new one.

#### Parameters

relkeys | set of related keys to change |
key | key to change or add. | [type GrlKeyID]
intvalue | the new value |

Since: 0.2.12

### grl_related_keys_set_string ()

    void
    grl_related_keys_set_string (GrlRelatedKeys *relkeys,
                                 GrlKeyID key,
                                 const gchar *strvalue);

Sets the value associated with `key` into `relkeys` . `key` must have been registered as a strying-type key. Old value is freed and the new one is set.

#### Parameters

relkeys | set of related keys to modify |
key | key to change or add. | [type GrlKeyID]
strvalue | the new value |

Since: 0.1.10

### grl_related_keys_remove ()

    void
    grl_related_keys_remove (GrlRelatedKeys *relkeys,
                             GrlKeyID key);

Removes `key` from `relkeys` set.

#### Parameters

relkeys | set of related keys |
key | key to remove. | [type GrlKeyID]

Since: 0.2.3

## Types and Values

### struct GrlRelatedKeys

    struct GrlRelatedKeys;

### struct GrlRelatedKeysClass

    struct GrlRelatedKeysClass {
      GObjectClass parent_class;
    };

Grilo Data Multivalued class

#### Members

## See Also

GrlRegistry, GrlData