GrlRelatedKeys

GrlRelatedKeys — A class where to store related metadata keys.

Synopsis

#include <grilo.h>

struct              GrlRelatedKeys;
struct              GrlRelatedKeysClass;
GrlRelatedKeys *    grl_related_keys_new                (void);
GrlRelatedKeys *    grl_related_keys_new_valist         (GrlKeyID key,
                                                         va_list args);
GrlRelatedKeys *    grl_related_keys_new_with_keys      (GrlKeyID key,
                                                         ...);
GrlRelatedKeys *    grl_related_keys_dup                (GrlRelatedKeys *relkeys);
const GValue *      grl_related_keys_get                (GrlRelatedKeys *relkeys,
                                                         GrlKeyID key);
const guint8 *      grl_related_keys_get_binary         (GrlRelatedKeys *relkeys,
                                                         GrlKeyID key,
                                                         gsize *size);
gconstpointer       grl_related_keys_get_boxed          (GrlRelatedKeys *relkeys,
                                                         GrlKeyID key);
gfloat              grl_related_keys_get_float          (GrlRelatedKeys *relkeys,
                                                         GrlKeyID key);
gint                grl_related_keys_get_int            (GrlRelatedKeys *relkeys,
                                                         GrlKeyID key);
GList *             grl_related_keys_get_keys           (GrlRelatedKeys *relkeys);
const gchar *       grl_related_keys_get_string         (GrlRelatedKeys *relkeys,
                                                         GrlKeyID key);
gboolean            grl_related_keys_has_key            (GrlRelatedKeys *relkeys,
                                                         GrlKeyID key);
void                grl_related_keys_set                (GrlRelatedKeys *relkeys,
                                                         GrlKeyID key,
                                                         const GValue *value);
void                grl_related_keys_set_binary         (GrlRelatedKeys *relkeys,
                                                         GrlKeyID key,
                                                         const guint8 *buf,
                                                         gsize size);
void                grl_related_keys_set_boxed          (GrlRelatedKeys *relkeys,
                                                         GrlKeyID key,
                                                         gconstpointer boxed);
void                grl_related_keys_set_float          (GrlRelatedKeys *relkeys,
                                                         GrlKeyID key,
                                                         gfloat floatvalue);
void                grl_related_keys_set_int            (GrlRelatedKeys *relkeys,
                                                         GrlKeyID key,
                                                         gint intvalue);
void                grl_related_keys_set_string         (GrlRelatedKeys *relkeys,
                                                         GrlKeyID key,
                                                         const gchar *strvalue);

Object Hierarchy

  GObject
   +----GrlRelatedKeys

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.

Details

struct GrlRelatedKeys

struct GrlRelatedKeys;

struct GrlRelatedKeysClass

struct GrlRelatedKeysClass {
  GObjectClass parent_class;
};

Grilo Data Multivalued class

GObjectClass parent_class;

the parent class structure

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.

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.

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.

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.

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.

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

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.

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.

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_keys ()

GList *             grl_related_keys_get_keys           (GrlRelatedKeys *relkeys);

Returns a list with keys contained in relkeys.

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.

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.

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.

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.

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

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.

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

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

relkeys :

set of related keys to modify

key :

key to change or add. [type GrlKeyID]

strvalue :

the new value

Since 0.1.10

See Also

GrlRegistry, GrlData