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