D-Bus Introspection Data

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

Object Hierarchy

    GBoxed
    ├── GDBusAnnotationInfo
    ├── GDBusArgInfo
    ├── GDBusInterfaceInfo
    ├── GDBusMethodInfo
    ├── GDBusNodeInfo
    ├── GDBusPropertyInfo
    ╰── GDBusSignalInfo

Includes

#include <gio/gio.h>

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

Functions

g_dbus_annotation_info_lookup ()

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

Looks up the value of an annotation.

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

Parameters

annotations

A NULL-terminated array of annotations or NULL.

[array zero-terminated=1][nullable]

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.

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

Parameters

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.

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

Parameters

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.

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

The introspection XML must contain exactly one top-level <node> element.

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

Parameters

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.

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

Parameters

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.

Parameters

info

A GDBusNodeInfo.

 

indent

Indentation level.

 

string_builder

A GString to to append XML data to.

 

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

info

A GDBusAnnotationInfo.

 

Since: 2.26

Types and Values

GDBusAnnotationInfo

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

Information about an annotation.

Members

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.

Members

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.

Members

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.

Members

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

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

Members

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.

Members

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.

Members

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.

Members

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