GumDictionary

GumDictionary — a dictionary container holding string keys and variant values

Synopsis

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

typedef             GumDictionary;
GumDictionary *     gum_dictionary_copy                 (GumDictionary *other);
GVariant *          gum_dictionary_get                  (GumDictionary *dict,
                                                         const gchar *key);
gboolean            gum_dictionary_get_boolean          (GumDictionary *dict,
                                                         const gchar *key,
                                                         gboolean *value);
gboolean            gum_dictionary_get_int32            (GumDictionary *dict,
                                                         const gchar *key,
                                                         gint *value);
gboolean            gum_dictionary_get_int64            (GumDictionary *dict,
                                                         const gchar *key,
                                                         gint64 *value);
const gchar *       gum_dictionary_get_string           (GumDictionary *dict,
                                                         const gchar *key);
gboolean            gum_dictionary_get_uint32           (GumDictionary *dict,
                                                         const gchar *key,
                                                         guint *value);
gboolean            gum_dictionary_get_uint64           (GumDictionary *dict,
                                                         const gchar *key,
                                                         guint64 *value);
GumDictionary *     gum_dictionary_new                  (void);
GumDictionary *     gum_dictionary_new_from_variant     (GVariant *variant);
void                gum_dictionary_ref                  (GumDictionary *dict);
gboolean            gum_dictionary_remove               (GumDictionary *dict,
                                                         const gchar *key);
gboolean            gum_dictionary_set                  (GumDictionary *dict,
                                                         const gchar *key,
                                                         GVariant *value);
gboolean            gum_dictionary_set_boolean          (GumDictionary *dict,
                                                         const gchar *key,
                                                         gboolean value);
gboolean            gum_dictionary_set_int32            (GumDictionary *dict,
                                                         const gchar *key,
                                                         gint value);
gboolean            gum_dictionary_set_int64            (GumDictionary *dict,
                                                         const gchar *key,
                                                         gint64 value);
gboolean            gum_dictionary_set_string           (GumDictionary *dict,
                                                         const gchar *key,
                                                         const gchar *value);
gboolean            gum_dictionary_set_uint32           (GumDictionary *dict,
                                                         const gchar *key,
                                                         guint32 value);
gboolean            gum_dictionary_set_uint64           (GumDictionary *dict,
                                                         const gchar *key,
                                                         guint64 value);
GVariant *          gum_dictionary_to_variant           (GumDictionary *dict);
void                gum_dictionary_unref                (GumDictionary *dict);

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);

Details

GumDictionary

typedef GHashTable GumDictionary;

GumDictionary is a typedef for GHashTable, which means the developers may also use methods associated with that structure.

gum_dictionary_copy ()

GumDictionary *     gum_dictionary_copy                 (GumDictionary *other);

Creates a copy of the dictionary.

other :

 instance of GumDictionary. [transfer none]

Returns :

 GumDictionary object if the copy was 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).

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

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

Retrieves a gboolean value.

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

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

Retrieves a int32 value.

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

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

Retrieves a int64 value.

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

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

Retrieves a string value.

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

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

Retrieves a uint32 value.

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

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

Retrieves a uint64 value.

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

GumDictionary *     gum_dictionary_new                  (void);

Creates a new instance of GumDictionary.

Returns :

 GumDictionary object if 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().

variant :

 instance of GVariant. [transfer none]

Returns :

 GumDictionary if successful, NULL otherwise. [transfer full]

gum_dictionary_ref ()

void                gum_dictionary_ref                  (GumDictionary *dict);

Increments the reference count of the dictionary structure.

dict :

 instance of GumDictionary. [transfer none]

gum_dictionary_remove ()

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

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

dict :

 instance of GumDictionary. [transfer none]

key :

 key which needs to be removed from the dictionary. [transfer none]

Returns :

 TRUE if successful, FALSE otherwise.

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.

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

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

Sets or replaces a gboolean value in the dictionary.

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

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

Sets or replaces a int32 value in the dictionary.

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

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

Sets or replaces a int64 value in the dictionary.

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

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

Sets or replaces a string value in the dictionary.

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

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

Sets or replaces a uint32 value in the dictionary.

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

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

Sets or replaces a uint64 value in the dictionary.

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

dict :

 instance of GumDictionary. [transfer none]

Returns :

 GVariant object if successful, NULL otherwise. [transfer full]

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.

dict :

 instance of GumDictionary. [transfer none]
Generated by GTK-Doc V1.18