D-Bus Introspection Data

D-Bus Introspection Data — Node and interface description data structures

Synopsis

#include <gio/gio.h>

                    GDBusAnnotationInfo;
                    GDBusArgInfo;
                    GDBusMethodInfo;
                    GDBusSignalInfo;
enum                GDBusPropertyInfoFlags;
                    GDBusPropertyInfo;
                    GDBusInterfaceInfo;
                    GDBusNodeInfo;
const gchar *       g_dbus_annotation_info_lookup       (GDBusAnnotationInfo **annotations,
                                                         const gchar *name);
GDBusMethodInfo *   g_dbus_interface_info_lookup_method (GDBusInterfaceInfo *info,
                                                         const gchar *name);
GDBusSignalInfo *   g_dbus_interface_info_lookup_signal (GDBusInterfaceInfo *info,
                                                         const gchar *name);
GDBusPropertyInfo * g_dbus_interface_info_lookup_property
                                                        (GDBusInterfaceInfo *info,
                                                         const gchar *name);
void                g_dbus_interface_info_cache_build   (GDBusInterfaceInfo *info);
void                g_dbus_interface_info_cache_release (GDBusInterfaceInfo *info);
void                g_dbus_interface_info_generate_xml  (GDBusInterfaceInfo *info,
                                                         guint indent,
                                                         GString *string_builder);
GDBusNodeInfo *     g_dbus_node_info_new_for_xml        (const gchar *xml_data,
                                                         GError **error);
GDBusInterfaceInfo * g_dbus_node_info_lookup_interface  (GDBusNodeInfo *info,
                                                         const gchar *name);
void                g_dbus_node_info_generate_xml       (GDBusNodeInfo *info,
                                                         guint indent,
                                                         GString *string_builder);
#define             G_TYPE_DBUS_NODE_INFO
#define             G_TYPE_DBUS_INTERFACE_INFO
#define             G_TYPE_DBUS_METHOD_INFO
#define             G_TYPE_DBUS_SIGNAL_INFO
#define             G_TYPE_DBUS_PROPERTY_INFO
#define             G_TYPE_DBUS_ARG_INFO
#define             G_TYPE_DBUS_ANNOTATION_INFO
GDBusNodeInfo *     g_dbus_node_info_ref                (GDBusNodeInfo *info);
GDBusInterfaceInfo * g_dbus_interface_info_ref          (GDBusInterfaceInfo *info);
GDBusMethodInfo *   g_dbus_method_info_ref              (GDBusMethodInfo *info);
GDBusSignalInfo *   g_dbus_signal_info_ref              (GDBusSignalInfo *info);
GDBusPropertyInfo * g_dbus_property_info_ref            (GDBusPropertyInfo *info);
GDBusArgInfo *      g_dbus_arg_info_ref                 (GDBusArgInfo *info);
GDBusAnnotationInfo * g_dbus_annotation_info_ref        (GDBusAnnotationInfo *info);
void                g_dbus_node_info_unref              (GDBusNodeInfo *info);
void                g_dbus_interface_info_unref         (GDBusInterfaceInfo *info);
void                g_dbus_method_info_unref            (GDBusMethodInfo *info);
void                g_dbus_signal_info_unref            (GDBusSignalInfo *info);
void                g_dbus_property_info_unref          (GDBusPropertyInfo *info);
void                g_dbus_arg_info_unref               (GDBusArgInfo *info);
void                g_dbus_annotation_info_unref        (GDBusAnnotationInfo *info);

Object Hierarchy

  GBoxed
   +----GDBusAnnotationInfo

  GBoxed
   +----GDBusArgInfo

  GBoxed
   +----GDBusMethodInfo

  GBoxed
   +----GDBusSignalInfo

  GBoxed
   +----GDBusPropertyInfo

  GBoxed
   +----GDBusInterfaceInfo

  GBoxed
   +----GDBusNodeInfo

Description

Various data structures and convenience routines to parse and generate D-Bus introspection XML. Introspection information is used when registering objects with g_dbus_connection_register_object().

The format of D-Bus introspection XML is specified in the D-Bus specification.

