GrlData: Grilo Reference Manual

## GrlData GrlData — Low-level class for storing metadata information about media resources provided by GrlSource objects. |

## Functions

GrlData * | grl_data_new ()
void | grl_data_add_binary ()
void | grl_data_add_boxed ()
void | grl_data_add_float ()
gboolean | grl_data_add_for_id ()
void | grl_data_add_int ()
void | grl_data_add_int64 ()
void | grl_data_add_related_keys ()
void | grl_data_add_string ()
GrlData * | grl_data_dup ()
const GValue * | grl_data_get ()
const guint8 * | grl_data_get_binary ()
gboolean | grl_data_get_boolean ()
gpointer | grl_data_get_boxed ()
gfloat | grl_data_get_float ()
gboolean | grl_data_set_for_id ()
gint | grl_data_get_int ()
gint64 | grl_data_get_int64 ()
GList * | grl_data_get_keys ()
GrlRelatedKeys * | grl_data_get_related_keys ()
GList * | grl_data_get_single_values_for_key ()
GList * | grl_data_get_single_values_for_key_string ()
const gchar * | grl_data_get_string ()
gboolean | grl_data_has_key ()
guint | grl_data_length ()
void | grl_data_remove ()
void | grl_data_remove_nth ()
void | grl_data_set ()
void | grl_data_set_binary ()
void | grl_data_set_boolean ()
void | grl_data_set_boxed ()
void | grl_data_set_float ()
void | grl_data_set_int ()
void | grl_data_set_int64 ()
void | grl_data_set_related_keys ()
void | grl_data_set_string ()

## Types and Values

struct | GrlData
struct | GrlDataClass

## Object Hierarchy

        GObject
        ╰── GrlData
            ╰── GrlMedia

## Includes

    #include <grilo.h>

## Description

This class acts as a generic metadata dictionary where metadata keys and their values can be stored. Usually, application and plugin developers would interact with specific subclass of GrlData, GrlMedia, which provide specific API to manipulate well known attributes of these media types.

## Functions

### grl_data_new ()

    GrlData *
    grl_data_new (void);

Creates a new data object.

#### Returns

a new data object.

Since: 0.1.4

### grl_data_add_binary ()

    void
    grl_data_add_binary (GrlData *data,
                         GrlKeyID key,
                         const guint8 *buf,
                         gsize size);

Appends a new binary value for `key` in `data` .

#### Parameters

data | data to append |
key | key to append. | [type GrlKeyID]
buf | the buffer containing the new value |
size | size of buffer |

Since: 0.1.10

### grl_data_add_boxed ()

    void
    grl_data_add_boxed (GrlData *data,
                        GrlKeyID key,
                        gconstpointer boxed);

Appends a new boxed value for `key` in `data` .

#### Parameters

data | data to append |
key | key to append. | [type GrlKeyID]
boxed | the new value |

Since: 0.2.0

### grl_data_add_float ()

    void
    grl_data_add_float (GrlData *data,
                        GrlKeyID key,
                        gfloat floatvalue);

Appends a new float value for `key` in `data` .

#### Parameters

data | data to append |
key | key to append. | [type GrlKeyID]
floatvalue | the new value |

Since: 0.1.10

### grl_data_add_for_id ()

    gboolean
    grl_data_add_for_id (GrlData *data,
                         const gchar *key_name,
                         const GValue *value);

