docs/reference/gio/gdbus-codegen.xml

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