docs/reference/gio/gdbus-codegen.xml

   1 <refentry id="gdbus-codegen" lang="en">
   2
   3 <refentryinfo>
   4   <title>gdbus</title>
   5   <productname>GIO</productname>
   6   <authorgroup>
   7     <author>
   8       <contrib>Developer</contrib>
   9       <firstname>David</firstname>
  10       <surname>Zeuthen</surname>
  11       <email>zeuthen@gmail.com</email>
  12     </author>
  13   </authorgroup>
  14 </refentryinfo>
  15
  16 <refmeta>
  17   <refentrytitle>gdbus-codegen</refentrytitle>
  18   <manvolnum>1</manvolnum>
  19   <refmiscinfo class="manual">User Commands</refmiscinfo>
  20 </refmeta>
  21
  22 <refnamediv>
  23   <refname>gdbus-codegen</refname>
  24   <refpurpose>D-Bus code and documentation generator</refpurpose>
  25 </refnamediv>
  26
  27 <refsynopsisdiv>
  28   <cmdsynopsis>
  29     <command>gdbus-codegen</command>
  30     <arg><option>-h</option>, <option>--help</option></arg>
  31     <arg><option>--interface-prefix</option> <replaceable>org.project.Prefix</replaceable></arg>
  32     <arg><option>--generate-c-code</option> <replaceable>OUTFILES</replaceable></arg>
  33     <arg><option>--c-namespace</option> <replaceable>YourProject</replaceable></arg>
  34     <arg><option>--c-generate-object-manager</option></arg>
  35     <arg><option>--c-generate-autocleanup</option> none|objects|all</arg>
  36     <arg><option>--output-directory</option> <replaceable>OUTDIR</replaceable></arg>
  37     <arg><option>--generate-docbook</option> <replaceable>OUTFILES</replaceable></arg>
  38     <arg><option>--pragma-once</option></arg>
  39     <arg><option>--xml-files</option> <replaceable>FILE</replaceable></arg>
  40     <arg><option>--header</option></arg>
  41     <arg><option>--body</option></arg>
  42     <arg><option>--interface-info-header</option></arg>
  43     <arg><option>--interface-info-body</option></arg>
  44     <arg><option>--output</option> <replaceable>OUTFILE</replaceable></arg>
  45     <group choice="plain" rep="repeat">
  46       <arg>
  47         <option>--annotate</option>
  48         <replaceable>ELEMENT</replaceable>
  49         <replaceable>KEY</replaceable>
  50         <replaceable>VALUE</replaceable>
  51       </arg>
  52     </group>
  53     <arg choice="plain">FILE</arg>
  54     <arg>
  55       <arg choice="plain" rep="repeat">FILE</arg>
  56     </arg>
  57   </cmdsynopsis>
  58 </refsynopsisdiv>
  59
  60 <refsect1>
  61   <title>Description</title>
  62   <para>
  63     <command>gdbus-codegen</command> is used to generate code and/or
  64     documentation for one or more D-Bus interfaces.
  65   </para>
  66   <para>
  67     <command>gdbus-codegen</command> reads
  68     <ulink
  69     url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus
  70     Introspection XML</ulink> from files passed as additional
  71     arguments on the command line and generates output files.
  72     It currently supports generating C source code (via
  73     <option>--body</option>) or header (via <option>--header</option>)
  74     and Docbook XML (via <option>--generate-docbook</option>). Alternatively,
  75     more restricted C source code and headers can be generated, which just
  76     contain the interface information (as <type>GDBusInterfaceInfo</type>
  77     structures) using <option>--interface-info-body</option> and
  78     <option>--interface-info-header</option>.
  79   </para>
  80 </refsect1>
  81
  82 <refsect1>
  83   <title>Generating C code</title>
  84   <para>
  85     When generating C code, a
  86     #GInterface<!-- -->-derived type is generated for each D-Bus
  87     interface. Additionally, for every generated type,
  88     <type>FooBar</type>, two concrete instantiable types,
  89     <type>FooBarProxy</type> and <type>FooBarSkeleton</type>, implementing
  90     said interface are also generated. The former is derived from
  91     #GDBusProxy and intended for use on the client side
  92     while the latter is derived from the
  93     #GDBusInterfaceSkeleton type making it easy to export on a
  94     #GDBusConnection either directly or via a
  95     #GDBusObjectManagerServer instance.
  96   </para>
  97   <para>
  98     For C code generation either <option>--body</option> that
  99     generates source code, <option>--header</option> that
 100     generates headers, <option>--interface-info-body</option> that generates
 101     interface information source code, or
 102     <option>--interface-info-header</option> that generates interface information
 103     headers, can be used. These options must be used along with
 104     <option>--output</option>, which is used to specify the file to output to.
 105   </para>
 106   <para>
 107     Both files can be generated at the same time by using
 108     <option>--generate-c-code</option>, but this option is deprecated.
 109     In this case <option>--output</option> cannot be used due to the
 110     generation of multiple files. Instead pass
 111     <option>--output-directory</option> to specify the directory to put
 112     the output files in. By default the current directory will be used.
 113   </para>
 114   <para>
 115     The name of each generated C type is derived from the D-Bus
 116     interface name stripped with the prefix given with
 117     <option>--interface-prefix</option> and with the dots removed and
 118     initial characters capitalized. For example, for the D-Bus
 119     interface <literal>com.acme.Coyote</literal> the name used is
 120     <literal>ComAcmeCoyote</literal>. For the D-Bus interface
 121     <literal>org.project.Bar.Frobnicator</literal> with
 122     <option>--interface-prefix</option>
 123     <literal>org.project.</literal>, the name used is
 124     <literal>BarFrobnicator</literal>.
 125   </para>
 126   <para>
 127     For methods, signals and properties, if not specified, the name
 128     defaults to the name of the method, signal or property.
 129   </para>
 130   <para>
 131     Two forms of the name are used - the CamelCase form and the
 132     lower-case form. The CamelCase form is used for the #GType and
 133     struct name, while lower-case form is used in function names. The
 134     lower-case form is calculated by converting from CamelCase to
 135     lower-case and inserting underscores at word boundaries (using
 136     certain heuristics).
 137   </para>
 138   <para>
 139     If the value given by the <literal>org.gtk.GDBus.C.Name</literal>
 140     annotation or the <option>--c-namespace</option> option contains
 141     an underscore (sometimes called <emphasis>Ugly_Case</emphasis>),
 142     then the camel-case name is derived by removing all underscores,
 143     and the lower-case name is derived by lower-casing the
 144     string. This is useful in some situations where abbreviations are
 145     used. For example, if the annotation is used on the interface
 146     <literal>net.MyCorp.MyApp.iSCSITarget</literal> with the value
 147     <literal>iSCSI_Target</literal> the CamelCase form is
 148     <literal>iSCSITarget</literal> while the lower-case form is
 149     <literal>iscsi_target</literal>. If the annotation is used on the
 150     method <literal>EjectTheiPod</literal> with the value
 151     <literal>Eject_The_iPod</literal>, the lower-case form is
 152     <literal>eject_the_ipod</literal>.
 153   </para>
 154 </refsect1>
 155
 156 <refsect1>
 157   <title>Generating Docbook documentation</title>
 158   <para>
 159     Each generated Docbook XML file (see the
 160     <option>--generate-docbook</option> option for details) is a <ulink
 161     url="http://www.docbook.org/tdg/en/html/refentry.html"><literal>RefEntry</literal></ulink>
 162     article describing the D-Bus interface.
 163   </para>
 164 </refsect1>
 165
 166 <refsect1>
 167   <title>Options</title>
 168   <para>
 169     The following options are supported:
 170   </para>
 171   <variablelist>
 172
 173     <varlistentry>
 174       <term><option>-h</option>, <option>--help</option></term>
 175       <listitem>
 176         <para>
 177           Show help and exit.
 178         </para>
 179       </listitem>
 180     </varlistentry>
 181
 182     <varlistentry>
 183       <term><option>--xml-files</option> <replaceable>FILE</replaceable></term>
 184       <listitem>
 185         <para>
 186           This option is deprecated; use positional arguments instead.
 187           The D-Bus introspection XML file.
 188         </para>
 189       </listitem>
 190     </varlistentry>
 191
 192     <varlistentry>
 193       <term><option>--interface-prefix</option> <replaceable>org.project.Prefix.</replaceable></term>
 194       <listitem>
 195         <para>
 196           A prefix to strip from all D-Bus interface names when
 197           calculating the typename for the C binding and the Docbook
 198           <ulink
 199           url="http://www.docbook.org/tdg/en/html/primary.html">sortas
 200           attribute</ulink>.
 201         </para>
 202       </listitem>
 203     </varlistentry>
 204
 205     <varlistentry>
 206       <term><option>--generate-docbook</option> <replaceable>OUTFILES</replaceable></term>
 207       <listitem>
 208         <para>
 209           Generate Docbook Documentation for each D-Bus interface and
 210           put it in <filename>OUTFILES-NAME.xml</filename> where
 211           <literal>NAME</literal> is a place-holder for the interface
 212           name, e.g. <literal>net.Corp.FooBar</literal> and so on.
 213         </para>
 214         <para>
 215           Pass <option>--output-directory</option> to specify the directory
 216           to put the output files in. By default the current directory
 217           will be used.
 218         </para>
 219       </listitem>
 220     </varlistentry>
 221
 222     <varlistentry>
 223       <term><option>--generate-c-code</option> <replaceable>OUTFILES</replaceable></term>
 224       <listitem>
 225         <para>
 226           Generate C code for all D-Bus interfaces and put it in
 227           <filename>OUTFILES.c</filename> and
 228           <filename>OUTFILES.h</filename> including any sub-directories. If you want the files to
 229           be output in a different location use <option>--output-directory</option> as <filename>OUTFILES.h</filename>
 230           including sub-directories will be referenced from <filename>OUTFILES.c</filename>.
 231         </para>
 232         <para>
 233           The full paths would then be <literal>$(OUTDIR)/$(dirname $OUTFILES)/$(basename $OUTFILES).{c,h}</literal>.
 234         </para>
 235       </listitem>
 236     </varlistentry>
 237
 238     <varlistentry>
 239       <term><option>--c-namespace</option> <replaceable>YourProject</replaceable></term>
 240       <listitem>
 241         <para>
 242           The namespace to use for generated C code. This is expected
 243           to be in <ulink
 244           url="http://en.wikipedia.org/wiki/CamelCase">CamelCase</ulink>
 245           or <emphasis>Ugly_Case</emphasis> (see above).
 246         </para>
 247       </listitem>
 248     </varlistentry>
 249
 250     <varlistentry>
 251       <term><option>--pragma-once</option></term>
 252       <listitem>
 253         <para>
 254           If this option is passed, the
 255           <ulink url="https://en.wikipedia.org/wiki/Pragma_once">&#35;pragma once</ulink>
 256           preprocessor directive is used instead of include guards.
 257         </para>
 258       </listitem>
 259     </varlistentry>
 260
 261     <varlistentry>
 262       <term><option>--c-generate-object-manager</option></term>
 263       <listitem>
 264         <para>
 265           If this option is passed, suitable #GDBusObject,
 266           #GDBusObjectProxy, #GDBusObjectSkeleton and
 267           #GDBusObjectManagerClient subclasses are generated.
 268         </para>
 269       </listitem>
 270     </varlistentry>
 271
 272     <varlistentry>
 273       <term><option>--c-generate-autocleanup</option> none|objects|all</term>
 274       <listitem>
 275         <para>
 276           This option influences what types autocleanup functions are
 277           generated for. 'none' means to not generate any autocleanup functions.
 278           'objects' means to generate them for object types, and 'all' means to
 279           generate them for object types and interfaces. The default is 'objects'
 280           due to a corner case in backwards compatibility with a few projects,
 281           but you should likely switch your project to use 'all'.
 282           This option was added in GLib 2.50.
 283         </para>
 284       </listitem>
 285     </varlistentry>
 286
 287     <varlistentry>
 288       <term><option>--output-directory</option> <replaceable>OUTDIR</replaceable></term>
 289       <listitem>
 290         <para>
 291           Directory to output generated source to. Equivalent to changing directory before generation.
 292         </para>
 293         <para>
 294           This option cannot be used with <option>--body</option>,
 295           <option>--header</option>, <option>--interface-info-body</option> or
 296           <option>--interface-info-header</option>; and
 297           <option>--output</option> must be used.
 298         </para>
 299
 300       </listitem>
 301     </varlistentry>
 302
 303     <varlistentry>
 304       <term><option>--header</option></term>
 305       <listitem>
 306         <para>
 307           If this option is passed, it will generate the header code and write it to the disk by
 308           using the path and file name provided by <option>--output</option>.
 309         </para>
 310         <para>
 311           Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or
 312           <option>--output-directory</option> are not allowed to be used along with
 313           <option>--header</option> and <option>--body</option> options, because these options
 314           are used to generate only one file.
 315         </para>
 316       </listitem>
 317     </varlistentry>
 318
 319     <varlistentry>
 320       <term><option>--body</option></term>
 321       <listitem>
 322         <para>
 323           If this option is passed, it will generate the source code and write it to the disk by
 324           using the path and file name provided by <option>--output</option>.
 325         </para>
 326         <para>
 327           Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or
 328           <option>--output-directory</option> are not allowed to be used along with
 329           <option>--header</option> and <option>--body</option> options, because these options
 330           are used to generate only one file.
 331         </para>
 332       </listitem>
 333     </varlistentry>
 334
 335     <varlistentry>
 336       <term><option>--interface-info-header</option></term>
 337       <listitem>
 338         <para>
 339           If this option is passed, it will generate the header code for the
 340           <type>GDBusInterfaceInfo</type> structures only and will write it to
 341           the disk by using the path and file name provided by
 342           <option>--output</option>.
 343         </para>
 344         <para>
 345           Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or
 346           <option>--output-directory</option> are not allowed to be used along with
 347           the <option>--interface-info-header</option> and
 348           <option>--interface-info-body</option> options, because these options
 349           are used to generate only one file.
 350         </para>
 351       </listitem>
 352     </varlistentry>
 353
 354     <varlistentry>
 355       <term><option>--interface-info-body</option></term>
 356       <listitem>
 357         <para>
 358           If this option is passed, it will generate the source code for the
 359           <type>GDBusInterfaceInfo</type> structures only and will write it to
 360           the disk by using the path and file name provided by
 361           <option>--output</option>.
 362         </para>
 363         <para>
 364           Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or
 365           <option>--output-directory</option> are not allowed to be used along with
 366           the <option>--interface-info-header</option> and
 367           <option>--interface-info-body</option> options, because these options
 368           are used to generate only one file.
 369         </para>
 370       </listitem>
 371     </varlistentry>
 372
 373     <varlistentry>
 374       <term><option>--output</option> <replaceable>OUTFILE</replaceable></term>
 375       <listitem>
 376         <para>
 377           The full path where the header (<option>--header</option>,
 378           <option>--interface-info-header</option>) or the source code
 379           (<option>--body</option>, <option>--interface-info-body</option>) will
 380           be written, using the path and filename provided by
 381           <option>--output</option>. The full path could be something like
 382           <literal>$($OUTFILE).{c,h}</literal>.
 383         </para>
 384         <para>
 385           Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or
 386           <option>--output-directory</option> is not allowed along with
 387           <option>--output</option>, because the latter is used to generate only one file.
 388         </para>
 389       </listitem>
 390     </varlistentry>
 391
 392     <varlistentry>
 393       <term><option>--annotate</option> <replaceable>ELEMENT</replaceable> <replaceable>KEY</replaceable> <replaceable>VALUE</replaceable></term>
 394       <listitem>
 395         <para>
 396           Used to inject D-Bus annotations into the given XML
 397           files. It can be used with interfaces, methods, signals,
 398           properties and arguments in the following way:
 399         </para>
 400 <informalexample><programlisting><![CDATA[
 401 gdbus-codegen --c-namespace MyApp                           \
 402   --generate-c-code myapp-generated                         \
 403   --annotate "org.project.InterfaceName"                    \
 404     org.gtk.GDBus.C.Name MyFrobnicator                      \
 405   --annotate "org.project.InterfaceName:Property"           \
 406     bar bat                                                 \
 407   --annotate "org.project.InterfaceName.Method()"           \
 408     org.freedesktop.DBus.Deprecated true                    \
 409   --annotate "org.project.InterfaceName.Method()[arg_name]" \
 410     snake hiss                                              \
 411   --annotate "org.project.InterfaceName::Signal"            \
 412     cat meow                                                \
 413   --annotate "org.project.InterfaceName::Signal[arg_name]"  \
 414     dog wuff                                                \
 415   myapp-dbus-interfaces.xml
 416 ]]></programlisting></informalexample>
 417         <para>
 418           Any UTF-8 string can be used for <replaceable>KEY</replaceable> and <replaceable>VALUE</replaceable>.
 419         </para>
 420       </listitem>
 421     </varlistentry>
 422
 423   </variablelist>
 424 </refsect1>
 425
 426 <refsect1>
 427   <title>Supported D-Bus Annotations</title>
 428   <para>
 429     The following D-Bus annotations are supported by
 430     <command>gdbus-codegen</command>:
 431   </para>
 432
 433   <variablelist>
 434
 435     <varlistentry>
 436       <term><literal>org.freedesktop.DBus.Deprecated</literal></term>
 437       <listitem>
 438         <para>
 439           Can be used on any <literal>&lt;interface&gt;</literal>,
 440           <literal>&lt;method&gt;</literal>,
 441           <literal>&lt;signal&gt;</literal> and
 442           <literal>&lt;property&gt;</literal> element to specify that
 443           the element is deprecated if its value is
 444           <literal>true</literal>. Note that this annotation is
 445           defined in the <ulink
 446           url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus
 447           specification</ulink> and can only assume the values
 448           <literal>true</literal> and <literal>false</literal>. In
 449           particular, you cannot specify the version that the element
 450           was deprecated in nor any helpful deprecation message. Such
 451           information should be added to the element documentation
 452           instead.
 453         </para>
 454         <para>
 455           When generating C code, this annotation is used to add
 456           #G_GNUC_DEPRECATED to generated functions for the element.
 457         </para>
 458         <para>
 459           When generating Docbook XML, a deprecation warning will
 460           appear along the documentation for the element.
 461         </para>
 462       </listitem>
 463     </varlistentry>
 464
 465     <varlistentry>
 466       <term><literal>org.gtk.GDBus.Since</literal></term>
 467       <listitem>
 468         <para>
 469           Can be used on any <literal>&lt;interface&gt;</literal>,
 470           <literal>&lt;method&gt;</literal>,
 471           <literal>&lt;signal&gt;</literal> and
 472           <literal>&lt;property&gt;</literal> element to specify the
 473           version (any free-form string but compared using a
 474           version-aware sort function) the element appeared in.
 475         </para>
 476         <para>
 477           When generating C code, this field is used to ensure
 478           function pointer order for preserving ABI/API, see <xref
 479           linkend="gdbus-code-stability"/>.
 480         </para>
 481         <para>
 482           When generating Docbook XML, the value of this tag appears
 483           in the documentation.
 484         </para>
 485       </listitem>
 486     </varlistentry>
 487
 488     <varlistentry>
 489       <term><literal>org.gtk.GDBus.DocString</literal></term>
 490       <listitem>
 491         <para>
 492           A string with Docbook content for documentation. This annotation can
 493           be used on <literal>&lt;interface&gt;</literal>,
 494           <literal>&lt;method&gt;</literal>,
 495           <literal>&lt;signal&gt;</literal>,
 496           <literal>&lt;property&gt;</literal> and
 497           <literal>&lt;arg&gt;</literal> elements.
 498         </para>
 499       </listitem>
 500     </varlistentry>
 501
 502     <varlistentry>
 503       <term><literal>org.gtk.GDBus.DocString.Short</literal></term>
 504       <listitem>
 505         <para>
 506           A string with Docbook content for short/brief
 507           documentation. This annotation can only be used on
 508           <literal>&lt;interface&gt;</literal> elements.
 509         </para>
 510       </listitem>
 511     </varlistentry>
 512
 513     <varlistentry>
 514       <term><literal>org.gtk.GDBus.C.Name</literal></term>
 515       <listitem>
 516         <para>
 517           Can be used on any <literal>&lt;interface&gt;</literal>,
 518           <literal>&lt;method&gt;</literal>,
 519           <literal>&lt;signal&gt;</literal> and
 520           <literal>&lt;property&gt;</literal> element to specify the
 521           name to use when generating C code. The value is expected to
 522           be in <ulink
 523           url="http://en.wikipedia.org/wiki/CamelCase">CamelCase</ulink>
 524           or <emphasis>Ugly_Case</emphasis> (see above).
 525         </para>
 526       </listitem>
 527     </varlistentry>
 528
 529     <varlistentry>
 530       <term><literal>org.gtk.GDBus.C.ForceGVariant</literal></term>
 531       <listitem>
 532         <para>
 533           If set to a non-empty string, a #GVariant instance will
 534           be used instead of the natural C type. This annotation can
 535           be used on any <literal>&lt;arg&gt;</literal> and
 536           <literal>&lt;property&gt;</literal> element.
 537         </para>
 538       </listitem>
 539     </varlistentry>
 540
 541     <varlistentry>
 542       <term><literal>org.gtk.GDBus.C.UnixFD</literal></term>
 543       <listitem>
 544         <para>
 545           If set to a non-empty string, the generated code will
 546           include parameters to exchange file descriptors using the
 547           #GUnixFDList type. This annotation can be used on
 548           <literal>&lt;method&gt;</literal> elements.
 549         </para>
 550       </listitem>
 551     </varlistentry>
 552
 553   </variablelist>
 554
 555   <para>
 556     As an easier alternative to using the
 557     <literal>org.gtk.GDBus.DocString</literal> annotation, note that
 558     parser used by <command>gdbus-codegen</command> parses XML
 559     comments in a way similar to <ulink
 560     url="http://www.gtk.org/gtk-doc/">gtk-doc</ulink>:
 561 <informalexample><programlisting><![CDATA[
 562 <!--
 563   net.Corp.Bar:
 564   @short_description: A short description
 565
 566   A <emphasis>longer</emphasis> description.
 567
 568   This is a new paragraph.
 569 -->
 570 <interface name="net.corp.Bar">
 571   <!--
 572     FooMethod:
 573     @greeting: The docs for greeting parameter.
 574     @response: The docs for response parameter.
 575
 576     The docs for the actual method.
 577   -->
 578   <method name="FooMethod">
 579     <arg name="greeting" direction="in" type="s"/>
 580     <arg name="response" direction="out" type="s"/>
 581   </method>
 582
 583   <!--
 584     BarSignal:
 585     @blah: The docs for blah parameter.
 586     @boo: The docs for boo parameter.
 587     @since: 2.30
 588
 589     The docs for the actual signal.
 590   -->
 591   <signal name="BarSignal">
 592     <arg name="blah" type="s"/>
 593     <arg name="boo" type="s"/>
 594   </signal>
 595
 596   <!-- BazProperty: The docs for the property. -->
 597   <property name="BazProperty" type="s" access="read"/>
 598 </interface>
 599 ]]></programlisting></informalexample>
 600   </para>
 601   <para>
 602     Note that <literal><![CDATA[@since]]></literal> can be used in any inline
 603     documentation bit (e.g. for interfaces, methods, signals and
 604     properties) to set the <literal>org.gtk.GDBus.Since</literal>
 605     annotation. For the <literal>org.gtk.GDBus.DocString</literal>
 606     annotation (and inline comments), note that substrings of the form
 607     <literal><![CDATA[#net.Corp.Bar]]></literal>,
 608     <literal><![CDATA[net.Corp.Bar.FooMethod()]]></literal>,
 609     <literal><![CDATA[#net.Corp.Bar::BarSignal]]></literal> and
 610     <literal><![CDATA[#net.Corp.InlineDocs:BazProperty]]></literal> are all
 611     expanded to links to the respective interface, method, signal and
 612     property.
 613     Additionally, substrings starting with <literal>@</literal> and <literal>%</literal> characters are rendered as
 614     <ulink url="http://www.docbook.org/tdg/en/html/parameter.html">parameter</ulink> and
 615     <ulink url="http://www.docbook.org/tdg/en/html/constant.html">constant</ulink> respectively.
 616   </para>
 617   <para>
 618     If both XML comments and
 619     <literal>org.gtk.GDBus.DocString</literal> or
 620     <literal>org.gtk.GDBus.DocString.Short</literal> annotations are
 621     present, the latter wins.
 622   </para>
 623 </refsect1>
 624
 625 <refsect1>
 626   <title>Example</title>
 627   <para>
 628     Consider the following D-Bus Introspection XML.
 629   </para>
 630   <informalexample><programlisting><![CDATA[
 631 <node>
 632   <interface name="net.Corp.MyApp.Frobber">
 633     <method name="HelloWorld">
 634       <arg name="greeting" direction="in" type="s"/>
 635       <arg name="response" direction="out" type="s"/>
 636     </method>
 637
 638     <signal name="Notification">
 639       <arg name="icon_blob" type="ay"/>
 640       <arg name="height" type="i"/>
 641       <arg name="messages" type="as"/>
 642     </signal>
 643
 644     <property name="Verbose" type="b" access="readwrite"/>
 645   </interface>
 646 </node>
 647 ]]></programlisting>
 648   </informalexample>
 649   <para>
 650     If <command>gdbus-codegen</command> is used on this file like this:
 651   </para>
 652 <informalexample><programlisting><![CDATA[
 653 gdbus-codegen --generate-c-code myapp-generated       \
 654               --c-namespace MyApp                     \
 655               --interface-prefix net.corp.MyApp.      \
 656               net.Corp.MyApp.Frobber.xml
 657 ]]></programlisting></informalexample>
 658   <para>
 659     two files called
 660     <filename>myapp-generated.[ch]</filename> are
 661     generated. The files provide an abstract
 662     #GTypeInterface<!-- -->-derived type called
 663     <type>MyAppFrobber</type> as well as two instantiable types with
 664     the same name but suffixed with <type>Proxy</type> and
 665     <type>Skeleton</type>. The generated file, roughly, contains the
 666     following facilities:
 667   </para>
 668 <informalexample><programlisting><![CDATA[
 669 /* GType macros for the three generated types */
 670 #define MY_APP_TYPE_FROBBER (my_app_frobber_get_type ())
 671 #define MY_APP_TYPE_FROBBER_SKELETON (my_app_frobber_skeleton_get_type ())
 672 #define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ())
 673
 674 typedef struct _MyAppFrobber MyAppFrobber; /* Dummy typedef */
 675
 676 typedef struct
 677 {
 678   GTypeInterface parent_iface;
 679
 680   /* Signal handler for the ::notification signal */
 681   void (*notification) (MyAppFrobber *proxy,
 682                         GVariant *icon_blob,
 683                         gint height,
 684                         const gchar* const *messages);
 685
 686   /* Signal handler for the ::handle-hello-world signal */
 687   gboolean (*handle_hello_world) (MyAppFrobber *proxy,
 688                                   GDBusMethodInvocation *invocation,
 689                                   const gchar *greeting);
 690 } MyAppFrobberIface;
 691
 692 /* Asynchronously calls HelloWorld() */
 693 void
 694 my_app_frobber_call_hello_world (MyAppFrobber *proxy,
 695                                  const gchar *greeting,
 696                                  GCancellable *cancellable,
 697                                  GAsyncReadyCallback callback,
 698                                  gpointer user_data);
 699 gboolean
 700 my_app_frobber_call_hello_world_finish (MyAppFrobber *proxy,
 701                                         gchar **out_response,
 702                                         GAsyncResult *res,
 703                                         GError **error);
 704
 705 /* Synchronously calls HelloWorld(). Blocks calling thread. */
 706 gboolean
 707 my_app_frobber_call_hello_world_sync (MyAppFrobber *proxy,
 708                                       const gchar *greeting,
 709                                       gchar **out_response,
 710                                       GCancellable *cancellable,
 711                                       GError **error);
 712
 713 /* Completes handling the HelloWorld() method call */
 714 void
 715 my_app_frobber_complete_hello_world (MyAppFrobber *object,
 716                                      GDBusMethodInvocation *invocation,
 717                                      const gchar *response);
 718
 719 /* Emits the ::notification signal / Notification() D-Bus signal */
 720 void
 721 my_app_frobber_emit_notification (MyAppFrobber *object,
 722                                   GVariant *icon_blob,
 723                                   gint height,
 724                                   const gchar* const *messages);
 725
 726 /* Gets the :verbose GObject property / Verbose D-Bus property.
 727  * Does no blocking I/O.
 728  */
 729 gboolean my_app_frobber_get_verbose (MyAppFrobber *object);
 730
 731 /* Sets the :verbose GObject property / Verbose D-Bus property.
 732  * Does no blocking I/O.
 733  */
 734 void my_app_frobber_set_verbose (MyAppFrobber *object,
 735                                  gboolean      value);
 736
 737 /* Gets the interface info */
 738 GDBusInterfaceInfo *my_app_frobber_interface_info (void);
 739
 740 /* Creates a new skeleton object, ready to be exported */
 741 MyAppFrobber *my_app_frobber_skeleton_new (void);
 742
 743 /* Client-side proxy constructors.
 744  *
 745  * Additionally, _new_for_bus(), _new_for_bus_finish() and
 746  * _new_for_bus_sync() proxy constructors are also generated.
 747  */
 748 void
 749 my_app_frobber_proxy_new        (GDBusConnection     *connection,
 750                                  GDBusProxyFlags      flags,
 751                                  const gchar         *name,
 752                                  const gchar         *object_path,
 753                                  GCancellable        *cancellable,
 754                                  GAsyncReadyCallback  callback,
 755                                  gpointer             user_data);
 756 MyAppFrobber *
 757 my_app_frobber_proxy_new_finish (GAsyncResult        *res,
 758                                  GError             **error);
 759 MyAppFrobber *
 760 my_app_frobber_proxy_new_sync   (GDBusConnection     *connection,
 761                                  GDBusProxyFlags      flags,
 762                                  const gchar         *name,
 763                                  const gchar         *object_path,
 764                                  GCancellable        *cancellable,
 765                                  GError             **error);
 766 ]]></programlisting></informalexample>
 767   <para>
 768     Thus, for every D-Bus method, there will be three C functions for
 769     calling the method, one #GObject signal for handling an incoming
 770     call and one C function for completing an incoming call. For every
 771     D-Bus signal, there's one #GObject signal and one C function for
 772     emitting it. For every D-Bus property, two C functions are
 773     generated (one setter, one getter) and one #GObject property. The
 774     following table summarizes the generated facilities and where they
 775     are applicable:
 776   </para>
 777   <informaltable>
 778     <tgroup cols="3">
 779       <thead>
 780         <row>
 781           <entry></entry>
 782           <entry>Client</entry>
 783           <entry>Server</entry>
 784         </row>
 785       </thead>
 786       <tbody>
 787         <row>
 788           <entry>Types</entry>
 789           <entry>Use <type>MyAppFrobberProxy</type></entry>
 790           <entry>Any type implementing the <type>MyAppFrobber</type> interface</entry>
 791         </row>
 792         <row>
 793           <entry>Methods</entry>
 794           <entry>Use <function>m_a_f_hello_world()</function> to call.</entry>
 795           <entry>Receive via the <function>handle_hello_world()</function> signal handler. Complete the call with <function>m_a_f_complete_hello_world()</function></entry>
 796         </row>
 797         <row>
 798           <entry>Signals</entry>
 799           <entry>Connect to the <function>::notification</function> GObject signal.</entry>
 800           <entry>Use <function>m_a_f_emit_notification()</function> to emit signal.</entry>
 801         </row>
 802         <row>
 803           <entry>Properties (Reading)</entry>
 804           <entry>Use <function>m_a_f_get_verbose()</function> or <parameter>:verbose</parameter>.</entry>
 805           <entry>Implement #GObject<!-- -->'s <function>get_property()</function> vfunc.</entry>
 806         </row>
 807         <row>
 808           <entry>Properties (writing)</entry>
 809           <entry>Use <function>m_a_f_set_verbose()</function> or <parameter>:verbose</parameter>.</entry>
 810           <entry>Implement #GObject<!-- -->'s <function>set_property()</function> vfunc.</entry>
 811         </row>
 812       </tbody>
 813     </tgroup>
 814   </informaltable>
 815
 816   <refsect2>
 817     <title>Client-side usage</title>
 818     <para>
 819       You can use the generated proxy type with the generated
 820       constructors:
 821     </para>
 822     <informalexample><programlisting><![CDATA[
 823     MyAppFrobber *proxy;
 824     GError *error;
 825
 826     error = NULL;
 827     proxy = my_app_frobber_proxy_new_for_bus_sync (
 828                 G_BUS_TYPE_SESSION,
 829                 G_DBUS_PROXY_FLAGS_NONE,
 830                 "net.Corp.MyApp",              /* bus name */
 831                 "/net/Corp/MyApp/SomeFrobber", /* object */
 832                 NULL,                          /* GCancellable* */
 833                 &error);
 834     /* do stuff with proxy */
 835     g_object_unref (proxy);
 836 ]]></programlisting></informalexample>
 837     <para>
 838       Instead of using the generic #GDBusProxy facilities, one can use
 839       the generated methods such as
 840       <function>my_app_frobber_call_hello_world()</function> to invoke
 841       the <function>net.Corp.MyApp.Frobber.HelloWorld()</function>
 842       D-Bus method, connect to the
 843       <function>::notification</function> GObject signal to receive
 844       the <function>net.Corp.MyApp.Frobber::Notication</function>
 845       D-Bus signal and get/set the
 846       <parameter>net.Corp.MyApp.Frobber:Verbose</parameter> D-Bus
 847       Property using either the GObject property
 848       <parameter>:verbose</parameter> or the
 849       <function>my_app_get_verbose()</function> and
 850       <function>my_app_set_verbose()</function> methods. Use the
 851       standard #GObject::notify signal to listen to property changes.
 852     </para>
 853     <para>
 854       Note that all property access is via #GDBusProxy<!-- -->'s
 855       property cache so no I/O is ever done when reading properties.
 856       Also note that setting a property will cause the
 857       <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties.Set</ulink> method to be
 858       called on the remote object. This call, however, is asynchronous
 859       so setting a property won't block. Further, the change is
 860       delayed and no error checking is possible.
 861     </para>
 862   </refsect2>
 863
 864   <refsect2>
 865     <title>Server-side usage</title>
 866     <para>
 867       The generated <type>MyAppFrobber</type> interface is designed so
 868       it is easy to implement it in a #GObject
 869       subclass. For example, to handle
 870       <function>HelloWorld()</function> method invocations, set the
 871       vfunc for <function>handle_hello_hello_world()</function> in the
 872       <type>MyAppFrobberIface</type> structure. Similary, to handle
 873       the <parameter>net.Corp.MyApp.Frobber:Verbose</parameter>
 874       property override the <parameter>:verbose</parameter> #GObject
 875       property from the subclass. To emit a signal, use
 876       e.g. <function>my_app_emit_signal()</function> or
 877       g_signal_emit_by_name().
 878     </para>
 879     <para>
 880       Instead of subclassing, it is often easier to use the generated
 881       <type>MyAppFrobberSkeleton</type> subclass. To handle incoming
 882       method calls, use <function>g_signal_connect()</function> with
 883       the <function>::handle-*</function> signals and instead of
 884       overriding #GObject<!-- -->'s
 885       <function>get_property()</function> and
 886       <function>set_property()</function> vfuncs, use
 887       g_object_get() and
 888       g_object_set() or the generated property
 889       getters and setters (the generated class has an internal
 890       property bag implementation).
 891     </para>
 892     <informalexample><programlisting><![CDATA[
 893 static gboolean
 894 on_handle_hello_world (MyAppFrobber           *interface,
 895                        GDBusMethodInvocation  *invocation,
 896                        const gchar            *greeting,
 897                        gpointer                user_data)
 898 {
 899   if (g_strcmp0 (greeting, "Boo") != 0)
 900     {
 901       gchar *response;
 902       response = g_strdup_printf ("Word! You said `%s'.", greeting);
 903       my_app_complete_hello_world (interface, invocation, response);
 904       g_free (response);
 905     }
 906   else
 907     {
 908       g_dbus_method_invocation_return_error (invocation,
 909                  MY_APP_ERROR,
 910                  MY_APP_ERROR_NO_WHINING,
 911                  "Hey, %s, there will be no whining!",
 912                  g_dbus_method_invocation_get_sender (invocation));
 913     }
 914   return TRUE;
 915 }
 916
 917   [...]
 918
 919   interface = my_app_frobber_skeleton_new ();
 920   my_app_frobber_set_verbose (interface, TRUE);
 921
 922   g_signal_connect (interface,
 923                     "handle-hello-world",
 924                     G_CALLBACK (on_handle_hello_world),
 925                     some_user_data);
 926
 927   [...]
 928
 929   error = NULL;
 930   if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
 931                                          connection,
 932                                          "/path/of/dbus_object",
 933                                          &error))
 934     {
 935       /* handle error */
 936     }
 937 ]]></programlisting></informalexample>
 938     <para>
 939       To facilitate atomic changesets (multiple properties changing at
 940       the same time), #GObject::notify signals are queued up when
 941       received. The queue is drained in an idle handler (which is called from the
 942       <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
 943       of the thread where the skeleton object was
 944       contructed) and will cause emissions of the <ulink
 945       url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties::PropertiesChanged</ulink>
 946       signal with all the properties that have changed. Use
 947       g_dbus_interface_skeleton_flush() or
 948       g_dbus_object_skeleton_flush() to empty the queue
 949       immediately. Use g_object_freeze_notify() and
 950       g_object_thaw_notify() for atomic changesets if on a different
 951       thread.
 952     </para>
 953   </refsect2>
 954 </refsect1>
 955
 956 <refsect1>
 957   <title>C Type Mapping</title>
 958   <para>
 959     Scalar types
 960     (type-strings
 961     <link linkend="G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</link>,
 962     <link linkend="G-VARIANT-TYPE-BYTE:CAPS">'y'</link>,
 963     <link linkend="G-VARIANT-TYPE-INT16:CAPS">'n'</link>,
 964     <link linkend="G-VARIANT-TYPE-UINT16:CAPS">'q'</link>,
 965     <link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link>,
 966     <link linkend="G-VARIANT-TYPE-UINT32:CAPS">'u'</link>,
 967     <link linkend="G-VARIANT-TYPE-INT64:CAPS">'x'</link>,
 968     <link linkend="G-VARIANT-TYPE-UINT64:CAPS">'t'</link> and
 969     <link linkend="G-VARIANT-TYPE-DOUBLE:CAPS">'d'</link>)
 970     ),
 971     strings (type-strings
 972     <link linkend="G-VARIANT-TYPE-STRING:CAPS">'s'</link>,
 973     <link linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link>,
 974     <link linkend="G-VARIANT-TYPE-OBJECT-PATH:CAPS">'o'</link> and
 975     <link linkend="G-VARIANT-TYPE-SIGNATURE:CAPS">'g'</link>) and
 976     arrays of string (type-strings
 977     <link linkend="G-VARIANT-TYPE-STRING-ARRAY:CAPS">'as'</link>,
 978     <link linkend="G-VARIANT-TYPE-OBJECT-PATH-ARRAY:CAPS">'ao'</link> and
 979     <link linkend="G-VARIANT-TYPE-BYTESTRING-ARRAY:CAPS">'aay'</link>)
 980     are mapped to the natural types,
 981     e.g. #gboolean, #gdouble, #gint, <link linkend="gchararray">gchar*</link>,
 982     <link linkend="GStrv">gchar**</link> and
 983     so on. Everything else is mapped to the #GVariant
 984     type.
 985   </para>
 986   <para>
 987     This automatic mapping can be turned off by using the annotation
 988     <literal>org.gtk.GDBus.C.ForceGVariant</literal> - if used then a
 989     #GVariant is always exchanged instead of the
 990     corresponding native C type. This annotation may be convenient to
 991     use when using
 992     bytestrings (type-string <link linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link>)
 993     for data that could have embedded NUL bytes.
 994   </para>
 995 </refsect1>
 996
 997 <refsect1 id="gdbus-code-stability">
 998   <title>Stability Guarantees</title>
 999   <para>
1000     The generated C functions are guaranteed to not change their ABI
1001     that is, if a method, signal or property does not change its
1002     signature in the introspection XML, the generated C functions will
1003     not change its C ABI either. The ABI of the generated instance and
1004     class structures will be preserved as well.
1005   </para>
1006   <para>
1007     The ABI of the generated #GType<!-- -->s will be preserved only if
1008     the <literal>org.gtk.GDBus.Since</literal> annotation is used
1009     judiciously — this is because the VTable for the #GInterface
1010     relies on functions pointers for signal handlers. Specifically, if
1011     a D-Bus method, property or signal or is added to a D-Bus
1012     interface, then ABI of the generated #GInterface type is preserved
1013     if, and only if, each added method, property signal is annotated
1014     with they <literal>org.gtk.GDBus.Since</literal> annotation using
1015     a greater version number than previous versions.
1016   </para>
1017   <para>
1018     The generated C code currently happens to be annotated with <ulink
1019     url="http://www.gtk.org/gtk-doc/">gtk-doc</ulink> / <ulink
1020     url="https://wiki.gnome.org/Projects/GObjectIntrospection">GObject
1021     Introspection</ulink> comments / annotations. The layout and
1022     contents might change in the future so no guarantees about
1023     e.g. <literal>SECTION</literal> usage etc. is given.
1024   </para>
1025   <para>
1026     While the generated Docbook for D-Bus interfaces isn't expected to
1027     change, no guarantees are given at this point.
1028   </para>
1029   <para>
1030     It is important to note that the generated code should not be
1031     checked into revision control systems, nor it should be included
1032     in distributed source archives.
1033   </para>
1034 </refsect1>
1035
1036 <refsect1>
1037   <title>Bugs</title>
1038   <para>
1039     Please send bug reports to either the distribution bug tracker
1040     or the upstream bug tracker at
1041     <ulink url="https://gitlab.gnome.org/GNOME/glib/issues/new">https://gitlab.gnome.org/GNOME/glib/issues/new</ulink>.
1042   </para>
1043 </refsect1>
1044
1045 <refsect1>
1046   <title>See also</title>
1047   <para>
1048     <citerefentry>
1049       <refentrytitle>gdbus</refentrytitle><manvolnum>1</manvolnum>
1050     </citerefentry>
1051   </para>
1052 </refsect1>
1053
1054 </refentry>