Description

gdbus-codegen is used to generate code and/or documentation for one or more D-Bus interfaces. The tool reads D-Bus Introspection XML files and generates output files. The tool currently supports generating C code (via --generate-c-code) and Docbook XML (via --generate-docbook).

Generating C code

When generating C code, a GInterface-derived type is generated for each D-Bus interface. Additionally, for every generated type, FooBar, two concrete instantiable types, FooBarProxy and FooBarSkeleton, implementing said interface are also generated. The former is derived from GDBusProxy and intended for use on the client side while the latter is derived from the GDBusInterfaceSkeleton type making it easy to export on a GDBusConnection either directly or via a GDBusObjectManagerServer instance.

The name of each generated C type is derived from the D-Bus interface name stripped with the prefix given with --interface-prefix and with the dots removed and initial characters capitalized. For example, for the D-Bus interface com.acme.Coyote the name used is ComAcmeCoyote. For the D-Bus interface org.project.Bar.Frobnicator with --interface-prefix org.project., the name used is BarFrobnicator.

For methods, signals and properties, if not specified, the name defaults to the name of the method, signal or property.

Two forms of the name are used - the CamelCase form and the lower-case form. The CamelCase form is used for the GType and struct name, while lower-case form is used in function names. The lower-case form is calculated by converting from CamelCase to lower-case and inserting underscores at word boundaries (using certain heuristics).

If the value given by the org.gtk.GDBus.C.Name annotation or the --c-namespace option contains an underscore (sometimes called Ugly_Case), then the camel-case name is derived by removing all underscores, and the lower-case name is derived by lower-casing the string. This is useful in some situations where abbreviations are used. For example, if the annotation is used on the interface net.MyCorp.MyApp.iSCSITarget with the value iSCSI_Target the CamelCase form is iSCSITarget while the lower-case form is iscsi_target. If the annotation is used on the method EjectTheiPod with the value Eject_The_iPod, the lower-case form is eject_the_ipod.

Generating Docbook documentation

Each generated Docbook XML file (see the --generate-docbook option for details) is a RefEntry article describing the D-Bus interface.

Options

The following options are supported:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

gdbus-codegen --c-namespace MyApp                           \
  --generate-c-code myapp-generated                         \
  --annotate "org.project.InterfaceName"                    \
    org.gtk.GDBus.C.Name MyFrobnicator                      \
  --annotate "org.project.InterfaceName:Property"           \
    bar bat                                                 \
  --annotate "org.project.InterfaceName.Method()"           \
    org.freedesktop.DBus.Deprecated true                    \
  --annotate "org.project.InterfaceName.Method()[arg_name]" \
    snake hiss                                              \
  --annotate "org.project.InterfaceName::Signal"            \
    cat meow                                                \
  --annotate "org.project.InterfaceName::Signal[arg_name]"  \
    dog wuff                                                \
  myapp-dbus-interfaces.xml

Supported D-Bus Annotations

The following D-Bus annotations are supported by gdbus-codegen:

As an easier alternative to using the org.gtk.GDBus.DocString annotation, note that parser used by gdbus-codegen parses XML comments in a way similar to gtk-doc:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

<!--
  net.Corp.Bar:
  @short_description: A short description

  A <emphasis>longer</emphasis> description.

  This is a new paragraph.
-->
<interface name="net.corp.Bar">
  <!--
    FooMethod:
    @greeting: The docs for greeting parameter.
    @response: The docs for response parameter.

    The docs for the actual method.
  -->
  <method name="FooMethod">
    <arg name="greeting" direction="in" type="s"/>
    <arg name="response" direction="out" type="s"/>
  </method>

  <!--
    BarSignal:
    @blah: The docs for blah parameter.
    @boo: The docs for boo parameter.
    @since: 2.30

    The docs for the actual signal.
  -->
  <signal name="BarSignal">
    <arg name="blah" type="s"/>
    <arg name="boo" type="s"/>
  </signal>

  <!-- BazProperty: The docs for the property. -->
  <property name="BazProperty" type="s" access="read"/>
</interface>

Note that @since can be used in any inline documentation bit (e.g. for interfaces, methods, signals and properties) to set the org.gtk.GDBus.Since annotation. For the org.gtk.GDBus.DocString annotation (and inline comments), note that substrings of the form #net.Corp.Bar, net.Corp.Bar.FooMethod(), #net.Corp.Bar::BarSignal and #net.Corp.InlineDocs:BazProperty are all expanded to links to the respective interface, method, signal and property. Additionally, substrings starting with @ and % characters are rendered as parameter and constant respectively.