Details

GDBusAnnotationInfo

typedef struct {
  volatile gint         ref_count;
  gchar                *key;
  gchar                *value;
  GDBusAnnotationInfo **annotations;
} GDBusAnnotationInfo;

Information about an annotation.

volatile gint `ref_count`;	The reference count or -1 if statically allocated.
gchar *`key`;	The name of the annotation, e.g. "org.freedesktop.DBus.Deprecated".
gchar *`value`;	The value of the annotation.
GDBusAnnotationInfo **`annotations`;	A pointer to a `NULL`-terminated array of pointers to GDBusAnnotationInfo structures or `NULL` if there are no annotations. [array zero-terminated=1]

Since 2.26

GDBusArgInfo

typedef struct {
  volatile gint         ref_count;
  gchar                *name;
  gchar                *signature;
  GDBusAnnotationInfo **annotations;
} GDBusArgInfo;

Information about an argument for a method or a signal.

volatile gint `ref_count`;	The reference count or -1 if statically allocated.
gchar *`name`;	Name of the argument, e.g. `unix_user_id`.
gchar *`signature`;	D-Bus signature of the argument (a single complete type).
GDBusAnnotationInfo **`annotations`;	A pointer to a `NULL`-terminated array of pointers to GDBusAnnotationInfo structures or `NULL` if there are no annotations. [array zero-terminated=1]

Since 2.26

GDBusMethodInfo

typedef struct {
  volatile gint         ref_count;
  gchar                *name;
  GDBusArgInfo        **in_args;
  GDBusArgInfo        **out_args;
  GDBusAnnotationInfo **annotations;
} GDBusMethodInfo;

Information about a method on an D-Bus interface.

volatile gint `ref_count`;	The reference count or -1 if statically allocated.
gchar *`name`;	The name of the D-Bus method, e.g. `RequestName`.
GDBusArgInfo **`in_args`;	A pointer to a `NULL`-terminated array of pointers to GDBusArgInfo structures or `NULL` if there are no in arguments. [array zero-terminated=1]
GDBusArgInfo **`out_args`;	A pointer to a `NULL`-terminated array of pointers to GDBusArgInfo structures or `NULL` if there are no out arguments. [array zero-terminated=1]
GDBusAnnotationInfo **`annotations`;	A pointer to a `NULL`-terminated array of pointers to GDBusAnnotationInfo structures or `NULL` if there are no annotations. [array zero-terminated=1]

Since 2.26

GDBusSignalInfo

typedef struct {
  volatile gint         ref_count;
  gchar                *name;
  GDBusArgInfo        **args;
  GDBusAnnotationInfo **annotations;
} GDBusSignalInfo;

Information about a signal on a D-Bus interface.

volatile gint `ref_count`;	The reference count or -1 if statically allocated.
gchar *`name`;	The name of the D-Bus signal, e.g. "NameOwnerChanged".
GDBusArgInfo **`args`;	A pointer to a `NULL`-terminated array of pointers to GDBusArgInfo structures or `NULL` if there are no arguments. [array zero-terminated=1]
GDBusAnnotationInfo **`annotations`;	A pointer to a `NULL`-terminated array of pointers to GDBusAnnotationInfo structures or `NULL` if there are no annotations. [array zero-terminated=1]

Since 2.26

enum GDBusPropertyInfoFlags

typedef enum {
  G_DBUS_PROPERTY_INFO_FLAGS_NONE = 0,
  G_DBUS_PROPERTY_INFO_FLAGS_READABLE = (1<<0),
  G_DBUS_PROPERTY_INFO_FLAGS_WRITABLE = (1<<1)
} GDBusPropertyInfoFlags;

Flags describing the access control of a D-Bus property.

`G_DBUS_PROPERTY_INFO_FLAGS_NONE`	No flags set.
`G_DBUS_PROPERTY_INFO_FLAGS_READABLE`	Property is readable.
`G_DBUS_PROPERTY_INFO_FLAGS_WRITABLE`	Property is writable.

Since 2.26

GDBusPropertyInfo

