Specializable GType System

Specializable GType System — Specialized GTypes

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <dbus/dbus-glib.h>

void                (*DBusGTypeSpecializedCollectionIterator)
                                                        (const GValue *value,
                                                         gpointer user_data);
void                (*DBusGTypeSpecializedMapIterator)  (const GValue *key_val,
                                                         const GValue *value_val,
                                                         gpointer user_data);
                    DBusGTypeSpecializedAppendContext;
gpointer            (*DBusGTypeSpecializedConstructor)  (GType type);
void                (*DBusGTypeSpecializedFreeFunc)     (GType type,
                                                         gpointer val);
gpointer            (*DBusGTypeSpecializedCopyFunc)     (GType type,
                                                         gpointer src);
                    DBusGTypeSpecializedVtable;
gboolean            (*DBusGTypeSpecializedCollectionFixedAccessorFunc)
                                                        (GType type,
                                                         gpointer instance,
                                                         gpointer *values,
                                                         guint *len);
void                (*DBusGTypeSpecializedCollectionIteratorFunc)
                                                        (GType type,
                                                         gpointer instance,
                                                         DBusGTypeSpecializedCollectionIterator iterator,
                                                         gpointer user_data);
void                (*DBusGTypeSpecializedCollectionAppendFunc)
                                                        (DBusGTypeSpecializedAppendContext *ctx,
                                                         GValue *val);
void                (*DBusGTypeSpecializedCollectionEndAppendFunc)
                                                        (DBusGTypeSpecializedAppendContext *ctx);
                    DBusGTypeSpecializedCollectionVtable;
void                (*DBusGTypeSpecializedMapIteratorFunc)
                                                        (GType type,
                                                         gpointer instance,
                                                         DBusGTypeSpecializedMapIterator iterator,
                                                         gpointer user_data);
void                (*DBusGTypeSpecializedMapAppendFunc)
                                                        (DBusGTypeSpecializedAppendContext *ctx,
                                                         GValue *key,
                                                         GValue *val);
                    DBusGTypeSpecializedMapVtable;
gboolean            (*DBusGTypeSpecializedStructGetMember)
                                                        (GType type,
                                                         gpointer instance,
                                                         guint member,
                                                         GValue *ret_value);
gboolean            (*DBusGTypeSpecializedStructSetMember)
                                                        (GType type,
                                                         gpointer instance,
                                                         guint member,
                                                         const GValue *new_value);
                    DBusGTypeSpecializedStructVtable;
GType               dbus_g_type_get_collection          (const char *container,
                                                         GType specialization);
GType               dbus_g_type_get_map                 (const char *container,
                                                         GType key_specialization,
                                                         GType value_specialization);
GType               dbus_g_type_get_structv             (const char *container,
                                                         guint num_members,
                                                         GType *types);
GType               dbus_g_type_get_struct              (const char *container,
                                                         GType first_type,
                                                         ...);
gboolean            dbus_g_type_is_collection           (GType gtype);
gboolean            dbus_g_type_is_map                  (GType gtype);
gboolean            dbus_g_type_is_struct               (GType gtype);
GType               dbus_g_type_get_collection_specialization
                                                        (GType gtype);
GType               dbus_g_type_get_map_key_specialization
                                                        (GType gtype);
GType               dbus_g_type_get_map_value_specialization
                                                        (GType gtype);
GType               dbus_g_type_get_struct_member_type  (GType gtype,
                                                         guint member);
guint               dbus_g_type_get_struct_size         (GType gtype);
gpointer            dbus_g_type_specialized_construct   (GType gtype);
void                dbus_g_type_specialized_init_append (GValue *value,
                                                         DBusGTypeSpecializedAppendContext *ctx);
void                dbus_g_type_specialized_collection_append
                                                        (DBusGTypeSpecializedAppendContext *ctx,
                                                         GValue *elt);
void                dbus_g_type_specialized_collection_end_append
                                                        (DBusGTypeSpecializedAppendContext *ctx);
void                dbus_g_type_specialized_map_append  (DBusGTypeSpecializedAppendContext *ctx,
                                                         GValue *key,
                                                         GValue *val);
gboolean            dbus_g_type_collection_get_fixed    (GValue *value,
                                                         gpointer *data_ret,
                                                         guint *len_ret);