If both XML comments and org.gtk.GDBus.DocString or org.gtk.GDBus.DocString.Short annotations are present, the latter wins.

Example

Consider the following D-Bus Introspection XML.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<node>
  <interface name="net.Corp.MyApp.Frobber">
    <method name="HelloWorld">
      <arg name="greeting" direction="in" type="s"/>
      <arg name="response" direction="out" type="s"/>
    </method>

    <signal name="Notification">
      <arg name="icon_blob" type="ay"/>
      <arg name="height" type="i"/>
      <arg name="messages" type="as"/>
    </signal>

    <property name="Verbose" type="b" access="readwrite"/>
  </interface>
</node>

If gdbus-codegen is used on this file like this:

1
2
3
4

gdbus-codegen --generate-c-code myapp-generated       \
              --c-namespace MyApp                     \
              --interface-prefix net.corp.MyApp.      \
              net.Corp.MyApp.Frobber.xml

two files called myapp-generated.[ch] are generated. The files provide an abstract GTypeInterface-derived type called MyAppFrobber as well as two instantiable types with the same name but suffixed with Proxy and Skeleton. The generated file, roughly, contains the following facilities:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

/* GType macros for the three generated types */
#define MY_APP_TYPE_FROBBER (my_app_frobber_get_type ())
#define MY_APP_TYPE_FROBBER_SKELETON (my_app_frobber_skeleton_get_type ())
#define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ())

typedef struct _MyAppFrobber MyAppFrobber; /* Dummy typedef */

typedef struct
{
  GTypeInterface parent_iface;

  /* Signal handler for the ::notification signal */
  void (*notification) (MyAppFrobber *proxy,
                        GVariant *icon_blob,
                        gint height,
                        const gchar* const *messages);

  /* Signal handler for the ::handle-hello-world signal */
  gboolean (*handle_hello_world) (MyAppFrobber *proxy,
                                  GDBusMethodInvocation *invocation,
                                  const gchar *greeting);
} MyAppFrobberIface;

/* Asynchronously calls HelloWorld() */
void
my_app_frobber_call_hello_world (MyAppFrobber *proxy,
                                 const gchar *greeting,
                                 GCancellable *cancellable,
                                 GAsyncReadyCallback callback,
                                 gpointer user_data);
gboolean
my_app_frobber_call_hello_world_finish (MyAppFrobber *proxy,
                                        gchar **out_response,
                                        GAsyncResult *res,
                                        GError **error);

/* Synchronously calls HelloWorld(). Blocks calling thread. */
gboolean
my_app_frobber_call_hello_world_sync (MyAppFrobber *proxy,
                                      const gchar *greeting,
                                      gchar **out_response,
                                      GCancellable *cancellable,
                                      GError **error);

/* Completes handling the HelloWorld() method call */
void
my_app_frobber_complete_hello_world (MyAppFrobber *object,
                                     GDBusMethodInvocation *invocation,
                                     const gchar *response);

/* Emits the ::notification signal / Notification() D-Bus signal */
void
my_app_frobber_emit_notification (MyAppFrobber *object,
                                  GVariant *icon_blob,
                                  gint height,
                                  const gchar* const *messages);

/* Gets the :verbose GObject property / Verbose D-Bus property.
 * Does no blocking I/O.
 */
gboolean my_app_frobber_get_verbose (MyAppFrobber *object);

/* Sets the :verbose GObject property / Verbose D-Bus property.
 * Does no blocking I/O.
 */
void my_app_frobber_set_verbose (MyAppFrobber *object,
                                 gboolean      value);

/* Gets the interface info */
GDBusInterfaceInfo *my_app_frobber_interface_info (void);

/* Creates a new skeleton object, ready to be exported */
MyAppFrobber *my_app_frobber_skeleton_new (void);

/* Client-side proxy constructors.
 *
 * Additionally, _new_for_bus(), _new_for_bus_finish() and
 * _new_for_bus_sync() proxy constructors are also generated.
 */
void
my_app_frobber_proxy_new        (GDBusConnection     *connection,
                                 GDBusProxyFlags      flags,
                                 const gchar         *name,
                                 const gchar         *object_path,
                                 GCancellable        *cancellable,
                                 GAsyncReadyCallback  callback,
                                 gpointer             user_data);