typedef struct {
  volatile gint             ref_count;
  gchar                    *name;
  gchar                    *signature;
  GDBusPropertyInfoFlags    flags;
  GDBusAnnotationInfo     **annotations;
} GDBusPropertyInfo;

Information about a D-Bus property on a D-Bus interface.

volatile gint `ref_count`;	The reference count or -1 if statically allocated.
gchar *`name`;	The name of the D-Bus property, e.g. "SupportedFilesystems".
gchar *`signature`;	The D-Bus signature of the property (a single complete type).
GDBusPropertyInfoFlags `flags`;	Access control flags for the property.
GDBusAnnotationInfo **`annotations`;	A pointer to a `NULL`-terminated array of pointers to GDBusAnnotationInfo structures or `NULL` if there are no annotations. [array zero-terminated=1]

Since 2.26

GDBusInterfaceInfo

typedef struct {
  volatile gint         ref_count;
  gchar                *name;
  GDBusMethodInfo     **methods;
  GDBusSignalInfo     **signals;
  GDBusPropertyInfo   **properties;
  GDBusAnnotationInfo **annotations;
} GDBusInterfaceInfo;

Information about a D-Bus interface.

volatile gint `ref_count`;	The reference count or -1 if statically allocated.
gchar *`name`;	The name of the D-Bus interface, e.g. "org.freedesktop.DBus.Properties".
GDBusMethodInfo **`methods`;	A pointer to a `NULL`-terminated array of pointers to GDBusMethodInfo structures or `NULL` if there are no methods. [array zero-terminated=1]
GDBusSignalInfo **`signals`;	A pointer to a `NULL`-terminated array of pointers to GDBusSignalInfo structures or `NULL` if there are no signals. [array zero-terminated=1]
GDBusPropertyInfo **`properties`;	A pointer to a `NULL`-terminated array of pointers to GDBusPropertyInfo structures or `NULL` if there are no properties. [array zero-terminated=1]
GDBusAnnotationInfo **`annotations`;	A pointer to a `NULL`-terminated array of pointers to GDBusAnnotationInfo structures or `NULL` if there are no annotations. [array zero-terminated=1]

Since 2.26

GDBusNodeInfo

typedef struct {
  volatile gint         ref_count;
  gchar                *path;
  GDBusInterfaceInfo  **interfaces;
  GDBusNodeInfo       **nodes;
  GDBusAnnotationInfo **annotations;
} GDBusNodeInfo;

Information about nodes in a remote object hierarchy.

volatile gint `ref_count`;	The reference count or -1 if statically allocated.
gchar *`path`;	The path of the node or `NULL` if omitted. Note that this may be a relative path. See the D-Bus specification for more details.
GDBusInterfaceInfo **`interfaces`;	A pointer to a `NULL`-terminated array of pointers to GDBusInterfaceInfo structures or `NULL` if there are no interfaces. [array zero-terminated=1]
GDBusNodeInfo **`nodes`;	A pointer to a `NULL`-terminated array of pointers to GDBusNodeInfo structures or `NULL` if there are no nodes. [array zero-terminated=1]
GDBusAnnotationInfo **`annotations`;	A pointer to a `NULL`-terminated array of pointers to GDBusAnnotationInfo structures or `NULL` if there are no annotations. [array zero-terminated=1]

Since 2.26

g_dbus_annotation_info_lookup ()

const gchar *       g_dbus_annotation_info_lookup       (GDBusAnnotationInfo **annotations,
                                                         const gchar *name);

Looks up the value of an annotation.

This cost of this function is O(n) in number of annotations.

`annotations` :	A `NULL`-terminated array of annotations or `NULL`. [array zero-terminated=1][allow-none]
`name` :	The name of the annotation to look up.
Returns :	The value or `NULL` if not found. Do not free, it is owned by `annotations`.

Since 2.26

g_dbus_interface_info_lookup_method ()

GDBusMethodInfo *   g_dbus_interface_info_lookup_method (GDBusInterfaceInfo *info,
                                                         const gchar *name);

Looks up information about a method.

This cost of this function is O(n) in number of methods unless g_dbus_interface_info_cache_build() has been used on info.