void                dbus_g_type_collection_value_iterate
                                                        (const GValue *value,
                                                         DBusGTypeSpecializedCollectionIterator iterator,
                                                         gpointer user_data);
void                dbus_g_type_map_value_iterate       (const GValue *value,
                                                         DBusGTypeSpecializedMapIterator iterator,
                                                         gpointer user_data);
gboolean            dbus_g_type_struct_get_member       (const GValue *value,
                                                         guint member,
                                                         GValue *dest);
gboolean            dbus_g_type_struct_set_member       (GValue *value,
                                                         guint member,
                                                         const GValue *src);
gboolean            dbus_g_type_struct_get              (const GValue *value,
                                                         guint member,
                                                         ...);
gboolean            dbus_g_type_struct_set              (GValue *value,
                                                         guint member,
                                                         ...);
void                dbus_g_type_specialized_init        (void);
void                dbus_g_type_register_collection     (const char *name,
                                                         const DBusGTypeSpecializedCollectionVtable *vtable,
                                                         guint flags);
void                dbus_g_type_register_map            (const char *name,
                                                         const DBusGTypeSpecializedMapVtable *vtable,
                                                         guint flags);
const DBusGTypeSpecializedMapVtable * dbus_g_type_map_peek_vtable
                                                        (GType map_type);
const DBusGTypeSpecializedCollectionVtable * dbus_g_type_collection_peek_vtable
                                                        (GType collection_type);
const DBusGTypeSpecializedStructVtable * dbus_g_type_struct_peek_vtable
                                                        (GType struct_type);
void                dbus_g_type_register_struct         (const char *name,
                                                         const DBusGTypeSpecializedStructVtable *vtable,
                                                         guint flags);
GVariant *          dbus_g_value_build_g_variant        (const GValue *value);
void                dbus_g_value_parse_g_variant        (GVariant *variant,
                                                         GValue *value);
#define             DBUS_TYPE_G_BOOLEAN_ARRAY
#define             DBUS_TYPE_G_UCHAR_ARRAY
#define             DBUS_TYPE_G_UINT_ARRAY
#define             DBUS_TYPE_G_INT_ARRAY
#define             DBUS_TYPE_G_UINT64_ARRAY
#define             DBUS_TYPE_G_INT64_ARRAY
#define             DBUS_TYPE_G_OBJECT_ARRAY
#define             DBUS_TYPE_G_STRING_STRING_HASHTABLE
typedef             DBusGSignature;
#define             DBUS_TYPE_G_SIGNATURE
typedef             DBusGObjectPath;
#define             DBUS_TYPE_G_OBJECT_PATH

Description

Specialized gtypes are basically a way to allow the definition of recursive GTypes. It allows the definition of 'containers' which is basically a user defined structure capable of holding other data, and a set of functions defining how to access that structure. Containers come in 3 flavors: collections, maps and structs.

A collection is a container that holds an ordered set of items, all of which must be the same type. (This is an array in standard D-Bus terminology.) dbus-glib specialized collections can be GArray (for numeric elements), GPtrArray (for string, object or boxed elements), GSList (for boxed elements, not recommended), or a user-defined type.

A map is a container that holds a set of key/value pairs. The keys have one type, and the values another; the type of the keys must be a numeric or string-like type. (This is a dict (dictionary) or array of dict entry in standard D-Bus terminology.) dbus-glib specialized maps can be GHashTable or a user-defined type.

A struct is a container that holds a fixed number of members, each member having a predefined type. (This is a struct in standard D-Bus terminology.) It is analogous to the C struct keyword, but dbus-glib does not generally represent D-Bus structs in C structs. dbus-glib specialized structs can be GValueArray or a user-defined type.

A specialization is a GType detailing a particular container with particular types (a type specialization).

Functions are provided for constructing and manipulating specializations.

This documentation needs splitting into two pages, one for defining new containers and using existing containers. I expect most users to only do the latter. I also need to add some examples.

Details

DBusGTypeSpecializedCollectionIterator ()

void                (*DBusGTypeSpecializedCollectionIterator)
                                                        (const GValue *value,
                                                         gpointer user_data);

A library-user-supplied function, called for each element in the collection when dbus_g_type_collection_value_iterate() is called.

value :

an element of the collection

user_data :

the data supplied when calling dbus_g_type_collection_value_iterate()

DBusGTypeSpecializedMapIterator ()

