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