`info` :	A GDBusInterfaceInfo.
`name` :	A D-Bus method name (typically in CamelCase)
Returns :	A GDBusMethodInfo or `NULL` if not found. Do not free, it is owned by `info`. [transfer none]

Since 2.26

g_dbus_interface_info_lookup_signal ()

GDBusSignalInfo *   g_dbus_interface_info_lookup_signal (GDBusInterfaceInfo *info,
                                                         const gchar *name);

Looks up information about a signal.

This cost of this function is O(n) in number of signals unless g_dbus_interface_info_cache_build() has been used on info.

`info` :	A GDBusInterfaceInfo.
`name` :	A D-Bus signal name (typically in CamelCase)
Returns :	A GDBusSignalInfo or `NULL` if not found. Do not free, it is owned by `info`. [transfer none]

Since 2.26

g_dbus_interface_info_lookup_property ()

GDBusPropertyInfo * g_dbus_interface_info_lookup_property
                                                        (GDBusInterfaceInfo *info,
                                                         const gchar *name);

Looks up information about a property.

This cost of this function is O(n) in number of properties unless g_dbus_interface_info_cache_build() has been used on info.

`info` :	A GDBusInterfaceInfo.
`name` :	A D-Bus property name (typically in CamelCase).
Returns :	A GDBusPropertyInfo or `NULL` if not found. Do not free, it is owned by `info`. [transfer none]

Since 2.26

g_dbus_interface_info_cache_build ()

void                g_dbus_interface_info_cache_build   (GDBusInterfaceInfo *info);

Builds a lookup-cache to speed up g_dbus_interface_info_lookup_method(), g_dbus_interface_info_lookup_signal() and g_dbus_interface_info_lookup_property().

If this has already been called with info, the existing cache is used and its use count is increased.

Note that info cannot be modified until g_dbus_interface_info_cache_release() is called.

info :

A GDBusInterfaceInfo.

Since 2.30

g_dbus_interface_info_cache_release ()

void                g_dbus_interface_info_cache_release (GDBusInterfaceInfo *info);

Decrements the usage count for the cache for info built by g_dbus_interface_info_cache_build() (if any) and frees the resources used by the cache if the usage count drops to zero.

info :

A GDBusInterfaceInfo

Since 2.30

g_dbus_interface_info_generate_xml ()

void                g_dbus_interface_info_generate_xml  (GDBusInterfaceInfo *info,
                                                         guint indent,
                                                         GString *string_builder);

Appends an XML representation of info (and its children) to string_builder.

This function is typically used for generating introspection XML documents at run-time for handling the org.freedesktop.DBus.Introspectable.Introspect method.

`info` :	A GDBusNodeInfo
`indent` :	Indentation level.
`string_builder` :	A GString to to append XML data to. [out]

Since 2.26

g_dbus_node_info_new_for_xml ()

GDBusNodeInfo *     g_dbus_node_info_new_for_xml        (const gchar *xml_data,
                                                         GError **error);

Parses xml_data and returns a GDBusNodeInfo representing the data.

Note that this routine is using a GMarkup-based parser that only accepts a subset of valid XML documents.

`xml_data` :	Valid D-Bus introspection XML.
`error` :	Return location for error.
Returns :	A GDBusNodeInfo structure or `NULL` if `error` is set. Free with `g_dbus_node_info_unref()`.

Since 2.26

g_dbus_node_info_lookup_interface ()

GDBusInterfaceInfo * g_dbus_node_info_lookup_interface  (GDBusNodeInfo *info,
                                                         const gchar *name);

Looks up information about an interface.

This cost of this function is O(n) in number of interfaces.

`info` :	A GDBusNodeInfo.
`name` :	A D-Bus interface name.
Returns :	A GDBusInterfaceInfo or `NULL` if not found. Do not free, it is owned by `info`. [transfer none]

Since 2.26

g_dbus_node_info_generate_xml ()

void                g_dbus_node_info_generate_xml       (GDBusNodeInfo *info,
                                                         guint indent,
                                                         GString *string_builder);

Appends an XML representation of info (and its children) to string_builder.

