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_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
   +----GDBusInterfaceInfo

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.

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.

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.

GDBusArgInfo **out_args;

A pointer to a NULL-terminated array of pointers to GDBusArgInfo structures or NULL if there are no out arguments.

GDBusAnnotationInfo **annotations;

A pointer to a NULL-terminated array of pointers to GDBusAnnotationInfo structures or NULL if there are no annotations.

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.

GDBusAnnotationInfo **annotations;

A pointer to a NULL-terminated array of pointers to GDBusAnnotationInfo structures or NULL if there are no annotations.

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.

Since 2.26


GDBusInterfaceInfo

typedef struct _GDBusInterfaceInfo GDBusInterfaceInfo;

Information about a D-Bus interface.

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.

GDBusNodeInfo **nodes;

A pointer to a NULL-terminated array of pointers to GDBusNodeInfo structures or NULL if there are no nodes.

GDBusAnnotationInfo **annotations;

A pointer to a NULL-terminated array of pointers to GDBusAnnotationInfo structures or NULL if there are no annotations.

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.

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.

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.

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.

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.

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.

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.

Since 2.26


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.

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.

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.

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.

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


g_dbus_node_info_unref ()

void                g_dbus_node_info_unref              (GDBusNodeInfo *info);

If info is statically allocated, does nothing. Otherwise decreases the reference count of info. When its reference count drops to 0, the memory used is freed.

info :

A GDBusNodeInfo.

Since 2.26


g_dbus_interface_info_unref ()

void                g_dbus_interface_info_unref         (GDBusInterfaceInfo *info);

If info is statically allocated, does nothing. Otherwise decreases the reference count of info. When its reference count drops to 0, the memory used is freed.

info :

A GDBusInterfaceInfo.

Since 2.26


g_dbus_method_info_unref ()

void                g_dbus_method_info_unref            (GDBusMethodInfo *info);

If info is statically allocated, does nothing. Otherwise decreases the reference count of info. When its reference count drops to 0, the memory used is freed.

info :

A GDBusMethodInfo.

Since 2.26


g_dbus_signal_info_unref ()

void                g_dbus_signal_info_unref            (GDBusSignalInfo *info);

If info is statically allocated, does nothing. Otherwise decreases the reference count of info. When its reference count drops to 0, the memory used is freed.

info :

A GDBusSignalInfo.

Since 2.26


g_dbus_property_info_unref ()

void                g_dbus_property_info_unref          (GDBusPropertyInfo *info);

If info is statically allocated, does nothing. Otherwise decreases the reference count of info. When its reference count drops to 0, the memory used is freed.

info :

A GDBusPropertyInfo.

Since 2.26


g_dbus_arg_info_unref ()

void                g_dbus_arg_info_unref               (GDBusArgInfo *info);

If info is statically allocated, does nothing. Otherwise decreases the reference count of info. When its reference count drops to 0, the memory used is freed.

info :

A GDBusArgInfo.

Since 2.26


g_dbus_annotation_info_unref ()

void                g_dbus_annotation_info_unref        (GDBusAnnotationInfo *info);

If info is statically allocated, does nothing. Otherwise decreases the reference count of info. When its reference count drops to 0, the memory used is freed.

info :

A GDBusAnnotationInfo.

Since 2.26