docs/reference/gio/gdbus-codegen.xml

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