void                (*DBusGTypeSpecializedMapIterator)  (const GValue *key_val,
                                                         const GValue *value_val,
                                                         gpointer user_data);

A library-user-supplied function, called for each key/value pair in the collection when dbus_g_type_map_value_iterate() is called.

key_val :

a key from the map

value_val :

a value from the map

user_data :

the data supplied when calling dbus_g_type_map_value_iterate()

DBusGTypeSpecializedAppendContext

typedef struct {
  /* public */
  GValue *val;
  GType specialization_type;
} DBusGTypeSpecializedAppendContext;

A context for appending. There are more fields, which are private.

GValue *val;

the GValue containing the array to which you're appending

GType specialization_type;

the GType of the array's elements

DBusGTypeSpecializedConstructor ()

gpointer            (*DBusGTypeSpecializedConstructor)  (GType type);

type :

a specialized boxed type

Returns :

a new instance of type

DBusGTypeSpecializedFreeFunc ()

void                (*DBusGTypeSpecializedFreeFunc)     (GType type,
                                                         gpointer val);

Frees val according to type. This is analogous to GBoxedFreeFunc, but can use information from type (for instance to free the contents of a container before freeing the actual container).

type :

a specialized boxed type

val :

an instance of type

DBusGTypeSpecializedCopyFunc ()

gpointer            (*DBusGTypeSpecializedCopyFunc)     (GType type,
                                                         gpointer src);

Copies src according to type. This is analogous to GBoxedCopyFunc, but can use information from type (for instance to copy each element of a collection).

type :

a specialized boxed type

src :

an instance of type

Returns :

a deep copy of src

DBusGTypeSpecializedVtable

typedef struct {
  DBusGTypeSpecializedConstructor    constructor;
  DBusGTypeSpecializedFreeFunc       free_func;
  DBusGTypeSpecializedCopyFunc       copy_func;
  GDestroyNotify                     simple_free_func; /* for type-independent freeing if possible */
} DBusGTypeSpecializedVtable;

A table of methods used to implement specialized container behaviour on user-defined collections, maps and structs. Exactly one of free_func and simple_free_func must be implemented; the other must be NULL. constructor and copy_func must always be implemented.

There are additional members, which are reserved for future expansion and must be NULL.

DBusGTypeSpecializedConstructor constructor;

returns a new, blank instance of the type

DBusGTypeSpecializedFreeFunc free_func;

if not NULL, frees the type instance val

DBusGTypeSpecializedCopyFunc copy_func;

returns a "deep copy" of the type instance val

GDestroyNotify simple_free_func;

if not NULL, frees its argument

DBusGTypeSpecializedCollectionFixedAccessorFunc ()

gboolean            (*DBusGTypeSpecializedCollectionFixedAccessorFunc)
                                                        (GType type,
                                                         gpointer instance,
                                                         gpointer *values,
                                                         guint *len);

Implements dbus_g_type_collection_get_fixed() for a GValue with type type, containing instance.

type :

a specialized collection boxed type

instance :

an instance of type

values :

used to return a pointer to the contents of instance

len :

used to return the number of elements in instance

Returns :

TRUE on success

DBusGTypeSpecializedCollectionIteratorFunc ()

void                (*DBusGTypeSpecializedCollectionIteratorFunc)
                                                        (GType type,
                                                         gpointer instance,
                                                         DBusGTypeSpecializedCollectionIterator iterator,
                                                         gpointer user_data);

Implements dbus_g_type_collection_value_iterate() for a GValue with type type, containing instance.

type :

a specialized collection boxed type

instance :

an instance of type

iterator :

the function to call for each element

user_data :

data to pass to iterator

DBusGTypeSpecializedCollectionAppendFunc ()

void                (*DBusGTypeSpecializedCollectionAppendFunc)
                                                        (DBusGTypeSpecializedAppendContext *ctx,
                                                         GValue *val);

Implements dbus_g_type_specialized_collection_append().

This function should use the val and specialization_type members of ctx.

ctx :

an appending context returned by dbus_g_type_specialized_init_append()

val :

a value to copy into the collection

DBusGTypeSpecializedCollectionEndAppendFunc ()

void                (*DBusGTypeSpecializedCollectionEndAppendFunc)
                                                        (DBusGTypeSpecializedAppendContext *ctx);

Implements dbus_g_type_specialized_collection_end_append().

This function should use the val and specialization_type members of ctx.

