gumd API Reference Manual: GumDictionary

GumDictionary

GumDictionary — a dictionary container holding string keys and variant values

Functions

GumDictionary *	gum_dictionary_new ()
void	gum_dictionary_ref ()
void	gum_dictionary_unref ()
GumDictionary *	gum_dictionary_copy ()
GumDictionary *	gum_dictionary_new_from_variant ()
GVariant *	gum_dictionary_to_variant ()
GVariant *	gum_dictionary_get ()
gboolean	gum_dictionary_set ()
gboolean	gum_dictionary_get_boolean ()
gboolean	gum_dictionary_set_boolean ()
gboolean	gum_dictionary_get_int32 ()
gboolean	gum_dictionary_set_int32 ()
gboolean	gum_dictionary_get_uint32 ()
gboolean	gum_dictionary_set_uint32 ()
gboolean	gum_dictionary_get_int64 ()
gboolean	gum_dictionary_set_int64 ()
gboolean	gum_dictionary_get_uint64 ()
gboolean	gum_dictionary_set_uint64 ()
const gchar *	gum_dictionary_get_string ()
gboolean	gum_dictionary_set_string ()
gboolean	gum_dictionary_remove ()

Object Hierarchy

Includes

#include <gum/common/gum-dictionary.h>

Description

A GumDictionary is a dictionary data structure that maps string keys to GVariant values. It's used in multiple places in gum and its public API to pass key-value data sets.

    GumDictionary* dict = gum_dictionary_new();
    gum_dictionary_set_string(dict, "name", "John Smith");
    gum_dictionary_set_uint32(dict, "age", 32);

    guint32 age;
    gboolean success = gum_dictionary_get_uint32(dict, "age", &age);
    const gchar* name = gum_dictionary_get_string(dict, "name");
    gum_dictionary_unref(dict);

Functions

gum_dictionary_new ()

GumDictionary *
gum_dictionary_new (void);

Creates a new instance of GumDictionary.

Returns

GumDictionary object if successful, NULL otherwise.

[transfer full]

gum_dictionary_ref ()

void
gum_dictionary_ref (GumDictionary *dict);

Increments the reference count of the dictionary structure.

Parameters

dict

instance of GumDictionary.

[transfer none]

gum_dictionary_unref ()

void
gum_dictionary_unref (GumDictionary *dict);

Decrements the reference count of the dictionary structure. If the reference count reaches zero, the structure is deallocated and shouldn't be used.

Parameters

dict

instance of GumDictionary.

[transfer none]

gum_dictionary_copy ()

GumDictionary *
gum_dictionary_copy (GumDictionary *other);

Creates a copy of the dictionary.

Parameters

other

instance of GumDictionary.

[transfer none]

Returns

GumDictionary object if the copy was successful, NULL otherwise.

[transfer full]

gum_dictionary_new_from_variant ()

GumDictionary *
gum_dictionary_new_from_variant (GVariant *variant);

Converts the GVariant to GumDictionary. This is useful for example if the dictionary needs to be deserialized, or if it's contained in another GumDictionary and has been retrieved using gum_dictionary_get().

Parameters

variant

instance of GVariant.

[transfer none]

Returns

GumDictionary if successful, NULL otherwise.

[transfer full]

gum_dictionary_to_variant ()

GVariant *
gum_dictionary_to_variant (GumDictionary *dict);

Converts the GumDictionary to a GVariant. The result can be serialized or put into another GumDictionary using gum_dictionary_set().

Parameters

dict

instance of GumDictionary.

[transfer none]

Returns

GVariant object if successful, NULL otherwise.

[transfer full]

gum_dictionary_get ()

GVariant *
gum_dictionary_get (GumDictionary *dict,
                    const gchar *key);

Retrieves a GVariant value from the dictionary. This can be used to retrieve a value of an arbitrary type, and then convert it manually to a specific type using GVariant methods. For most commonly used types, also getters that return the specific type directly are provided (gum_dictionary_get_string() and similar).

Parameters

dict	instance of GumDictionary.	[transfer none]
key	the key to look up in the dictionary.	[transfer none]

Returns

