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