gdbus-codegengdbus-codegen — D-Bus code and documentation generator |
Synopsis
gdbus-codegen
[-h
, --help
] [--interface-prefix
org.project.Prefix
] [--generate-c-code
OUTFILES
] [--c-namespace
YourProject
] [--c-generate-object-manager
] [--c-generate-autocleanup
none|objects|all] [--output-directory
OUTDIR
] [--generate-docbook
OUTFILES
] [--pragma-once
] [--xml-files
FILE
] [--header
] [--body
] [--output
OUTFILE
] [
--annotate
ELEMENT
KEY
VALUE
]... FILE [
FILE...
]
Description
gdbus-codegen is used to generate code and/or documentation for one or more D-Bus interfaces.
gdbus-codegen reads
D-Bus
Introspection XML from files passed as additional
arguments on the command line and generates output files.
It currently supports generating C source code (via
--body
) or header (via --header
)
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.
For C code generation either --body
that
generates source code, or --header
that
generates headers, can be used. These options must be used along with
--output
, which is used to specify the file to output to.
Both files can be generated at the same time by using
--generate-c-code
, but this option is deprecated.
In this case --output
cannot be used due to the
generation of multiple files. Instead pass
--output-directory
to specify the directory to put
the output files in. By default the current directory will be used.
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:
|
Show help and exit. |
||
|
This option is deprecated; use positional arguments instead. The D-Bus introspection XML file. |
||
|
A prefix to strip from all D-Bus interface names when calculating the typename for the C binding and the Docbook sortas attribute. |
||
|
Generate Docbook Documentation for each D-Bus interface and
put it in
Pass |
||
|
Generate C code for all D-Bus interfaces and put it in
The full paths would then be |
||
|
The namespace to use for generated C code. This is expected to be in CamelCase or Ugly_Case (see above). |
||
|
If this option is passed, the #pragma once preprocessor directive is used instead of include guards. |
||
|
If this option is passed, suitable GDBusObject, GDBusObjectProxy, GDBusObjectSkeleton and GDBusObjectManagerClient subclasses are generated. |
||
|
This option influences what types autocleanup functions are generated for. 'none' means to not generate any autocleanup functions. 'objects' means to generate them for object types, and 'all' means to generate them for object types and interfaces. The default is 'objects' due to a corner case in backwards compatibility with a few projects, but you should likely switch your project to use 'all'. This option was added in GLib 2.50. |
||
|
Directory to output generated source to. Equivalent to changing directory before generation.
This option cannot be used with neither |
||
|
If this option is passed, it will generate the header code and write it to the disk by
using the path and file name provided by
Using |
||
|
If this option is passed, it will generate the source code and write it to the disk by
using the path and file name provided by
Using |
||
|
The full path where the header (
Using |
||
|
Used to inject D-Bus annotations into the given XML files. It can be used with interfaces, methods, signals, properties and arguments in the following way:
Any UTF-8 string can be used for |
Supported D-Bus Annotations
The following D-Bus annotations are supported by gdbus-codegen:
|
Can be used on any When generating C code, this annotation is used to add G_GNUC_DEPRECATED to generated functions for the element. When generating Docbook XML, a deprecation warning will appear along the documentation for the element. |
|
Can be used on any When generating C code, this field is used to ensure function pointer order for preserving ABI/API, see the section called “Stability Guarantees”. When generating Docbook XML, the value of this tag appears in the documentation. |
|
A string with Docbook content for documentation. This annotation can
be used on |
|
A string with Docbook content for short/brief
documentation. This annotation can only be used on
|
|
Can be used on any |
|
If set to a non-empty string, a GVariant instance will
be used instead of the natural C type. This annotation can
be used on any |
|
If set to a non-empty string, the generated code will
include parameters to exchange file descriptors using the
GUnixFDList type. This annotation can be used on
|
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 <parameter>since</parameter>
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
<link linkend="net.Corp.Bar"><type>net.Corp.Bar</type></link>
,
net.Corp.Bar.FooMethod()
,
<link linkend="net.Corp.Bar-BarSignal"><type>“BarSignal”</type></link>
and
<link linkend="net.Corp.InlineDocs--BazProperty"><type>“BazProperty”</type></link>
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:
Client | Server | |
---|---|---|
Types | Use MyAppFrobberProxy | Any type implementing the MyAppFrobber interface |
Methods | Use to call. |
Receive via the signal handler. Complete the call with
|
Signals | Connect to the ::notification GObject signal. |
Use to emit signal. |
Properties (Reading) | Use or :verbose . |
Implement GObject's vfunc. |
Properties (writing) | Use or :verbose . |
Implement GObject's vfunc. |
Client-side usage
You can use the generated proxy type with the generated constructors:
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); |
Instead of using the generic GDBusProxy facilities, one can use
the generated methods such as
to invoke
the my_app_frobber_call_hello_world()
net.Corp.MyApp.Frobber.HelloWorld()
D-Bus method, connect to the
::notification
GObject signal to receive
the net.Corp.MyApp.Frobber::Notication
D-Bus signal and get/set the
net.Corp.MyApp.Frobber:Verbose
D-Bus
Property using either the GObject property
:verbose
or the
and
my_app_get_verbose()
methods. Use the
standard “notify” signal to listen to property changes.
my_app_set_verbose()
Note that all property access is via GDBusProxy's property cache so no I/O is ever done when reading properties. Also note that setting a property will cause the org.freedesktop.DBus.Properties.Set method to be called on the remote object. This call, however, is asynchronous so setting a property won't block. Further, the change is delayed and no error checking is possible.
Server-side usage
The generated MyAppFrobber interface is designed so
it is easy to implement it in a GObject
subclass. For example, to handle
method invocations, set the
vfunc for HelloWorld()
in the
MyAppFrobberIface structure. Similary, to handle
the handle_hello_hello_world()
net.Corp.MyApp.Frobber:Verbose
property override the :verbose
GObject
property from the subclass. To emit a signal, use
e.g.
or
my_app_emit_signal()
g_signal_emit_by_name()
.
Instead of subclassing, it is often easier to use the generated
MyAppFrobberSkeleton subclass. To handle incoming
method calls, use
with
the g_signal_connect()
::handle-*
signals and instead of
overriding GObject's
and
get_property()
vfuncs, use
set_property()
g_object_get()
and
g_object_set()
or the generated property
getters and setters (the generated class has an internal
property bag implementation).
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 */ } |
To facilitate atomic changesets (multiple properties changing at
the same time), “notify” signals are queued up when
received. The queue is drained in an idle handler (which is called from the
thread-default main loop
of the thread where the skeleton object was
contructed) and will cause emissions of the org.freedesktop.DBus.Properties::PropertiesChanged
signal with all the properties that have changed. Use
g_dbus_interface_skeleton_flush()
or
g_dbus_object_skeleton_flush()
to empty the queue
immediately. Use g_object_freeze_notify()
and
g_object_thaw_notify()
for atomic changesets if on a different
thread.
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.