libsoup Reference Manual: GValue Support

GValue Support

GValue Support — GValue utilities

Functions

GHashTable *	soup_value_hash_new ()
GHashTable *	soup_value_hash_new_with_vals ()
void	soup_value_hash_insert_value ()
void	soup_value_hash_insert ()
void	soup_value_hash_insert_vals ()
gboolean	soup_value_hash_lookup ()
gboolean	soup_value_hash_lookup_vals ()
GValueArray *	soup_value_array_from_args ()
gboolean	soup_value_array_to_args ()
GValueArray *	soup_value_array_new ()
GValueArray *	soup_value_array_new_with_vals ()
void	soup_value_array_insert ()
void	soup_value_array_append ()
void	soup_value_array_append_vals ()
gboolean	soup_value_array_get_nth ()
#define	SOUP_VALUE_SETV()
#define	SOUP_VALUE_GETV()
#define	SOUP_TYPE_BYTE_ARRAY

Object Hierarchy

Includes

#include <libsoup/soup.h>

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.

Functions

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.

[element-type utf8 GValue][transfer full]

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.

Parameters

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.

[element-type utf8 GValue][transfer full]

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

Parameters

hash	a value hash.	[element-type utf8 GValue]
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).

Parameters

hash	a value hash.	[element-type utf8 GValue]
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.

Parameters

hash	a value hash.	[element-type utf8 GValue]
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.

Parameters

hash	a value hash.	[element-type utf8 GValue]
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.

Parameters

hash	a value hash.	[element-type utf8 GValue]
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.)

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 did not used to define a GType for GByteArray, so libsoup defines this one itself.

GValue Support

Functions

Object Hierarchy

Includes

Description

Functions

soup_value_hash_new ()

Returns

soup_value_hash_new_with_vals ()

Parameters

Returns

soup_value_hash_insert_value ()

Parameters

soup_value_hash_insert ()

Parameters

soup_value_hash_insert_vals ()

Parameters

soup_value_hash_lookup ()

Parameters

Returns

soup_value_hash_lookup_vals ()

Parameters

Returns

soup_value_array_from_args ()

Parameters

Returns

soup_value_array_to_args ()

Parameters

Returns

soup_value_array_new ()

Returns

soup_value_array_new_with_vals ()

Parameters

Returns

soup_value_array_insert ()

Parameters

soup_value_array_append ()

Parameters

soup_value_array_append_vals ()

Parameters

soup_value_array_get_nth ()

Parameters

Returns

SOUP_VALUE_SETV()

Parameters

SOUP_VALUE_GETV()

Parameters

SOUP_TYPE_BYTE_ARRAY

Types and Values