This function is typically used for generating introspection XML documents at run-time for handling the org.freedesktop.DBus.Introspectable.Introspect method.

`info` :	A GDBusNodeInfo.
`indent` :	Indentation level.
`string_builder` :	A GString to to append XML data to. [out]

Since 2.26

G_TYPE_DBUS_NODE_INFO

#define G_TYPE_DBUS_NODE_INFO       (g_dbus_node_info_get_type ())

The GType for a boxed type holding a GDBusNodeInfo.

Since 2.26

G_TYPE_DBUS_INTERFACE_INFO

#define G_TYPE_DBUS_INTERFACE_INFO  (g_dbus_interface_info_get_type ())

The GType for a boxed type holding a GDBusInterfaceInfo.

Since 2.26

G_TYPE_DBUS_METHOD_INFO

#define G_TYPE_DBUS_METHOD_INFO     (g_dbus_method_info_get_type ())

The GType for a boxed type holding a GDBusMethodInfo.

Since 2.26

G_TYPE_DBUS_SIGNAL_INFO

#define G_TYPE_DBUS_SIGNAL_INFO     (g_dbus_signal_info_get_type ())

The GType for a boxed type holding a GDBusSignalInfo.

Since 2.26

G_TYPE_DBUS_PROPERTY_INFO

#define G_TYPE_DBUS_PROPERTY_INFO   (g_dbus_property_info_get_type ())

The GType for a boxed type holding a GDBusPropertyInfo.

Since 2.26

G_TYPE_DBUS_ARG_INFO

#define G_TYPE_DBUS_ARG_INFO        (g_dbus_arg_info_get_type ())

The GType for a boxed type holding a GDBusArgInfo.

Since 2.26

G_TYPE_DBUS_ANNOTATION_INFO

#define G_TYPE_DBUS_ANNOTATION_INFO (g_dbus_annotation_info_get_type ())

The GType for a boxed type holding a GDBusAnnotationInfo.

Since 2.26

g_dbus_node_info_ref ()

GDBusNodeInfo *     g_dbus_node_info_ref                (GDBusNodeInfo *info);

If info is statically allocated does nothing. Otherwise increases the reference count.

`info` :	A GDBusNodeInfo
Returns :	The same `info`.

Since 2.26

g_dbus_interface_info_ref ()

GDBusInterfaceInfo * g_dbus_interface_info_ref          (GDBusInterfaceInfo *info);

If info is statically allocated does nothing. Otherwise increases the reference count.

`info` :	A GDBusInterfaceInfo
Returns :	The same `info`.

Since 2.26

g_dbus_method_info_ref ()

GDBusMethodInfo *   g_dbus_method_info_ref              (GDBusMethodInfo *info);

If info is statically allocated does nothing. Otherwise increases the reference count.

`info` :	A GDBusMethodInfo
Returns :	The same `info`.

Since 2.26

g_dbus_signal_info_ref ()

GDBusSignalInfo *   g_dbus_signal_info_ref              (GDBusSignalInfo *info);

If info is statically allocated does nothing. Otherwise increases the reference count.

`info` :	A GDBusSignalInfo
Returns :	The same `info`.

Since 2.26

g_dbus_property_info_ref ()

GDBusPropertyInfo * g_dbus_property_info_ref            (GDBusPropertyInfo *info);

If info is statically allocated does nothing. Otherwise increases the reference count.

`info` :	A GDBusPropertyInfo
Returns :	The same `info`.

Since 2.26

g_dbus_arg_info_ref ()

GDBusArgInfo *      g_dbus_arg_info_ref                 (GDBusArgInfo *info);

If info is statically allocated does nothing. Otherwise increases the reference count.

`info` :	A GDBusArgInfo
Returns :	The same `info`.

Since 2.26

g_dbus_annotation_info_ref ()

GDBusAnnotationInfo * g_dbus_annotation_info_ref        (GDBusAnnotationInfo *info);

If info is statically allocated does nothing. Otherwise increases the reference count.

`info` :	A GDBusNodeInfo
Returns :	The same `info`.

Since 2.26