1 <refentry id="gdbus-codegen" lang="en">
4 <refentrytitle>gdbus-codegen</refentrytitle>
5 <manvolnum>1</manvolnum>
6 <refmiscinfo class="manual">User Commands</refmiscinfo>
10 <refname>gdbus-codegen</refname>
11 <refpurpose>D-Bus code and documentation generator</refpurpose>
16 <command>gdbus-codegen</command>
17 <arg><option>--interface-prefix</option> <replaceable>org.project.Prefix</replaceable></arg>
18 <arg><option>--generate-c-code</option> <replaceable>OUTFILES</replaceable></arg>
19 <arg><option>--c-namespace</option> <replaceable>YourProject</replaceable></arg>
20 <arg><option>--c-generate-object-manager</option></arg>
21 <arg><option>--generate-docbook</option> <replaceable>OUTFILES</replaceable></arg>
22 <group choice="plain" rep="repeat">
24 <option>--annotate</option>
25 <replaceable>element</replaceable>
26 <option>--key</option>
27 <replaceable>key</replaceable>
28 <option>--value</option>
29 <replaceable>key</replaceable>
32 <arg choice="plain">FILE</arg>
34 <arg choice="plain" rep="repeat">FILE</arg>
40 <title>Description</title>
42 <command>gdbus-codegen</command> is used to generate code and/or
43 documentation for one or more D-Bus interfaces. The tool reads
45 url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus
46 Introspection XML</ulink> files and generates output files. The
47 tool currently supports generating C code (via
48 <option>--generate-c-code</option>) and Docbook XML (via
49 <option>--generate-docbook</option>).
54 <title>Generating C code</title>
56 When generating C code, a
57 #GInterface<!-- -->-derived type is generated for each D-Bus
58 interface. Additionally, for every generated type,
59 <type>FooBar</type>, two concrete instantiable types,
60 <type>FooBarProxy</type> and <type>FooBarSkeleton</type>, implementing
61 said interface are also generated. The former is derived from
62 #GDBusProxy and intended for use on the client side
63 while the latter is derived from the
64 #GDBusInterfaceSkeleton type making it easy to export on a
65 #GDBusConnection either directly or via a
66 #GDBusObjectManagerServer instance.
71 <title>Generating Docbook documentation</title>
73 Each generated Docbook XML file (see the
74 <option>--generate-docbook</option> option for details) is a <ulink
75 url="http://www.docbook.org/tdg/en/html/refentry.html"><literal>RefEntry</literal></ulink>
76 article describing the D-Bus interface.
81 <title>Options</title>
83 The following options are supported:
88 <term><option>--interface-prefix</option> <replaceable>org.project.Prefix.</replaceable></term>
91 A prefix to strip from all D-Bus interface names when
92 calculating the typename for the C binding and the Docbook
94 url="http://www.docbook.org/tdg/en/html/primary.html">sortas
101 <term><option>--generate-docbook</option> <replaceable>OUTFILES</replaceable></term>
104 Generate Docbook Documentation for each D-Bus interface and
105 put it in <filename>OUTFILES-NAME.xml</filename> where
106 <literal>NAME</literal> is a place-holder for the interface
107 name, e.g. <literal>net.Corp.FooBar</literal> and so on.
113 <term><option>--generate-c-code</option> <replaceable>OUTFILES</replaceable></term>
116 Generate C code for all D-Bus interfaces and put it in
117 <filename>OUTFILES.c</filename> and
118 <filename>OUTFILES.h</filename>.
124 <term><option>--c-namespace</option> <replaceable>YourProject</replaceable></term>
127 The namespace to use for generated C code. This must be
128 provided in CamelCase format.
134 <term><option>--c-generate-object-manager</option></term>
137 If this option is passed, suitable #GDBusObject,
138 #GDBusObjectProxy, #GDBusObjectSkeleton and
139 #GDBusObjectManagerClient subclasses are generated.
145 <term><option>--annotate</option> <option>--key</option> <replaceable>KEY</replaceable> <option>--value</option> <replaceable>VALUE</replaceable></term>
148 Used together with <option>--key</option> and
149 <option>--value</option> to annotate the given XML files (for each <option>--annotate</option>, there must be exactly one <option>--key</option> and <option>--value</option>). It
150 can be used with interfaces, methods, signals, properties
151 and arguments in the following way:
153 <informalexample><programlisting><![CDATA[
154 gdbus-codegen --c-namespace MyApp \
155 --generate-c-code myapp-generated \
156 --annotate "org.project.InterfaceName" \
157 --key org.gtk.GDBus.C.Name --value MyFrobnicator \
158 --annotate "org.project.InterfaceName:Property" \
159 --key bar --value bat \
160 --annotate "org.project.InterfaceName.Method()" \
161 --key org.freedesktop.DBus.Deprecated --value true \
162 --annotate "org.project.InterfaceName.Method()[arg_name]" \
163 --key snake --value hiss \
164 --annotate "org.project.InterfaceName::Signal" \
165 --key cat --value meow \
166 --annotate "org.project.InterfaceName::Signal[arg_name]" \
167 --key dog --value wuff \
168 myapp-dbus-interfaces.xml
169 ]]></programlisting></informalexample>
171 Any UTF-8 string can be used for the value of
172 <option>--key</option> and <option>--value</option>.
181 <title>Supported D-Bus Annotations</title>
183 The following D-Bus annotations are supported by
184 <command>gdbus-codegen</command>:
190 <term><literal>org.freedesktop.DBus.Deprecated</literal></term>
193 Can be used on any <literal><interface></literal>,
194 <literal><method></literal>,
195 <literal><signal></literal> and
196 <literal><property></literal> element to specify that
197 the element is deprecated if its value is
198 <literal>true</literal>. Note that this annotation is
199 defined in the <ulink
200 url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus
201 specification</ulink> and can only assume the values
202 <literal>true</literal> and <literal>false</literal>. In
203 particular, you cannot specify the version that the element
204 was deprecated in nor any helpful deprecation message. Such
205 information should be added to the element documentation
209 When generating C code, this annotation is used to add
210 #G_GNUC_DEPRECATED to generated functions for the element.
213 When generating Docbook XML, a deprecation warning will
214 appear along the documentation for the element.
220 <term><literal>org.gtk.GDBus.Since</literal></term>
223 Can be used on any <literal><interface></literal>,
224 <literal><method></literal>,
225 <literal><signal></literal> and
226 <literal><property></literal> element to specify the
227 version (any free-form string but compared using a
228 version-aware sort function) the element appeared in.
231 When generating C code, this field is used to ensure
232 function pointer order for preserving ABI/API, see <xref
233 linkend="gdbus-code-stability"/>.
236 When generating Docbook XML, the value of this tag appears
237 in the documentation.
243 <term><literal>org.gtk.GDBus.DocString</literal></term>
246 A string with Docbook content for documentation. This annotation can
247 be used on <literal><interface></literal>,
248 <literal><method></literal>,
249 <literal><signal></literal>,
250 <literal><property></literal> and
251 <literal><arg></literal> elements.
257 <term><literal>org.gtk.GDBus.DocString.Short</literal></term>
260 A string with Docbook content for short/brief
261 documentation. This annotation can only be used on
262 <literal><interface></literal> elements.
268 <term><literal>org.gtk.GDBus.C.Name</literal></term>
271 Can be used on any <literal><interface></literal>,
272 <literal><method></literal>,
273 <literal><signal></literal> and
274 <literal><property></literal> element to specify the
275 name to use when generating C code. The value is always
276 expected to be in <ulink
277 url="http://en.wikipedia.org/wiki/CamelCase">CamelCase</ulink>
278 or <emphasis>Ugly_Case</emphasis> (see below).
281 For interfaces, if not specified, the name defaults to the
282 D-Bus interface name stripped with the prefix given with
283 <option>--interface-prefix</option> and with the dots
284 removed and initial characters capitalized. For example, for
285 the D-Bus interface <literal>com.acme.Coyote</literal> the
286 name used is <literal>ComAcmeCoyote</literal>. For the D-Bus
287 interface <literal>org.project.Bar.Frobnicator</literal>
288 with <option>--interface-prefix</option>
289 <literal>org.project.</literal>, the name used is
290 <literal>BarFrobnicator</literal>.
293 For methods, signals and properties, if not specified, the
294 name defaults to the name of the method, signal or property.
297 Two forms of the name are used - the CamelCase form and
298 the lower-case form. The CamelCase form is used for the #GType
299 and struct name, while lower-case form is used in function
300 names. The lower-case form is calculated by converting from
301 CamelCase to lower-case and inserting underscores at word
302 boundaries (using certain heuristics).
305 If the value given by the annotation contains an underscore
306 (sometimes called <emphasis>Ugly_Case</emphasis>), then the
307 camel-case name is derived by removing all underscores, and
308 the lower-case name is derived by lower-casing the
309 string. This is useful in some situations where
310 abbreviations are used. For example, if the annotation is
311 used on the interface
312 <literal>net.MyCorp.MyApp.iSCSITarget</literal> with the
313 value <literal>iSCSI_Target</literal> the CamelCase form is
314 <literal>iSCSITarget</literal> while the lower-case form is
315 <literal>iscsi_target</literal>. If the annotation is used
316 on the method <literal>EjectTheiPod</literal> with the value
317 <literal>Eject_The_iPod</literal>, the lower-case form is
318 <literal>eject_the_ipod</literal>.
324 <term><literal>org.gtk.GDBus.C.ForceGVariant</literal></term>
327 If set to a non-empty string, a #GVariant instance will
328 be used instead of the natural C type. This annotation can
329 be used on any <literal><arg></literal> and
330 <literal><property></literal> element.
338 As an easier alternative to using the
339 <literal>org.gtk.GDBus.DocString</literal> annotation, note that
340 parser used by <command>gdbus-codegen</command> parses XML
341 comments in a way similar to <ulink
342 url="http://www.gtk.org/gtk-doc/">gtk-doc</ulink>:
343 <informalexample><programlisting><![CDATA[
346 @short_description: A short description
348 A <emphasis>longer</emphasis> description.
350 This is a new paragraph.
352 <interface name="net.corp.Bar">
355 @greeting: The docs for greeting parameter.
356 @response: The docs for response parameter.
358 The docs for the actual method.
360 <method name="FooMethod">
361 <arg name="greeting" direction="in" type="s"/>
362 <arg name="response" direction="out" type="s"/>
367 @blah: The docs for blah parameter.
368 @boo: The docs for boo parameter.
371 The docs for the actual signal.
373 <signal name="BarSignal">
374 <arg name="blah" type="s"/>
375 <arg name="boo" type="s"/>
378 <!-- BazProperty: The docs for the property. -->
379 <property name="BazProperty" type="s" access="read"/>
381 ]]></programlisting></informalexample>
384 Note that <literal><![CDATA[@since]]></literal> can be used in any inline
385 documentation bit (e.g. for interfaces, methods, signals and
386 properties) to set the <literal>org.gtk.GDBus.Since</literal>
387 annotation. For the <literal>org.gtk.GDBus.DocString</literal>
388 annotation (and inline comments), note that substrings of the form
389 <literal><![CDATA[#net.Corp.Bar]]></literal>,
390 <literal><![CDATA[net.Corp.Bar.FooMethod()]]></literal>,
391 <literal><![CDATA[#net.Corp.Bar::BarSignal]]></literal> and
392 <literal><![CDATA[#net.Corp.InlineDocs:BazProperty]]></literal> are all
393 expanded to links to the respective interface, method, signal and
395 Additionally, substrings starting with <literal>@</literal> and <literal>%</literal> characters are rendered as
396 <ulink url="http://www.docbook.org/tdg/en/html/parameter.html">parameter</ulink> and
397 <ulink url="http://www.docbook.org/tdg/en/html/constant.html">constant</ulink> respectively.
400 If both XML comments and
401 <literal>org.gtk.GDBus.DocString</literal> or
402 <literal>org.gtk.GDBus.DocString.Short</literal> annotations are
403 present, the latter wins.
408 <title>Example</title>
410 Consider the following D-Bus Introspection XML.
412 <informalexample><programlisting><![CDATA[
413 <interface name="net.Corp.MyApp.Frobber">
414 <method name="HelloWorld">
415 <arg name="greeting" direction="in" type="s"/>
416 <arg name="response" direction="out" type="s"/>
419 <signal name="Notification">
420 <arg name="icon_blob" type="ay"/>
421 <arg name="height" type="i"/>
422 <arg name="messages" type="as"/>
425 <property name="Verbose" type="b" access="readwrite"/>
430 If <command>gdbus-codegen</command> is used on this file like this:
432 <informalexample><programlisting><![CDATA[
433 gdbus-codegen --generate-c-code myapp-generated \
434 --c-namespace MyApp \
435 --interface-prefix net.corp.MyApp. \
436 net.Corp.MyApp.Frobber.xml
437 ]]></programlisting></informalexample>
440 <filename>myapp-generated.[ch]</filename> are
441 generated. The files provide an abstract
442 #GTypeInterface<!-- -->-derived type called
443 <type>MyAppFrobber</type> as well as two instantiable types with
444 the same name but suffixed with <type>Proxy</type> and
445 <type>Skeleton</type>. The generated file, roughly, contains the
446 following facilities:
448 <informalexample><programlisting><![CDATA[
449 /* GType macros for the three generated types */
450 #define MY_APP_TYPE_FROBBER (my_app_frobber_get_type ())
451 #define MY_APP_TYPE_FROBBER_SKELETON (my_app_frobber_skeleton_get_type ())
452 #define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ())
454 typedef struct _MyAppFrobber MyAppFrobber; /* Dummy typedef */
458 GTypeInterface parent_iface;
460 /* Signal handler for the ::notification signal */
461 void (*notification) (MyAppFrobber *proxy,
464 const gchar* const *messages);
466 /* Signal handler for the ::handle-hello-world signal */
467 gboolean (*handle_hello_world) (MyAppFrobber *proxy,
468 GDBusMethodInvocation *invocation,
469 const gchar *greeting);
472 /* Asynchronously calls HelloWorld() */
474 my_app_frobber_call_hello_world (MyAppFrobber *proxy,
475 const gchar *greeting,
476 GCancellable *cancellable,
477 GAsyncReadyCallback callback,
480 my_app_frobber_call_hello_world_finish (MyAppFrobber *proxy,
481 gchar **out_response,
485 /* Synchronously calls HelloWorld(). Blocks calling thread. */
487 my_app_frobber_call_hello_world_sync (MyAppFrobber *proxy,
488 const gchar *greeting,
489 gchar **out_response,
490 GCancellable *cancellable,
493 /* Completes handling the HelloWorld() method call */
495 my_app_frobber_complete_hello_world (MyAppFrobber *object,
496 GDBusMethodInvocation *invocation,
497 const gchar *response);
499 /* Emits the ::notification signal / Notification() D-Bus signal */
501 my_app_frobber_emit_notification (MyAppFrobber *object,
504 const gchar* const *messages);
506 /* Gets the :verbose GObject property / Verbose D-Bus property.
507 * Does no blocking I/O.
509 gboolean my_app_frobber_get_verbose (MyAppFrobber *object);
511 /* Sets the :verbose GObject property / Verbose D-Bus property.
512 * Does no blocking I/O.
514 void my_app_frobber_set_verbose (MyAppFrobber *object,
517 /* Gets the interface info */
518 GDBusInterfaceInfo *my_app_frobber_interface_info (void);
520 /* Creates a new skeleton object, ready to be exported */
521 MyAppFrobber *my_app_frobber_skeleton_new (void);
523 /* Client-side proxy constructors.
525 * Additionally, _new_for_bus(), _new_for_bus_finish() and
526 * _new_for_bus_sync() proxy constructors are also generated.
529 my_app_frobber_proxy_new (GDBusConnection *connection,
530 GDBusProxyFlags flags,
532 const gchar *object_path,
533 GCancellable *cancellable,
534 GAsyncReadyCallback callback,
537 my_app_frobber_proxy_new_finish (GAsyncResult *res,
540 my_app_frobber_proxy_new_sync (GDBusConnection *connection,
541 GDBusProxyFlags flags,
543 const gchar *object_path,
544 GCancellable *cancellable,
546 ]]></programlisting></informalexample>
548 Thus, for every D-Bus method, there will be three C functions for
549 calling the method, one #GObject signal for handling an incoming
550 call and one C function for completing an incoming call. For every
551 D-Bus signal, there's one #GObject signal and one C function for
552 emitting it. For every D-Bus property, two C functions are
553 generated (one setter, one getter) and one #GObject property. The
554 following table summarizes the generated facilities and where they
562 <entry>Client</entry>
563 <entry>Server</entry>
569 <entry>Use <type>MyAppFrobberProxy</type></entry>
570 <entry>Any type implementing the <type>MyAppFrobber</type> interface</entry>
573 <entry>Methods</entry>
574 <entry>Use <function>m_a_f_hello_world()</function> to call.</entry>
575 <entry>Receive via the <function>handle_hello_world()</function> signal handler. Complete the call with <function>m_a_f_complete_hello_world()</function></entry>
578 <entry>Signals</entry>
579 <entry>Connect to the <function>::notification</function> GObject signal.</entry>
580 <entry>Use <function>m_a_f_emit_notification()</function> to emit signal.</entry>
583 <entry>Properties (Reading)</entry>
584 <entry>Use <function>m_a_f_get_verbose()</function> or <parameter>:verbose</parameter>.</entry>
585 <entry>Implement #GObject<!-- -->'s <function>get_property()</function> vfunc.</entry>
588 <entry>Properties (writing)</entry>
589 <entry>Use <function>m_a_f_set_verbose()</function> or <parameter>:verbose</parameter>.</entry>
590 <entry>Implement #GObject<!-- -->'s <function>set_property()</function> vfunc.</entry>
597 <title>Client-side usage</title>
599 You can use the generated proxy type with the generated
602 <informalexample><programlisting><![CDATA[
607 proxy = my_app_frobber_proxy_new_for_bus_sync (
609 G_DBUS_PROXY_FLAGS_NONE,
610 "net.Corp.MyApp", /* bus name */
611 "/net/Corp/MyApp/SomeFrobber", /* object */
612 NULL, /* GCancellable* */
614 /* do stuff with proxy */
615 g_object_unref (proxy);
616 ]]></programlisting></informalexample>
618 Instead of using the generic #GDBusProxy facilities, one can use
619 the generated methods such as
620 <function>my_app_frobber_call_hello_world()</function> to invoke
621 the <function>net.Corp.MyApp.Frobber.HelloWorld()</function>
622 D-Bus method, connect to the the
623 <function>::notification</function> GObject signal to receive
624 the <function>net.Corp.MyApp.Frobber::Notication</function>
625 D-Bus signal and get/set the
626 <parameter>net.Corp.MyApp.Frobber:Verbose</parameter> D-Bus
627 Property using either the GObject property
628 <parameter>:verbose</parameter> or the
629 <function>my_app_get_verbose()</function> and
630 <function>my_app_set_verbose()</function> methods. Use the
631 standard #GObject::notify signal to listen to property changes.
634 Note that all property access is via #GDBusProxy<!-- -->'s
635 property cache so no I/O is ever done when reading properties.
636 Also note that setting a property will cause the
637 <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties.Set</ulink> method to be
638 called on the remote object. This call, however, is asynchronous
639 so setting a property won't block. Further, the change is
640 delayed and no error checking is possible.
645 <title>Server-side usage</title>
647 The generated <type>MyAppFrobber</type> interface is designed so
648 it is easy to implement it in a #GObject
649 subclass. For example, to handle
650 <function>HelloWorld()</function> method invocations, set the
651 vfunc for <function>handle_hello_hello_world()</function> in the
652 <type>MyAppFrobberIface</type> structure. Similary, to handle
653 the <parameter>net.Corp.MyApp.Frobber:Verbose</parameter>
654 property override the <parameter>:verbose</parameter> #GObject
655 property from the subclass. To emit a signal, use
656 e.g. <function>my_app_emit_signal()</function> or
657 g_signal_emit_by_name().
660 Instead of subclassing, it is often easier to use the generated
661 <type>MyAppFrobberSkeleton</type> subclass. To handle incoming
662 method calls, use <function>g_signal_connect()</function> with
663 the <function>::handle-*</function> signals and instead of
664 overriding #GObject<!-- -->'s
665 <function>get_property()</function> and
666 <function>set_property()</function> vfuncs, use
668 g_object_set() or the generated property
669 getters and setters (the generated class has an internal
670 property bag implementation).
672 <informalexample><programlisting><![CDATA[
674 on_handle_hello_world (MyAppFrobber *interface,
675 GDBusMethodInvocation *invocation,
676 const gchar *greeting,
679 if (g_strcmp0 (greeting, "Boo") != 0)
682 response = g_strdup_printf ("Word! You said `%s'.", greeting);
683 my_app_complete_hello_world (interface, invocation, response);
688 g_dbus_method_invocation_return_error (MY_APP_ERROR,
689 MY_APP_ERROR_NO_WHINING,
690 "Hey, %s, there will be no whining!",
691 g_dbus_method_invocation_get_sender (invocation));
698 interface = my_app_frobber_skeleton_new ();
699 my_app_frobber_set_verbose (interface, TRUE);
701 g_signal_connect (interface,
702 "handle-hello-world",
703 G_CALLBACK (on_handle_hello_world),
709 if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
711 "/path/of/dbus_object",
716 ]]></programlisting></informalexample>
718 To facilitate atomic changesets (multiple properties changing at
719 the same time), #GObject::notify signals are queued up when
720 received. The queue is drained in an idle handler (which is called from the
721 <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
722 of the thread where the skeleton object was
723 contructed) and will cause emissions of the <ulink
724 url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties::PropertiesChanged</ulink>
725 signal with all the properties that have changed. Use
726 g_dbus_interface_skeleton_flush() or
727 g_dbus_object_skeleton_flush() to empty the queue
728 immediately. Use g_object_freeze_notify() and
729 g_object_thaw_notify() for atomic changesets if on a different
736 <title>C Type Mapping</title>
740 <link linkend="G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</link>,
741 <link linkend="G-VARIANT-TYPE-BYTE:CAPS">'y'</link>,
742 <link linkend="G-VARIANT-TYPE-INT16:CAPS">'n'</link>,
743 <link linkend="G-VARIANT-TYPE-UINT16:CAPS">'q'</link>,
744 <link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link>,
745 <link linkend="G-VARIANT-TYPE-UINT32:CAPS">'u'</link>,
746 <link linkend="G-VARIANT-TYPE-INT64:CAPS">'x'</link>,
747 <link linkend="G-VARIANT-TYPE-UINT64:CAPS">'t'</link>,
748 <link linkend="G-VARIANT-TYPE-HANDLE:CAPS">'h'</link> and
749 <link linkend="G-VARIANT-TYPE-DOUBLE:CAPS">'d'</link>)
751 strings (type-strings
752 <link linkend="G-VARIANT-TYPE-STRING:CAPS">'s'</link>,
753 <link linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link>,
754 <link linkend="G-VARIANT-TYPE-OBJECT-PATH:CAPS">'o'</link> and
755 <link linkend="G-VARIANT-TYPE-SIGNATURE:CAPS">'g'</link>) and
756 arrays of string (type-strings
757 <link linkend="G-VARIANT-TYPE-STRING-ARRAY:CAPS">'as'</link>,
758 <link linkend="G-VARIANT-TYPE-OBJECT-PATH-ARRAY:CAPS">'ao'</link> and
759 <link linkend="G-VARIANT-TYPE-BYTESTRING-ARRAY:CAPS">'aay'</link>)
760 are mapped to the natural types,
761 e.g. #gboolean, #gdouble, #gint, <link linkend="gchararray">gchar*</link>,
762 <link linkend="GStrv">gchar**</link> and
763 so on. Everything else is mapped to the #GVariant
767 This automatic mapping can be turned off by using the annotation
768 <literal>org.gtk.GDBus.C.ForceGVariant</literal> - if used then a
769 #GVariant is always exchanged instead of the
770 corresponding native C type. This annotation may be convenient to
772 bytestrings (type-string <link linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link>)
773 for data that could have embedded NUL bytes.
777 <refsect1 id="gdbus-code-stability">
778 <title>Stability Guarantees</title>
780 The generated C functions are guaranteed to not change their ABI
781 that is, if a method, signal or property does not change its
782 signature in the introspection XML, the generated C functions will
783 not change its C ABI either. One exception to this guarantee is if
784 you are using type <link
785 linkend="G-VARIANT-TYPE-HANDLE:CAPS">'h'</link> for passing file
786 descriptors on Unix. Future versions of gdbus-codegen will include
787 guarantees for this type as well.
790 The ABI of the generated #GType<!-- -->s will be preserved only if
791 the <literal>org.gtk.GDBus.Since</literal> annotation is used
792 judiciously — this is because the VTable for the #GInterface
793 relies on functions pointers for signal handlers. Specifically, if
794 a D-Bus method, property or signal or is added to a D-Bus
795 interface, then ABI of the generated #GInterface type is preserved
796 if, and only if, each added method, property signal is annotated
797 with they <literal>org.gtk.GDBus.Since</literal> annotation using
798 a greater version number than previous versions.
801 The generated C code currently happens to be annotated with <ulink
802 url="http://www.gtk.org/gtk-doc/">gtk-doc</ulink> / <ulink
803 url="https://live.gnome.org/GObjectIntrospection">GObject
804 Introspection</ulink> comments / annotations. The layout and
805 contents might change in the future so no guarantees about
806 e.g. <literal>SECTION</literal> usage etc. is given.
809 While the generated Docbook for D-Bus interfaces isn't expected to
810 change, no guarantees are given at this point.
815 <title>Author</title>
817 Written by David Zeuthen <email><![CDATA[zeuthen@gmail.com]]></email> with
818 a lot of help from many others.
825 Please send bug reports to either the distribution bug tracker
826 or the upstream bug tracker at
827 <ulink url="https://bugzilla.gnome.org/enter_bug.cgi?product=glib"/>.
832 <title>See also</title>
835 <refentrytitle>gdbus</refentrytitle><manvolnum>1</manvolnum>