GValue Support

GValue Support — GValue utilities

Synopsis

GHashTable*         soup_value_hash_new                 (void);
GHashTable*         soup_value_hash_new_with_vals       (const char *first_key,
                                                         ...);
void                soup_value_hash_insert_value        (GHashTable *hash,
                                                         const char *key,
                                                         GValue *value);
void                soup_value_hash_insert              (GHashTable *hash,
                                                         const char *key,
                                                         GType type,
                                                         ...);
void                soup_value_hash_insert_vals         (GHashTable *hash,
                                                         const char *first_key,
                                                         ...);
gboolean            soup_value_hash_lookup              (GHashTable *hash,
                                                         const char *key,
                                                         GType type,
                                                         ...);
gboolean            soup_value_hash_lookup_vals         (GHashTable *hash,
                                                         const char *first_key,
                                                         ...);

GValueArray*        soup_value_array_from_args          (va_list args);
gboolean            soup_value_array_to_args            (GValueArray *array,
                                                         va_list args);
GValueArray*        soup_value_array_new                (void);
GValueArray*        soup_value_array_new_with_vals      (GType first_type,
                                                         ...);
void                soup_value_array_insert             (GValueArray *array,
                                                         guint index_,
                                                         GType type,
                                                         ...);
void                soup_value_array_append             (GValueArray *array,
                                                         GType type,
                                                         ...);
void                soup_value_array_append_vals        (GValueArray *array,
                                                         GType first_type,
                                                         ...);
gboolean            soup_value_array_get_nth            (GValueArray *array,
                                                         guint index_,
                                                         GType type,
                                                         ...);

#define             SOUP_VALUE_SETV                     (val, type, args)
#define             SOUP_VALUE_GETV                     (val, type, args)

#define             SOUP_TYPE_BYTE_ARRAY

Description

These methods are useful for manipulating GValues, and in particular, arrays and hash tables of GValues, in a slightly nicer way than the standard GValue API.

They are written for use with soup-xmlrpc, but they also work with types not used by XML-RPC.

Details

soup_value_hash_new ()

GHashTable*         soup_value_hash_new                 (void);

Creates a GHashTable whose keys are strings and whose values are GValue.

Returns : a new empty GHashTable

soup_value_hash_new_with_vals ()

GHashTable*         soup_value_hash_new_with_vals       (const char *first_key,
                                                         ...);

Creates a GHashTable whose keys are strings and whose values are GValue, and initializes it with the provided data. As with soup_value_hash_insert(), the keys and values are copied rather than being inserted directly.

first_key : the key for the first value
... : the type of first_key, followed by the value, followed by additional key/type/value triplets, terminated by NULL
Returns : a new GHashTable, initialized with the given values

soup_value_hash_insert_value ()

void                soup_value_hash_insert_value        (GHashTable *hash,
                                                         const char *key,
                                                         GValue *value);

Inserts value into hash. (Unlike with g_hash_table_insert(), both the key and the value are copied).

hash : a value hash
key : the key
value : a value

soup_value_hash_insert ()

void                soup_value_hash_insert              (GHashTable *hash,
                                                         const char *key,
                                                         GType type,
                                                         ...);

Inserts the provided value of type type into hash. (Unlike with g_hash_table_insert(), both the key and the value are copied).

hash : a value hash
key : the key
type : a GType
... : a value of type type

soup_value_hash_insert_vals ()

void                soup_value_hash_insert_vals         (GHashTable *hash,
                                                         const char *first_key,
                                                         ...);

Inserts the given data into hash. As with soup_value_hash_insert(), the keys and values are copied rather than being inserted directly.

hash : a value hash
first_key : the key for the first value
... : the type of first_key, followed by the value, followed by additional key/type/value triplets, terminated by NULL

soup_value_hash_lookup ()

gboolean            soup_value_hash_lookup              (GHashTable *hash,
                                                         const char *key,
                                                         GType type,
                                                         ...);

Looks up key in hash and stores its value into the provided location.

hash : a value hash
key : the key to look up
type : a GType
... : a value of type pointer-to-type
Returns : TRUE if hash contained a value with key key and type type, FALSE if not.