ctx :

an appending context returned by dbus_g_type_specialized_init_append()

DBusGTypeSpecializedCollectionVtable

typedef struct {
  DBusGTypeSpecializedVtable                        base_vtable;
  DBusGTypeSpecializedCollectionFixedAccessorFunc   fixed_accessor;
  DBusGTypeSpecializedCollectionIteratorFunc        iterator;
  DBusGTypeSpecializedCollectionAppendFunc          append_func;
  DBusGTypeSpecializedCollectionEndAppendFunc       end_append_func;
} DBusGTypeSpecializedCollectionVtable;

A table of methods used to implement specialized collection behaviour on user-defined types. At least iterator and append_func must be implemented.

DBusGTypeSpecializedVtable base_vtable;

base methods shared between collections and other types

DBusGTypeSpecializedCollectionFixedAccessorFunc fixed_accessor;

if not NULL, provides access to the contents of this collection, as documented for dbus_g_type_collection_get_fixed()

DBusGTypeSpecializedCollectionIteratorFunc iterator;

iterates through the members of instance

DBusGTypeSpecializedCollectionAppendFunc append_func;

appends a new member to instance

DBusGTypeSpecializedCollectionEndAppendFunc end_append_func;

if not NULL, called after each group of calls to the append_func

DBusGTypeSpecializedMapIteratorFunc ()

void                (*DBusGTypeSpecializedMapIteratorFunc)
                                                        (GType type,
                                                         gpointer instance,
                                                         DBusGTypeSpecializedMapIterator iterator,
                                                         gpointer user_data);

Implements dbus_g_type_map_value_iterate() for a GValue with type type, containing instance.

type :

a specialized map boxed type

instance :

an instance of type

iterator :

the function to call for each key/value pair

user_data :

data to pass to iterator

DBusGTypeSpecializedMapAppendFunc ()

void                (*DBusGTypeSpecializedMapAppendFunc)
                                                        (DBusGTypeSpecializedAppendContext *ctx,
                                                         GValue *key,
                                                         GValue *val);

Implements dbus_g_type_specialized_map_append().

This function should use the val and specialization_type members of ctx, and replace any existing value with key equal to key.

ctx :

an appending context returned by dbus_g_type_specialized_init_append()

key :

a key to add to the collection

val :

a value to add to the collection

DBusGTypeSpecializedMapVtable

typedef struct {
  DBusGTypeSpecializedVtable                        base_vtable;
  DBusGTypeSpecializedMapIteratorFunc               iterator;
  DBusGTypeSpecializedMapAppendFunc                 append_func;
} DBusGTypeSpecializedMapVtable;

A table of methods used to implement specialized collection behaviour on user-defined types. Both methods must be implemented.

DBusGTypeSpecializedVtable base_vtable;

base methods shared between maps and other types

DBusGTypeSpecializedMapIteratorFunc iterator;

iterates through the members of instance

DBusGTypeSpecializedMapAppendFunc append_func;

adds a new key/value pair to instance

DBusGTypeSpecializedStructGetMember ()

gboolean            (*DBusGTypeSpecializedStructGetMember)
                                                        (GType type,
                                                         gpointer instance,
                                                         guint member,
                                                         GValue *ret_value);

Implements dbus_g_type_struct_get_member() for a GValue with type type, containing instance.

type :

a specialized struct boxed type

instance :

an instance of type

member :

the index of the member, starting from 0

ret_value :

an initialized GValue of the appropriate type for the given member of type

Returns :

TRUE on success

DBusGTypeSpecializedStructSetMember ()

gboolean            (*DBusGTypeSpecializedStructSetMember)
                                                        (GType type,
                                                         gpointer instance,
                                                         guint member,
                                                         const GValue *new_value);

Implements dbus_g_type_struct_set_member() for a GValue with type type, containing instance.

type :

a specialized struct boxed type

instance :

an instance of type

member :

the index of the member, starting from 0

new_value :

an initialized GValue of the appropriate type for the given member of type

Returns :

TRUE on success

DBusGTypeSpecializedStructVtable

typedef struct {
  DBusGTypeSpecializedVtable                        base_vtable;
  DBusGTypeSpecializedStructGetMember               get_member;
  DBusGTypeSpecializedStructSetMember               set_member;
} DBusGTypeSpecializedStructVtable;

