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-<replaceanle>NAME</replaceanle>.rst where
120 NAME is a place-holder for the interface name, e.g.
121 net.Corp.FooBar and so on.
122 Pass --output-directory to specify the directory to put the output
124 files in. By default the current directory will be used.
125 --generate-c-code OUTFILES
127 Generate C code for all D-Bus interfaces and put it in OUTFILES.c
128 and OUTFILES.h including any sub-directories. If you want the files
129 to be output in a different location use --output-directory as
130 OUTFILES.h including sub-directories will be referenced from
131 OUTFILES.c.
132 The full paths would then be $(OUTDIR)/$(dirname
134 $OUTFILES)/$(basename $OUTFILES).{c,h}.
135 --c-namespace YourProject
137 The namespace to use for generated C code. This is expected to be
138 in CamelCase[5] or Ugly_Case (see above).
139 --pragma-once
141 If this option is passed, the #pragma once[6] preprocessor
142 directive is used instead of include guards.
143 --c-generate-object-manager
145 If this option is passed, suitable #GDBusObject, #GDBusObjectProxy,
146 #GDBusObjectSkeleton and #GDBusObjectManagerClient subclasses are
147 generated.
148 --c-generate-autocleanup none|objects|all
150 This option influences what types autocleanup functions are
151 generated for. 'none' means to not generate any autocleanup
152 functions. 'objects' means to generate them for object types, and
153 'all' means to generate them for object types and interfaces. The
154 default is 'objects' due to a corner case in backwards
155 compatibility with a few projects, but you should likely switch
156 your project to use 'all'. This option was added in GLib 2.50.
157 --output-directory OUTDIR
159 Directory to output generated source to. Equivalent to changing
160 directory before generation.
161 This option cannot be used with --body, --header,
163 --interface-info-body or --interface-info-header; and --output must
164 be used.
165 --header
167 If this option is passed, it will generate the header code and
168 write it to the disk by using the path and file name provided by
169 --output.
170 Using --generate-c-code, --generate-docbook or --output-directory
172 are not allowed to be used along with --header and --body options,
173 because these options are used to generate only one file.
174 --body
176 If this option is passed, it will generate the source code and
177 write it to the disk by using the path and file name provided by
178 --output.
179 Using --generate-c-code, --generate-docbook or --output-directory
181 are not allowed to be used along with --header and --body options,
182 because these options are used to generate only one file.
183 --interface-info-header
185 If this option is passed, it will generate the header code for the
186 GDBusInterfaceInfo structures only and will write it to the disk by
187 using the path and file name provided by --output.
188 Using --generate-c-code, --generate-docbook or --output-directory
190 are not allowed to be used along with the --interface-info-header
191 and --interface-info-body options, because these options are used
192 to generate only one file.
193 --interface-info-body
195 If this option is passed, it will generate the source code for the
196 GDBusInterfaceInfo structures only and will write it to the disk by
197 using the path and file name provided by --output.
198 Using --generate-c-code, --generate-docbook or --output-directory
200 are not allowed to be used along with the --interface-info-header
201 and --interface-info-body options, because these options are used
202 to generate only one file.
203 --symbol-decorator DECORATOR
205 If a DECORATOR is passed in with this option, all the generated
206 function prototypes in the generated header will be marked with
207 DECORATOR. This can be used, for instance, to export symbols from
208 code generated with gdbus-codegen. This option is added in
209 GLib-2.66
210 --symbol-decorator-header HEADER
212 If a HEADER is passed in with this option, the generated header
213 will put a #include HEADER before the rest of the items, except for
214 the inclusion guards or #pragma once (if --pragma-once is used).
215 This is used if using another header file is needed for the
216 decorator passed in via --symbol-decorator to be defined. This
217 option is added in GLib-2.66.
218 This option can only be used if --symbol-decorator is used.
220 --symbol-decorator-define DEFINE
222 If a DEFINE is passed in with this option, the generated source
223 will add a #define DEFINE before the rest of the items. This is
224 used if a particular macro is needed to ensure the decorator passed
225 in via --symbol-decorator uses the correct definition when the
226 generated source is being compiled. This option is added in
227 GLib-2.66.
228 This option can only be used if --symbol-decorator is used.
230 --output OUTFILE
232 The full path where the header (--header, --interface-info-header)
233 or the source code (--body, --interface-info-body) will be written,
234 using the path and filename provided by --output. The full path
235 could be something like $($OUTFILE).{c,h}.
236 Using --generate-c-code, --generate-docbook or --output-directory
238 is not allowed along with --output, because the latter is used to
239 generate only one file.
240 --annotate ELEMENT KEY VALUE
242 Used to inject D-Bus annotations into the given XML files. It can
243 be used with interfaces, methods, signals, properties and arguments
244 in the following way:
245 gdbus-codegen --c-namespace MyApp \
247 --generate-c-code myapp-generated \
248 --annotate "org.project.InterfaceName" \
249 org.gtk.GDBus.C.Name MyFrobnicator \
250 --annotate "org.project.InterfaceName:Property" \
251 bar bat \
252 --annotate "org.project.InterfaceName.Method()" \
253 org.freedesktop.DBus.Deprecated true \
254 --annotate "org.project.InterfaceName.Method()[arg_name]" \
255 snake hiss \
256 --annotate "org.project.InterfaceName::Signal" \
257 cat meow \
258 --annotate "org.project.InterfaceName::Signal[arg_name]" \
259 dog wuff \
260 myapp-dbus-interfaces.xml
261 Any UTF-8 string can be used for KEY and VALUE.
262 --glib-min-required VERSION
264 Specifies the minimum version of GLib which the code generated by
265 gdbus-codegen can depend on. This may be used to make
266 backwards-incompatible changes in the output or behaviour of
267 gdbus-codegen in future, which users may opt in to by increasing
268 the value they pass for --glib-min-required. If this option is not
269 passed, the output from gdbus-codegen is guaranteed to be
270 compatible with all versions of GLib from 2.30 upwards, as that is
271 when gdbus-codegen was first released.
272 Note that some version parameters introduce incompatible changes:
274 all callers of the generated code might need to be updated, and if
275 the generated code is part of a library's API or ABI, then
276 increasing the version parameter can result in an API or ABI break.
277 The version number must be of the form MAJOR.MINOR.MICRO, where all
279 parts are integers. MINOR and MICRO are optional. The version
280 number may not be smaller than 2.30.
281 If the version number is 2.64 or greater, the generated code will
283 have the following features: (1) If a method has h (file
284 descriptor) parameter(s), a GUnixFDList parameter will exist in the
285 generated code for it (whereas previously the annotation
286 org.gtk.GDBus.C.UnixFD was required), and (2) Method call functions
287 will have two additional arguments to allow the user to specify
288 GDBusCallFlags and a timeout value, as is possible when using
289 g_dbus_proxy_call().
290 --glib-max-allowed VERSION
292 Specifies the maximum version of GLib which the code generated by
293 gdbus-codegen can depend on. This may be used to ensure that code
294 generated by gdbus-codegen is compilable with specific older
295 versions of GLib that your software has to support.
296 The version number must be of the form MAJOR.MINOR.MICRO, where all
298 parts are integers. MINOR and MICRO are optional. The version
299 number must be greater than or equal to that passed to
300 --glib-min-required. It defaults to the version of GLib which
301 provides this gdbus-codegen.
302
304 The following D-Bus annotations are supported by gdbus-codegen:
305 org.freedesktop.DBus.Deprecated
307 Can be used on any <interface>, <method>, <signal> and <property>
308 element to specify that the element is deprecated if its value is
309 true. Note that this annotation is defined in the D-Bus
310 specification[1] and can only assume the values true and false. In
311 particular, you cannot specify the version that the element was
312 deprecated in nor any helpful deprecation message. Such information
313 should be added to the element documentation instead.
314 When generating C code, this annotation is used to add
316 #G_GNUC_DEPRECATED to generated functions for the element.
317 When generating Docbook XML, a deprecation warning will appear
319 along the documentation for the element.
320 org.gtk.GDBus.Since
322 Can be used on any <interface>, <method>, <signal> and <property>
323 element to specify the version (any free-form string but compared
324 using a version-aware sort function) the element appeared in.
325 When generating C code, this field is used to ensure function
327 pointer order for preserving ABI/API, see the section called
328 “STABILITY GUARANTEES”.
329 When generating Docbook XML, the value of this tag appears in the
331 documentation.
332 org.gtk.GDBus.DocString
334 A string with Docbook content for documentation. This annotation
335 can be used on <interface>, <method>, <signal>, <property> and
336 <arg> elements.
337 org.gtk.GDBus.DocString.Short
339 A string with Docbook content for short/brief documentation. This
340 annotation can only be used on <interface> elements.
341 org.gtk.GDBus.C.Name
343 Can be used on any <interface>, <method>, <signal> and <property>
344 element to specify the name to use when generating C code. The
345 value is expected to be in CamelCase[5] or Ugly_Case (see above).
346 org.gtk.GDBus.C.ForceGVariant
348 If set to a non-empty string, a #GVariant instance will be used
349 instead of the natural C type. This annotation can be used on any
350 <arg> and <property> element.
351 org.gtk.GDBus.C.UnixFD
353 If set to a non-empty string, the generated code will include
354 parameters to exchange file descriptors using the #GUnixFDList
355 type. This annotation can be used on <method> elements.
356 As an easier alternative to using the org.gtk.GDBus.DocString
358 annotation, note that parser used by gdbus-codegen parses XML comments
359 in a way similar to gtk-doc[7]:
360 Note that @since can be used in any inline documentation bit (e.g. for
362 interfaces, methods, signals and properties) to set the
363 org.gtk.GDBus.Since annotation. For the org.gtk.GDBus.DocString
364 annotation (and inline comments), note that substrings of the form
365 #net.Corp.Bar, net.Corp.Bar.FooMethod(), #net.Corp.Bar::BarSignal and
366 #net.Corp.InlineDocs:BazProperty are all expanded to links to the
367 respective interface, method, signal and property. Additionally,
368 substrings starting with @ and % characters are rendered as
369 parameter[8] and constant[9] respectively.
370 If both XML comments and org.gtk.GDBus.DocString or
372 org.gtk.GDBus.DocString.Short annotations are present, the latter wins.
373
375 Consider the following D-Bus Introspection XML.
376 <node>
378 <interface name="net.Corp.MyApp.Frobber">
379 <method name="HelloWorld">
380 <arg name="greeting" direction="in" type="s"/>
381 <arg name="response" direction="out" type="s"/>
382 </method>
383 <signal name="Notification">
385 <arg name="icon_blob" type="ay"/>
386 <arg name="height" type="i"/>
387 <arg name="messages" type="as"/>
388 </signal>
389 <property name="Verbose" type="b" access="readwrite"/>
391 </interface>
392 </node>
393 If gdbus-codegen is used on this file like this:
395 gdbus-codegen --generate-c-code myapp-generated \
397 --c-namespace MyApp \
398 --interface-prefix net.corp.MyApp. \
399 net.Corp.MyApp.Frobber.xml
400 two files called myapp-generated.[ch] are generated. The files provide
402 an abstract #GTypeInterface -derived type called MyAppFrobber as well
403 as two instantiatable types with the same name but suffixed with Proxy
404 and Skeleton. The generated file, roughly, contains the following
405 facilities:
406 /* GType macros for the three generated types */
408 #define MY_APP_TYPE_FROBBER (my_app_frobber_get_type ())
409 #define MY_APP_TYPE_FROBBER_SKELETON (my_app_frobber_skeleton_get_type ())
410 #define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ())
411 typedef struct _MyAppFrobber MyAppFrobber; /* Dummy typedef */
413 typedef struct
415 {
416 GTypeInterface parent_iface;
417 /* Signal handler for the ::notification signal */
419 void (*notification) (MyAppFrobber *proxy,
420 GVariant *icon_blob,
421 gint height,
422 const gchar* const *messages);
423 /* Signal handler for the ::handle-hello-world signal */
425 gboolean (*handle_hello_world) (MyAppFrobber *proxy,
426 GDBusMethodInvocation *invocation,
427 const gchar *greeting);
428 } MyAppFrobberIface;
429 /* Asynchronously calls HelloWorld() */
431 void
432 my_app_frobber_call_hello_world (MyAppFrobber *proxy,
433 const gchar *greeting,
434 GCancellable *cancellable,
435 GAsyncReadyCallback callback,
436 gpointer user_data);
437 gboolean
438 my_app_frobber_call_hello_world_finish (MyAppFrobber *proxy,
439 gchar **out_response,
440 GAsyncResult *res,
441 GError **error);
442 /* Synchronously calls HelloWorld(). Blocks calling thread. */
444 gboolean
445 my_app_frobber_call_hello_world_sync (MyAppFrobber *proxy,
446 const gchar *greeting,
447 gchar **out_response,
448 GCancellable *cancellable,
449 GError **error);
450 /* Completes handling the HelloWorld() method call */
452 void
453 my_app_frobber_complete_hello_world (MyAppFrobber *object,
454 GDBusMethodInvocation *invocation,
455 const gchar *response);
456 /* Emits the ::notification signal / Notification() D-Bus signal */
458 void
459 my_app_frobber_emit_notification (MyAppFrobber *object,
460 GVariant *icon_blob,
461 gint height,
462 const gchar* const *messages);
463 /* Gets the :verbose GObject property / Verbose D-Bus property.
465 * Does no blocking I/O.
466 */
467 gboolean my_app_frobber_get_verbose (MyAppFrobber *object);
468 /* Sets the :verbose GObject property / Verbose D-Bus property.
470 * Does no blocking I/O.
471 */
472 void my_app_frobber_set_verbose (MyAppFrobber *object,
473 gboolean value);
474 /* Gets the interface info */
476 GDBusInterfaceInfo *my_app_frobber_interface_info (void);
477 /* Creates a new skeleton object, ready to be exported */
479 MyAppFrobber *my_app_frobber_skeleton_new (void);
480 /* Client-side proxy constructors.
482 *
483 * Additionally, _new_for_bus(), _new_for_bus_finish() and
484 * _new_for_bus_sync() proxy constructors are also generated.
485 */
486 void
487 my_app_frobber_proxy_new (GDBusConnection *connection,
488 GDBusProxyFlags flags,
489 const gchar *name,
490 const gchar *object_path,
491 GCancellable *cancellable,
492 GAsyncReadyCallback callback,
493 gpointer user_data);
494 MyAppFrobber *
495 my_app_frobber_proxy_new_finish (GAsyncResult *res,
496 GError **error);
497 MyAppFrobber *
498 my_app_frobber_proxy_new_sync (GDBusConnection *connection,
499 GDBusProxyFlags flags,
500 const gchar *name,
501 const gchar *object_path,
502 GCancellable *cancellable,
503 GError **error);
504 Thus, for every D-Bus method, there will be three C functions for
506 calling the method, one #GObject signal for handling an incoming call
507 and one C function for completing an incoming call. For every D-Bus
508 signal, there's one #GObject signal and one C function for emitting it.
509 For every D-Bus property, two C functions are generated (one setter,
510 one getter) and one #GObject property. The following table summarizes
511 the generated facilities and where they are applicable:
512 ┌───────────┬─────────────────────┬──────────────────────────────┐
514 │ │ Client │ Server │
515 ├───────────┼─────────────────────┼──────────────────────────────┤
516 │Types │ Use │ Any type │
517 │ │ MyAppFrobberProxy │ implementing the │
518 │ │ │ MyAppFrobber │
519 │ │ │ interface │
520 ├───────────┼─────────────────────┼──────────────────────────────┤
521 │Methods │ Use │ Receive via the │
522 │ │ m_a_f_hello_world() │ handle_hello_world() │
523 │ │ to call. │ signal handler. │
524 │ │ │ Complete the call │
525 │ │ │ with │
526 │ │ │ m_a_f_complete_hello_world() │
527 ├───────────┼─────────────────────┼──────────────────────────────┤
528 │Signals │ Connect to the │ Use │
529 │ │ ::notification │ m_a_f_emit_notification() to │
530 │ │ GObject signal. │ emit signal. │
531 ├───────────┼─────────────────────┼──────────────────────────────┤
532 │Properties │ Use │ Implement #GObject's │
533 │(Reading) │ m_a_f_get_verbose() │ get_property() vfunc. │
534 │ │ or :verbose. │ │
535 ├───────────┼─────────────────────┼──────────────────────────────┤
536 │Properties │ Use │ Implement #GObject's │
537 │(writing) │ m_a_f_set_verbose() │ set_property() vfunc. │
538 │ │ or :verbose. │ │
539 └───────────┴─────────────────────┴──────────────────────────────┘
540 Client-side usage
542 You can use the generated proxy type with the generated constructors:
543 MyAppFrobber *proxy;
545 GError *error;
546 error = NULL;
548 proxy = my_app_frobber_proxy_new_for_bus_sync (
549 G_BUS_TYPE_SESSION,
550 G_DBUS_PROXY_FLAGS_NONE,
551 "net.Corp.MyApp", /* bus name */
552 "/net/Corp/MyApp/SomeFrobber", /* object */
553 NULL, /* GCancellable* */
554 &error);
555 /* do stuff with proxy */
556 g_object_unref (proxy);
557 Instead of using the generic #GDBusProxy facilities, one can use the
559 generated methods such as my_app_frobber_call_hello_world() to invoke
560 the net.Corp.MyApp.Frobber.HelloWorld() D-Bus method, connect to the
561 ::notification GObject signal to receive the
562 net.Corp.MyApp.Frobber::Notification D-Bus signal and get/set the
563 net.Corp.MyApp.Frobber:Verbose D-Bus Property using either the GObject
564 property :verbose or the my_app_get_verbose() and my_app_set_verbose()
565 methods. Use the standard #GObject::notify signal to listen to property
566 changes.
567 Note that all property access is via #GDBusProxy 's property cache so
569 no I/O is ever done when reading properties. Also note that setting a
570 property will cause the org.freedesktop.DBus.Properties.Set[10] method
571 to be called on the remote object. This call, however, is asynchronous
572 so setting a property won't block. Further, the change is delayed and
573 no error checking is possible.
574 Server-side usage
576 The generated MyAppFrobber interface is designed so it is easy to
577 implement it in a #GObject subclass. For example, to handle
578 HelloWorld() method invocations, set the vfunc for
579 handle_hello_hello_world() in the MyAppFrobberIface structure.
580 Similarly, to handle the net.Corp.MyApp.Frobber:Verbose property
581 override the :verbose #GObject property from the subclass. To emit a
582 signal, use e.g. my_app_emit_signal() or g_signal_emit_by_name().
583 Instead of subclassing, it is often easier to use the generated
585 MyAppFrobberSkeleton subclass. To handle incoming method calls, use
586 g_signal_connect() with the ::handle-* signals and instead of
587 overriding #GObject 's get_property() and set_property() vfuncs, use
588 g_object_get() and g_object_set() or the generated property getters and
589 setters (the generated class has an internal property bag
590 implementation).
591 static gboolean
593 on_handle_hello_world (MyAppFrobber *interface,
594 GDBusMethodInvocation *invocation,
595 const gchar *greeting,
596 gpointer user_data)
597 {
598 if (g_strcmp0 (greeting, "Boo") != 0)
599 {
600 gchar *response;
601 response = g_strdup_printf ("Word! You said `%s'.", greeting);
602 my_app_complete_hello_world (interface, invocation, response);
603 g_free (response);
604 }
605 else
606 {
607 g_dbus_method_invocation_return_error (invocation,
608 MY_APP_ERROR,
609 MY_APP_ERROR_NO_WHINING,
610 "Hey, %s, there will be no whining!",
611 g_dbus_method_invocation_get_sender (invocation));
612 }
613 return TRUE;
614 }
615 [...]
617 interface = my_app_frobber_skeleton_new ();
619 my_app_frobber_set_verbose (interface, TRUE);
620 g_signal_connect (interface,
622 "handle-hello-world",
623 G_CALLBACK (on_handle_hello_world),
624 some_user_data);
625 [...]
627 error = NULL;
629 if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
630 connection,
631 "/path/of/dbus_object",
632 &error))
633 {
634 /* handle error */
635 }
636 To facilitate atomic changesets (multiple properties changing at the
638 same time), #GObject::notify signals are queued up when received. The
639 queue is drained in an idle handler (which is called from the
640 thread-default main loop of the thread where the skeleton object was
641 constructed) and will cause emissions of the
642 org.freedesktop.DBus.Properties::PropertiesChanged[10] signal with all
643 the properties that have changed. Use g_dbus_interface_skeleton_flush()
644 or g_dbus_object_skeleton_flush() to empty the queue immediately. Use
645 g_object_freeze_notify() and g_object_thaw_notify() for atomic
646 changesets if on a different thread.
647
649 Scalar types (type-strings 'b', 'y', 'n', 'q', 'i', 'u', 'x', 't' and
650 'd') ), strings (type-strings 's', 'ay', 'o' and 'g') and arrays of
651 string (type-strings 'as', 'ao' and 'aay') are mapped to the natural
652 types, e.g. #gboolean, #gdouble, #gint, gchar*, gchar** and so on.
653 Everything else is mapped to the #GVariant type.
654 This automatic mapping can be turned off by using the annotation
656 org.gtk.GDBus.C.ForceGVariant - if used then a #GVariant is always
657 exchanged instead of the corresponding native C type. This annotation
658 may be convenient to use when using bytestrings (type-string 'ay') for
659 data that could have embedded NUL bytes.
660
662 The generated C functions are guaranteed to not change their ABI that
663 is, if a method, signal or property does not change its signature in
664 the introspection XML, the generated C functions will not change its C
665 ABI either. The ABI of the generated instance and class structures will
666 be preserved as well.
667 The ABI of the generated #GType s will be preserved only if the
669 org.gtk.GDBus.Since annotation is used judiciously — this is because
670 the VTable for the #GInterface relies on functions pointers for signal
671 handlers. Specifically, if a D-Bus method, property or signal or is
672 added to a D-Bus interface, then ABI of the generated #GInterface type
673 is preserved if, and only if, each added method, property signal is
674 annotated with they org.gtk.GDBus.Since annotation using a greater
675 version number than previous versions.
676 The generated C code currently happens to be annotated with gtk-doc[7]
678 / GObject Introspection[11] comments / annotations. The layout and
679 contents might change in the future so no guarantees about e.g.
680 SECTION usage etc. is given.
681 While the generated Docbook for D-Bus interfaces isn't expected to
683 change, no guarantees are given at this point.
684 It is important to note that the generated code should not be checked
686 into revision control systems, nor it should be included in distributed
687 source archives.
688
690 Please send bug reports to either the distribution bug tracker or the
691 upstream bug tracker at https://gitlab.gnome.org/GNOME/glib/issues/new.
692
694 gdbus(1)
695
697 1. D-Bus Introspection XML
698 http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format
699 2. RefEntry
701 http://www.docbook.org/tdg/en/html/refentry.html
702 3. reStructuredText
704 https://docutils.sourceforge.io/rst.html
705 4. sortas attribute
707 http://www.docbook.org/tdg/en/html/primary.html
708 5. CamelCase
710 http://en.wikipedia.org/wiki/CamelCase
711 6. #pragma once
713 https://en.wikipedia.org/wiki/Pragma_once
714 7. gtk-doc
716 http://www.gtk.org/gtk-doc/
717 8. parameter
719 http://www.docbook.org/tdg/en/html/parameter.html
720 9. constant
722 http://www.docbook.org/tdg/en/html/constant.html
723 10. org.freedesktop.DBus.Properties.Set
725 http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties
726 11. GObject Introspection
728 https://wiki.gnome.org/Projects/GObjectIntrospection
729GIO GDBUS-CODEGEN(1)