soup_value_hash_lookup_vals ()

gboolean            soup_value_hash_lookup_vals         (GHashTable *hash,
                                                         const char *first_key,
                                                         ...);

Looks up a number of keys in hash and returns their values.

hash : a value hash
first_key : the first key to look up
... : the type of first_key, a pointer to that type, and then additional key/type/pointer triplets, terminated by NULL.
Returns : TRUE if all of the keys were found, FALSE if any were missing; note that you will generally need to initialize each destination variable to a reasonable default value, since there is no way to tell which keys were found and which were not.

soup_value_array_from_args ()

GValueArray*        soup_value_array_from_args          (va_list args);

Creates a GValueArray from the provided arguments, which must consist of pairs of a GType and a value of that type, terminated by G_TYPE_INVALID. (The array will contain copies of the provided data rather than pointing to the passed-in data directly.)

args : arguments to create a GValueArray from
Returns : a new GValueArray, or NULL if an error occurred.

soup_value_array_to_args ()

gboolean            soup_value_array_to_args            (GValueArray *array,
                                                         va_list args);

Extracts a GValueArray into the provided arguments, which must consist of pairs of a GType and a value of pointer-to-that-type, terminated by G_TYPE_INVALID. The returned values will point to the same memory as the values in the array.

array : a GValueArray
args : arguments to extract array into
Returns : success or failure

soup_value_array_new ()

GValueArray*        soup_value_array_new                (void);

Creates a new GValueArray. (This is just a wrapper around g_value_array_new(), for naming consistency purposes.)

Returns : a new GValueArray

soup_value_array_new_with_vals ()

GValueArray*        soup_value_array_new_with_vals      (GType first_type,
                                                         ...);

Creates a new GValueArray and copies the provided values into it.

first_type : the type of the first value to add
... : the first value to add, followed by other type/value pairs, terminated by G_TYPE_INVALID
Returns : a new GValueArray

soup_value_array_insert ()

void                soup_value_array_insert             (GValueArray *array,
                                                         guint index_,
                                                         GType type,
                                                         ...);

Inserts the provided value of type type into array as with g_value_array_insert(). (The provided data is copied rather than being inserted directly.)

array : a GValueArray
index_ : the index to insert at
type : a GType
... : a value of type type

soup_value_array_append ()

void                soup_value_array_append             (GValueArray *array,
                                                         GType type,
                                                         ...);

Appends the provided value of type type to array as with g_value_array_append(). (The provided data is copied rather than being inserted directly.)

array : a GValueArray
type : a GType
... : a value of type type

soup_value_array_append_vals ()

void                soup_value_array_append_vals        (GValueArray *array,
                                                         GType first_type,
                                                         ...);

Appends the provided values into array as with g_value_array_append(). (The provided data is copied rather than being inserted directly.)

array : a GValueArray
first_type : the type of the first value to add
... : the first value to add, followed by other type/value pairs, terminated by G_TYPE_INVALID

soup_value_array_get_nth ()

gboolean            soup_value_array_get_nth            (GValueArray *array,
                                                         guint index_,
                                                         GType type,
                                                         ...);

Gets the index_ element of array and stores its value into the provided location.

array : a GValueArray
index_ : the index to look up
type : a GType
... : a value of type pointer-to-type
Returns : TRUE if array contained a value with index index_ and type type, FALSE if not.

SOUP_VALUE_SETV()

#define             SOUP_VALUE_SETV(val, type, args)

Copies an argument of type type from args into val. val will point directly to the value in args rather than copying it, so you must g_value_copy() it if you want it to remain valid.

val : a GValue
type : a GType
args : va_list pointing to a value of type type

SOUP_VALUE_GETV()

#define             SOUP_VALUE_GETV(val, type, args)

Extracts a value of type type from val into args. The return value will point to the same data as val rather than being a copy of it.

val : a GValue
type : a GType
args : va_list pointing to a value of type pointer-to-type

SOUP_TYPE_BYTE_ARRAY

#define SOUP_TYPE_BYTE_ARRAY (soup_byte_array_get_type ())

glib does not define a GType for GByteArray, so libsoup defines this one itself.

Generated by GTK-Doc V1.10