A table of methods used to implement specialized collection behaviour on user-defined types. Both methods must be implemented.

DBusGTypeSpecializedVtable base_vtable;

base methods shared between maps and other types

DBusGTypeSpecializedStructGetMember get_member;

returns a member by its index

DBusGTypeSpecializedStructSetMember set_member;

sets a member by its index

dbus_g_type_get_collection ()

GType               dbus_g_type_get_collection          (const char *container,
                                                         GType specialization);

Gets a GType for a particular collection instance, creating the type if not already created.

container :

a string specifying a registered collection type

specialization :

GType of collection elements

Returns :

the GType of that instance

dbus_g_type_get_map ()

GType               dbus_g_type_get_map                 (const char *container,
                                                         GType key_specialization,
                                                         GType value_specialization);

Gets a GType for a particular map instance, creating the type if not already created.

container :

a string specifying a registered map type

key_specialization :

GType of keys

value_specialization :

GType of values

Returns :

the GType of that instance

dbus_g_type_get_structv ()

GType               dbus_g_type_get_structv             (const char *container,
                                                         guint num_members,
                                                         GType *types);

Gets a GType for a particular struct instance, creating the type if not already created.

container :

a string specifying a registered struct type

num_members :

number of members in the struct

types :

an array specufying a GType for each struct element

Returns :

the GType of that instance

dbus_g_type_get_struct ()

GType               dbus_g_type_get_struct              (const char *container,
                                                         GType first_type,
                                                         ...);

Varags methsod to get a GType for a particular struct instance, creating the type if not already created.

container :

a string specifying a registered struct type

first_type :

GType for the struct's first member

... :

more GTypes for the struct's members, terminated by G_TYPE_INVALID

Returns :

the GType of that instance

dbus_g_type_is_collection ()

gboolean            dbus_g_type_is_collection           (GType gtype);

Tests if a given GType is a collection.

gtype :

a GType to test

Returns :

true if the given GType is a collection

dbus_g_type_is_map ()

gboolean            dbus_g_type_is_map                  (GType gtype);

Tests if a given GType is a map, i.e. it was created with dbus_g_type_get_map().

gtype :

a GType to test

Returns :

true if the given GType is a map

dbus_g_type_is_struct ()

gboolean            dbus_g_type_is_struct               (GType gtype);

Tests if a given GType is a struct, i.e. it was created with dbus_g_type_get_struct()

gtype :

a GType to test

Returns :

true if the given GType is a struct

dbus_g_type_get_collection_specialization ()

GType               dbus_g_type_get_collection_specialization
                                                        (GType gtype);

Return the type of each element in collections of type gtype. It is an error to call this function on a non-collection type.

gtype :

a collection GType, as created by dbus_g_type_get_collection()

Returns :

the element type for a given collection GType.

dbus_g_type_get_map_key_specialization ()

GType               dbus_g_type_get_map_key_specialization
                                                        (GType gtype);

Return the type of the keys in maps of type gtype. It is an error to call this function on a non-map type.

gtype :

a map GType, as created by dbus_g_type_get_map()

Returns :

the key type for a given map GType.

dbus_g_type_get_map_value_specialization ()

GType               dbus_g_type_get_map_value_specialization
                                                        (GType gtype);

Return the type of the values in maps of type gtype. It is an error to call this function on a non-map type.

gtype :

a map GType, as created by dbus_g_type_get_map().

Returns :

the value type for a given map GType.

dbus_g_type_get_struct_member_type ()

GType               dbus_g_type_get_struct_member_type  (GType gtype,
                                                         guint member);

Get the type of a member of a specialized struct. It is an error to call this function on a non-struct type.

gtype :

a struct GType, as created with dbus_g_type_get_struct()

member :

the index of a struct member

Returns :

the type for a given member of a struct GType, or G_TYPE_INVALID if member >= dbus_g_type_get_struct_size()

dbus_g_type_get_struct_size ()

guint               dbus_g_type_get_struct_size         (GType gtype);

Get the number of members in a specialized struct. It is an error to call this function on a non-struct type.

gtype :

a struct GType, as created with dbus_g_type_get_struct().

Returns :

the number of members in a given struct GType.

dbus_g_type_specialized_construct ()

gpointer            dbus_g_type_specialized_construct   (GType gtype);

