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

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.

`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

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