Appends the value associated with `key_name` to `data` . 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()`.

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

data | data to change |
key_name | name of the key to change or add |
value | the new value |

#### Returns

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

Since: 0.3.6

### grl_data_add_int ()

    void
    grl_data_add_int (GrlData *data,
                      GrlKeyID key,
                      gint intvalue);

Appends a new int value for `key` in `data` .

#### Parameters

data | data to append |
key | key to append. | [type GrlKeyID]
intvalue | the new value |

Since: 0.1.10

### grl_data_add_int64 ()

    void
    grl_data_add_int64 (GrlData *data,
                        GrlKeyID key,
                        gint64 intvalue);

Appends a new int64 value for `key` in `data` .

#### Parameters

data | data to append |
key | key to append. | [type GrlKeyID]
intvalue | the new value |

Since: 0.2.12

### grl_data_add_related_keys ()

    void
    grl_data_add_related_keys (GrlData *data,
                               GrlRelatedKeys *relkeys);

Adds a new set of values into `data` .

All keys in `prop` must be related among them.

`data` will take the ownership of `relkeys` , so do not modify it.

#### Parameters

data | data to change |
relkeys | a set of related properties with their values. | [transfer full]

Since: 0.1.10

### grl_data_add_string ()

    void
    grl_data_add_string (GrlData *data,
                         GrlKeyID key,
                         const gchar *strvalue);

Appends a new string value for `key` in `data` .

#### Parameters

data | data to append |
key | key to append. | [type GrlKeyID]
strvalue | the new value |

Since: 0.1.10

### grl_data_dup ()

    GrlData *
    grl_data_dup (GrlData *data);

Makes a deep copy of `data` and all its contents.

#### Parameters

data | data to duplicate |

#### Returns

a new GrlData. Free it with g_object_unref.

[transfer full]

Since: 0.1.10

### grl_data_get ()

    const GValue *
    grl_data_get (GrlData *data,
                  GrlKeyID key);

Get the first value from `data` associated with `key` .

#### Parameters

data | data 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.4

### grl_data_get_binary ()

    const guint8 *
    grl_data_get_binary (GrlData *data,
                         GrlKeyID key,
                         gsize *size);

Returns the first binary value associated with `key` from `data` . If `key` has no first value, or value is not a gfloat, or `key` is not in data, then `NULL` is returned.

#### Parameters

data | data to inspect |
key | key to use. | [type GrlKeyID]
size | location to store the buffer size. | [out]

#### Returns

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

Since: 0.1.9

### grl_data_get_boolean ()

    gboolean
    grl_data_get_boolean (GrlData *data,
                          GrlKeyID key);

#### Parameters

data | data to inspect |
key | key to use. | [type GrlKeyID]

#### Returns

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

Since: 0.2.3

### grl_data_get_boxed ()

    gpointer
    grl_data_get_boxed (GrlData *data,
                        GrlKeyID key);

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

#### Parameters

data | data to inspect |
key | key to use. | [type GrlKeyID]

#### Returns

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

[transfer none]

Since: 0.2.0

### grl_data_get_float ()

    gfloat
    grl_data_get_float (GrlData *data,
                        GrlKeyID key);

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

#### Parameters

data | data to inspect |
key | key to use. | [type GrlKeyID]

#### Returns

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

Since: 0.1.5

### grl_data_set_for_id ()

    gboolean
    grl_data_set_for_id (GrlData *data,
                         const gchar *key_name,
                         const GValue *value);

Sets the first value associated with `key_name` in `data` . 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 first `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

data | data to change |
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.6

### grl_data_get_int ()

    gint
    grl_data_get_int (GrlData *data,
                      GrlKeyID key);

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

#### Parameters

data | data to inspect |
key | key to use. | [type GrlKeyID]

#### Returns

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

Since: 0.1.4

### grl_data_get_int64 ()

    gint64
    grl_data_get_int64 (GrlData *data,
                        GrlKeyID key);

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

#### Parameters

data | data to inspect |
key | key to use. | [type GrlKeyID]

#### Returns

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

Since: 0.2.12

### grl_data_get_keys ()

    GList *
    grl_data_get_keys (GrlData *data);

Returns a list with keys contained in `data` .

#### Parameters

data | data to inspect |

#### Returns

an array 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.4

### grl_data_get_related_keys ()

    GrlRelatedKeys *
    grl_data_get_related_keys (GrlData *data,
                               GrlKeyID key,
                               guint index);

Returns a set containing the values for `key` and related keys at position `index` from `data` .

If user changes any of the values in the related keys, the changes will become permanent.

#### Parameters

data | a data |
key | a metadata key |
index | element to retrieve, starting at 0 |

#### Returns

a GrlRelatedKeys. Do not free it.

[transfer none]

Since: 0.1.10

### grl_data_get_single_values_for_key ()

    GList *
    grl_data_get_single_values_for_key (GrlData *data,
                                        GrlKeyID key);

Returns all non-`NULL` values for `key` from `data` . This ignores related keys.

#### Parameters

data | a data |
key | a metadata key |

#### Returns

a GList with values. Do not change or free the values. Free the list with g_list_free.

[element-type GObject.Value][transfer container]

Since: 0.1.13

### grl_data_get_single_values_for_key_string ()

    GList *
    grl_data_get_single_values_for_key_string
                                   (GrlData *data,
                                    GrlKeyID key);

Returns all non-`NULL` values for `key` from `data` . `key` must have been registered as a string-type key. This ignores related keys.

#### Parameters

data | a data |
key | a metadata key |

#### Returns

a GList with values. Do not change or free the strings. Free the list with g_list_free.

[element-type utf8][transfer container]

Since: 0.1.13

### grl_data_get_string ()

    const gchar *
    grl_data_get_string (GrlData *data,
                         GrlKeyID key);

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

#### Parameters

data | data 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.4

### grl_data_has_key ()

    gboolean
    grl_data_has_key (GrlData *data,
                      GrlKeyID key);

Checks if `key` is in `data` .

#### Parameters

data | data to inspect |
key | key to search. | [type GrlKeyID]

#### Returns

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

Since: 0.1.4

### grl_data_length ()

    guint
    grl_data_length (GrlData *data,
                     GrlKeyID key);

Returns how many values `key` or related keys have in `data` : if `key` has no value, but a related key has, then it is counted as positive.

