GIO Reference Manual: D-Bus Introspection Data

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

## Functions

const gchar * | g_dbus_annotation_info_lookup ()
GDBusMethodInfo * | g_dbus_interface_info_lookup_method ()
GDBusSignalInfo * | g_dbus_interface_info_lookup_signal ()
GDBusPropertyInfo * | g_dbus_interface_info_lookup_property ()
void | g_dbus_interface_info_cache_build ()
void | g_dbus_interface_info_cache_release ()
void | g_dbus_interface_info_generate_xml ()
GDBusNodeInfo * | g_dbus_node_info_new_for_xml ()
GDBusInterfaceInfo * | g_dbus_node_info_lookup_interface ()
void | g_dbus_node_info_generate_xml ()
#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 ()
GDBusInterfaceInfo * | g_dbus_interface_info_ref ()
GDBusMethodInfo * | g_dbus_method_info_ref ()
GDBusSignalInfo * | g_dbus_signal_info_ref ()
GDBusPropertyInfo * | g_dbus_property_info_ref ()
GDBusArgInfo * | g_dbus_arg_info_ref ()
GDBusAnnotationInfo * | g_dbus_annotation_info_ref ()
void | g_dbus_node_info_unref ()
void | g_dbus_interface_info_unref ()
void | g_dbus_method_info_unref ()
void | g_dbus_signal_info_unref ()
void | g_dbus_property_info_unref ()
void | g_dbus_arg_info_unref ()
void | g_dbus_annotation_info_unref ()

## Types and Values

| GDBusAnnotationInfo
| GDBusArgInfo
| GDBusMethodInfo
| GDBusSignalInfo
enum | GDBusPropertyInfoFlags
| GDBusPropertyInfo
| GDBusInterfaceInfo
| GDBusNodeInfo

## 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][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.

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. | [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.

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. | [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.

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