![]() |
![]() |
![]() |
D-Bus GLib bindings - Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
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
,guint *len
); 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
); 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
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 capabale 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.
A map is a container that holds a set of key/value pairs. The keys have one type, and the values another.
A struct is a container that holds a fixed number of members, each member having a predefined 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.
void (*DBusGTypeSpecializedCollectionIterator) (const GValue *value
,gpointer user_data
);
void (*DBusGTypeSpecializedMapIterator) (const GValue *key_val
,const GValue *value_val
,gpointer user_data
);
typedef struct { /* public */ GValue *val; GType specialization_type; /* padding */ gpointer b; guint c; gpointer d; } DBusGTypeSpecializedAppendContext;
gpointer (*DBusGTypeSpecializedCopyFunc) (GType type
,gpointer src
);
typedef struct { DBusGTypeSpecializedConstructor constructor; DBusGTypeSpecializedFreeFunc free_func; DBusGTypeSpecializedCopyFunc copy_func; GDestroyNotify simple_free_func; /* for type-independent freeing if possible */ gpointer padding2; gpointer padding3; } 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
);
typedef struct { DBusGTypeSpecializedVtable base_vtable; DBusGTypeSpecializedCollectionFixedAccessorFunc fixed_accessor; DBusGTypeSpecializedCollectionIteratorFunc iterator; DBusGTypeSpecializedCollectionAppendFunc append_func; DBusGTypeSpecializedCollectionEndAppendFunc end_append_func; } DBusGTypeSpecializedCollectionVtable;
void (*DBusGTypeSpecializedMapIteratorFunc) (GType type
,gpointer instance
,DBusGTypeSpecializedMapIterator iterator
,gpointer user_data
);
void (*DBusGTypeSpecializedMapAppendFunc) (DBusGTypeSpecializedAppendContext *ctx
,GValue *key
,GValue *val
);
typedef struct { DBusGTypeSpecializedVtable base_vtable; DBusGTypeSpecializedMapIteratorFunc iterator; DBusGTypeSpecializedMapAppendFunc append_func; } DBusGTypeSpecializedMapVtable;
gboolean (*DBusGTypeSpecializedStructGetMember) (GType type
,gpointer instance
,guint member
,GValue *ret_value
);
gboolean (*DBusGTypeSpecializedStructSetMember) (GType type
,gpointer instance
,guint member
,const GValue *new_value
);
typedef struct { DBusGTypeSpecializedVtable base_vtable; DBusGTypeSpecializedStructGetMember get_member; DBusGTypeSpecializedStructSetMember set_member; } DBusGTypeSpecializedStructVtable;
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.
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.
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.
|
a string specifying a registered struct type |
|
number of members in the struct |
|
an array specufying a GType for each struct element |
Returns : |
the GType of that instance |
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.
gboolean dbus_g_type_is_collection (GType gtype
);
Tests if a given GType is a collection.
|
a GType to test |
Returns : |
true if the given GType is a collection |
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.
|
a GType to test |
Returns : |
true if the given GType is a map |
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
|
a GType to test |
Returns : |
true if the given GType is a struct |
GType dbus_g_type_get_collection_specialization
(GType gtype
);
|
a collection GType, as created by dbus_g_type_get_collection. |
Returns : |
the element type for a given collection GType. Returns G_TYPE_INVALID if not a collection GType |
GType dbus_g_type_get_map_key_specialization
(GType gtype
);
|
a map GType, as created by dbus_g_type_get_map. |
Returns : |
the key type for a given map GType. Returns G_TYPE_INVALID if not a map GType |
GType dbus_g_type_get_map_value_specialization
(GType gtype
);
|
a map GType, as created by dbus_g_type_get_map. |
Returns : |
the value type for a given map GType. Returns G_TYPE_INVALID if not a map GType |
GType dbus_g_type_get_struct_member_type (GType gtype
,guint member
);
|
a struct GType, as created with dbus_g_type_get_struct |
|
the index of a struct member |
Returns : |
the type for a given member of a struct GType. Returns G_TYPE_INVALID if not a struct GType |
guint dbus_g_type_get_struct_size (GType gtype
);
|
a struct GType, as created with dbus_g_type_get_struct. |
Returns : |
the number of members in a given struct GType. Returns G_TYPE_INVALID if not a struct GType |
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)
|
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. |
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..
|
a GValue containing an instance of specialized type |
|
a DBusGTypeSpecializedAppendContext in which to return a new appending context. |
void dbus_g_type_specialized_collection_append (DBusGTypeSpecializedAppendContext *ctx
,GValue *elt
);
Appends a given element to the end of a collection.
|
a context created by dbus_g_type_specialized_init_append |
|
a GValue containing an element to append to the collection. |
void dbus_g_type_specialized_collection_end_append
(DBusGTypeSpecializedAppendContext *ctx
);
Finish appending elements to a given collection
|
a context created by dbus_g_type_specialized_init_append |
void dbus_g_type_specialized_map_append (DBusGTypeSpecializedAppendContext *ctx
,GValue *key
,GValue *val
);
Inserts the given key/value pair into the map instance.
|
a context created by dbus_g_type_specialized_init_append |
|
a GValue containing a key, whose contents will be stolen by ctx
|
|
a GValue containing a value, whose contents will be stolen by ctx
|
gboolean dbus_g_type_collection_get_fixed (GValue *value
,gpointer *data
,guint *len
);
if the collection has elements of fixed size (i.e. a fundamental type), return the contents of the array. Its pretty obscure and I don't think anyone uses it.
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.
|
a GValue holding a collection type. |
|
a function to call for each element |
|
user data to pass to the iterator
|
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.
|
a GValue holding a collection type. |
|
a function to call for each element |
|
user data to pass to the iterator
|
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
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 exiting type of member
member of the struct.
gboolean dbus_g_type_struct_get (const GValue *value
,guint member
,...
);
Collects the selected values of this struct into the return locations provided.
gboolean dbus_g_type_struct_set (GValue *value
,guint member
,...
);
Sets the selected members of the struct in value
.
void dbus_g_type_register_collection (const char *name
,const DBusGTypeSpecializedCollectionVtable *vtable
,guint flags
);
Defines a new collection container.
|
The name of a new collection container |
|
the vtable defining the new container |
|
As yet unused. |
void dbus_g_type_register_map (const char *name
,const DBusGTypeSpecializedMapVtable *vtable
,guint flags
);
Defines a new map container.
|
The name of a new map container |
|
the vtable defining the new container |
|
As yet unused. |
const DBusGTypeSpecializedMapVtable * dbus_g_type_map_peek_vtable
(GType map_type
);
Peek the vtable for a given map specialization
|
a gtype of a map specialization |
const DBusGTypeSpecializedCollectionVtable * dbus_g_type_collection_peek_vtable
(GType collection_type
);
Peek the vtable for a given collection specialization
|
a gtype of a collection specialization |
void dbus_g_type_register_struct (const char *name
,const DBusGTypeSpecializedStructVtable *vtable
,guint flags
);
Defines a new struct container.
|
The name of a new struct container |
|
the vtable defining the new container |
|
As yet unused. |
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).
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.
#define DBUS_TYPE_G_BOOLEAN_ARRAY (dbus_g_type_get_collection ("GArray", G_TYPE_BOOLEAN))
#define DBUS_TYPE_G_UCHAR_ARRAY (dbus_g_type_get_collection ("GArray", G_TYPE_UCHAR))
#define DBUS_TYPE_G_UINT_ARRAY (dbus_g_type_get_collection ("GArray", G_TYPE_UINT))
#define DBUS_TYPE_G_INT_ARRAY (dbus_g_type_get_collection ("GArray", G_TYPE_INT))
#define DBUS_TYPE_G_UINT64_ARRAY (dbus_g_type_get_collection ("GArray", G_TYPE_UINT64))
#define DBUS_TYPE_G_INT64_ARRAY (dbus_g_type_get_collection ("GArray", G_TYPE_INT64))
#define DBUS_TYPE_G_OBJECT_ARRAY (dbus_g_type_get_collection ("GPtrArray", G_TYPE_OBJECT))
#define DBUS_TYPE_G_STRING_STRING_HASHTABLE (dbus_g_type_get_map ("GHashTable", G_TYPE_STRING, G_TYPE_STRING))
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
#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
|
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
#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
|