the value; NULL is returned in case of failure (for example if the entry corresponding to the supplied key doesn't exist).

[transfer none]

gum_dictionary_set ()

gboolean
gum_dictionary_set (GumDictionary *dict,
                    const gchar *key,
                    GVariant *value);

Adds or replaces key-value pair in the dictionary. This allows to set a value of an arbitrary type: it first needs to be converted to a GVariant. For most commonly used types also type-specific setters are provided.

Parameters

dict	instance of GumDictionary.	[transfer none]
key	key to be set.	[transfer none]
value	value to be set.	[transfer full]

Returns

TRUE if successful, FALSE otherwise.

gum_dictionary_get_boolean ()

gboolean
gum_dictionary_get_boolean (GumDictionary *dict,
                            const gchar *key,
                            gboolean *value);

Retrieves a gboolean value.

Parameters

dict	instance of GumDictionary.	[transfer none]
key	key to look up.	[transfer none]
value	points to the location where the value should be set.	[transfer none]

Returns

TRUE if the value was retrieved successfully, FALSE otherwise.

gum_dictionary_set_boolean ()

gboolean
gum_dictionary_set_boolean (GumDictionary *dict,
                            const gchar *key,
                            gboolean value);

Sets or replaces a gboolean value in the dictionary.

Parameters

dict	instance of GumDictionary.	[transfer none]
key	key to set.	[transfer none]
value	value to set

Returns

TRUE if the value was set or replaced successfully, FALSE otherwise.

gum_dictionary_get_int32 ()

gboolean
gum_dictionary_get_int32 (GumDictionary *dict,
                          const gchar *key,
                          gint *value);

Retrieves a int32 value.

Parameters

dict	instance of GumDictionary.	[transfer none]
key	key to look up.	[transfer none]
value	points to the location where the value should be set.	[transfer none]

Returns

TRUE if the value was retrieved successfully, FALSE otherwise.

gum_dictionary_set_int32 ()

gboolean
gum_dictionary_set_int32 (GumDictionary *dict,
                          const gchar *key,
                          gint value);

Sets or replaces a int32 value in the dictionary.

Parameters

dict	instance of GumDictionary.	[transfer none]
key	key to set.	[transfer none]
value	value to set

Returns

TRUE if the value was set or replaced successfully, FALSE otherwise.

gum_dictionary_get_uint32 ()

gboolean
gum_dictionary_get_uint32 (GumDictionary *dict,
                           const gchar *key,
                           guint *value);

Retrieves a uint32 value.

Parameters

dict	instance of GumDictionary.	[transfer none]
key	key to look up.	[transfer none]
value	points to the location where the value should be set.	[transfer none]

Returns

TRUE if the value was retrieved successfully, FALSE otherwise.

gum_dictionary_set_uint32 ()

gboolean
gum_dictionary_set_uint32 (GumDictionary *dict,
                           const gchar *key,
                           guint32 value);

Sets or replaces a uint32 value in the dictionary.

Parameters

dict	instance of GumDictionary.	[transfer none]
key	key to set.	[transfer none]
value	value to set

Returns

TRUE if the value was set or replaced successfully, FALSE otherwise.

gum_dictionary_get_int64 ()

gboolean
gum_dictionary_get_int64 (GumDictionary *dict,
                          const gchar *key,
                          gint64 *value);

Retrieves a int64 value.

Parameters

dict	instance of GumDictionary.	[transfer none]
key	key to look up.	[transfer none]
value	points to the location where the value should be set.	[transfer none]

Returns

TRUE if the value was retrieved successfully, FALSE otherwise.

gum_dictionary_set_int64 ()

gboolean
gum_dictionary_set_int64 (GumDictionary *dict,
                          const gchar *key,
                          gint64 value);

Sets or replaces a int64 value in the dictionary.

Parameters

dict	instance of GumDictionary.	[transfer none]
key	key to set.	[transfer none]
value	value to set

Returns

TRUE if the value was set or replaced successfully, FALSE otherwise.

gum_dictionary_get_uint64 ()

gboolean
gum_dictionary_get_uint64 (GumDictionary *dict,
                           const gchar *key,
                           guint64 *value);

Retrieves a uint64 value.

Parameters

dict	instance of GumDictionary.	[transfer none]
key	key to look up.	[transfer none]
value	points to the location where the value should be set.	[transfer none]

Returns

TRUE if the value was retrieved successfully, FALSE otherwise.

gum_dictionary_set_uint64 ()

gboolean
gum_dictionary_set_uint64 (GumDictionary *dict,
                           const gchar *key,
                           guint64 value);

Sets or replaces a uint64 value in the dictionary.

Parameters

dict	instance of GumDictionary.	[transfer none]
key	key to set.	[transfer none]
value	value to set

Returns

TRUE if the value was set or replaced successfully, FALSE otherwise.

gum_dictionary_get_string ()

const gchar *
gum_dictionary_get_string (GumDictionary *dict,
                           const gchar *key);

Retrieves a string value.

Parameters

dict	instance of GumDictionary.	[transfer none]
key	key to look up.	[transfer none]

Returns

the value if it was retrieved successfully, NULL otherwise.

[transfer none]

gum_dictionary_set_string ()

gboolean
gum_dictionary_set_string (GumDictionary *dict,
                           const gchar *key,
                           const gchar *value);

Sets or replaces a string value in the dictionary.

Parameters

dict	instance of GumDictionary.	[transfer none]
key	key to set.	[transfer none]
value	value to set.	[transfer none]

Returns

TRUE if the value was set or replaced successfully, FALSE otherwise.

gum_dictionary_remove ()

gboolean
gum_dictionary_remove (GumDictionary *dict,
                       const gchar *key);

Removes key-value pair in the dictionary as per key.

Parameters

dict	instance of GumDictionary.	[transfer none]
key	key which needs to be removed from the dictionary.	[transfer none]

Returns

TRUE if successful, FALSE otherwise.

GumDictionary

Functions

Object Hierarchy

Includes

Description

Functions

gum_dictionary_new ()

Returns

gum_dictionary_ref ()

Parameters

gum_dictionary_unref ()

Parameters

gum_dictionary_copy ()

Parameters

Returns

gum_dictionary_new_from_variant ()

Parameters

Returns

gum_dictionary_to_variant ()

Parameters

Returns

gum_dictionary_get ()

Parameters

Returns

gum_dictionary_set ()

Parameters

Returns

gum_dictionary_get_boolean ()

Parameters

Returns

gum_dictionary_set_boolean ()

Parameters

Returns

gum_dictionary_get_int32 ()

Parameters

Returns

gum_dictionary_set_int32 ()

Parameters

Returns

gum_dictionary_get_uint32 ()

Parameters

Returns

gum_dictionary_set_uint32 ()

Parameters

Returns

gum_dictionary_get_int64 ()

Parameters

Returns

gum_dictionary_set_int64 ()

Parameters

Returns

gum_dictionary_get_uint64 ()

Parameters

Returns

gum_dictionary_set_uint64 ()

Parameters

Returns

gum_dictionary_get_string ()

Parameters

Returns

gum_dictionary_set_string ()

Parameters

Returns

gum_dictionary_remove ()

Parameters

Returns

Types and Values