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 [--interface-info-header] [--interface-info-body]
16 [--symbol-decorator DECORATOR]
17 [--symbol-decorator-header HEADER]
18 [--symbol-decorator-define DEFINE] [--output OUTFILE]
19 [--annotate ELEMENT KEY VALUE]...
20 [--glib-min-required VERSION]
21 [--glib-max-allowed VERSION] FILE [FILE...]
22
24 gdbus-codegen is used to generate code and/or documentation for one or
25 more D-Bus interfaces.
26 gdbus-codegen reads D-Bus Introspection XML[1] from files passed as
28 additional arguments on the command line and generates output files. It
29 currently supports generating C source code (via --body) or header (via
30 --header) and Docbook XML (via --generate-docbook). Alternatively, more
31 restricted C source code and headers can be generated, which just
32 contain the interface information (as GDBusInterfaceInfo structures)
33 using --interface-info-body and --interface-info-header.
34
36 When generating C code, a #GInterface -derived type is generated for
37 each D-Bus interface. Additionally, for every generated type, FooBar,
38 two concrete instantiatable types, FooBarProxy and FooBarSkeleton,
39 implementing said interface are also generated. The former is derived
40 from #GDBusProxy and intended for use on the client side while the
41 latter is derived from the #GDBusInterfaceSkeleton type making it easy
42 to export on a #GDBusConnection either directly or via a
43 #GDBusObjectManagerServer instance.
44 For C code generation either --body that generates source code,
46 --header that generates headers, --interface-info-body that generates
47 interface information source code, or --interface-info-header that
48 generates interface information headers, can be used. These options
49 must be used along with --output, which is used to specify the file to
50 output to.
51 Both files can be generated at the same time by using
53 --generate-c-code, but this option is deprecated. In this case --output
54 cannot be used due to the generation of multiple files. Instead pass
55 --output-directory to specify the directory to put the output files in.
56 By default the current directory will be used.
57 The name of each generated C type is derived from the D-Bus interface
59 name stripped with the prefix given with --interface-prefix and with
60 the dots removed and initial characters capitalized. For example, for
61 the D-Bus interface com.acme.Coyote the name used is ComAcmeCoyote. For
62 the D-Bus interface org.project.Bar.Frobnicator with --interface-prefix
63 org.project., the name used is BarFrobnicator.
64 For methods, signals and properties, if not specified, the name
66 defaults to the name of the method, signal or property.
67 Two forms of the name are used - the CamelCase form and the lower-case
69 form. The CamelCase form is used for the #GType and struct name, while
70 lower-case form is used in function names. The lower-case form is
71 calculated by converting from CamelCase to lower-case and inserting
72 underscores at word boundaries (using certain heuristics).
73 If the value given by the org.gtk.GDBus.C.Name annotation or the
75 --c-namespace option contains an underscore (sometimes called
76 Ugly_Case), then the camel-case name is derived by removing all
77 underscores, and the lower-case name is derived by lower-casing the
78 string. This is useful in some situations where abbreviations are used.
79 For example, if the annotation is used on the interface
80 net.MyCorp.MyApp.iSCSITarget with the value iSCSI_Target the CamelCase
81 form is iSCSITarget while the lower-case form is iscsi_target. If the
82 annotation is used on the method EjectTheiPod with the value
83 Eject_The_iPod, the lower-case form is eject_the_ipod.
84
86 Each generated Docbook XML file (see the --generate-docbook option for
87 details) is a RefEntry[2] article describing the D-Bus interface.
88
90 The following options are supported:
91 -h, --help
93 Show help and exit.
94 --xml-files FILE
96 This option is deprecated; use positional arguments instead. The
97 D-Bus introspection XML file.
98 --interface-prefix org.project.Prefix.
100 A prefix to strip from all D-Bus interface names when calculating
101 the typename for the C binding and the Docbook sortas attribute[3].
102 --generate-docbook OUTFILES
104 Generate Docbook Documentation for each D-Bus interface and put it
105 in OUTFILES-NAME.xml where NAME is a place-holder for the interface
106 name, e.g. net.Corp.FooBar and so on.
107 Pass --output-directory to specify the directory to put the output
109 files in. By default the current directory will be used.
110 --generate-c-code OUTFILES
112 Generate C code for all D-Bus interfaces and put it in OUTFILES.c
113 and OUTFILES.h including any sub-directories. If you want the files
114 to be output in a different location use --output-directory as
115 OUTFILES.h including sub-directories will be referenced from
116 OUTFILES.c.
117 The full paths would then be $(OUTDIR)/$(dirname
119 $OUTFILES)/$(basename $OUTFILES).{c,h}.
120 --c-namespace YourProject
122 The namespace to use for generated C code. This is expected to be
123 in CamelCase[4] or Ugly_Case (see above).
124 --pragma-once
126 If this option is passed, the #pragma once[5] preprocessor
127 directive is used instead of include guards.
128 --c-generate-object-manager
130 If this option is passed, suitable #GDBusObject, #GDBusObjectProxy,
131 #GDBusObjectSkeleton and #GDBusObjectManagerClient subclasses are
132 generated.
133 --c-generate-autocleanup none|objects|all
135 This option influences what types autocleanup functions are
136 generated for. 'none' means to not generate any autocleanup
137 functions. 'objects' means to generate them for object types, and
138 'all' means to generate them for object types and interfaces. The
139 default is 'objects' due to a corner case in backwards
140 compatibility with a few projects, but you should likely switch
141 your project to use 'all'. This option was added in GLib 2.50.
142 --output-directory OUTDIR
144 Directory to output generated source to. Equivalent to changing
145 directory before generation.
146 This option cannot be used with --body, --header,
148 --interface-info-body or --interface-info-header; and --output must
149 be used.
150 --header
152 If this option is passed, it will generate the header code and
153 write it to the disk by using the path and file name provided by
154 --output.
155 Using --generate-c-code, --generate-docbook or --output-directory
157 are not allowed to be used along with --header and --body options,
158 because these options are used to generate only one file.
159 --body
161 If this option is passed, it will generate the source code and
162 write it to the disk by using the path and file name provided by
163 --output.
164 Using --generate-c-code, --generate-docbook or --output-directory
166 are not allowed to be used along with --header and --body options,
167 because these options are used to generate only one file.
168 --interface-info-header
170 If this option is passed, it will generate the header code for the
171 GDBusInterfaceInfo structures only and will write it to the disk by
172 using the path and file name provided by --output.
173 Using --generate-c-code, --generate-docbook or --output-directory
175 are not allowed to be used along with the --interface-info-header
176 and --interface-info-body options, because these options are used
177 to generate only one file.
178 --interface-info-body
180 If this option is passed, it will generate the source code for the
181 GDBusInterfaceInfo structures only and will write it to the disk by
182 using the path and file name provided by --output.
183 Using --generate-c-code, --generate-docbook or --output-directory
185 are not allowed to be used along with the --interface-info-header
186 and --interface-info-body options, because these options are used
187 to generate only one file.
188 --symbol-decorator DECORATOR
190 If a DECORATOR is passed in with this option, all the generated
191 function prototypes in the generated header will be marked with
192 DECORATOR. This can be used, for instance, to export symbols from
193 code generated with gdbus-codegen. This option is added in
194 GLib-2.66
195 --symbol-decorator-header HEADER
197 If a HEADER is passed in with this option, the generated header
198 will put a #include HEADER before the rest of the items, except for
199 the inclusion guards or #pragma once (if --pragma-once is used).
200 This is used if using another header file is needed for the
201 decorator passed in via --symbol-decorator to be defined. This
202 option is added in GLib-2.66.
203 This option can only be used if --symbol-decorator is used.
205 --symbol-decorator-define DEFINE
207 If a DEFINE is passed in with this option, the generated source
208 will add a #define DEFINE before the rest of the items. This is
209 used if a particular macro is needed to ensure the decorator passed
210 in via --symbol-decorator uses the correct definition when the
211 generated source is being compiled. This option is added in
212 GLib-2.66.
213 This option can only be used if --symbol-decorator is used.
215 --output OUTFILE
217 The full path where the header (--header, --interface-info-header)
218 or the source code (--body, --interface-info-body) will be written,
219 using the path and filename provided by --output. The full path
220 could be something like $($OUTFILE).{c,h}.
221 Using --generate-c-code, --generate-docbook or --output-directory
223 is not allowed along with --output, because the latter is used to
224 generate only one file.
225 --annotate ELEMENT KEY VALUE
227 Used to inject D-Bus annotations into the given XML files. It can
228 be used with interfaces, methods, signals, properties and arguments
229 in the following way:
230 gdbus-codegen --c-namespace MyApp \
232 --generate-c-code myapp-generated \
233 --annotate "org.project.InterfaceName" \
234 org.gtk.GDBus.C.Name MyFrobnicator \
235 --annotate "org.project.InterfaceName:Property" \
236 bar bat \
237 --annotate "org.project.InterfaceName.Method()" \
238 org.freedesktop.DBus.Deprecated true \
239 --annotate "org.project.InterfaceName.Method()[arg_name]" \
240 snake hiss \
241 --annotate "org.project.InterfaceName::Signal" \
242 cat meow \
243 --annotate "org.project.InterfaceName::Signal[arg_name]" \
244 dog wuff \
245 myapp-dbus-interfaces.xml
246 Any UTF-8 string can be used for KEY and VALUE.
247 --glib-min-required VERSION
249 Specifies the minimum version of GLib which the code generated by
250 gdbus-codegen can depend on. This may be used to make
251 backwards-incompatible changes in the output or behaviour of
252 gdbus-codegen in future, which users may opt in to by increasing
253 the value they pass for --glib-min-required. If this option is not
254 passed, the output from gdbus-codegen is guaranteed to be
255 compatible with all versions of GLib from 2.30 upwards, as that is
256 when gdbus-codegen was first released.
257 Note that some version parameters introduce incompatible changes:
259 all callers of the generated code might need to be updated, and if
260 the generated code is part of a library's API or ABI, then
261 increasing the version parameter can result in an API or ABI break.
262 The version number must be of the form MAJOR.MINOR.MICRO, where all
264 parts are integers. MINOR and MICRO are optional. The version
265 number may not be smaller than 2.30.
266 If the version number is 2.64 or greater, the generated code will
268 have the following features: (1) If a method has h (file
269 descriptor) parameter(s), a GUnixFDList parameter will exist in the
270 generated code for it (whereas previously the annotation
271 org.gtk.GDBus.C.UnixFD was required), and (2) Method call functions
272 will have two additional arguments to allow the user to specify
273 GDBusCallFlags and a timeout value, as is possible when using
274 g_dbus_proxy_call().
275 --glib-max-allowed VERSION
277 Specifies the maximum version of GLib which the code generated by
278 gdbus-codegen can depend on. This may be used to ensure that code
279 generated by gdbus-codegen is compilable with specific older
280 versions of GLib that your software has to support.
281 The version number must be of the form MAJOR.MINOR.MICRO, where all
283 parts are integers. MINOR and MICRO are optional. The version
284 number must be greater than or equal to that passed to
285 --glib-min-required. It defaults to the version of GLib which
286 provides this gdbus-codegen.
287
289 The following D-Bus annotations are supported by gdbus-codegen:
290 org.freedesktop.DBus.Deprecated
292 Can be used on any <interface>, <method>, <signal> and <property>
293 element to specify that the element is deprecated if its value is
294 true. Note that this annotation is defined in the D-Bus
295 specification[1] and can only assume the values true and false. In
296 particular, you cannot specify the version that the element was
297 deprecated in nor any helpful deprecation message. Such information
298 should be added to the element documentation instead.
299 When generating C code, this annotation is used to add
301 #G_GNUC_DEPRECATED to generated functions for the element.
302 When generating Docbook XML, a deprecation warning will appear
304 along the documentation for the element.
305 org.gtk.GDBus.Since
307 Can be used on any <interface>, <method>, <signal> and <property>
308 element to specify the version (any free-form string but compared
309 using a version-aware sort function) the element appeared in.
310 When generating C code, this field is used to ensure function
312 pointer order for preserving ABI/API, see the section called
313 “STABILITY GUARANTEES”.
314 When generating Docbook XML, the value of this tag appears in the
316 documentation.
317 org.gtk.GDBus.DocString
319 A string with Docbook content for documentation. This annotation
320 can be used on <interface>, <method>, <signal>, <property> and
321 <arg> elements.
322 org.gtk.GDBus.DocString.Short
324 A string with Docbook content for short/brief documentation. This
325 annotation can only be used on <interface> elements.
326 org.gtk.GDBus.C.Name
328 Can be used on any <interface>, <method>, <signal> and <property>
329 element to specify the name to use when generating C code. The
330 value is expected to be in CamelCase[4] or Ugly_Case (see above).
331 org.gtk.GDBus.C.ForceGVariant
333 If set to a non-empty string, a #GVariant instance will be used
334 instead of the natural C type. This annotation can be used on any
335 <arg> and <property> element.
336 org.gtk.GDBus.C.UnixFD
338 If set to a non-empty string, the generated code will include
339 parameters to exchange file descriptors using the #GUnixFDList
340 type. This annotation can be used on <method> elements.
341 As an easier alternative to using the org.gtk.GDBus.DocString
343 annotation, note that parser used by gdbus-codegen parses XML comments
344 in a way similar to gtk-doc[6]:
345 Note that @since can be used in any inline documentation bit (e.g. for
347 interfaces, methods, signals and properties) to set the
348 org.gtk.GDBus.Since annotation. For the org.gtk.GDBus.DocString
349 annotation (and inline comments), note that substrings of the form
350 #net.Corp.Bar, net.Corp.Bar.FooMethod(), #net.Corp.Bar::BarSignal and
351 #net.Corp.InlineDocs:BazProperty are all expanded to links to the
352 respective interface, method, signal and property. Additionally,
353 substrings starting with @ and % characters are rendered as
354 parameter[7] and constant[8] respectively.
355 If both XML comments and org.gtk.GDBus.DocString or
357 org.gtk.GDBus.DocString.Short annotations are present, the latter wins.
358
360 Consider the following D-Bus Introspection XML.
361 <node>
363 <interface name="net.Corp.MyApp.Frobber">
364 <method name="HelloWorld">
365 <arg name="greeting" direction="in" type="s"/>
366 <arg name="response" direction="out" type="s"/>
367 </method>
368 <signal name="Notification">
370 <arg name="icon_blob" type="ay"/>
371 <arg name="height" type="i"/>
372 <arg name="messages" type="as"/>
373 </signal>
374 <property name="Verbose" type="b" access="readwrite"/>
376 </interface>
377 </node>
378 If gdbus-codegen is used on this file like this:
380 gdbus-codegen --generate-c-code myapp-generated \
382 --c-namespace MyApp \
383 --interface-prefix net.corp.MyApp. \
384 net.Corp.MyApp.Frobber.xml
385 two files called myapp-generated.[ch] are generated. The files provide
387 an abstract #GTypeInterface -derived type called MyAppFrobber as well
388 as two instantiatable types with the same name but suffixed with Proxy
389 and Skeleton. The generated file, roughly, contains the following
390 facilities:
391 /* GType macros for the three generated types */
393 #define MY_APP_TYPE_FROBBER (my_app_frobber_get_type ())
394 #define MY_APP_TYPE_FROBBER_SKELETON (my_app_frobber_skeleton_get_type ())
395 #define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ())
396 typedef struct _MyAppFrobber MyAppFrobber; /* Dummy typedef */
398 typedef struct
400 {
401 GTypeInterface parent_iface;
402 /* Signal handler for the ::notification signal */
404 void (*notification) (MyAppFrobber *proxy,
405 GVariant *icon_blob,
406 gint height,
407 const gchar* const *messages);
408 /* Signal handler for the ::handle-hello-world signal */
410 gboolean (*handle_hello_world) (MyAppFrobber *proxy,
411 GDBusMethodInvocation *invocation,
412 const gchar *greeting);
413 } MyAppFrobberIface;
414 /* Asynchronously calls HelloWorld() */
416 void
417 my_app_frobber_call_hello_world (MyAppFrobber *proxy,
418 const gchar *greeting,
419 GCancellable *cancellable,
420 GAsyncReadyCallback callback,
421 gpointer user_data);
422 gboolean
423 my_app_frobber_call_hello_world_finish (MyAppFrobber *proxy,
424 gchar **out_response,
425 GAsyncResult *res,
426 GError **error);
427 /* Synchronously calls HelloWorld(). Blocks calling thread. */
429 gboolean
430 my_app_frobber_call_hello_world_sync (MyAppFrobber *proxy,
431 const gchar *greeting,
432 gchar **out_response,
433 GCancellable *cancellable,
434 GError **error);
435 /* Completes handling the HelloWorld() method call */
437 void
438 my_app_frobber_complete_hello_world (MyAppFrobber *object,
439 GDBusMethodInvocation *invocation,
440 const gchar *response);
441 /* Emits the ::notification signal / Notification() D-Bus signal */
443 void
444 my_app_frobber_emit_notification (MyAppFrobber *object,
445 GVariant *icon_blob,
446 gint height,
447 const gchar* const *messages);
448 /* Gets the :verbose GObject property / Verbose D-Bus property.
450 * Does no blocking I/O.
451 */
452 gboolean my_app_frobber_get_verbose (MyAppFrobber *object);
453 /* Sets the :verbose GObject property / Verbose D-Bus property.
455 * Does no blocking I/O.
456 */
457 void my_app_frobber_set_verbose (MyAppFrobber *object,
458 gboolean value);
459 /* Gets the interface info */
461 GDBusInterfaceInfo *my_app_frobber_interface_info (void);
462 /* Creates a new skeleton object, ready to be exported */
464 MyAppFrobber *my_app_frobber_skeleton_new (void);
465 /* Client-side proxy constructors.
467 *
468 * Additionally, _new_for_bus(), _new_for_bus_finish() and
469 * _new_for_bus_sync() proxy constructors are also generated.
470 */
471 void
472 my_app_frobber_proxy_new (GDBusConnection *connection,
473 GDBusProxyFlags flags,
474 const gchar *name,
475 const gchar *object_path,
476 GCancellable *cancellable,
477 GAsyncReadyCallback callback,
478 gpointer user_data);
479 MyAppFrobber *
480 my_app_frobber_proxy_new_finish (GAsyncResult *res,
481 GError **error);
482 MyAppFrobber *
483 my_app_frobber_proxy_new_sync (GDBusConnection *connection,
484 GDBusProxyFlags flags,
485 const gchar *name,
486 const gchar *object_path,
487 GCancellable *cancellable,
488 GError **error);
489 Thus, for every D-Bus method, there will be three C functions for
491 calling the method, one #GObject signal for handling an incoming call
492 and one C function for completing an incoming call. For every D-Bus
493 signal, there's one #GObject signal and one C function for emitting it.
494 For every D-Bus property, two C functions are generated (one setter,
495 one getter) and one #GObject property. The following table summarizes
496 the generated facilities and where they are applicable:
497 ┌───────────┬─────────────────────┬──────────────────────────────┐
499 │ │ Client │ Server │
500 ├───────────┼─────────────────────┼──────────────────────────────┤
501 │Types │ Use │ Any type │
502 │ │ MyAppFrobberProxy │ implementing the │
503 │ │ │ MyAppFrobber │
504 │ │ │ interface │
505 ├───────────┼─────────────────────┼──────────────────────────────┤
506 │Methods │ Use │ Receive via the │
507 │ │ m_a_f_hello_world() │ handle_hello_world() │
508 │ │ to call. │ signal handler. │
509 │ │ │ Complete the call │
510 │ │ │ with │
511 │ │ │ m_a_f_complete_hello_world() │
512 ├───────────┼─────────────────────┼──────────────────────────────┤
513 │Signals │ Connect to the │ Use │
514 │ │ ::notification │ m_a_f_emit_notification() to │
515 │ │ GObject signal. │ emit signal. │
516 ├───────────┼─────────────────────┼──────────────────────────────┤
517 │Properties │ Use │ Implement #GObject's │
518 │(Reading) │ m_a_f_get_verbose() │ get_property() vfunc. │
519 │ │ or :verbose. │ │
520 ├───────────┼─────────────────────┼──────────────────────────────┤
521 │Properties │ Use │ Implement #GObject's │
522 │(writing) │ m_a_f_set_verbose() │ set_property() vfunc. │
523 │ │ or :verbose. │ │
524 └───────────┴─────────────────────┴──────────────────────────────┘
525 Client-side usage
527 You can use the generated proxy type with the generated constructors:
528 MyAppFrobber *proxy;
530 GError *error;
531 error = NULL;
533 proxy = my_app_frobber_proxy_new_for_bus_sync (
534 G_BUS_TYPE_SESSION,
535 G_DBUS_PROXY_FLAGS_NONE,
536 "net.Corp.MyApp", /* bus name */
537 "/net/Corp/MyApp/SomeFrobber", /* object */
538 NULL, /* GCancellable* */
539 &error);
540 /* do stuff with proxy */
541 g_object_unref (proxy);
542 Instead of using the generic #GDBusProxy facilities, one can use the
544 generated methods such as my_app_frobber_call_hello_world() to invoke
545 the net.Corp.MyApp.Frobber.HelloWorld() D-Bus method, connect to the
546 ::notification GObject signal to receive the
547 net.Corp.MyApp.Frobber::Notification D-Bus signal and get/set the
548 net.Corp.MyApp.Frobber:Verbose D-Bus Property using either the GObject
549 property :verbose or the my_app_get_verbose() and my_app_set_verbose()
550 methods. Use the standard #GObject::notify signal to listen to property
551 changes.
552 Note that all property access is via #GDBusProxy 's property cache so
554 no I/O is ever done when reading properties. Also note that setting a
555 property will cause the org.freedesktop.DBus.Properties.Set[9] method
556 to be called on the remote object. This call, however, is asynchronous
557 so setting a property won't block. Further, the change is delayed and
558 no error checking is possible.
559 Server-side usage
561 The generated MyAppFrobber interface is designed so it is easy to
562 implement it in a #GObject subclass. For example, to handle
563 HelloWorld() method invocations, set the vfunc for
564 handle_hello_hello_world() in the MyAppFrobberIface structure.
565 Similarly, to handle the net.Corp.MyApp.Frobber:Verbose property
566 override the :verbose #GObject property from the subclass. To emit a
567 signal, use e.g. my_app_emit_signal() or g_signal_emit_by_name().
568 Instead of subclassing, it is often easier to use the generated
570 MyAppFrobberSkeleton subclass. To handle incoming method calls, use
571 g_signal_connect() with the ::handle-* signals and instead of
572 overriding #GObject 's get_property() and set_property() vfuncs, use
573 g_object_get() and g_object_set() or the generated property getters and
574 setters (the generated class has an internal property bag
575 implementation).
576 static gboolean
578 on_handle_hello_world (MyAppFrobber *interface,
579 GDBusMethodInvocation *invocation,
580 const gchar *greeting,
581 gpointer user_data)
582 {
583 if (g_strcmp0 (greeting, "Boo") != 0)
584 {
585 gchar *response;
586 response = g_strdup_printf ("Word! You said `%s'.", greeting);
587 my_app_complete_hello_world (interface, invocation, response);
588 g_free (response);
589 }
590 else
591 {
592 g_dbus_method_invocation_return_error (invocation,
593 MY_APP_ERROR,
594 MY_APP_ERROR_NO_WHINING,
595 "Hey, %s, there will be no whining!",
596 g_dbus_method_invocation_get_sender (invocation));
597 }
598 return TRUE;
599 }
600 [...]
602 interface = my_app_frobber_skeleton_new ();
604 my_app_frobber_set_verbose (interface, TRUE);
605 g_signal_connect (interface,
607 "handle-hello-world",
608 G_CALLBACK (on_handle_hello_world),
609 some_user_data);
610 [...]
612 error = NULL;
614 if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
615 connection,
616 "/path/of/dbus_object",
617 &error))
618 {
619 /* handle error */
620 }
621 To facilitate atomic changesets (multiple properties changing at the
623 same time), #GObject::notify signals are queued up when received. The
624 queue is drained in an idle handler (which is called from the
625 thread-default main loop of the thread where the skeleton object was
626 constructed) and will cause emissions of the
627 org.freedesktop.DBus.Properties::PropertiesChanged[9] signal with all
628 the properties that have changed. Use g_dbus_interface_skeleton_flush()
629 or g_dbus_object_skeleton_flush() to empty the queue immediately. Use
630 g_object_freeze_notify() and g_object_thaw_notify() for atomic
631 changesets if on a different thread.
632
634 Scalar types (type-strings 'b', 'y', 'n', 'q', 'i', 'u', 'x', 't' and
635 'd') ), strings (type-strings 's', 'ay', 'o' and 'g') and arrays of
636 string (type-strings 'as', 'ao' and 'aay') are mapped to the natural
637 types, e.g. #gboolean, #gdouble, #gint, gchar*, gchar** and so on.
638 Everything else is mapped to the #GVariant type.
639 This automatic mapping can be turned off by using the annotation
641 org.gtk.GDBus.C.ForceGVariant - if used then a #GVariant is always
642 exchanged instead of the corresponding native C type. This annotation
643 may be convenient to use when using bytestrings (type-string 'ay') for
644 data that could have embedded NUL bytes.
645
647 The generated C functions are guaranteed to not change their ABI that
648 is, if a method, signal or property does not change its signature in
649 the introspection XML, the generated C functions will not change its C
650 ABI either. The ABI of the generated instance and class structures will
651 be preserved as well.
652 The ABI of the generated #GType s will be preserved only if the
654 org.gtk.GDBus.Since annotation is used judiciously — this is because
655 the VTable for the #GInterface relies on functions pointers for signal
656 handlers. Specifically, if a D-Bus method, property or signal or is
657 added to a D-Bus interface, then ABI of the generated #GInterface type
658 is preserved if, and only if, each added method, property signal is
659 annotated with they org.gtk.GDBus.Since annotation using a greater
660 version number than previous versions.
661 The generated C code currently happens to be annotated with gtk-doc[6]
663 / GObject Introspection[10] comments / annotations. The layout and
664 contents might change in the future so no guarantees about e.g.
665 SECTION usage etc. is given.
666 While the generated Docbook for D-Bus interfaces isn't expected to
668 change, no guarantees are given at this point.
669 It is important to note that the generated code should not be checked
671 into revision control systems, nor it should be included in distributed
672 source archives.
673
675 Please send bug reports to either the distribution bug tracker or the
676 upstream bug tracker at https://gitlab.gnome.org/GNOME/glib/issues/new.
677
679 gdbus(1)
680
682 1. D-Bus Introspection XML
683 http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format
684 2. RefEntry
686 http://www.docbook.org/tdg/en/html/refentry.html
687 3. sortas attribute
689 http://www.docbook.org/tdg/en/html/primary.html
690 4. CamelCase
692 http://en.wikipedia.org/wiki/CamelCase
693 5. #pragma once
695 https://en.wikipedia.org/wiki/Pragma_once
696 6. gtk-doc
698 http://www.gtk.org/gtk-doc/
699 7. parameter
701 http://www.docbook.org/tdg/en/html/parameter.html
702 8. constant
704 http://www.docbook.org/tdg/en/html/constant.html
705 9. org.freedesktop.DBus.Properties.Set
707 http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties
708 10. GObject Introspection
710 https://wiki.gnome.org/Projects/GObjectIntrospection
711GIO GDBUS-CODEGEN(1)