Create an instance of a given specialized type. The structure created and returned will depend on the container type of the GType. E.g. If the given type was created by dbus_g_type_get_collection("GArray", G_TYPE_INT), then this will return a GArray with element_size of sizeof(int)

gtype :

a specialized GType, as created by dbus_g_type_get_collection(), dbus_g_type_get_map() or dbus_g_type_get_struct()

Returns :

a pointer to a newly constructed instance of the given type.

dbus_g_type_specialized_init_append ()

void                dbus_g_type_specialized_init_append (GValue *value,
                                                         DBusGTypeSpecializedAppendContext *ctx);

Create a new context for adding elements to a collection or key/value pairs to a map. You generally don't need or want to use this..

value :

a GValue containing an instance of specialized type

ctx :

a DBusGTypeSpecializedAppendContext in which to return a new appending context.

dbus_g_type_specialized_collection_append ()

void                dbus_g_type_specialized_collection_append
                                                        (DBusGTypeSpecializedAppendContext *ctx,
                                                         GValue *elt);

Appends a given element to the end of a collection.

ctx :

a context created by dbus_g_type_specialized_init_append() for a GValue containing a collection

elt :

a GValue containing an element to append to the collection

dbus_g_type_specialized_collection_end_append ()

void                dbus_g_type_specialized_collection_end_append
                                                        (DBusGTypeSpecializedAppendContext *ctx);

Finish appending elements to a given collection

ctx :

a context created by dbus_g_type_specialized_init_append() for a GValue containing a collection

dbus_g_type_specialized_map_append ()

void                dbus_g_type_specialized_map_append  (DBusGTypeSpecializedAppendContext *ctx,
                                                         GValue *key,
                                                         GValue *val);

Inserts the given key/value pair into the map instance.

ctx :

a context created by dbus_g_type_specialized_init_append() for a GValue containing a map

key :

a GValue containing a key, whose contents will be stolen by ctx

val :

a GValue containing a value, whose contents will be stolen by ctx

dbus_g_type_collection_get_fixed ()

gboolean            dbus_g_type_collection_get_fixed    (GValue *value,
                                                         gpointer *data_ret,
                                                         guint *len_ret);

Calling this function is likely to be a bad idea. Consider using dbus_g_type_collection_value_iterate() instead.

On success, data_ret is a pointer to the underlying data in a collection of fixed-length fundamental types. Knowledge of the underlying data model of the collection is needed in order to use data_ret correctly.

It is an error to call this function on a specialized type that is not a collection, or on a collection that does not have a fixed_accessor in its DBusGTypeSpecializedCollectionVtable.

Specialized GArrays are the only types provided by dbus-glib that can be used with this function; user-defined types might also work.

value :

a GValue containing a boxed specialized collection that has a fixed_accessor in its vtable

data_ret :

used to return a pointer to the fixed data, which must not be modified (for instance, for a GArray of gint, this would point to an array of gint)

len_ret :

used to return the length (counting collection elements, not bytes: in a GArray containing one gint, this would be 1)

Returns :

TRUE on success

dbus_g_type_collection_value_iterate ()

void                dbus_g_type_collection_value_iterate
                                                        (const GValue *value,
                                                         DBusGTypeSpecializedCollectionIterator iterator,
                                                         gpointer user_data);

Calls the given function for each element of the collection. The function is passed a GValue containing the element and the given user_data parameter. The collection may not be modified while iterating over it.

value :

a GValue holding a collection type.

iterator :

a function to call for each element

user_data :

user data to pass to the iterator

dbus_g_type_map_value_iterate ()

void                dbus_g_type_map_value_iterate       (const GValue *value,
                                                         DBusGTypeSpecializedMapIterator iterator,
                                                         gpointer user_data);

Calls the given function for each key/value pair of the map. The function is passed two GValues containing the key/value pair and the given user_data parameter. The map may not be modified while iterating over it.

value :

a GValue holding a specialized map

iterator :

a function to call for each element

user_data :

user data to pass to the iterator

dbus_g_type_struct_get_member ()

gboolean            dbus_g_type_struct_get_member       (const GValue *value,
                                                         guint member,
                                                         GValue *dest);

Fetches a given member of a given struct instance. dest must be initialised was the correct type for that member, e.g. as returned by dbus_g_type_get_struct_member_type

value :

a GValue containing a struct instance

member :

the index of a given member

dest :

an initialised GValue in which to return the struct member

Returns :

TRUE if successful