As example, let's think in three related keys, K1, K2 and K3, and then thinks we have added several values for those keys, as:

(V10, V20, V30), (V11, NULL, V31), (V12, NULL, V32)

Therefore, when invoking grl_data_length (data, K2) it will return 3: considering K2 and the related keys (K1 and K3), there are 3 values.

#### Parameters

data | a data |
key | a metadata key |

#### Returns

number of values

Since: 0.1.10

### grl_data_remove ()

    void
    grl_data_remove (GrlData *data,
                     GrlKeyID key);

Removes the first value for `key` from `data` . If there are other keys related to `key` their values will also be removed from `data` .

#### Parameters

data | data to change |
key | key to remove. | [type GrlKeyID]

Since: 0.1.4

### grl_data_remove_nth ()

    void
    grl_data_remove_nth (GrlData *data,
                         GrlKeyID key,
                         guint index);

Removes the value at position `index` for `key` from `data` . If there are other keys related to `key` , their values at position `index` will also be removed from `data` .

#### Parameters

data | a data |
key | a metadata key |
index | index of key to be removed, starting at 0 |

Since: 0.1.10

### grl_data_set ()

    void
    grl_data_set (GrlData *data,
                  GrlKeyID key,
                  const GValue *value);

Sets the first value associated with `key` in `data` . If key already has a value 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

data | data to modify |
key | key to change or add. | [type GrlKeyID]
value | the new value |

Since: 0.1.4

### grl_data_set_binary ()

    void
    grl_data_set_binary (GrlData *data,
                         GrlKeyID key,
                         const guint8 *buf,
                         gsize size);

Sets the first binary value associated with `key` in `data` . If `key` already has a first value old value is replaced by the new one.

#### Parameters

data | data to change |
key | key to change or add. | [type GrlKeyID]
buf | buffer holding the data |
size | size of the buffer |

Since: 0.1.9

### grl_data_set_boolean ()

    void
    grl_data_set_boolean (GrlData *data,
                          GrlKeyID key,
                          gboolean boolvalue);

Sets the first boolean value associated with `key` in `data` . If `key` already has a first value, old value is replaced by the new one.

#### Parameters

data | data to change |
key | key to change or add. | [type GrlKeyID]
boolvalue | the new value |

Since: 0.2.3

### grl_data_set_boxed ()

    void
    grl_data_set_boxed (GrlData *data,
                        GrlKeyID key,
                        gconstpointer boxed);

Sets the first boxed value associated with `key` in `data` . If `key` already has a value, the old value is freed and the new one is set.

#### Parameters

data | data to modify |
key | key to change or add |
boxed | the new value |

Since: 0.2.0

### grl_data_set_float ()

    void
    grl_data_set_float (GrlData *data,
                        GrlKeyID key,
                        gfloat floatvalue);

Sets the first float value associated with `key` in `data` . If `key` already has a first value old value is replaced by the new one.

#### Parameters

data | data to change |
key | key to change or add. | [type GrlKeyID]
floatvalue | the new value |

Since: 0.1.5

### grl_data_set_int ()

    void
    grl_data_set_int (GrlData *data,
                      GrlKeyID key,
                      gint intvalue);

Sets the first int value associated with `key` in `data` . If `key` already has a first value old value is replaced by the new one.

#### Parameters

data | data to change |
key | key to change or add. | [type GrlKeyID]
intvalue | the new value |

Since: 0.1.4

### grl_data_set_int64 ()

    void
    grl_data_set_int64 (GrlData *data,
                        GrlKeyID key,
                        gint64 intvalue);

Sets the first int64 value associated with `key` in `data` . If `key` already has a first value old value is replaced by the new one.

#### Parameters

data | data to change |
key | key to change or add. | [type GrlKeyID]
intvalue | the new value |

Since: 0.2.12

### grl_data_set_related_keys ()

    void
    grl_data_set_related_keys (GrlData *data,
                               GrlRelatedKeys *relkeys,
                               guint index);

Updates the values at position `index` in `data` with values in `relkeys` .

`data` will take ownership of `relkeys` , so do not free it after invoking this function.

#### Parameters

data | a data |
relkeys | a set of related keys |
index | position to be updated, starting at 0 |

Since: 0.1.10

### grl_data_set_string ()

    void
    grl_data_set_string (GrlData *data,
                         GrlKeyID key,
                         const gchar *strvalue);

Sets the first string value associated with `key` in `data` . If `key` already has a value old value is freed and the new one is set.

#### Parameters

data | data to modify |
key | key to change or add. | [type GrlKeyID]
strvalue | the new value |

Since: 0.1.4

## Types and Values

### struct GrlData

    struct GrlData;

### struct GrlDataClass

    struct GrlDataClass {
      GObjectClass parent_class;
    };

Grilo Data class

#### Members

## See Also

GrlMedia