MyAppFrobber *
my_app_frobber_proxy_new_finish (GAsyncResult        *res,
                                 GError             **error);
MyAppFrobber *
my_app_frobber_proxy_new_sync   (GDBusConnection     *connection,
                                 GDBusProxyFlags      flags,
                                 const gchar         *name,
                                 const gchar         *object_path,
                                 GCancellable        *cancellable,
                                 GError             **error);

Thus, for every D-Bus method, there will be three C functions for calling the method, one GObject signal for handling an incoming call and one C function for completing an incoming call. For every D-Bus signal, there's one GObject signal and one C function for emitting it. For every D-Bus property, two C functions are generated (one setter, one getter) and one GObject property. The following table summarizes the generated facilities and where they are applicable:

1
2
3
4
5
6
7
8
9
10
11
12
13

MyAppFrobber *proxy;
GError *error;

error = NULL;
proxy = my_app_frobber_proxy_new_for_bus_sync (
            G_BUS_TYPE_SESSION,
            G_DBUS_PROXY_FLAGS_NONE,
            "net.Corp.MyApp",              /* bus name */
            "/net/Corp/MyApp/SomeFrobber", /* object */
            NULL,                          /* GCancellable* */
            &error);
/* do stuff with proxy */
g_object_unref (proxy);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

static gboolean
on_handle_hello_world (MyAppFrobber           *interface,
                       GDBusMethodInvocation  *invocation,
                       const gchar            *greeting,
                       gpointer                user_data)
{
  if (g_strcmp0 (greeting, "Boo") != 0)
    {
      gchar *response;
      response = g_strdup_printf ("Word! You said `%s'.", greeting);
      my_app_complete_hello_world (interface, invocation, response);
      g_free (response);
    }
  else
    {
      g_dbus_method_invocation_return_error (invocation,
                 MY_APP_ERROR,
                 MY_APP_ERROR_NO_WHINING,
                 "Hey, %s, there will be no whining!",
                 g_dbus_method_invocation_get_sender (invocation));
    }
  return TRUE;
}

  [...]

  interface = my_app_frobber_skeleton_new ();
  my_app_frobber_set_verbose (interface, TRUE);

  g_signal_connect (interface,
                    "handle-hello-world",
                    G_CALLBACK (on_handle_hello_world),
                    some_user_data);

  [...]

  error = NULL;
  if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
                                         connection,
                                         "/path/of/dbus_object",
                                         &error))
    {
      /* handle error */
    }

C Type Mapping

Scalar types (type-strings 'b', 'y', 'n', 'q', 'i', 'u', 'x', 't' and 'd') ), strings (type-strings 's', 'ay', 'o' and 'g') and arrays of string (type-strings 'as', 'ao' and 'aay') are mapped to the natural types, e.g. gboolean, gdouble, gint, gchar*, gchar** and so on. Everything else is mapped to the GVariant type.

This automatic mapping can be turned off by using the annotation org.gtk.GDBus.C.ForceGVariant - if used then a GVariant is always exchanged instead of the corresponding native C type. This annotation may be convenient to use when using bytestrings (type-string 'ay') for data that could have embedded NUL bytes.

Stability Guarantees

The generated C functions are guaranteed to not change their ABI that is, if a method, signal or property does not change its signature in the introspection XML, the generated C functions will not change its C ABI either. The ABI of the generated instance and class structures will be preserved as well.

The ABI of the generated GTypes will be preserved only if the org.gtk.GDBus.Since annotation is used judiciously — this is because the VTable for the GInterface relies on functions pointers for signal handlers. Specifically, if a D-Bus method, property or signal or is added to a D-Bus interface, then ABI of the generated GInterface type is preserved if, and only if, each added method, property signal is annotated with they org.gtk.GDBus.Since annotation using a greater version number than previous versions.

The generated C code currently happens to be annotated with gtk-doc / GObject Introspection comments / annotations. The layout and contents might change in the future so no guarantees about e.g. SECTION usage etc. is given.

While the generated Docbook for D-Bus interfaces isn't expected to change, no guarantees are given at this point.

It is important to note that the generated code should not be checked into revision control systems, nor it should be included in distributed source archives.

Bugs

Please send bug reports to either the distribution bug tracker or the upstream bug tracker at https://bugzilla.gnome.org/enter_bug.cgi?product=glib.

See also

gdbus(1)