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