docs/reference/gio/html/gdbus-codegen.html

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