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>GLib 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, an abstract
  57     #GTypeInterface<!-- -->-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>FooBarStub</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     #GDBusInterfaceStub 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 a #GDBusObjectManagerClient
 138           subclass with an appropriate #GDBusProxyTypeFunc is
 139           generated.
 140         </para>
 141       </listitem>
 142     </varlistentry>
 143
 144     <varlistentry>
 145       <term><option>--annotate</option></term>
 146       <listitem>
 147         <para>
 148           Used together with <option>--key</option> and
 149           <option>--value</option> to annotate the given XML files. 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.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       </listitem>
 171     </varlistentry>
 172   </variablelist>
 173 </refsect1>
 174
 175 <refsect1>
 176   <title>Supported D-Bus Annotations</title>
 177   <para>
 178     The following D-Bus annotations are supported by
 179     <command>gdbus-codegen</command>:
 180   </para>
 181
 182   <variablelist>
 183
 184     <varlistentry>
 185       <term><literal>org.gtk.GDBus.Name</literal></term>
 186       <listitem>
 187         <para>
 188           Can be used on any <literal>&lt;interface&gt;</literal>,
 189           <literal>&lt;method&gt;</literal>,
 190           <literal>&lt;signal&gt;</literal> and
 191           <literal>&lt;property&gt;</literal> element to specify the
 192           name to use.
 193         </para>
 194         <para>
 195           For interfaces where this annotation is not specified, the
 196           name used is the D-Bus interface name stripped with the
 197           prefix given with <option>--interface-prefix</option> and with
 198           the dots removed and initial characters capitalized. For
 199           example the D-Bus interface
 200           <literal>com.acme.Coyote</literal> the name used is
 201           <type>ComAcmeCoyote</type>. For the D-Bus interface
 202           <literal>org.project.Bar.Frobnicator</literal> with
 203           <option>--interface-prefix</option>
 204           <literal>org.project.</literal>, the name used is
 205           <type>BarFrobnicator</type>.
 206         </para>
 207         <para>
 208           For methods, signals and properties the name used is
 209           calculated by transforming
 210           <literal>NameGivenThisWay</literal> into
 211           <literal>name_given_this_way</literal>, e.g. roughly
 212           converting from camel-case to lower-case with underscores
 213           using certain heuristics.
 214         </para>
 215       </listitem>
 216     </varlistentry>
 217
 218     <varlistentry>
 219       <term><literal>org.gtk.GDBus.Since</literal></term>
 220       <listitem>
 221         <para>
 222           Can be used on any <literal>&lt;interface&gt;</literal>,
 223           <literal>&lt;method&gt;</literal>,
 224           <literal>&lt;signal&gt;</literal> and
 225           <literal>&lt;property&gt;</literal> element to specify the
 226           version (any free-form string but compared using a
 227           version-aware sort function) the element appeared in.
 228         </para>
 229         <para>
 230           When generating C code, this field is used to ensure
 231           function pointer order for preserving ABI/API.
 232         </para>
 233         <para>
 234           When generating Docbook XML, the value of this tag appears
 235           in the documentation.
 236         </para>
 237       </listitem>
 238     </varlistentry>
 239
 240     <varlistentry>
 241       <term><literal>org.gtk.GDBus.C.ForceGVariant</literal></term>
 242       <listitem>
 243         <para>
 244           If set to a non-empty string, a #GVariant instance will
 245           be used instead of the natural C type. This annotation can
 246           be used on any <literal>&lt;arg&gt;</literal> and
 247           <literal>&lt;property&gt;</literal> element.
 248         </para>
 249       </listitem>
 250     </varlistentry>
 251
 252     <varlistentry>
 253       <term><literal>org.gtk.GDBus.DocString</literal></term>
 254       <listitem>
 255         <para>
 256           A string with Docbook content for documentation. This annotation can
 257           be used on <literal>&lt;interface&gt;</literal>,
 258           <literal>&lt;method&gt;</literal>,
 259           <literal>&lt;signal&gt;</literal>,
 260           <literal>&lt;property&gt;</literal> and
 261           <literal>&lt;arg&gt;</literal> elements.
 262         </para>
 263       </listitem>
 264     </varlistentry>
 265
 266     <varlistentry>
 267       <term><literal>org.gtk.GDBus.DocString.Short</literal></term>
 268       <listitem>
 269         <para>
 270           A string with Docbook content for short/brief
 271           documentation. This annotation can only be used on
 272           <literal>&lt;interface&gt;</literal> elements.
 273         </para>
 274       </listitem>
 275     </varlistentry>
 276
 277   </variablelist>
 278
 279   <para>
 280     As an easier alternative to using the
 281     <literal>org.gtk.GDBus.DocString</literal> annotation, note that
 282     XML parser used by <command>gdbus-codegen</command> parses XML
 283     comments in a way similar to <ulink
 284     url="http://www.gtk.org/gtk-doc/">gtk-doc</ulink>:
 285 <informalexample><programlisting><![CDATA[
 286 <!--
 287   net.Corp.Bar:
 288   @short_description: A short description
 289
 290   A <emphasis>longer</emphasis> description.
 291
 292   This is a new paragraph.
 293 -->
 294 <interface name="net.corp.Bar">
 295   <!--
 296     FooMethod:
 297     @greeting: The docs for greeting parameter.
 298     @response: The docs for response parameter.
 299
 300     The docs for the actual method.
 301   -->
 302   <method name="FooMethod">
 303     <arg name="greeting" direction="in" type="s"/>
 304     <arg name="response" direction="out" type="s"/>
 305   </method>
 306
 307   <!--
 308     BarSignal:
 309     @blah: The docs for blah parameter.
 310     @boo: The docs for boo parameter.
 311
 312     The docs for the actual signal.
 313   -->
 314   <signal name="BarSignal">
 315     <arg name="blah" type="s"/>
 316     <arg name="boo" type="s"/>
 317   </signal>
 318
 319   <!-- BazProperty: The docs for the property. -->
 320   <property name="BazProperty" type="s" access="read"/>
 321 </interface>
 322 ]]></programlisting></informalexample>
 323   </para>
 324   <para>
 325     For the <literal>org.gtk.GDBus.DocString</literal> annotation (and
 326     inline comments), note that substrings of the form
 327     <literal>#net.Corp.Bar</literal>,
 328     <literal>net.Corp.Bar.FooMethod()</literal>,
 329     <literal>#net.Corp.Bar::BarSignal</literal> and
 330     <literal>#net.Corp.InlineDocs:BazProperty</literal> are all expanded
 331     to links to the respective interface, method, signal and property.
 332   </para>
 333 </refsect1>
 334
 335 <refsect1>
 336   <title>Example</title>
 337   <para>
 338     Consider the following D-Bus Introspection XML.
 339   </para>
 340   <informalexample><programlisting><![CDATA[
 341 <interface name="net.Corp.MyApp.Frobber">
 342   <method name="HelloWorld">
 343     <arg name="greeting" direction="in" type="s"/>
 344     <arg name="response" direction="out" type="s"/>
 345   </method>
 346
 347   <signal name="Notification">
 348     <arg name="icon_blob" type="ay"/>
 349     <arg name="height" type="i"/>
 350     <arg name="messages" type="as"/>
 351   </signal>
 352
 353   <property name="Verbose" type="b" access="readwrite"/>
 354 </interface>
 355 ]]></programlisting>
 356   </informalexample>
 357   <para>
 358     If <command>gdbus-codegen</command> is used on this file like this:
 359   </para>
 360 <informalexample><programlisting><![CDATA[
 361 gdbus-codegen --generate-c-code myapp-generated       \
 362               --c-namespace MyApp                     \
 363               --interface-prefix net.corp.MyApp.      \
 364               net.Corp.MyApp.Frobber.xml
 365 ]]></programlisting></informalexample>
 366   <para>
 367     two files called
 368     <filename>myapp-generated.[ch]</filename> are
 369     generated. The files provide an abstract
 370     #GTypeInterface<!-- -->-derived type called
 371     <type>MyAppFrobber</type> as well as two instantiable types with
 372     the same name but suffixed with <type>Proxy</type> and
 373     <type>Stub</type>. The generated file, roughly, contains the
 374     following facilities:
 375   </para>
 376 <informalexample><programlisting><![CDATA[
 377 /* GType macros for the three generated types */
 378 #define MY_APP_TYPE_FROBBER (my_app_frobber_get_type ())
 379 #define MY_APP_TYPE_FROBBER_STUB (my_app_frobber_stub_get_type ())
 380 #define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ())
 381
 382 typedef struct _MyAppFrobber MyAppFrobber; /* Dummy typedef */
 383
 384 typedef struct
 385 {
 386   GTypeInterface parent_iface;
 387
 388   /* Signal handler for the ::notification signal */
 389   void (*notification) (MyAppFrobber *proxy,
 390                         GVariant *icon_blob,
 391                         gint height,
 392                         const gchar* const *messages);
 393
 394   /* Signal handler for the ::handle-hello-world signal */
 395   gboolean (*handle_hello_world) (MyAppFrobber *proxy,
 396                                   GDBusMethodInvocation *invocation,
 397                                   const gchar *greeting);
 398 } MyAppFrobberIface;
 399
 400 /* Asynchronously calls HelloWorld() */
 401 void
 402 my_app_frobber_call_hello_world (MyAppFrobber *proxy,
 403                                  const gchar *greeting,
 404                                  GCancellable *cancellable,
 405                                  GAsyncReadyCallback callback,
 406                                  gpointer user_data);
 407 gboolean
 408 my_app_frobber_call_hello_world_finish (MyAppFrobber *proxy,
 409                                         gchar **out_response,
 410                                         GAsyncResult *res,
 411                                         GError **error);
 412
 413 /* Synchronously calls HelloWorld(). Blocks calling thread. */
 414 gboolean
 415 my_app_frobber_call_hello_world_sync (MyAppFrobber *proxy,
 416                                       const gchar *greeting,
 417                                       gchar **out_response,
 418                                       GCancellable *cancellable,
 419                                       GError **error);
 420
 421 /* Completes handling the HelloWorld() method call */
 422 void
 423 my_app_frobber_complete_hello_world (MyAppFrobber *object,
 424                                      GDBusMethodInvocation *invocation,
 425                                      const gchar *response);
 426
 427 /* Emits the ::notification signal / Notification() D-Bus signal */
 428 void
 429 my_app_frobber_emit_notification (MyAppFrobber *object,
 430                                   GVariant *icon_blob,
 431                                   gint height,
 432                                   const gchar* const *messages);
 433
 434 /* Gets the :verbose GObject property / Verbose D-Bus property.
 435  * Does no blocking I/O.
 436  */
 437 gboolean my_app_frobber_get_verbose (MyAppFrobber *object);
 438
 439 /* Sets the :verbose GObject property / Verbose D-Bus property.
 440  * Does no blocking I/O.
 441  */
 442 void my_app_frobber_set_verbose (MyAppFrobber *object,
 443                                  gboolean      value);
 444
 445 /* Gets the interface info */
 446 GDBusInterfaceInfo *my_app_frobber_interface_info (void);
 447
 448 /* Creates a new stub object, ready to be exported */
 449 MyAppFrobber *my_app_frobber_stub_new (void);
 450
 451 /* Client-side proxy constructors.
 452  *
 453  * Additionally, _new_for_bus(), _new_for_bus_finish() and
 454  * _new_for_bus_sync() proxy constructors are also generated.
 455  */
 456 void
 457 my_app_frobber_proxy_new        (GDBusConnection     *connection,
 458                                  GDBusProxyFlags      flags,
 459                                  const gchar         *name,
 460                                  const gchar         *object_path,
 461                                  GCancellable        *cancellable,
 462                                  GAsyncReadyCallback  callback,
 463                                  gpointer             user_data);
 464 MyAppFrobber *
 465 my_app_frobber_proxy_new_finish (GAsyncResult        *res,
 466                                  GError             **error);
 467 MyAppFrobber *
 468 my_app_frobber_proxy_new_sync   (GDBusConnection     *connection,
 469                                  GDBusProxyFlags      flags,
 470                                  const gchar         *name,
 471                                  const gchar         *object_path,
 472                                  GCancellable        *cancellable,
 473                                  GError             **error);
 474 ]]></programlisting></informalexample>
 475   <para>
 476     Thus, for every D-Bus method, there will be three C functions for
 477     calling the method, one #GObject signal for handling an incoming
 478     call and one C function for completing an incoming call. For every
 479     D-Bus signal, there's one #GObject signal and one C function for
 480     emitting it. For every D-Bus property, two C functions are
 481     generated (one setter, one getter) and one #GObject property. The
 482     following table summarizes the generated facilities and where they
 483     are applicable:
 484   </para>
 485   <informaltable>
 486     <tgroup cols="3">
 487       <thead>
 488         <row>
 489           <entry></entry>
 490           <entry>Client</entry>
 491           <entry>Server</entry>
 492         </row>
 493       </thead>
 494       <tbody>
 495         <row>
 496           <entry>Types</entry>
 497           <entry>Use <type>MyAppFrobberProxy</type></entry>
 498           <entry>Any type implementing the <type>MyAppFrobber</type> interface</entry>
 499         </row>
 500         <row>
 501           <entry>Methods</entry>
 502           <entry>Use <function>m_a_f_hello_world()</function> to call.</entry>
 503           <entry>Receive via the <function>handle_hello_world()</function> signal handler. Complete the call with <function>m_a_f_complete_hello_world()</function></entry>
 504         </row>
 505         <row>
 506           <entry>Signals</entry>
 507           <entry>Connect to the <function>::notification</function> GObject signal.</entry>
 508           <entry>Use <function>m_a_f_emit_notification()</function> to emit signal.</entry>
 509         </row>
 510         <row>
 511           <entry>Properties (Reading)</entry>
 512           <entry>Use <function>m_a_f_get_verbose()</function> or <parameter>:verbose</parameter>.</entry>
 513           <entry>Implement #GObject<!-- -->'s <function>get_property()</function> vfunc.</entry>
 514         </row>
 515         <row>
 516           <entry>Properties (writing)</entry>
 517           <entry>Use <function>m_a_f_set_verbose()</function> or <parameter>:verbose</parameter>.</entry>
 518           <entry>Implement #GObject<!-- -->'s <function>set_property()</function> vfunc.</entry>
 519         </row>
 520       </tbody>
 521     </tgroup>
 522   </informaltable>
 523
 524   <refsect2>
 525     <title>Client-side usage</title>
 526     <para>
 527       You can use the generated proxy type with the generated
 528       constructors:
 529     </para>
 530     <informalexample><programlisting><![CDATA[
 531     MyAppFrobber *proxy;
 532     GError *error;
 533
 534     error = NULL;
 535     proxy = my_app_frobber_proxy_new_for_bus_sync (
 536                 G_BUS_TYPE_SESSION,
 537                 G_DBUS_PROXY_FLAGS_NONE,
 538                 "net.Corp.MyApp",              /* bus name */
 539                 "/net/Corp/MyApp/SomeFrobber", /* object */
 540                 NULL,                          /* GCancellable* */
 541                 &error);
 542     /* do stuff with proxy */
 543     g_object_unref (proxy);
 544 ]]></programlisting></informalexample>
 545     <para>
 546       Instead of using the generic #GDBusProxy facilities, one can use
 547       the generated methods such as
 548       <function>my_app_frobber_call_hello_world()</function> to invoke
 549       the <function>net.Corp.MyApp.Frobber.HelloWorld()</function>
 550       D-Bus method, connect to the the
 551       <function>::notification</function> GObject signal to receive
 552       the <function>net.Corp.MyApp.Frobber::Notication</function>
 553       D-Bus signal and get/set the
 554       <parameter>net.Corp.MyApp.Frobber:Verbose</parameter> D-Bus
 555       Property using either the GObject property
 556       <parameter>:verbose</parameter> or the
 557       <function>my_app_get_verbose()</function> and
 558       <function>my_app_set_verbose()</function> methods. Use the
 559       standard #GObject::notify signal to listen to property changes.
 560     </para>
 561     <para>
 562       Note that all property access is via #GDBusProxy<!-- -->'s
 563       property cache so no IO is ever done when reading properties.
 564       Also note that setting a property will cause the
 565       <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties.Set</ulink> method to be
 566       called on the remote object. This call, however, is asynchronous
 567       so setting a property won't block. Further, the change is
 568       delayed and no error checking is possible.
 569     </para>
 570   </refsect2>
 571
 572   <refsect2>
 573     <title>Server-side usage</title>
 574     <para>
 575       The generated <type>MyAppFrobber</type> interface is designed so
 576       it is easy to implement it in a #GObject
 577       subclass. For example, to handle
 578       <function>HelloWorld()</function> method invocations, set the
 579       vfunc for <function>handle_hello_hello_world()</function> in the
 580       <type>MyAppFrobberIface</type> structure. Similary, to handle
 581       the <parameter>net.Corp.MyApp.Frobber:Verbose</parameter>
 582       property override the <parameter>:verbose</parameter> #GObject
 583       property from the subclass. To emit a signal, use
 584       e.g. <function>my_app_emit_signal()</function> or
 585       g_signal_emit_by_name().
 586     </para>
 587     <para>
 588       Instead of subclassing, it is often easier to use the generated
 589       <type>MyAppFrobberStub</type> subclass. To handle incoming
 590       method calls, use <function>g_signal_connect()</function> with
 591       the <function>::handle-*</function> signals and instead of
 592       overriding #GObject<!-- -->'s
 593       <function>get_property()</function> and
 594       <function>set_property()</function> vfuncs, use
 595       g_object_get() and
 596       g_object_set() or the generated property
 597       getters and setters (the generated class has an internal
 598       property bag implementation).
 599     </para>
 600     <informalexample><programlisting><![CDATA[
 601 static gboolean
 602 on_handle_hello_world (MyAppFrobber           *object,
 603                        GDBusMethodInvocation  *invocation,
 604                        const gchar            *greeting,
 605                        gpointer                user_data)
 606 {
 607   if (g_strcmp0 (greeting, "Boo") != 0)
 608     {
 609       gchar *response;
 610       response = g_strdup_printf ("Word! You said `%s'.", greeting);
 611       my_app_complete_hello_world (object, invocation, response);
 612       g_free (response);
 613     }
 614   else
 615     {
 616       g_dbus_method_invocation_return_error (MY_APP_ERROR,
 617                  MY_APP_ERROR_NO_WHINING,
 618                  "Hey, %s, there will be no whining!",
 619                  g_dbus_method_invocation_get_sender (invocation));
 620     }
 621   return TRUE;
 622 }
 623
 624   [...]
 625
 626   object = my_app_frobber_stub_new ();
 627   my_app_frobber_set_verbose (object, TRUE);
 628
 629   g_signal_connect (object,
 630                     "handle-hello-world",
 631                     G_CALLBACK (on_handle_hello-world),
 632                     some_user_data);
 633
 634   [...]
 635
 636   error = NULL;
 637   id = g_dbus_interface_register_object (G_DBUS_INTERFACE (object),
 638                                          connection,
 639                                          "/path/of/object",
 640                                          &error);
 641 ]]></programlisting></informalexample>
 642     <para>
 643       To facility atomic changesets (multiple properties changing at
 644       the same time), #GObject::notify signals are queued up when
 645       received. The queue is drained in an idle handler and will cause
 646       emissions of the <ulink
 647       url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties::PropertiesChanged</ulink>
 648       signal with all the properties that has changed. Use
 649       g_dbus_interface_stub_flush() or g_dbus_object_stub_flush() to
 650       empty the queue immediately.
 651     </para>
 652   </refsect2>
 653 </refsect1>
 654
 655 <refsect1>
 656   <title>C Type Mapping</title>
 657   <para>
 658     Scalar types
 659     (type-strings
 660     <link linkend="G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</link>,
 661     <link linkend="G-VARIANT-TYPE-BYTE:CAPS">'y'</link>,
 662     <link linkend="G-VARIANT-TYPE-INT16:CAPS">'n'</link>,
 663     <link linkend="G-VARIANT-TYPE-UINT16:CAPS">'q'</link>,
 664     <link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link>,
 665     <link linkend="G-VARIANT-TYPE-UINT32:CAPS">'u'</link>,
 666     <link linkend="G-VARIANT-TYPE-INT64:CAPS">'x'</link>,
 667     <link linkend="G-VARIANT-TYPE-UINT64:CAPS">'t'</link>,
 668     <link linkend="G-VARIANT-TYPE-HANDLE:CAPS">'h'</link> and
 669     <link linkend="G-VARIANT-TYPE-DOUBLE:CAPS">'d'</link>)
 670     ),
 671     strings (type-strings
 672     <link linkend="G-VARIANT-TYPE-STRING:CAPS">'s'</link>,
 673     <link linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link>,
 674     <link linkend="G-VARIANT-TYPE-OBJECT-PATH:CAPS">'o'</link> and
 675     <link linkend="G-VARIANT-TYPE-SIGNATURE:CAPS">'g'</link>) and
 676     arrays of string (type-strings
 677     <link linkend="G-VARIANT-TYPE-STRING-ARRAY:CAPS">'as'</link> and
 678     <link linkend="G-VARIANT-TYPE-BYTESTRING-ARRAY:CAPS">'aay'</link>)
 679     are mapped to the natural types,
 680     e.g. #gboolean, #gdouble, #gint, <link linkend="gchararray">gchar*</link>,
 681     <link linkend="GStrv">gchar**</link> and
 682     so on. Everything else is mapped to the #GVariant
 683     type.
 684   </para>
 685   <para>
 686     This automatic mapping can be turned off by using the annotation
 687     <literal>org.gtk.GDBus.C.ForceGVariant</literal> - if used then a
 688     #GVariant is always exchanged instead of the
 689     corresponding native C type. This annotation may be convenient to
 690     use when using
 691     bytestrings (type-string <link linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link>)
 692     for data that could have embedded NUL bytes.
 693   </para>
 694 </refsect1>
 695
 696 <refsect1>
 697   <title>Stability Guarantees</title>
 698   <para>
 699     No guarantees about the API and ABI of the code generated by
 700     <command>gdbus-codegen</command> are given. This means that code
 701     generated by future versions of this program may have a different
 702     API or ABI even if the underlying D-Bus interface hasn't
 703     changed. As such, always include the generated code in
 704     distribution tarballs and never expose the code in any stable
 705     interfaces.
 706   </para>
 707   <para>
 708     Future versions of <command>gdbus-codegen</command> will provide
 709     ABI and API guarantees on the generated code.
 710   </para>
 711 </refsect1>
 712
 713 <refsect1>
 714   <title>Author</title>
 715   <para>
 716     Written by David Zeuthen <email>zeuthen(at)gmail.com</email> with
 717     a lot of help from many others.
 718   </para>
 719 </refsect1>
 720
 721 <refsect1>
 722   <title>Bugs</title>
 723   <para>
 724     Please send bug reports to either the distribution bug tracker
 725     or the upstream bug tracker at
 726     <ulink url="https://bugzilla.gnome.org/enter_bug.cgi?product=glib"/>.
 727   </para>
 728 </refsect1>
 729
 730 <refsect1>
 731   <title>See also</title>
 732   <para>
 733     <citerefentry>
 734       <refentrytitle>gdbus</refentrytitle><manvolnum>1</manvolnum>
 735     </citerefentry>
 736   </para>
 737 </refsect1>
 738
 739 </refentry>