1 <refentry id="gdbus-codegen" lang="en">
5 <productname>GIO</productname>
8 <contrib>Developer</contrib>
9 <firstname>David</firstname>
10 <surname>Zeuthen</surname>
11 <email>zeuthen@gmail.com</email>
17 <refentrytitle>gdbus-codegen</refentrytitle>
18 <manvolnum>1</manvolnum>
19 <refmiscinfo class="manual">User Commands</refmiscinfo>
23 <refname>gdbus-codegen</refname>
24 <refpurpose>D-Bus code and documentation generator</refpurpose>
29 <command>gdbus-codegen</command>
30 <arg><option>--interface-prefix</option> <replaceable>org.project.Prefix</replaceable></arg>
31 <arg><option>--generate-c-code</option> <replaceable>OUTFILES</replaceable></arg>
32 <arg><option>--c-namespace</option> <replaceable>YourProject</replaceable></arg>
33 <arg><option>--c-generate-object-manager</option></arg>
34 <arg><option>--generate-docbook</option> <replaceable>OUTFILES</replaceable></arg>
35 <group choice="plain" rep="repeat">
37 <option>--annotate</option>
38 <replaceable>ELEMENT</replaceable>
39 <replaceable>KEY</replaceable>
40 <replaceable>VALUE</replaceable>
43 <arg choice="plain">FILE</arg>
45 <arg choice="plain" rep="repeat">FILE</arg>
51 <title>Description</title>
53 <command>gdbus-codegen</command> is used to generate code and/or
54 documentation for one or more D-Bus interfaces. The tool reads
56 url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus
57 Introspection XML</ulink> files and generates output files. The
58 tool currently supports generating C code (via
59 <option>--generate-c-code</option>) and Docbook XML (via
60 <option>--generate-docbook</option>).
65 <title>Generating C code</title>
67 When generating C code, a
68 #GInterface<!-- -->-derived type is generated for each D-Bus
69 interface. Additionally, for every generated type,
70 <type>FooBar</type>, two concrete instantiable types,
71 <type>FooBarProxy</type> and <type>FooBarSkeleton</type>, implementing
72 said interface are also generated. The former is derived from
73 #GDBusProxy and intended for use on the client side
74 while the latter is derived from the
75 #GDBusInterfaceSkeleton type making it easy to export on a
76 #GDBusConnection either directly or via a
77 #GDBusObjectManagerServer instance.
80 The name of each generated C type is derived from the D-Bus
81 interface name stripped with the prefix given with
82 <option>--interface-prefix</option> and with the dots removed and
83 initial characters capitalized. For example, for the D-Bus
84 interface <literal>com.acme.Coyote</literal> the name used is
85 <literal>ComAcmeCoyote</literal>. For the D-Bus interface
86 <literal>org.project.Bar.Frobnicator</literal> with
87 <option>--interface-prefix</option>
88 <literal>org.project.</literal>, the name used is
89 <literal>BarFrobnicator</literal>.
92 For methods, signals and properties, if not specified, the name
93 defaults to the name of the method, signal or property.
96 Two forms of the name are used - the CamelCase form and the
97 lower-case form. The CamelCase form is used for the #GType and
98 struct name, while lower-case form is used in function names. The
99 lower-case form is calculated by converting from CamelCase to
100 lower-case and inserting underscores at word boundaries (using
104 If the value given by the <literal>org.gtk.GDBus.C.Name</literal>
105 annotation or the <option>--c-namespace</option> option contains
106 an underscore (sometimes called <emphasis>Ugly_Case</emphasis>),
107 then the camel-case name is derived by removing all underscores,
108 and the lower-case name is derived by lower-casing the
109 string. This is useful in some situations where abbreviations are
110 used. For example, if the annotation is used on the interface
111 <literal>net.MyCorp.MyApp.iSCSITarget</literal> with the value
112 <literal>iSCSI_Target</literal> the CamelCase form is
113 <literal>iSCSITarget</literal> while the lower-case form is
114 <literal>iscsi_target</literal>. If the annotation is used on the
115 method <literal>EjectTheiPod</literal> with the value
116 <literal>Eject_The_iPod</literal>, the lower-case form is
117 <literal>eject_the_ipod</literal>.
122 <title>Generating Docbook documentation</title>
124 Each generated Docbook XML file (see the
125 <option>--generate-docbook</option> option for details) is a <ulink
126 url="http://www.docbook.org/tdg/en/html/refentry.html"><literal>RefEntry</literal></ulink>
127 article describing the D-Bus interface.
132 <title>Options</title>
134 The following options are supported:
139 <term><option>--interface-prefix</option> <replaceable>org.project.Prefix.</replaceable></term>
142 A prefix to strip from all D-Bus interface names when
143 calculating the typename for the C binding and the Docbook
145 url="http://www.docbook.org/tdg/en/html/primary.html">sortas
152 <term><option>--generate-docbook</option> <replaceable>OUTFILES</replaceable></term>
155 Generate Docbook Documentation for each D-Bus interface and
156 put it in <filename>OUTFILES-NAME.xml</filename> where
157 <literal>NAME</literal> is a place-holder for the interface
158 name, e.g. <literal>net.Corp.FooBar</literal> and so on.
164 <term><option>--generate-c-code</option> <replaceable>OUTFILES</replaceable></term>
167 Generate C code for all D-Bus interfaces and put it in
168 <filename>OUTFILES.c</filename> and
169 <filename>OUTFILES.h</filename>.
175 <term><option>--c-namespace</option> <replaceable>YourProject</replaceable></term>
178 The namespace to use for generated C code. This is expected
180 url="http://en.wikipedia.org/wiki/CamelCase">CamelCase</ulink>
181 or <emphasis>Ugly_Case</emphasis> (see above).
187 <term><option>--c-generate-object-manager</option></term>
190 If this option is passed, suitable #GDBusObject,
191 #GDBusObjectProxy, #GDBusObjectSkeleton and
192 #GDBusObjectManagerClient subclasses are generated.
198 <term><option>--annotate</option> <replaceable>ELEMENT</replaceable> <replaceable>KEY</replaceable> <replaceable>VALUE</replaceable></term>
201 Used to inject D-Bus annotations into the given XML
202 files. It can be used with interfaces, methods, signals,
203 properties and arguments in the following way:
205 <informalexample><programlisting><![CDATA[
206 gdbus-codegen --c-namespace MyApp \
207 --generate-c-code myapp-generated \
208 --annotate "org.project.InterfaceName" \
209 org.gtk.GDBus.C.Name MyFrobnicator \
210 --annotate "org.project.InterfaceName:Property" \
212 --annotate "org.project.InterfaceName.Method()" \
213 org.freedesktop.DBus.Deprecated true \
214 --annotate "org.project.InterfaceName.Method()[arg_name]" \
216 --annotate "org.project.InterfaceName::Signal" \
218 --annotate "org.project.InterfaceName::Signal[arg_name]" \
220 myapp-dbus-interfaces.xml
221 ]]></programlisting></informalexample>
223 Any UTF-8 string can be used for <replaceable>KEY</replaceable> and <replaceable>VALUE</replaceable>.
232 <title>Supported D-Bus Annotations</title>
234 The following D-Bus annotations are supported by
235 <command>gdbus-codegen</command>:
241 <term><literal>org.freedesktop.DBus.Deprecated</literal></term>
244 Can be used on any <literal><interface></literal>,
245 <literal><method></literal>,
246 <literal><signal></literal> and
247 <literal><property></literal> element to specify that
248 the element is deprecated if its value is
249 <literal>true</literal>. Note that this annotation is
250 defined in the <ulink
251 url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus
252 specification</ulink> and can only assume the values
253 <literal>true</literal> and <literal>false</literal>. In
254 particular, you cannot specify the version that the element
255 was deprecated in nor any helpful deprecation message. Such
256 information should be added to the element documentation
260 When generating C code, this annotation is used to add
261 #G_GNUC_DEPRECATED to generated functions for the element.
264 When generating Docbook XML, a deprecation warning will
265 appear along the documentation for the element.
271 <term><literal>org.gtk.GDBus.Since</literal></term>
274 Can be used on any <literal><interface></literal>,
275 <literal><method></literal>,
276 <literal><signal></literal> and
277 <literal><property></literal> element to specify the
278 version (any free-form string but compared using a
279 version-aware sort function) the element appeared in.
282 When generating C code, this field is used to ensure
283 function pointer order for preserving ABI/API, see <xref
284 linkend="gdbus-code-stability"/>.
287 When generating Docbook XML, the value of this tag appears
288 in the documentation.
294 <term><literal>org.gtk.GDBus.DocString</literal></term>
297 A string with Docbook content for documentation. This annotation can
298 be used on <literal><interface></literal>,
299 <literal><method></literal>,
300 <literal><signal></literal>,
301 <literal><property></literal> and
302 <literal><arg></literal> elements.
308 <term><literal>org.gtk.GDBus.DocString.Short</literal></term>
311 A string with Docbook content for short/brief
312 documentation. This annotation can only be used on
313 <literal><interface></literal> elements.
319 <term><literal>org.gtk.GDBus.C.Name</literal></term>
322 Can be used on any <literal><interface></literal>,
323 <literal><method></literal>,
324 <literal><signal></literal> and
325 <literal><property></literal> element to specify the
326 name to use when generating C code. The value is expected to
328 url="http://en.wikipedia.org/wiki/CamelCase">CamelCase</ulink>
329 or <emphasis>Ugly_Case</emphasis> (see above).
335 <term><literal>org.gtk.GDBus.C.ForceGVariant</literal></term>
338 If set to a non-empty string, a #GVariant instance will
339 be used instead of the natural C type. This annotation can
340 be used on any <literal><arg></literal> and
341 <literal><property></literal> element.
347 <term><literal>org.gtk.GDBus.C.UnixFD</literal></term>
350 If set to a non-empty string, the generated code will
351 include parameters to exchange file descriptors using the
352 #GUnixFDList type. This annotation can be used on
353 <literal><method></literal> elements.
361 As an easier alternative to using the
362 <literal>org.gtk.GDBus.DocString</literal> annotation, note that
363 parser used by <command>gdbus-codegen</command> parses XML
364 comments in a way similar to <ulink
365 url="http://www.gtk.org/gtk-doc/">gtk-doc</ulink>:
366 <informalexample><programlisting><![CDATA[
369 @short_description: A short description
371 A <emphasis>longer</emphasis> description.
373 This is a new paragraph.
375 <interface name="net.corp.Bar">
378 @greeting: The docs for greeting parameter.
379 @response: The docs for response parameter.
381 The docs for the actual method.
383 <method name="FooMethod">
384 <arg name="greeting" direction="in" type="s"/>
385 <arg name="response" direction="out" type="s"/>
390 @blah: The docs for blah parameter.
391 @boo: The docs for boo parameter.
394 The docs for the actual signal.
396 <signal name="BarSignal">
397 <arg name="blah" type="s"/>
398 <arg name="boo" type="s"/>
401 <!-- BazProperty: The docs for the property. -->
402 <property name="BazProperty" type="s" access="read"/>
404 ]]></programlisting></informalexample>
407 Note that <literal><![CDATA[@since]]></literal> can be used in any inline
408 documentation bit (e.g. for interfaces, methods, signals and
409 properties) to set the <literal>org.gtk.GDBus.Since</literal>
410 annotation. For the <literal>org.gtk.GDBus.DocString</literal>
411 annotation (and inline comments), note that substrings of the form
412 <literal><![CDATA[#net.Corp.Bar]]></literal>,
413 <literal><![CDATA[net.Corp.Bar.FooMethod()]]></literal>,
414 <literal><![CDATA[#net.Corp.Bar::BarSignal]]></literal> and
415 <literal><![CDATA[#net.Corp.InlineDocs:BazProperty]]></literal> are all
416 expanded to links to the respective interface, method, signal and
418 Additionally, substrings starting with <literal>@</literal> and <literal>%</literal> characters are rendered as
419 <ulink url="http://www.docbook.org/tdg/en/html/parameter.html">parameter</ulink> and
420 <ulink url="http://www.docbook.org/tdg/en/html/constant.html">constant</ulink> respectively.
423 If both XML comments and
424 <literal>org.gtk.GDBus.DocString</literal> or
425 <literal>org.gtk.GDBus.DocString.Short</literal> annotations are
426 present, the latter wins.
431 <title>Example</title>
433 Consider the following D-Bus Introspection XML.
435 <informalexample><programlisting><![CDATA[
437 <interface name="net.Corp.MyApp.Frobber">
438 <method name="HelloWorld">
439 <arg name="greeting" direction="in" type="s"/>
440 <arg name="response" direction="out" type="s"/>
443 <signal name="Notification">
444 <arg name="icon_blob" type="ay"/>
445 <arg name="height" type="i"/>
446 <arg name="messages" type="as"/>
449 <property name="Verbose" type="b" access="readwrite"/>
455 If <command>gdbus-codegen</command> is used on this file like this:
457 <informalexample><programlisting><![CDATA[
458 gdbus-codegen --generate-c-code myapp-generated \
459 --c-namespace MyApp \
460 --interface-prefix net.corp.MyApp. \
461 net.Corp.MyApp.Frobber.xml
462 ]]></programlisting></informalexample>
465 <filename>myapp-generated.[ch]</filename> are
466 generated. The files provide an abstract
467 #GTypeInterface<!-- -->-derived type called
468 <type>MyAppFrobber</type> as well as two instantiable types with
469 the same name but suffixed with <type>Proxy</type> and
470 <type>Skeleton</type>. The generated file, roughly, contains the
471 following facilities:
473 <informalexample><programlisting><![CDATA[
474 /* GType macros for the three generated types */
475 #define MY_APP_TYPE_FROBBER (my_app_frobber_get_type ())
476 #define MY_APP_TYPE_FROBBER_SKELETON (my_app_frobber_skeleton_get_type ())
477 #define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ())
479 typedef struct _MyAppFrobber MyAppFrobber; /* Dummy typedef */
483 GTypeInterface parent_iface;
485 /* Signal handler for the ::notification signal */
486 void (*notification) (MyAppFrobber *proxy,
489 const gchar* const *messages);
491 /* Signal handler for the ::handle-hello-world signal */
492 gboolean (*handle_hello_world) (MyAppFrobber *proxy,
493 GDBusMethodInvocation *invocation,
494 const gchar *greeting);
497 /* Asynchronously calls HelloWorld() */
499 my_app_frobber_call_hello_world (MyAppFrobber *proxy,
500 const gchar *greeting,
501 GCancellable *cancellable,
502 GAsyncReadyCallback callback,
505 my_app_frobber_call_hello_world_finish (MyAppFrobber *proxy,
506 gchar **out_response,
510 /* Synchronously calls HelloWorld(). Blocks calling thread. */
512 my_app_frobber_call_hello_world_sync (MyAppFrobber *proxy,
513 const gchar *greeting,
514 gchar **out_response,
515 GCancellable *cancellable,
518 /* Completes handling the HelloWorld() method call */
520 my_app_frobber_complete_hello_world (MyAppFrobber *object,
521 GDBusMethodInvocation *invocation,
522 const gchar *response);
524 /* Emits the ::notification signal / Notification() D-Bus signal */
526 my_app_frobber_emit_notification (MyAppFrobber *object,
529 const gchar* const *messages);
531 /* Gets the :verbose GObject property / Verbose D-Bus property.
532 * Does no blocking I/O.
534 gboolean my_app_frobber_get_verbose (MyAppFrobber *object);
536 /* Sets the :verbose GObject property / Verbose D-Bus property.
537 * Does no blocking I/O.
539 void my_app_frobber_set_verbose (MyAppFrobber *object,
542 /* Gets the interface info */
543 GDBusInterfaceInfo *my_app_frobber_interface_info (void);
545 /* Creates a new skeleton object, ready to be exported */
546 MyAppFrobber *my_app_frobber_skeleton_new (void);
548 /* Client-side proxy constructors.
550 * Additionally, _new_for_bus(), _new_for_bus_finish() and
551 * _new_for_bus_sync() proxy constructors are also generated.
554 my_app_frobber_proxy_new (GDBusConnection *connection,
555 GDBusProxyFlags flags,
557 const gchar *object_path,
558 GCancellable *cancellable,
559 GAsyncReadyCallback callback,
562 my_app_frobber_proxy_new_finish (GAsyncResult *res,
565 my_app_frobber_proxy_new_sync (GDBusConnection *connection,
566 GDBusProxyFlags flags,
568 const gchar *object_path,
569 GCancellable *cancellable,
571 ]]></programlisting></informalexample>
573 Thus, for every D-Bus method, there will be three C functions for
574 calling the method, one #GObject signal for handling an incoming
575 call and one C function for completing an incoming call. For every
576 D-Bus signal, there's one #GObject signal and one C function for
577 emitting it. For every D-Bus property, two C functions are
578 generated (one setter, one getter) and one #GObject property. The
579 following table summarizes the generated facilities and where they
587 <entry>Client</entry>
588 <entry>Server</entry>
594 <entry>Use <type>MyAppFrobberProxy</type></entry>
595 <entry>Any type implementing the <type>MyAppFrobber</type> interface</entry>
598 <entry>Methods</entry>
599 <entry>Use <function>m_a_f_hello_world()</function> to call.</entry>
600 <entry>Receive via the <function>handle_hello_world()</function> signal handler. Complete the call with <function>m_a_f_complete_hello_world()</function></entry>
603 <entry>Signals</entry>
604 <entry>Connect to the <function>::notification</function> GObject signal.</entry>
605 <entry>Use <function>m_a_f_emit_notification()</function> to emit signal.</entry>
608 <entry>Properties (Reading)</entry>
609 <entry>Use <function>m_a_f_get_verbose()</function> or <parameter>:verbose</parameter>.</entry>
610 <entry>Implement #GObject<!-- -->'s <function>get_property()</function> vfunc.</entry>
613 <entry>Properties (writing)</entry>
614 <entry>Use <function>m_a_f_set_verbose()</function> or <parameter>:verbose</parameter>.</entry>
615 <entry>Implement #GObject<!-- -->'s <function>set_property()</function> vfunc.</entry>
622 <title>Client-side usage</title>
624 You can use the generated proxy type with the generated
627 <informalexample><programlisting><![CDATA[
632 proxy = my_app_frobber_proxy_new_for_bus_sync (
634 G_DBUS_PROXY_FLAGS_NONE,
635 "net.Corp.MyApp", /* bus name */
636 "/net/Corp/MyApp/SomeFrobber", /* object */
637 NULL, /* GCancellable* */
639 /* do stuff with proxy */
640 g_object_unref (proxy);
641 ]]></programlisting></informalexample>
643 Instead of using the generic #GDBusProxy facilities, one can use
644 the generated methods such as
645 <function>my_app_frobber_call_hello_world()</function> to invoke
646 the <function>net.Corp.MyApp.Frobber.HelloWorld()</function>
647 D-Bus method, connect to the the
648 <function>::notification</function> GObject signal to receive
649 the <function>net.Corp.MyApp.Frobber::Notication</function>
650 D-Bus signal and get/set the
651 <parameter>net.Corp.MyApp.Frobber:Verbose</parameter> D-Bus
652 Property using either the GObject property
653 <parameter>:verbose</parameter> or the
654 <function>my_app_get_verbose()</function> and
655 <function>my_app_set_verbose()</function> methods. Use the
656 standard #GObject::notify signal to listen to property changes.
659 Note that all property access is via #GDBusProxy<!-- -->'s
660 property cache so no I/O is ever done when reading properties.
661 Also note that setting a property will cause the
662 <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties.Set</ulink> method to be
663 called on the remote object. This call, however, is asynchronous
664 so setting a property won't block. Further, the change is
665 delayed and no error checking is possible.
670 <title>Server-side usage</title>
672 The generated <type>MyAppFrobber</type> interface is designed so
673 it is easy to implement it in a #GObject
674 subclass. For example, to handle
675 <function>HelloWorld()</function> method invocations, set the
676 vfunc for <function>handle_hello_hello_world()</function> in the
677 <type>MyAppFrobberIface</type> structure. Similary, to handle
678 the <parameter>net.Corp.MyApp.Frobber:Verbose</parameter>
679 property override the <parameter>:verbose</parameter> #GObject
680 property from the subclass. To emit a signal, use
681 e.g. <function>my_app_emit_signal()</function> or
682 g_signal_emit_by_name().
685 Instead of subclassing, it is often easier to use the generated
686 <type>MyAppFrobberSkeleton</type> subclass. To handle incoming
687 method calls, use <function>g_signal_connect()</function> with
688 the <function>::handle-*</function> signals and instead of
689 overriding #GObject<!-- -->'s
690 <function>get_property()</function> and
691 <function>set_property()</function> vfuncs, use
693 g_object_set() or the generated property
694 getters and setters (the generated class has an internal
695 property bag implementation).
697 <informalexample><programlisting><![CDATA[
699 on_handle_hello_world (MyAppFrobber *interface,
700 GDBusMethodInvocation *invocation,
701 const gchar *greeting,
704 if (g_strcmp0 (greeting, "Boo") != 0)
707 response = g_strdup_printf ("Word! You said `%s'.", greeting);
708 my_app_complete_hello_world (interface, invocation, response);
713 g_dbus_method_invocation_return_error (invocation,
715 MY_APP_ERROR_NO_WHINING,
716 "Hey, %s, there will be no whining!",
717 g_dbus_method_invocation_get_sender (invocation));
724 interface = my_app_frobber_skeleton_new ();
725 my_app_frobber_set_verbose (interface, TRUE);
727 g_signal_connect (interface,
728 "handle-hello-world",
729 G_CALLBACK (on_handle_hello_world),
735 if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
737 "/path/of/dbus_object",
742 ]]></programlisting></informalexample>
744 To facilitate atomic changesets (multiple properties changing at
745 the same time), #GObject::notify signals are queued up when
746 received. The queue is drained in an idle handler (which is called from the
747 <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
748 of the thread where the skeleton object was
749 contructed) and will cause emissions of the <ulink
750 url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties::PropertiesChanged</ulink>
751 signal with all the properties that have changed. Use
752 g_dbus_interface_skeleton_flush() or
753 g_dbus_object_skeleton_flush() to empty the queue
754 immediately. Use g_object_freeze_notify() and
755 g_object_thaw_notify() for atomic changesets if on a different
762 <title>C Type Mapping</title>
766 <link linkend="G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</link>,
767 <link linkend="G-VARIANT-TYPE-BYTE:CAPS">'y'</link>,
768 <link linkend="G-VARIANT-TYPE-INT16:CAPS">'n'</link>,
769 <link linkend="G-VARIANT-TYPE-UINT16:CAPS">'q'</link>,
770 <link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link>,
771 <link linkend="G-VARIANT-TYPE-UINT32:CAPS">'u'</link>,
772 <link linkend="G-VARIANT-TYPE-INT64:CAPS">'x'</link>,
773 <link linkend="G-VARIANT-TYPE-UINT64:CAPS">'t'</link> and
774 <link linkend="G-VARIANT-TYPE-DOUBLE:CAPS">'d'</link>)
776 strings (type-strings
777 <link linkend="G-VARIANT-TYPE-STRING:CAPS">'s'</link>,
778 <link linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link>,
779 <link linkend="G-VARIANT-TYPE-OBJECT-PATH:CAPS">'o'</link> and
780 <link linkend="G-VARIANT-TYPE-SIGNATURE:CAPS">'g'</link>) and
781 arrays of string (type-strings
782 <link linkend="G-VARIANT-TYPE-STRING-ARRAY:CAPS">'as'</link>,
783 <link linkend="G-VARIANT-TYPE-OBJECT-PATH-ARRAY:CAPS">'ao'</link> and
784 <link linkend="G-VARIANT-TYPE-BYTESTRING-ARRAY:CAPS">'aay'</link>)
785 are mapped to the natural types,
786 e.g. #gboolean, #gdouble, #gint, <link linkend="gchararray">gchar*</link>,
787 <link linkend="GStrv">gchar**</link> and
788 so on. Everything else is mapped to the #GVariant
792 This automatic mapping can be turned off by using the annotation
793 <literal>org.gtk.GDBus.C.ForceGVariant</literal> - if used then a
794 #GVariant is always exchanged instead of the
795 corresponding native C type. This annotation may be convenient to
797 bytestrings (type-string <link linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link>)
798 for data that could have embedded NUL bytes.
802 <refsect1 id="gdbus-code-stability">
803 <title>Stability Guarantees</title>
805 The generated C functions are guaranteed to not change their ABI
806 that is, if a method, signal or property does not change its
807 signature in the introspection XML, the generated C functions will
808 not change its C ABI either.
811 The ABI of the generated #GType<!-- -->s will be preserved only if
812 the <literal>org.gtk.GDBus.Since</literal> annotation is used
813 judiciously — this is because the VTable for the #GInterface
814 relies on functions pointers for signal handlers. Specifically, if
815 a D-Bus method, property or signal or is added to a D-Bus
816 interface, then ABI of the generated #GInterface type is preserved
817 if, and only if, each added method, property signal is annotated
818 with they <literal>org.gtk.GDBus.Since</literal> annotation using
819 a greater version number than previous versions.
822 The generated C code currently happens to be annotated with <ulink
823 url="http://www.gtk.org/gtk-doc/">gtk-doc</ulink> / <ulink
824 url="https://live.gnome.org/GObjectIntrospection">GObject
825 Introspection</ulink> comments / annotations. The layout and
826 contents might change in the future so no guarantees about
827 e.g. <literal>SECTION</literal> usage etc. is given.
830 While the generated Docbook for D-Bus interfaces isn't expected to
831 change, no guarantees are given at this point.
838 Please send bug reports to either the distribution bug tracker
839 or the upstream bug tracker at
840 <ulink url="https://bugzilla.gnome.org/enter_bug.cgi?product=glib">https://bugzilla.gnome.org/enter_bug.cgi?product=glib</ulink>.
845 <title>See also</title>
848 <refentrytitle>gdbus</refentrytitle><manvolnum>1</manvolnum>