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 ()
void	grl_data_add_int ()
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 ()
gint	grl_data_get_int ()
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_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_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_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

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_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_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_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