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