dbus_g_type_struct_set_member ()

gboolean            dbus_g_type_struct_set_member       (GValue *value,
                                                         guint member,
                                                         const GValue *src);

Sets a given member of a struct to a new value. The type of src must match the existing type of member member of the struct.

value :

a GValue containing a struct instance

member :

the index of a given member

src :

an GValue containing the new value for that struct member

Returns :

TRUE if successful

dbus_g_type_struct_get ()

gboolean            dbus_g_type_struct_get              (const GValue *value,
                                                         guint member,
                                                         ...);

Collects the selected values of this struct into the return locations provided.

value :

a GValue containing a struct instance

member :

struct member to get

... :

location in which to return the value of this member, followed optionally by more member/return locations pairs, followed by by G_MAXUINT

Returns :

FALSE on failure

dbus_g_type_struct_set ()

gboolean            dbus_g_type_struct_set              (GValue *value,
                                                         guint member,
                                                         ...);

Sets the selected members of the struct in value.

value :

a GValue containing a struct instance

member :

struct member to set

... :

value for the first member, followed optionally by more member/value pairs, followed by G_MAXUINT

Returns :

FALSE on failure

dbus_g_type_specialized_init ()

void                dbus_g_type_specialized_init        (void);

Initialize dbus-glib specialized GTypes.

In older versions of dbus-glib, it was necessary to do this before instantiating or registering any specialized type. It is now done automatically whenever necessary.


dbus_g_type_register_collection ()

void                dbus_g_type_register_collection     (const char *name,
                                                         const DBusGTypeSpecializedCollectionVtable *vtable,
                                                         guint flags);

Defines a new collection container.

name :

The name of a new collection container

vtable :

the vtable defining the new container

flags :

As yet unused.

dbus_g_type_register_map ()

void                dbus_g_type_register_map            (const char *name,
                                                         const DBusGTypeSpecializedMapVtable *vtable,
                                                         guint flags);

Defines a new map container.

name :

The name of a new map container

vtable :

the vtable defining the new container

flags :

As yet unused.

dbus_g_type_map_peek_vtable ()

const DBusGTypeSpecializedMapVtable * dbus_g_type_map_peek_vtable
                                                        (GType map_type);

Peek the vtable for a given map specialization

map_type :

a gtype of a map specialization

Returns :

the vtable

dbus_g_type_collection_peek_vtable ()

const DBusGTypeSpecializedCollectionVtable * dbus_g_type_collection_peek_vtable
                                                        (GType collection_type);

Peek the vtable for a given collection specialization

collection_type :

a gtype of a collection specialization

Returns :

the vtable

dbus_g_type_struct_peek_vtable ()

const DBusGTypeSpecializedStructVtable * dbus_g_type_struct_peek_vtable
                                                        (GType struct_type);

Peek the vtable for a given struct specialization

struct_type :

a gtype of a struct specialization

Returns :

the vtable

dbus_g_type_register_struct ()

void                dbus_g_type_register_struct         (const char *name,
                                                         const DBusGTypeSpecializedStructVtable *vtable,
                                                         guint flags);

Defines a new struct container.

name :

The name of a new struct container

vtable :

the vtable defining the new container

flags :

As yet unused.

dbus_g_value_build_g_variant ()

GVariant *          dbus_g_value_build_g_variant        (const GValue *value);

Recurses value and converts its contents to a GVariant.

The value must either be a simple value (integer, string, boolean, object path etc.) or a specialized container registered with dbus_g_type_get_collection(), dbus_g_type_get_map() or dbus_g_type_get_struct(). Providing any other type is a programming error (including as a child type).

value :

a simple or specialized GValue to convert to a GVariant

Returns :

a new GVariant containing value with a floating reference

dbus_g_value_parse_g_variant ()

void                dbus_g_value_parse_g_variant        (GVariant *variant,
                                                         GValue *value);

Deserialize variant and put an equivalent dbus-glib data structure in value.

It is an error if variant contains any GVariant extensions not supported by dbus-glib, including handles (file descriptor passing) and 'maybe' types.

variant :

a GVariant

value :

a zero-filled GValue

DBUS_TYPE_G_BOOLEAN_ARRAY

#define DBUS_TYPE_G_BOOLEAN_ARRAY  (dbus_g_type_get_collection ("GArray", G_TYPE_BOOLEAN))

