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