1GDBUS-CODEGEN(1) User Commands GDBUS-CODEGEN(1)
2
6 gdbus-codegen - D-Bus code and documentation generator
7
9 gdbus-codegen [-h, --help] [--interface-prefix org.project.Prefix]
10 [--generate-c-code OUTFILES] [--c-namespace YourProject]
11 [--c-generate-object-manager]
12 [--c-generate-autocleanup none|objects|all]
13 [--output-directory OUTDIR] [--generate-docbook OUTFILES]
14 [--pragma-once] [--xml-files FILE] [--header] [--body]
15 [--output OUTFILE] [--annotate ELEMENT KEY VALUE]...
16 FILE [FILE...]
17
19 gdbus-codegen is used to generate code and/or documentation for one or
20 more D-Bus interfaces.
21 gdbus-codegen reads D-Bus Introspection XML[1] from files passed as
23 additional arguments on the command line and generates output files. It
24 currently supports generating C source code (via --body) or header (via
25 --header) and Docbook XML (via --generate-docbook).
26
28 When generating C code, a #GInterface -derived type is generated for
29 each D-Bus interface. Additionally, for every generated type, FooBar,
30 two concrete instantiable types, FooBarProxy and FooBarSkeleton,
31 implementing said interface are also generated. The former is derived
32 from #GDBusProxy and intended for use on the client side while the
33 latter is derived from the #GDBusInterfaceSkeleton type making it easy
34 to export on a #GDBusConnection either directly or via a
35 #GDBusObjectManagerServer instance.
36 For C code generation either --body that generates source code, or
38 --header that generates headers, can be used. These options must be
39 used along with --output, which is used to specify the file to output
40 to.
41 Both files can be generated at the same time by using
43 --generate-c-code, but this option is deprecated. In this case --output
44 cannot be used due to the generation of multiple files. Instead pass
45 --output-directory to specify the directory to put the output files in.
46 By default the current directory will be used.
47 The name of each generated C type is derived from the D-Bus interface
49 name stripped with the prefix given with --interface-prefix and with
50 the dots removed and initial characters capitalized. For example, for
51 the D-Bus interface com.acme.Coyote the name used is ComAcmeCoyote. For
52 the D-Bus interface org.project.Bar.Frobnicator with --interface-prefix
53 org.project., the name used is BarFrobnicator.
54 For methods, signals and properties, if not specified, the name
56 defaults to the name of the method, signal or property.
57 Two forms of the name are used - the CamelCase form and the lower-case
59 form. The CamelCase form is used for the #GType and struct name, while
60 lower-case form is used in function names. The lower-case form is
61 calculated by converting from CamelCase to lower-case and inserting
62 underscores at word boundaries (using certain heuristics).
63 If the value given by the org.gtk.GDBus.C.Name annotation or the
65 --c-namespace option contains an underscore (sometimes called
66 Ugly_Case), then the camel-case name is derived by removing all
67 underscores, and the lower-case name is derived by lower-casing the
68 string. This is useful in some situations where abbreviations are used.
69 For example, if the annotation is used on the interface
70 net.MyCorp.MyApp.iSCSITarget with the value iSCSI_Target the CamelCase
71 form is iSCSITarget while the lower-case form is iscsi_target. If the
72 annotation is used on the method EjectTheiPod with the value
73 Eject_The_iPod, the lower-case form is eject_the_ipod.
74
76 Each generated Docbook XML file (see the --generate-docbook option for
77 details) is a RefEntry[2] article describing the D-Bus interface.
78
80 The following options are supported:
81 -h, --help
83 Show help and exit.
84 --xml-files FILE
86 This option is deprecated; use positional arguments instead. The
87 D-Bus introspection XML file.
88 --interface-prefix org.project.Prefix.
90 A prefix to strip from all D-Bus interface names when calculating
91 the typename for the C binding and the Docbook sortas attribute[3].
92 --generate-docbook OUTFILES
94 Generate Docbook Documentation for each D-Bus interface and put it
95 in OUTFILES-NAME.xml where NAME is a place-holder for the interface
96 name, e.g. net.Corp.FooBar and so on.
97 Pass --output-directory to specify the directory to put the output
99 files in. By default the current directory will be used.
100 --generate-c-code OUTFILES
102 Generate C code for all D-Bus interfaces and put it in OUTFILES.c
103 and OUTFILES.h including any sub-directories. If you want the files
104 to be output in a different location use --output-directory as
105 OUTFILES.h including sub-directories will be referenced from
106 OUTFILES.c.
107 The full paths would then be $(OUTDIR)/$(dirname
109 $OUTFILES)/$(basename $OUTFILES).{c,h}.
110 --c-namespace YourProject
112 The namespace to use for generated C code. This is expected to be
113 in CamelCase[4] or Ugly_Case (see above).
114 --pragma-once
116 If this option is passed, the #pragma once[5] preprocessor
117 directive is used instead of include guards.
118 --c-generate-object-manager
120 If this option is passed, suitable #GDBusObject, #GDBusObjectProxy,
121 #GDBusObjectSkeleton and #GDBusObjectManagerClient subclasses are
122 generated.
123 --c-generate-autocleanup none|objects|all
125 This option influences what types autocleanup functions are
126 generated for. 'none' means to not generate any autocleanup
127 functions. 'objects' means to generate them for object types, and
128 'all' means to generate them for object types and interfaces. The
129 default is 'objects' due to a corner case in backwards
130 compatibility with a few projects, but you should likely switch
131 your project to use 'all'. This option was added in GLib 2.50.
132 --output-directory OUTDIR
134 Directory to output generated source to. Equivalent to changing
135 directory before generation.
136 This option cannot be used with neither --body nor --header, and
138 --output must be used.
139 --header
141 If this option is passed, it will generate the header code and
142 write it to the disk by using the path and file name provided by
143 --output.
144 Using --generate-c-code, --generate-docbook or --output-directory
146 are not allowed to be used along with --header and --body options,
147 because these options are used to generate only one file.
148 --body
150 If this option is passed, it will generate the source code and
151 write it to the disk by using the path and file name provided by
152 --output.
153 Using --generate-c-code, --generate-docbook or --output-directory
155 are not allowed to be used along with --header and --body options,
156 because these options are used to generate only one file.
157 --output OUTFILE
159 The full path where the header (--header) or the source code
160 (--body) will be written, using the path and filename provided by
161 --output. The full path could be something like $($OUTFILE).{c,h}.
162 Using --generate-c-code, --generate-docbook or --output-directory
164 is not allowed along with --output, because the latter is used to
165 generate only one file.
166 --annotate ELEMENT KEY VALUE
168 Used to inject D-Bus annotations into the given XML files. It can
169 be used with interfaces, methods, signals, properties and arguments
170 in the following way:
171 gdbus-codegen --c-namespace MyApp \
173 --generate-c-code myapp-generated \
174 --annotate "org.project.InterfaceName" \
175 org.gtk.GDBus.C.Name MyFrobnicator \
176 --annotate "org.project.InterfaceName:Property" \
177 bar bat \
178 --annotate "org.project.InterfaceName.Method()" \
179 org.freedesktop.DBus.Deprecated true \
180 --annotate "org.project.InterfaceName.Method()[arg_name]" \
181 snake hiss \
182 --annotate "org.project.InterfaceName::Signal" \
183 cat meow \
184 --annotate "org.project.InterfaceName::Signal[arg_name]" \
185 dog wuff \
186 myapp-dbus-interfaces.xml
187 Any UTF-8 string can be used for KEY and VALUE.
188
190 The following D-Bus annotations are supported by gdbus-codegen:
191 org.freedesktop.DBus.Deprecated
193 Can be used on any <interface>, <method>, <signal> and <property>
194 element to specify that the element is deprecated if its value is
195 true. Note that this annotation is defined in the D-Bus
196 specification[1] and can only assume the values true and false. In
197 particular, you cannot specify the version that the element was
198 deprecated in nor any helpful deprecation message. Such information
199 should be added to the element documentation instead.
200 When generating C code, this annotation is used to add
202 #G_GNUC_DEPRECATED to generated functions for the element.
203 When generating Docbook XML, a deprecation warning will appear
205 along the documentation for the element.
206 org.gtk.GDBus.Since
208 Can be used on any <interface>, <method>, <signal> and <property>
209 element to specify the version (any free-form string but compared
210 using a version-aware sort function) the element appeared in.
211 When generating C code, this field is used to ensure function
213 pointer order for preserving ABI/API, see the section called
214 “STABILITY GUARANTEES”.
215 When generating Docbook XML, the value of this tag appears in the
217 documentation.
218 org.gtk.GDBus.DocString
220 A string with Docbook content for documentation. This annotation
221 can be used on <interface>, <method>, <signal>, <property> and
222 <arg> elements.
223 org.gtk.GDBus.DocString.Short
225 A string with Docbook content for short/brief documentation. This
226 annotation can only be used on <interface> elements.
227 org.gtk.GDBus.C.Name
229 Can be used on any <interface>, <method>, <signal> and <property>
230 element to specify the name to use when generating C code. The
231 value is expected to be in CamelCase[4] or Ugly_Case (see above).
232 org.gtk.GDBus.C.ForceGVariant
234 If set to a non-empty string, a #GVariant instance will be used
235 instead of the natural C type. This annotation can be used on any
236 <arg> and <property> element.
237 org.gtk.GDBus.C.UnixFD
239 If set to a non-empty string, the generated code will include
240 parameters to exchange file descriptors using the #GUnixFDList
241 type. This annotation can be used on <method> elements.
242 As an easier alternative to using the org.gtk.GDBus.DocString
244 annotation, note that parser used by gdbus-codegen parses XML comments
245 in a way similar to gtk-doc[6]:
246 Note that @since can be used in any inline documentation bit (e.g. for
248 interfaces, methods, signals and properties) to set the
249 org.gtk.GDBus.Since annotation. For the org.gtk.GDBus.DocString
250 annotation (and inline comments), note that substrings of the form
251 #net.Corp.Bar, net.Corp.Bar.FooMethod(), #net.Corp.Bar::BarSignal and
252 #net.Corp.InlineDocs:BazProperty are all expanded to links to the
253 respective interface, method, signal and property. Additionally,
254 substrings starting with @ and % characters are rendered as
255 parameter[7] and constant[8] respectively.
256 If both XML comments and org.gtk.GDBus.DocString or
258 org.gtk.GDBus.DocString.Short annotations are present, the latter wins.
259
261 Consider the following D-Bus Introspection XML.
262 <node>
264 <interface name="net.Corp.MyApp.Frobber">
265 <method name="HelloWorld">
266 <arg name="greeting" direction="in" type="s"/>
267 <arg name="response" direction="out" type="s"/>
268 </method>
269 <signal name="Notification">
271 <arg name="icon_blob" type="ay"/>
272 <arg name="height" type="i"/>
273 <arg name="messages" type="as"/>
274 </signal>
275 <property name="Verbose" type="b" access="readwrite"/>
277 </interface>
278 </node>
279 If gdbus-codegen is used on this file like this:
281 gdbus-codegen --generate-c-code myapp-generated \
283 --c-namespace MyApp \
284 --interface-prefix net.corp.MyApp. \
285 net.Corp.MyApp.Frobber.xml
286 two files called myapp-generated.[ch] are generated. The files provide
288 an abstract #GTypeInterface -derived type called MyAppFrobber as well
289 as two instantiable types with the same name but suffixed with Proxy
290 and Skeleton. The generated file, roughly, contains the following
291 facilities:
292 /* GType macros for the three generated types */
294 #define MY_APP_TYPE_FROBBER (my_app_frobber_get_type ())
295 #define MY_APP_TYPE_FROBBER_SKELETON (my_app_frobber_skeleton_get_type ())
296 #define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ())
297 typedef struct _MyAppFrobber MyAppFrobber; /* Dummy typedef */
299 typedef struct
301 {
302 GTypeInterface parent_iface;
303 /* Signal handler for the ::notification signal */
305 void (*notification) (MyAppFrobber *proxy,
306 GVariant *icon_blob,
307 gint height,
308 const gchar* const *messages);
309 /* Signal handler for the ::handle-hello-world signal */
311 gboolean (*handle_hello_world) (MyAppFrobber *proxy,
312 GDBusMethodInvocation *invocation,
313 const gchar *greeting);
314 } MyAppFrobberIface;
315 /* Asynchronously calls HelloWorld() */
317 void
318 my_app_frobber_call_hello_world (MyAppFrobber *proxy,
319 const gchar *greeting,
320 GCancellable *cancellable,
321 GAsyncReadyCallback callback,
322 gpointer user_data);
323 gboolean
324 my_app_frobber_call_hello_world_finish (MyAppFrobber *proxy,
325 gchar **out_response,
326 GAsyncResult *res,
327 GError **error);
328 /* Synchronously calls HelloWorld(). Blocks calling thread. */
330 gboolean
331 my_app_frobber_call_hello_world_sync (MyAppFrobber *proxy,
332 const gchar *greeting,
333 gchar **out_response,
334 GCancellable *cancellable,
335 GError **error);
336 /* Completes handling the HelloWorld() method call */
338 void
339 my_app_frobber_complete_hello_world (MyAppFrobber *object,
340 GDBusMethodInvocation *invocation,
341 const gchar *response);
342 /* Emits the ::notification signal / Notification() D-Bus signal */
344 void
345 my_app_frobber_emit_notification (MyAppFrobber *object,
346 GVariant *icon_blob,
347 gint height,
348 const gchar* const *messages);
349 /* Gets the :verbose GObject property / Verbose D-Bus property.
351 * Does no blocking I/O.
352 */
353 gboolean my_app_frobber_get_verbose (MyAppFrobber *object);
354 /* Sets the :verbose GObject property / Verbose D-Bus property.
356 * Does no blocking I/O.
357 */
358 void my_app_frobber_set_verbose (MyAppFrobber *object,
359 gboolean value);
360 /* Gets the interface info */
362 GDBusInterfaceInfo *my_app_frobber_interface_info (void);
363 /* Creates a new skeleton object, ready to be exported */
365 MyAppFrobber *my_app_frobber_skeleton_new (void);
366 /* Client-side proxy constructors.
368 *
369 * Additionally, _new_for_bus(), _new_for_bus_finish() and
370 * _new_for_bus_sync() proxy constructors are also generated.
371 */
372 void
373 my_app_frobber_proxy_new (GDBusConnection *connection,
374 GDBusProxyFlags flags,
375 const gchar *name,
376 const gchar *object_path,
377 GCancellable *cancellable,
378 GAsyncReadyCallback callback,
379 gpointer user_data);
380 MyAppFrobber *
381 my_app_frobber_proxy_new_finish (GAsyncResult *res,
382 GError **error);
383 MyAppFrobber *
384 my_app_frobber_proxy_new_sync (GDBusConnection *connection,
385 GDBusProxyFlags flags,
386 const gchar *name,
387 const gchar *object_path,
388 GCancellable *cancellable,
389 GError **error);
390 Thus, for every D-Bus method, there will be three C functions for
392 calling the method, one #GObject signal for handling an incoming call
393 and one C function for completing an incoming call. For every D-Bus
394 signal, there's one #GObject signal and one C function for emitting it.
395 For every D-Bus property, two C functions are generated (one setter,
396 one getter) and one #GObject property. The following table summarizes
397 the generated facilities and where they are applicable:
398 ┌───────────┬─────────────────────┬──────────────────────────────┐
400 │ │ Client │ Server │
401 ├───────────┼─────────────────────┼──────────────────────────────┤
402 │Types │ Use │ Any type │
403 │ │ MyAppFrobberProxy │ implementing the │
404 │ │ │ MyAppFrobber │
405 │ │ │ interface │
406 ├───────────┼─────────────────────┼──────────────────────────────┤
407 │Methods │ Use │ Receive via the │
408 │ │ m_a_f_hello_world() │ handle_hello_world() │
409 │ │ to call. │ signal handler. │
410 │ │ │ Complete the call │
411 │ │ │ with │
412 │ │ │ m_a_f_complete_hello_world() │
413 ├───────────┼─────────────────────┼──────────────────────────────┤
414 │Signals │ Connect to the │ Use │
415 │ │ ::notification │ m_a_f_emit_notification() to │
416 │ │ GObject signal. │ emit signal. │
417 ├───────────┼─────────────────────┼──────────────────────────────┤
418 │Properties │ Use │ Implement #GObject's │
419 │(Reading) │ m_a_f_get_verbose() │ get_property() vfunc. │
420 │ │ or :verbose. │ │
421 ├───────────┼─────────────────────┼──────────────────────────────┤
422 │Properties │ Use │ Implement #GObject's │
423 │(writing) │ m_a_f_set_verbose() │ set_property() vfunc. │
424 │ │ or :verbose. │ │
425 └───────────┴─────────────────────┴──────────────────────────────┘
426 Client-side usage
428 You can use the generated proxy type with the generated constructors:
429 MyAppFrobber *proxy;
431 GError *error;
432 error = NULL;
434 proxy = my_app_frobber_proxy_new_for_bus_sync (
435 G_BUS_TYPE_SESSION,
436 G_DBUS_PROXY_FLAGS_NONE,
437 "net.Corp.MyApp", /* bus name */
438 "/net/Corp/MyApp/SomeFrobber", /* object */
439 NULL, /* GCancellable* */
440 &error);
441 /* do stuff with proxy */
442 g_object_unref (proxy);
443 Instead of using the generic #GDBusProxy facilities, one can use the
445 generated methods such as my_app_frobber_call_hello_world() to invoke
446 the net.Corp.MyApp.Frobber.HelloWorld() D-Bus method, connect to the
447 ::notification GObject signal to receive the
448 net.Corp.MyApp.Frobber::Notication D-Bus signal and get/set the
449 net.Corp.MyApp.Frobber:Verbose D-Bus Property using either the GObject
450 property :verbose or the my_app_get_verbose() and my_app_set_verbose()
451 methods. Use the standard #GObject::notify signal to listen to property
452 changes.
453 Note that all property access is via #GDBusProxy 's property cache so
455 no I/O is ever done when reading properties. Also note that setting a
456 property will cause the org.freedesktop.DBus.Properties.Set[9] method
457 to be called on the remote object. This call, however, is asynchronous
458 so setting a property won't block. Further, the change is delayed and
459 no error checking is possible.
460 Server-side usage
462 The generated MyAppFrobber interface is designed so it is easy to
463 implement it in a #GObject subclass. For example, to handle
464 HelloWorld() method invocations, set the vfunc for
465 handle_hello_hello_world() in the MyAppFrobberIface structure.
466 Similary, to handle the net.Corp.MyApp.Frobber:Verbose property
467 override the :verbose #GObject property from the subclass. To emit a
468 signal, use e.g. my_app_emit_signal() or g_signal_emit_by_name().
469 Instead of subclassing, it is often easier to use the generated
471 MyAppFrobberSkeleton subclass. To handle incoming method calls, use
472 g_signal_connect() with the ::handle-* signals and instead of
473 overriding #GObject 's get_property() and set_property() vfuncs, use
474 g_object_get() and g_object_set() or the generated property getters and
475 setters (the generated class has an internal property bag
476 implementation).
477 static gboolean
479 on_handle_hello_world (MyAppFrobber *interface,
480 GDBusMethodInvocation *invocation,
481 const gchar *greeting,
482 gpointer user_data)
483 {
484 if (g_strcmp0 (greeting, "Boo") != 0)
485 {
486 gchar *response;
487 response = g_strdup_printf ("Word! You said `%s'.", greeting);
488 my_app_complete_hello_world (interface, invocation, response);
489 g_free (response);
490 }
491 else
492 {
493 g_dbus_method_invocation_return_error (invocation,
494 MY_APP_ERROR,
495 MY_APP_ERROR_NO_WHINING,
496 "Hey, %s, there will be no whining!",
497 g_dbus_method_invocation_get_sender (invocation));
498 }
499 return TRUE;
500 }
501 [...]
503 interface = my_app_frobber_skeleton_new ();
505 my_app_frobber_set_verbose (interface, TRUE);
506 g_signal_connect (interface,
508 "handle-hello-world",
509 G_CALLBACK (on_handle_hello_world),
510 some_user_data);
511 [...]
513 error = NULL;
515 if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
516 connection,
517 "/path/of/dbus_object",
518 &error))
519 {
520 /* handle error */
521 }
522 To facilitate atomic changesets (multiple properties changing at the
524 same time), #GObject::notify signals are queued up when received. The
525 queue is drained in an idle handler (which is called from the
526 thread-default main loop of the thread where the skeleton object was
527 contructed) and will cause emissions of the
528 org.freedesktop.DBus.Properties::PropertiesChanged[9] signal with all
529 the properties that have changed. Use g_dbus_interface_skeleton_flush()
530 or g_dbus_object_skeleton_flush() to empty the queue immediately. Use
531 g_object_freeze_notify() and g_object_thaw_notify() for atomic
532 changesets if on a different thread.
533
535 Scalar types (type-strings 'b', 'y', 'n', 'q', 'i', 'u', 'x', 't' and
536 'd') ), strings (type-strings 's', 'ay', 'o' and 'g') and arrays of
537 string (type-strings 'as', 'ao' and 'aay') are mapped to the natural
538 types, e.g. #gboolean, #gdouble, #gint, gchar*, gchar** and so on.
539 Everything else is mapped to the #GVariant type.
540 This automatic mapping can be turned off by using the annotation
542 org.gtk.GDBus.C.ForceGVariant - if used then a #GVariant is always
543 exchanged instead of the corresponding native C type. This annotation
544 may be convenient to use when using bytestrings (type-string 'ay') for
545 data that could have embedded NUL bytes.
546
548 The generated C functions are guaranteed to not change their ABI that
549 is, if a method, signal or property does not change its signature in
550 the introspection XML, the generated C functions will not change its C
551 ABI either. The ABI of the generated instance and class structures will
552 be preserved as well.
553 The ABI of the generated #GType s will be preserved only if the
555 org.gtk.GDBus.Since annotation is used judiciously — this is because
556 the VTable for the #GInterface relies on functions pointers for signal
557 handlers. Specifically, if a D-Bus method, property or signal or is
558 added to a D-Bus interface, then ABI of the generated #GInterface type
559 is preserved if, and only if, each added method, property signal is
560 annotated with they org.gtk.GDBus.Since annotation using a greater
561 version number than previous versions.
562 The generated C code currently happens to be annotated with gtk-doc[6]
564 / GObject Introspection[10] comments / annotations. The layout and
565 contents might change in the future so no guarantees about e.g.
566 SECTION usage etc. is given.
567 While the generated Docbook for D-Bus interfaces isn't expected to
569 change, no guarantees are given at this point.
570 It is important to note that the generated code should not be checked
572 into revision control systems, nor it should be included in distributed
573 source archives.
574
576 Please send bug reports to either the distribution bug tracker or the
577 upstream bug tracker at
578 https://bugzilla.gnome.org/enter_bug.cgi?product=glib.
579
581 gdbus(1)
582
584 1. D-Bus Introspection XML
585 http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format
586 2. RefEntry
588 http://www.docbook.org/tdg/en/html/refentry.html
589 3. sortas attribute
591 http://www.docbook.org/tdg/en/html/primary.html
592 4. CamelCase
594 http://en.wikipedia.org/wiki/CamelCase
595 5. #pragma once
597 https://en.wikipedia.org/wiki/Pragma_once
598 6. gtk-doc
600 http://www.gtk.org/gtk-doc/
601 7. parameter
603 http://www.docbook.org/tdg/en/html/parameter.html
604 8. constant
606 http://www.docbook.org/tdg/en/html/constant.html
607 9. org.freedesktop.DBus.Properties.Set
609 http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties
610 10. GObject Introspection
612 https://wiki.gnome.org/Projects/GObjectIntrospection
613GIO GDBUS-CODEGEN(1)