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