Expands to a function call returning the GType of a GArray of gboolean (corresponding to the D-Bus signature "ab").


DBUS_TYPE_G_UCHAR_ARRAY

#define DBUS_TYPE_G_UCHAR_ARRAY    (dbus_g_type_get_collection ("GArray", G_TYPE_UCHAR))

Expands to a function call returning the GType of a GArray of guchar (corresponding to the D-Bus signature "ay").

Note that this is not the same thing as a GByteArray! dbus-glib does not know about the GByteArray type.


DBUS_TYPE_G_UINT_ARRAY

#define DBUS_TYPE_G_UINT_ARRAY     (dbus_g_type_get_collection ("GArray", G_TYPE_UINT))

Expands to a function call returning the GType of a GArray of guint (corresponding to the D-Bus signature "au").


DBUS_TYPE_G_INT_ARRAY

#define DBUS_TYPE_G_INT_ARRAY      (dbus_g_type_get_collection ("GArray", G_TYPE_INT))

Expands to a function call returning the GType of a GArray of gint (corresponding to the D-Bus signature "ai").


DBUS_TYPE_G_UINT64_ARRAY

#define DBUS_TYPE_G_UINT64_ARRAY   (dbus_g_type_get_collection ("GArray", G_TYPE_UINT64))

Expands to a function call returning the GType of a GArray of guint64 (corresponding to the D-Bus signature "at").


DBUS_TYPE_G_INT64_ARRAY

#define DBUS_TYPE_G_INT64_ARRAY    (dbus_g_type_get_collection ("GArray", G_TYPE_INT64))

Expands to a function call returning the GType of a GArray of gint64 (corresponding to the D-Bus signature "ax").


DBUS_TYPE_G_OBJECT_ARRAY

#define DBUS_TYPE_G_OBJECT_ARRAY   (dbus_g_type_get_collection ("GPtrArray", G_TYPE_OBJECT))

Expands to a function call returning the GType of a GPtrArray of GObject.

Use this type with caution: it can sometimes be used as a representation of arrays whose D-Bus signature is "ao" (transferred as an array of object paths), but the conventional type for such arrays is (dbus_g_type_get_collection ("GPtrArray", DBUS_TYPE_G_OBJECT_PATH)).


DBUS_TYPE_G_STRING_STRING_HASHTABLE

#define DBUS_TYPE_G_STRING_STRING_HASHTABLE (dbus_g_type_get_map ("GHashTable", G_TYPE_STRING, G_TYPE_STRING))

Expands to a function call returning the GType of a GHashTable where the keys are strings and the values are also strings (corresponding to the D-Bus signature "a{ss}").


DBusGSignature

typedef gchar DBusGSignature;

A typedef for a string used to represent D-Bus signatures. Its GType is DBUS_TYPE_G_SIGNATURE, derived from G_TYPE_BOXED.

Prior to version 0.FIXME this was used as the type name of DBUS_TYPE_G_SIGNATURE, but did not actually exist as a typedef.

Since 0.FIXME


DBUS_TYPE_G_SIGNATURE

#define DBUS_TYPE_G_SIGNATURE (dbus_g_signature_get_g_type ())

The GType of a DBusGSignature, which is a boxed type containing a D-Bus signature as a zero-terminated string. Signatures can be copied with g_strdup() and freed with g_free(), just like G_TYPE_STRING, but have a distinct boxed type to allow them to be distinguished when stored in a GValue.

Returns :

a type derived from G_TYPE_BOXED

DBusGObjectPath

typedef gchar DBusGObjectPath;

A typedef for a string used to represent D-Bus object paths. Its GType is DBUS_TYPE_G_OBJECT_PATH, derived from G_TYPE_BOXED.

Prior to version 0.FIXME this was used as the type name of DBUS_TYPE_G_OBJECT_PATH, but did not actually exist as a typedef.

Since 0.FIXME


DBUS_TYPE_G_OBJECT_PATH

#define DBUS_TYPE_G_OBJECT_PATH (dbus_g_object_path_get_g_type ())

The GType of a DBusGObjectPath, which is a boxed type containing a D-Bus object path as a zero-terminated string. Object paths can be copied with g_strdup() and freed with g_free(), just like G_TYPE_STRING, but have a distinct boxed type to allow them to be distinguished when stored in a GValue.

Returns :

a type derived from G_TYPE_BOXED