RubyGems - glib2 - Versions diffs - 2.2.4-x64-mingw32 - Mend

glib2 2.2.4-x64-mingw32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2228) hide show

data/vendor/local/share/gtk-doc/html/gio/gdbus-codegen.html ADDED Viewed

@@ -0,0 +1,1098 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>GIO Reference Manual: gdbus-codegen</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
+<link rel="home" href="index.html" title="GIO Reference Manual">
+<link rel="up" href="tools.html" title="GIO Tools">
+<link rel="prev" href="gdbus.html" title="gdbus">
+<link rel="next" href="gresource-tool.html" title="gresource">
+<meta name="generator" content="GTK-Doc V1.21.1 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
+<td width="100%" align="left" class="shortcuts"></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
+<td><a accesskey="u" href="tools.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
+<td><a accesskey="p" href="gdbus.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
+<td><a accesskey="n" href="gresource-tool.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
+</tr></table>
+<div lang="en" class="refentry">
+<a name="gdbus-codegen"></a><div class="titlepage"></div>
+<div class="refnamediv"><table width="100%"><tr>
+<td valign="top">
+<h2><span class="refentrytitle">gdbus-codegen</span></h2>
+<p>gdbus-codegen — D-Bus code and documentation generator</p>
+</td>
+<td class="gallery_image" valign="top" align="right"></td>
+</tr></table></div>
+<div class="refsynopsisdiv">
+<h2>Synopsis</h2>
+<div class="cmdsynopsis"><p><code class="command">gdbus-codegen</code>  [<code class="option">-h</code>, <code class="option">--help</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>] [<code class="option">--xml-files</code> <em class="replaceable"><code>FILE</code></em>]  [
+        <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>
+      ]...   FILE  [
+       FILE...
+    ]</p></div>
+</div>
+<div class="refsect1">
+<a name="id-1.4.24.7.5"></a><h2>Description</h2>
+<p>
+    <span class="command"><strong>gdbus-codegen</strong></span> is used to generate code and/or
+    documentation for one or more D-Bus interfaces. The tool reads
+    <a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format" target="_top">D-Bus
+    Introspection XML</a> files and generates output files. The
+    tool currently supports generating C code (via
+    <code class="option">--generate-c-code</code>) and Docbook XML (via
+    <code class="option">--generate-docbook</code>).
+  </p>
+</div>
+<div class="refsect1">
+<a name="id-1.4.24.7.6"></a><h2>Generating C code</h2>
+<p>
+    When generating C code, a
+    <span class="type">GInterface</span>-derived type is generated for each D-Bus
+    interface. Additionally, for every generated type,
+    <span class="type">FooBar</span>, two concrete instantiable types,
+    <span class="type">FooBarProxy</span> and <span class="type">FooBarSkeleton</span>, implementing
+    said interface are also generated. The former is derived from
+    <a class="link" href="GDBusProxy.html" title="GDBusProxy"><span class="type">GDBusProxy</span></a> and intended for use on the client side
+    while the latter is derived from the
+    <a class="link" href="GDBusInterfaceSkeleton.html" title="GDBusInterfaceSkeleton"><span class="type">GDBusInterfaceSkeleton</span></a> type making it easy to export on a
+    <a class="link" href="GDBusConnection.html" title="GDBusConnection"><span class="type">GDBusConnection</span></a> either directly or via a
+    <a class="link" href="GDBusObjectManagerServer.html" title="GDBusObjectManagerServer"><span class="type">GDBusObjectManagerServer</span></a> instance.
+  </p>
+<p>
+    The name of each generated C type is derived from the D-Bus
+    interface name stripped with the prefix given with
+    <code class="option">--interface-prefix</code> and with the dots removed and
+    initial characters capitalized. For example, for the D-Bus
+    interface <code class="literal">com.acme.Coyote</code> the name used is
+    <code class="literal">ComAcmeCoyote</code>. For the D-Bus interface
+    <code class="literal">org.project.Bar.Frobnicator</code> with
+    <code class="option">--interface-prefix</code>
+    <code class="literal">org.project.</code>, the name used is
+    <code class="literal">BarFrobnicator</code>.
+  </p>
+<p>
+    For methods, signals and properties, if not specified, the name
+    defaults to the name of the method, signal or property.
+  </p>
+<p>
+    Two forms of the name are used - the CamelCase form and the
+    lower-case form. The CamelCase form is used for the <a href="../gobject/gobject-Type-Information.html#GType"><span class="type">GType</span></a> and
+    struct name, while lower-case form is used in function names. The
+    lower-case form is calculated by converting from CamelCase to
+    lower-case and inserting underscores at word boundaries (using
+    certain heuristics).
+  </p>
+<p>
+    If the value given by the <code class="literal">org.gtk.GDBus.C.Name</code>
+    annotation or the <code class="option">--c-namespace</code> option contains
+    an underscore (sometimes called <span class="emphasis"><em>Ugly_Case</em></span>),
+    then the camel-case name is derived by removing all underscores,
+    and the lower-case name is derived by lower-casing the
+    string. This is useful in some situations where abbreviations are
+    used. For example, if the annotation is used on the interface
+    <code class="literal">net.MyCorp.MyApp.iSCSITarget</code> with the value
+    <code class="literal">iSCSI_Target</code> the CamelCase form is
+    <code class="literal">iSCSITarget</code> while the lower-case form is
+    <code class="literal">iscsi_target</code>. If the annotation is used on the
+    method <code class="literal">EjectTheiPod</code> with the value
+    <code class="literal">Eject_The_iPod</code>, the lower-case form is
+    <code class="literal">eject_the_ipod</code>.
+  </p>
+</div>
+<div class="refsect1">
+<a name="id-1.4.24.7.7"></a><h2>Generating Docbook documentation</h2>
+<p>
+    Each generated Docbook XML file (see the
+    <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>
+    article describing the D-Bus interface.
+  </p>
+</div>
+<div class="refsect1">
+<a name="id-1.4.24.7.8"></a><h2>Options</h2>
+<p>
+    The following options are supported:
+  </p>
+<div class="variablelist"><table border="0" class="variablelist">
+<colgroup>
+<col align="left" valign="top">
+<col>
+</colgroup>
+<tbody>
+<tr>
+<td><p><span class="term"><code class="option">-h</code>, <code class="option">--help</code></span></p></td>
+<td><p>
+          Show help and exit.
+        </p></td>
+</tr>
+<tr>
+<td><p><span class="term"><code class="option">--xml-files</code> <em class="replaceable"><code>FILE</code></em></span></p></td>
+<td><p>
+          The D-Bus introspection XML file.
+        </p></td>
+</tr>
+<tr>
+<td><p><span class="term"><code class="option">--interface-prefix</code> <em class="replaceable"><code>org.project.Prefix.</code></em></span></p></td>
+<td><p>
+          A prefix to strip from all D-Bus interface names when
+          calculating the typename for the C binding and the Docbook
+          <a class="ulink" href="http://www.docbook.org/tdg/en/html/primary.html" target="_top">sortas
+          attribute</a>.
+        </p></td>
+</tr>
+<tr>
+<td><p><span class="term"><code class="option">--generate-docbook</code> <em class="replaceable"><code>OUTFILES</code></em></span></p></td>
+<td><p>
+          Generate Docbook Documentation for each D-Bus interface and
+          put it in <code class="filename">OUTFILES-NAME.xml</code> where
+          <code class="literal">NAME</code> is a place-holder for the interface
+          name, e.g. <code class="literal">net.Corp.FooBar</code> and so on.
+        </p></td>
+</tr>
+<tr>
+<td><p><span class="term"><code class="option">--generate-c-code</code> <em class="replaceable"><code>OUTFILES</code></em></span></p></td>
+<td><p>
+          Generate C code for all D-Bus interfaces and put it in
+          <code class="filename">OUTFILES.c</code> and
+          <code class="filename">OUTFILES.h</code>.
+        </p></td>
+</tr>
+<tr>
+<td><p><span class="term"><code class="option">--c-namespace</code> <em class="replaceable"><code>YourProject</code></em></span></p></td>
+<td><p>
+          The namespace to use for generated C code. This is expected
+          to be in <a class="ulink" href="http://en.wikipedia.org/wiki/CamelCase" target="_top">CamelCase</a>
+          or <span class="emphasis"><em>Ugly_Case</em></span> (see above).
+        </p></td>
+</tr>
+<tr>
+<td><p><span class="term"><code class="option">--c-generate-object-manager</code></span></p></td>
+<td><p>
+          If this option is passed, suitable <a class="link" href="GDBusObject.html" title="GDBusObject"><span class="type">GDBusObject</span></a>,
+          <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
+          <a class="link" href="GDBusObjectManagerClient.html" title="GDBusObjectManagerClient"><span class="type">GDBusObjectManagerClient</span></a> subclasses are generated.
+        </p></td>
+</tr>
+<tr>
+<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>
+<td>
+<p>
+          Used to inject D-Bus annotations into the given XML
+          files. It can be used with interfaces, methods, signals,
+          properties and arguments in the following way:
+        </p>
+<div class="informalexample">
+  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
+    <tbody>
+      <tr>
+        <td class="listing_lines" align="right"><pre>1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15</pre></td>
+        <td class="listing_code"><pre class="programlisting"><span class="normal"><a href="gdbus.html">gdbus</a></span><span class="symbol">-</span><span class="normal">codegen </span><span class="symbol">--</span><span class="normal">c</span><span class="symbol">-</span><span class="usertype">namespace</span><span class="normal"> MyApp                           </span><span class="symbol">\</span>
+<span class="normal">  </span><span class="symbol">--</span><span class="normal">generate</span><span class="symbol">-</span><span class="normal">c</span><span class="symbol">-</span><span class="usertype">code</span><span class="normal"> myapp</span><span class="symbol">-</span><span class="normal">generated                         </span><span class="symbol">\</span>
+<span class="normal">  </span><span class="symbol">--</span><span class="normal">annotate </span><span class="string">"org.project.InterfaceName"</span><span class="normal">                    </span><span class="symbol">\</span>
+<span class="normal">    org</span><span class="symbol">.</span><span class="normal">gtk</span><span class="symbol">.</span><span class="normal">GDBus</span><span class="symbol">.</span><span class="normal">C</span><span class="symbol">.</span><span class="usertype">Name</span><span class="normal"> MyFrobnicator                      </span><span class="symbol">\</span>
+<span class="normal">  </span><span class="symbol">--</span><span class="normal">annotate </span><span class="string">"org.project.InterfaceName:Property"</span><span class="normal">           </span><span class="symbol">\</span>
+<span class="normal">    </span><span class="usertype">bar</span><span class="normal"> bat                                                 </span><span class="symbol">\</span>
+<span class="normal">  </span><span class="symbol">--</span><span class="normal">annotate </span><span class="string">"org.project.InterfaceName.Method()"</span><span class="normal">           </span><span class="symbol">\</span>
+<span class="normal">    org</span><span class="symbol">.</span><span class="normal">freedesktop</span><span class="symbol">.</span><span class="normal">DBus</span><span class="symbol">.</span><span class="usertype">Deprecated</span><span class="normal"> true                    </span><span class="symbol">\</span>
+<span class="normal">  </span><span class="symbol">--</span><span class="normal">annotate </span><span class="string">"org.project.InterfaceName.Method()[arg_name]"</span><span class="normal"> </span><span class="symbol">\</span>
+<span class="normal">    </span><span class="usertype">snake</span><span class="normal"> hiss                                              </span><span class="symbol">\</span>
+<span class="normal">  </span><span class="symbol">--</span><span class="normal">annotate </span><span class="string">"org.project.InterfaceName::Signal"</span><span class="normal">            </span><span class="symbol">\</span>
+<span class="normal">    </span><span class="usertype">cat</span><span class="normal"> meow                                                </span><span class="symbol">\</span>
+<span class="normal">  </span><span class="symbol">--</span><span class="normal">annotate </span><span class="string">"org.project.InterfaceName::Signal[arg_name]"</span><span class="normal">  </span><span class="symbol">\</span>
+<span class="normal">    </span><span class="usertype">dog</span><span class="normal"> wuff                                                </span><span class="symbol">\</span>
+<span class="normal">  myapp</span><span class="symbol">-</span><span class="normal">dbus</span><span class="symbol">-</span><span class="normal">interfaces</span><span class="symbol">.</span><span class="normal">xml</span></pre></td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+<p>
+          Any UTF-8 string can be used for <em class="replaceable"><code>KEY</code></em> and <em class="replaceable"><code>VALUE</code></em>.
+        </p>
+</td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<div class="refsect1">
+<a name="id-1.4.24.7.9"></a><h2>Supported D-Bus Annotations</h2>
+<p>
+    The following D-Bus annotations are supported by
+    <span class="command"><strong>gdbus-codegen</strong></span>:
+  </p>
+<div class="variablelist"><table border="0" class="variablelist">
+<colgroup>
+<col align="left" valign="top">
+<col>
+</colgroup>
+<tbody>
+<tr>
+<td><p><span class="term"><code class="literal">org.freedesktop.DBus.Deprecated</code></span></p></td>
+<td>
+<p>
+          Can be used on any <code class="literal">&lt;interface&gt;</code>,
+          <code class="literal">&lt;method&gt;</code>,
+          <code class="literal">&lt;signal&gt;</code> and
+          <code class="literal">&lt;property&gt;</code> element to specify that
+          the element is deprecated if its value is
+          <code class="literal">true</code>. Note that this annotation is
+          defined in the <a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format" target="_top">D-Bus
+          specification</a> and can only assume the values
+          <code class="literal">true</code> and <code class="literal">false</code>. In
+          particular, you cannot specify the version that the element
+          was deprecated in nor any helpful deprecation message. Such
+          information should be added to the element documentation
+          instead.
+        </p>
+<p>
+          When generating C code, this annotation is used to add
+          <a href="../glib/glib-Miscellaneous-Macros.html#G-GNUC-DEPRECATED:CAPS"><span class="type">G_GNUC_DEPRECATED</span></a> to generated functions for the element.
+        </p>
+<p>
+          When generating Docbook XML, a deprecation warning will
+          appear along the documentation for the element.
+        </p>
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><code class="literal">org.gtk.GDBus.Since</code></span></p></td>
+<td>
+<p>
+          Can be used on any <code class="literal">&lt;interface&gt;</code>,
+          <code class="literal">&lt;method&gt;</code>,
+          <code class="literal">&lt;signal&gt;</code> and
+          <code class="literal">&lt;property&gt;</code> element to specify the
+          version (any free-form string but compared using a
+          version-aware sort function) the element appeared in.
+        </p>
+<p>
+          When generating C code, this field is used to ensure
+          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>.
+        </p>
+<p>
+          When generating Docbook XML, the value of this tag appears
+          in the documentation.
+        </p>
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><code class="literal">org.gtk.GDBus.DocString</code></span></p></td>
+<td><p>
+          A string with Docbook content for documentation. This annotation can
+          be used on <code class="literal">&lt;interface&gt;</code>,
+          <code class="literal">&lt;method&gt;</code>,
+          <code class="literal">&lt;signal&gt;</code>,
+          <code class="literal">&lt;property&gt;</code> and
+          <code class="literal">&lt;arg&gt;</code> elements.
+        </p></td>
+</tr>
+<tr>
+<td><p><span class="term"><code class="literal">org.gtk.GDBus.DocString.Short</code></span></p></td>
+<td><p>
+          A string with Docbook content for short/brief
+          documentation. This annotation can only be used on
+          <code class="literal">&lt;interface&gt;</code> elements.
+        </p></td>
+</tr>
+<tr>
+<td><p><span class="term"><code class="literal">org.gtk.GDBus.C.Name</code></span></p></td>
+<td><p>
+          Can be used on any <code class="literal">&lt;interface&gt;</code>,
+          <code class="literal">&lt;method&gt;</code>,
+          <code class="literal">&lt;signal&gt;</code> and
+          <code class="literal">&lt;property&gt;</code> element to specify the
+          name to use when generating C code. The value is expected to
+          be in <a class="ulink" href="http://en.wikipedia.org/wiki/CamelCase" target="_top">CamelCase</a>
+          or <span class="emphasis"><em>Ugly_Case</em></span> (see above).
+        </p></td>
+</tr>
+<tr>
+<td><p><span class="term"><code class="literal">org.gtk.GDBus.C.ForceGVariant</code></span></p></td>
+<td><p>
+          If set to a non-empty string, a <a href="../glib/glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> instance will
+          be used instead of the natural C type. This annotation can
+          be used on any <code class="literal">&lt;arg&gt;</code> and
+          <code class="literal">&lt;property&gt;</code> element.
+        </p></td>
+</tr>
+<tr>
+<td><p><span class="term"><code class="literal">org.gtk.GDBus.C.UnixFD</code></span></p></td>
+<td><p>
+          If set to a non-empty string, the generated code will
+          include parameters to exchange file descriptors using the
+          <a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a> type. This annotation can be used on
+          <code class="literal">&lt;method&gt;</code> elements.
+        </p></td>
+</tr>
+</tbody>
+</table></div>
+<p>
+    As an easier alternative to using the
+    <code class="literal">org.gtk.GDBus.DocString</code> annotation, note that
+    parser used by <span class="command"><strong>gdbus-codegen</strong></span> parses XML
+    comments in a way similar to <a class="ulink" href="http://www.gtk.org/gtk-doc/" target="_top">gtk-doc</a>:
+</p>
+<div class="informalexample">
+  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
+    <tbody>
+      <tr>
+        <td class="listing_lines" align="right"><pre>1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
+33
+34
+35
+36
+37</pre></td>
+        <td class="listing_code"><pre class="programlisting"><span class="symbol">&lt;!--</span>
+<span class="normal">  net</span><span class="symbol">.</span><span class="normal">Corp</span><span class="symbol">.</span><span class="normal">Bar</span><span class="symbol">:</span>
+<span class="normal">  @short_description</span><span class="symbol">:</span><span class="normal"> A </span><span class="type">short</span><span class="normal"> description</span>
+<span class="normal">  A </span><span class="symbol">&lt;</span><span class="normal">emphasis</span><span class="symbol">&gt;</span><span class="usertype">longer&lt;/emphasis&gt;</span><span class="normal"> description</span><span class="symbol">.</span>
+<span class="normal">  This is a </span><span class="usertype">new</span><span class="normal"> paragraph</span><span class="symbol">.</span>
+<span class="symbol">--&gt;</span>
+<span class="symbol">&lt;</span><span class="usertype">interface</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"net.corp.Bar"</span><span class="symbol">&gt;</span>
+<span class="normal">  </span><span class="symbol">&lt;!--</span>
+<span class="label">    FooMethod:</span>
+<span class="normal">    @greeting</span><span class="symbol">:</span><span class="normal"> The docs </span><span class="keyword">for</span><span class="normal"> </span><span class="usertype">greeting</span><span class="normal"> parameter</span><span class="symbol">.</span>
+<span class="normal">    @response</span><span class="symbol">:</span><span class="normal"> The docs </span><span class="keyword">for</span><span class="normal"> </span><span class="usertype">response</span><span class="normal"> parameter</span><span class="symbol">.</span>
+<span class="normal">    The docs </span><span class="keyword">for</span><span class="normal"> the </span><span class="usertype">actual</span><span class="normal"> method</span><span class="symbol">.</span>
+<span class="normal">  </span><span class="symbol">--&gt;</span>
+<span class="normal">  </span><span class="symbol">&lt;</span><span class="usertype">method</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"FooMethod"</span><span class="symbol">&gt;</span>
+<span class="normal">    </span><span class="symbol">&lt;</span><span class="usertype">arg</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"greeting"</span><span class="normal"> direction</span><span class="symbol">=</span><span class="string">"in"</span><span class="normal"> type</span><span class="symbol">=</span><span class="string">"s"</span><span class="symbol">/&gt;</span>
+<span class="normal">    </span><span class="symbol">&lt;</span><span class="usertype">arg</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"response"</span><span class="normal"> direction</span><span class="symbol">=</span><span class="string">"out"</span><span class="normal"> type</span><span class="symbol">=</span><span class="string">"s"</span><span class="symbol">/&gt;</span>
+<span class="normal">  </span><span class="symbol">&lt;/</span><span class="normal">method</span><span class="symbol">&gt;</span>
+<span class="normal">  </span><span class="symbol">&lt;!--</span>
+<span class="label">    BarSignal:</span>
+<span class="normal">    @blah</span><span class="symbol">:</span><span class="normal"> The docs </span><span class="keyword">for</span><span class="normal"> </span><span class="usertype">blah</span><span class="normal"> parameter</span><span class="symbol">.</span>
+<span class="normal">    @boo</span><span class="symbol">:</span><span class="normal"> The docs </span><span class="keyword">for</span><span class="normal"> </span><span class="usertype">boo</span><span class="normal"> parameter</span><span class="symbol">.</span>
+<span class="normal">    @since</span><span class="symbol">:</span><span class="normal"> </span><span class="number">2.30</span>
+<span class="normal">    The docs </span><span class="keyword">for</span><span class="normal"> the </span><span class="usertype">actual</span><span class="normal"> signal</span><span class="symbol">.</span>
+<span class="normal">  </span><span class="symbol">--&gt;</span>
+<span class="normal">  </span><span class="symbol">&lt;</span><span class="usertype">signal</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"BarSignal"</span><span class="symbol">&gt;</span>
+<span class="normal">    </span><span class="symbol">&lt;</span><span class="usertype">arg</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"blah"</span><span class="normal"> type</span><span class="symbol">=</span><span class="string">"s"</span><span class="symbol">/&gt;</span>
+<span class="normal">    </span><span class="symbol">&lt;</span><span class="usertype">arg</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"boo"</span><span class="normal"> type</span><span class="symbol">=</span><span class="string">"s"</span><span class="symbol">/&gt;</span>
+<span class="normal">  </span><span class="symbol">&lt;/</span><span class="normal">signal</span><span class="symbol">&gt;</span>
+<span class="normal">  </span><span class="symbol">&lt;!--</span><span class="normal"> BazProperty</span><span class="symbol">:</span><span class="normal"> The docs </span><span class="keyword">for</span><span class="normal"> </span><span class="usertype">the</span><span class="normal"> property</span><span class="symbol">.</span><span class="normal"> </span><span class="symbol">--&gt;</span>
+<span class="normal">  </span><span class="symbol">&lt;</span><span class="usertype">property</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"BazProperty"</span><span class="normal"> type</span><span class="symbol">=</span><span class="string">"s"</span><span class="normal"> access</span><span class="symbol">=</span><span class="string">"read"</span><span class="symbol">/&gt;</span>
+<span class="symbol">&lt;/</span><span class="normal">interface</span><span class="symbol">&gt;</span></pre></td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+<p>
+  </p>
+<p>
+    Note that <code class="literal">@since</code> can be used in any inline
+    documentation bit (e.g. for interfaces, methods, signals and
+    properties) to set the <code class="literal">org.gtk.GDBus.Since</code>
+    annotation. For the <code class="literal">org.gtk.GDBus.DocString</code>
+    annotation (and inline comments), note that substrings of the form
+    <code class="literal">#net.Corp.Bar</code>,
+    <code class="literal">net.Corp.Bar.FooMethod()</code>,
+    <code class="literal">#net.Corp.Bar::BarSignal</code> and
+    <code class="literal">#net.Corp.InlineDocs:BazProperty</code> are all
+    expanded to links to the respective interface, method, signal and
+    property.
+    Additionally, substrings starting with <code class="literal">@</code> and <code class="literal">%</code> characters are rendered as
+    <a class="ulink" href="http://www.docbook.org/tdg/en/html/parameter.html" target="_top">parameter</a> and
+    <a class="ulink" href="http://www.docbook.org/tdg/en/html/constant.html" target="_top">constant</a> respectively.
+  </p>
+<p>
+    If both XML comments and
+    <code class="literal">org.gtk.GDBus.DocString</code> or
+    <code class="literal">org.gtk.GDBus.DocString.Short</code> annotations are
+    present, the latter wins.
+  </p>
+</div>
+<div class="refsect1">
+<a name="id-1.4.24.7.10"></a><h2>Example</h2>
+<p>
+    Consider the following D-Bus Introspection XML.
+  </p>
+<div class="informalexample">
+  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
+    <tbody>
+      <tr>
+        <td class="listing_lines" align="right"><pre>1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+16</pre></td>
+        <td class="listing_code"><pre class="programlisting"><span class="symbol">&lt;</span><span class="normal">node</span><span class="symbol">&gt;</span>
+<span class="normal">  </span><span class="symbol">&lt;</span><span class="usertype">interface</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"net.Corp.MyApp.Frobber"</span><span class="symbol">&gt;</span>
+<span class="normal">    </span><span class="symbol">&lt;</span><span class="usertype">method</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"HelloWorld"</span><span class="symbol">&gt;</span>
+<span class="normal">      </span><span class="symbol">&lt;</span><span class="usertype">arg</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"greeting"</span><span class="normal"> direction</span><span class="symbol">=</span><span class="string">"in"</span><span class="normal"> type</span><span class="symbol">=</span><span class="string">"s"</span><span class="symbol">/&gt;</span>
+<span class="normal">      </span><span class="symbol">&lt;</span><span class="usertype">arg</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"response"</span><span class="normal"> direction</span><span class="symbol">=</span><span class="string">"out"</span><span class="normal"> type</span><span class="symbol">=</span><span class="string">"s"</span><span class="symbol">/&gt;</span>
+<span class="normal">    </span><span class="symbol">&lt;/</span><span class="normal">method</span><span class="symbol">&gt;</span>
+<span class="normal">    </span><span class="symbol">&lt;</span><span class="usertype">signal</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"Notification"</span><span class="symbol">&gt;</span>
+<span class="normal">      </span><span class="symbol">&lt;</span><span class="usertype">arg</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"icon_blob"</span><span class="normal"> type</span><span class="symbol">=</span><span class="string">"ay"</span><span class="symbol">/&gt;</span>
+<span class="normal">      </span><span class="symbol">&lt;</span><span class="usertype">arg</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"height"</span><span class="normal"> type</span><span class="symbol">=</span><span class="string">"i"</span><span class="symbol">/&gt;</span>
+<span class="normal">      </span><span class="symbol">&lt;</span><span class="usertype">arg</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"messages"</span><span class="normal"> type</span><span class="symbol">=</span><span class="string">"as"</span><span class="symbol">/&gt;</span>
+<span class="normal">    </span><span class="symbol">&lt;/</span><span class="normal">signal</span><span class="symbol">&gt;</span>
+<span class="normal">    </span><span class="symbol">&lt;</span><span class="usertype">property</span><span class="normal"> name</span><span class="symbol">=</span><span class="string">"Verbose"</span><span class="normal"> type</span><span class="symbol">=</span><span class="string">"b"</span><span class="normal"> access</span><span class="symbol">=</span><span class="string">"readwrite"</span><span class="symbol">/&gt;</span>
+<span class="normal">  </span><span class="symbol">&lt;/</span><span class="normal">interface</span><span class="symbol">&gt;</span>
+<span class="symbol">&lt;/</span><span class="normal">node</span><span class="symbol">&gt;</span></pre></td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+<p>
+    If <span class="command"><strong>gdbus-codegen</strong></span> is used on this file like this:
+  </p>
+<div class="informalexample">
+  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
+    <tbody>
+      <tr>
+        <td class="listing_lines" align="right"><pre>1
+2
+3
+4</pre></td>
+        <td class="listing_code"><pre class="programlisting"><span class="normal"><a href="gdbus.html">gdbus</a></span><span class="symbol">-</span><span class="normal">codegen </span><span class="symbol">--</span><span class="normal">generate</span><span class="symbol">-</span><span class="normal">c</span><span class="symbol">-</span><span class="usertype">code</span><span class="normal"> myapp</span><span class="symbol">-</span><span class="normal">generated       </span><span class="symbol">\</span>
+<span class="normal">              </span><span class="symbol">--</span><span class="normal">c</span><span class="symbol">-</span><span class="usertype">namespace</span><span class="normal"> MyApp                     </span><span class="symbol">\</span>
+<span class="normal">              </span><span class="symbol">--</span><span class="normal">interface</span><span class="symbol">-</span><span class="usertype">prefix</span><span class="normal"> net</span><span class="symbol">.</span><span class="normal">corp</span><span class="symbol">.</span><span class="normal">MyApp</span><span class="symbol">.</span><span class="normal">      </span><span class="symbol">\</span>
+<span class="normal">              net</span><span class="symbol">.</span><span class="normal">Corp</span><span class="symbol">.</span><span class="normal">MyApp</span><span class="symbol">.</span><span class="normal">Frobber</span><span class="symbol">.</span><span class="normal">xml</span></pre></td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+<p>
+    two files called
+    <code class="filename">myapp-generated.[ch]</code> are
+    generated. The files provide an abstract
+    <a href="../gobject/gobject-Type-Information.html#GTypeInterface"><span class="type">GTypeInterface</span></a>-derived type called
+    <span class="type">MyAppFrobber</span> as well as two instantiable types with
+    the same name but suffixed with <span class="type">Proxy</span> and
+    <span class="type">Skeleton</span>. The generated file, roughly, contains the
+    following facilities:
+  </p>
+<div class="informalexample">
+  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
+    <tbody>
+      <tr>
+        <td class="listing_lines" align="right"><pre>1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
+33
+34
+35
+36
+37
+38
+39
+40
+41
+42
+43
+44
+45
+46
+47
+48
+49
+50
+51
+52
+53
+54
+55
+56
+57
+58
+59
+60
+61
+62
+63
+64
+65
+66
+67
+68
+69
+70
+71
+72
+73
+74
+75
+76
+77
+78
+79
+80
+81
+82
+83
+84
+85
+86
+87
+88
+89
+90
+91
+92
+93
+94
+95
+96
+97</pre></td>
+        <td class="listing_code"><pre class="programlisting"><span class="comment">/* GType macros for the three generated types */</span>
+<span class="preproc">#define</span><span class="normal"> </span><span class="function">MY_APP_TYPE_FROBBER</span><span class="normal"> </span><span class="symbol">(</span><span class="function">my_app_frobber_get_type</span><span class="normal"> </span><span class="symbol">())</span>
+<span class="preproc">#define</span><span class="normal"> </span><span class="function">MY_APP_TYPE_FROBBER_SKELETON</span><span class="normal"> </span><span class="symbol">(</span><span class="function">my_app_frobber_skeleton_get_type</span><span class="normal"> </span><span class="symbol">())</span>
+<span class="preproc">#define</span><span class="normal"> </span><span class="function">MY_APP_TYPE_FROBBER_PROXY</span><span class="normal"> </span><span class="symbol">(</span><span class="function">my_app_frobber_proxy_get_type</span><span class="normal"> </span><span class="symbol">())</span>
+<span class="keyword">typedef</span><span class="normal"> </span><span class="keyword">struct</span><span class="normal"> </span><span class="classname">_MyAppFrobber</span><span class="normal"> MyAppFrobber</span><span class="symbol">;</span><span class="normal"> </span><span class="comment">/* Dummy typedef */</span>
+<span class="keyword">typedef</span><span class="normal"> </span><span class="keyword">struct</span>
+<span class="cbracket">{</span>
+<span class="normal">  </span><span class="usertype">GTypeInterface</span><span class="normal"> parent_iface</span><span class="symbol">;</span>
+<span class="normal">  </span><span class="comment">/* Signal handler for the ::notification signal */</span>
+<span class="normal">  </span><span class="type">void</span><span class="normal"> </span><span class="symbol">(*</span><span class="normal">notification</span><span class="symbol">)</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MyAppFrobber</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">proxy</span><span class="symbol">,</span>
+<span class="normal">                        </span><span class="usertype">GVariant</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">icon_blob</span><span class="symbol">,</span>
+<span class="normal">                        </span><span class="usertype">gint</span><span class="normal"> height</span><span class="symbol">,</span>
+<span class="normal">                        </span><span class="keyword">const</span><span class="normal"> <a href="../glib/glib-Basic-Types.html#gchar">gchar</a></span><span class="symbol">*</span><span class="normal"> </span><span class="keyword">const</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">messages</span><span class="symbol">);</span>
+<span class="normal">  </span><span class="comment">/* Signal handler for the ::handle-hello-world signal */</span>
+<span class="normal">  </span><span class="function"><a href="../glib/glib-Basic-Types.html#gboolean">gboolean</a></span><span class="normal"> </span><span class="symbol">(*</span><span class="normal">handle_hello_world</span><span class="symbol">)</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MyAppFrobber</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">proxy</span><span class="symbol">,</span>
+<span class="normal">                                  </span><span class="usertype">GDBusMethodInvocation</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">invocation</span><span class="symbol">,</span>
+<span class="normal">                                  </span><span class="keyword">const</span><span class="normal"> </span><span class="usertype">gchar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">greeting</span><span class="symbol">);</span>
+<span class="cbracket">}</span><span class="normal"> MyAppFrobberIface</span><span class="symbol">;</span>
+<span class="comment">/* Asynchronously calls HelloWorld() */</span>
+<span class="type">void</span>
+<span class="function">my_app_frobber_call_hello_world</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MyAppFrobber</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">proxy</span><span class="symbol">,</span>
+<span class="normal">                                 </span><span class="keyword">const</span><span class="normal"> </span><span class="usertype">gchar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">greeting</span><span class="symbol">,</span>
+<span class="normal">                                 </span><span class="usertype">GCancellable</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cancellable</span><span class="symbol">,</span>
+<span class="normal">                                 </span><span class="usertype">GAsyncReadyCallback</span><span class="normal"> callback</span><span class="symbol">,</span>
+<span class="normal">                                 </span><span class="usertype">gpointer</span><span class="normal"> user_data</span><span class="symbol">);</span>
+<span class="normal"><a href="../glib/glib-Basic-Types.html#gboolean">gboolean</a></span>
+<span class="function">my_app_frobber_call_hello_world_finish</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MyAppFrobber</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">proxy</span><span class="symbol">,</span>
+<span class="normal">                                        </span><span class="usertype">gchar</span><span class="normal"> </span><span class="symbol">**</span><span class="normal">out_response</span><span class="symbol">,</span>
+<span class="normal">                                        </span><span class="usertype">GAsyncResult</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">res</span><span class="symbol">,</span>
+<span class="normal">                                        </span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">**</span><span class="normal">error</span><span class="symbol">);</span>
+<span class="comment">/* Synchronously calls HelloWorld(). Blocks calling thread. */</span>
+<span class="normal"><a href="../glib/glib-Basic-Types.html#gboolean">gboolean</a></span>
+<span class="function">my_app_frobber_call_hello_world_sync</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MyAppFrobber</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">proxy</span><span class="symbol">,</span>
+<span class="normal">                                      </span><span class="keyword">const</span><span class="normal"> </span><span class="usertype">gchar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">greeting</span><span class="symbol">,</span>
+<span class="normal">                                      </span><span class="usertype">gchar</span><span class="normal"> </span><span class="symbol">**</span><span class="normal">out_response</span><span class="symbol">,</span>
+<span class="normal">                                      </span><span class="usertype">GCancellable</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cancellable</span><span class="symbol">,</span>
+<span class="normal">                                      </span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">**</span><span class="normal">error</span><span class="symbol">);</span>
+<span class="comment">/* Completes handling the HelloWorld() method call */</span>
+<span class="type">void</span>
+<span class="function">my_app_frobber_complete_hello_world</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MyAppFrobber</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">object</span><span class="symbol">,</span>
+<span class="normal">                                     </span><span class="usertype">GDBusMethodInvocation</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">invocation</span><span class="symbol">,</span>
+<span class="normal">                                     </span><span class="keyword">const</span><span class="normal"> </span><span class="usertype">gchar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">response</span><span class="symbol">);</span>
+<span class="comment">/* Emits the ::notification signal / Notification() D-Bus signal */</span>
+<span class="type">void</span>
+<span class="function">my_app_frobber_emit_notification</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MyAppFrobber</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">object</span><span class="symbol">,</span>
+<span class="normal">                                  </span><span class="usertype">GVariant</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">icon_blob</span><span class="symbol">,</span>
+<span class="normal">                                  </span><span class="usertype">gint</span><span class="normal"> height</span><span class="symbol">,</span>
+<span class="normal">                                  </span><span class="keyword">const</span><span class="normal"> <a href="../glib/glib-Basic-Types.html#gchar">gchar</a></span><span class="symbol">*</span><span class="normal"> </span><span class="keyword">const</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">messages</span><span class="symbol">);</span>
+<span class="comment">/* Gets the :verbose GObject property / Verbose D-Bus property.</span>
+<span class="comment"> * Does no blocking I/O.</span>
+<span class="comment"> */</span>
+<span class="usertype">gboolean</span><span class="normal"> </span><span class="function">my_app_frobber_get_verbose</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MyAppFrobber</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">object</span><span class="symbol">);</span>
+<span class="comment">/* Sets the :verbose GObject property / Verbose D-Bus property.</span>
+<span class="comment"> * Does no blocking I/O.</span>
+<span class="comment"> */</span>
+<span class="type">void</span><span class="normal"> </span><span class="function">my_app_frobber_set_verbose</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MyAppFrobber</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">object</span><span class="symbol">,</span>
+<span class="normal">                                 </span><span class="usertype">gboolean</span><span class="normal">      value</span><span class="symbol">);</span>
+<span class="comment">/* Gets the interface info */</span>
+<span class="usertype">GDBusInterfaceInfo</span><span class="normal"> </span><span class="symbol">*</span><span class="function">my_app_frobber_interface_info</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">);</span>
+<span class="comment">/* Creates a new skeleton object, ready to be exported */</span>
+<span class="usertype">MyAppFrobber</span><span class="normal"> </span><span class="symbol">*</span><span class="function">my_app_frobber_skeleton_new</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">);</span>
+<span class="comment">/* Client-side proxy constructors.</span>
+<span class="comment"> *</span>
+<span class="comment"> * Additionally, _new_for_bus(), _new_for_bus_finish() and</span>
+<span class="comment"> * _new_for_bus_sync() proxy constructors are also generated.</span>
+<span class="comment"> */</span>
+<span class="type">void</span>
+<span class="function">my_app_frobber_proxy_new</span><span class="normal">        </span><span class="symbol">(</span><span class="usertype">GDBusConnection</span><span class="normal">     </span><span class="symbol">*</span><span class="normal">connection</span><span class="symbol">,</span>
+<span class="normal">                                 </span><span class="usertype">GDBusProxyFlags</span><span class="normal">      flags</span><span class="symbol">,</span>
+<span class="normal">                                 </span><span class="keyword">const</span><span class="normal"> </span><span class="usertype">gchar</span><span class="normal">         </span><span class="symbol">*</span><span class="normal">name</span><span class="symbol">,</span>
+<span class="normal">                                 </span><span class="keyword">const</span><span class="normal"> </span><span class="usertype">gchar</span><span class="normal">         </span><span class="symbol">*</span><span class="normal">object_path</span><span class="symbol">,</span>
+<span class="normal">                                 </span><span class="usertype">GCancellable</span><span class="normal">        </span><span class="symbol">*</span><span class="normal">cancellable</span><span class="symbol">,</span>
+<span class="normal">                                 </span><span class="usertype">GAsyncReadyCallback</span><span class="normal">  callback</span><span class="symbol">,</span>
+<span class="normal">                                 </span><span class="usertype">gpointer</span><span class="normal">             user_data</span><span class="symbol">);</span>
+<span class="normal">MyAppFrobber </span><span class="symbol">*</span>
+<span class="function">my_app_frobber_proxy_new_finish</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GAsyncResult</span><span class="normal">        </span><span class="symbol">*</span><span class="normal">res</span><span class="symbol">,</span>
+<span class="normal">                                 </span><span class="usertype">GError</span><span class="normal">             </span><span class="symbol">**</span><span class="normal">error</span><span class="symbol">);</span>
+<span class="normal">MyAppFrobber </span><span class="symbol">*</span>
+<span class="function">my_app_frobber_proxy_new_sync</span><span class="normal">   </span><span class="symbol">(</span><span class="usertype">GDBusConnection</span><span class="normal">     </span><span class="symbol">*</span><span class="normal">connection</span><span class="symbol">,</span>
+<span class="normal">                                 </span><span class="usertype">GDBusProxyFlags</span><span class="normal">      flags</span><span class="symbol">,</span>
+<span class="normal">                                 </span><span class="keyword">const</span><span class="normal"> </span><span class="usertype">gchar</span><span class="normal">         </span><span class="symbol">*</span><span class="normal">name</span><span class="symbol">,</span>
+<span class="normal">                                 </span><span class="keyword">const</span><span class="normal"> </span><span class="usertype">gchar</span><span class="normal">         </span><span class="symbol">*</span><span class="normal">object_path</span><span class="symbol">,</span>
+<span class="normal">                                 </span><span class="usertype">GCancellable</span><span class="normal">        </span><span class="symbol">*</span><span class="normal">cancellable</span><span class="symbol">,</span>
+<span class="normal">                                 </span><span class="usertype">GError</span><span class="normal">             </span><span class="symbol">**</span><span class="normal">error</span><span class="symbol">);</span></pre></td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+<p>
+    Thus, for every D-Bus method, there will be three C functions for
+    calling the method, one <a href="../gobject/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> signal for handling an incoming
+    call and one C function for completing an incoming call. For every
+    D-Bus signal, there's one <a href="../gobject/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> signal and one C function for
+    emitting it. For every D-Bus property, two C functions are
+    generated (one setter, one getter) and one <a href="../gobject/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> property. The
+    following table summarizes the generated facilities and where they
+    are applicable:
+  </p>
+<div class="informaltable"><table border="1">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th> </th>
+<th>Client</th>
+<th>Server</th>
+</tr></thead>
+<tbody>
+<tr>
+<td>Types</td>
+<td>Use <span class="type">MyAppFrobberProxy</span>
+</td>
+<td>Any type implementing the <span class="type">MyAppFrobber</span> interface</td>
+</tr>
+<tr>
+<td>Methods</td>
+<td>Use <code class="function"><code class="function">m_a_f_hello_world()</code></code> to call.</td>
+<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>
+</td>
+</tr>
+<tr>
+<td>Signals</td>
+<td>Connect to the <code class="function">::notification</code> GObject signal.</td>
+<td>Use <code class="function"><code class="function">m_a_f_emit_notification()</code></code> to emit signal.</td>
+</tr>
+<tr>
+<td>Properties (Reading)</td>
+<td>Use <code class="function"><code class="function">m_a_f_get_verbose()</code></code> or <em class="parameter"><code>:verbose</code></em>.</td>
+<td>Implement <a href="../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>
+</tr>
+<tr>
+<td>Properties (writing)</td>
+<td>Use <code class="function"><code class="function">m_a_f_set_verbose()</code></code> or <em class="parameter"><code>:verbose</code></em>.</td>
+<td>Implement <a href="../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>
+</tr>
+</tbody>
+</table></div>
+<div class="refsect2">
+<a name="id-1.4.24.7.10.10"></a><h3>Client-side usage</h3>
+<p>
+      You can use the generated proxy type with the generated
+      constructors:
+    </p>
+<div class="informalexample">
+  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
+    <tbody>
+      <tr>
+        <td class="listing_lines" align="right"><pre>1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13</pre></td>
+        <td class="listing_code"><pre class="programlisting"><span class="usertype">MyAppFrobber</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">proxy</span><span class="symbol">;</span>
+<span class="usertype">GError</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">error</span><span class="symbol">;</span>
+<span class="normal">error </span><span class="symbol">=</span><span class="normal"> <a href="../glib/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span>
+<span class="normal">proxy </span><span class="symbol">=</span><span class="normal"> </span><span class="function">my_app_frobber_proxy_new_for_bus_sync</span><span class="normal"> </span><span class="symbol">(</span>
+<span class="normal">            G_BUS_TYPE_SESSION</span><span class="symbol">,</span>
+<span class="normal">            G_DBUS_PROXY_FLAGS_NONE</span><span class="symbol">,</span>
+<span class="normal">            </span><span class="string">"net.Corp.MyApp"</span><span class="symbol">,</span><span class="normal">              </span><span class="comment">/* bus name */</span>
+<span class="normal">            </span><span class="string">"/net/Corp/MyApp/SomeFrobber"</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* object */</span>
+<span class="normal">            <a href="../glib/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">,</span><span class="normal">                          </span><span class="comment">/* GCancellable* */</span>
+<span class="normal">            </span><span class="symbol">&amp;</span><span class="normal">error</span><span class="symbol">);</span>
+<span class="comment">/* do stuff with proxy */</span>
+<span class="function"><a href="../gobject/gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">proxy</span><span class="symbol">);</span></pre></td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+<p>
+      Instead of using the generic <a class="link" href="GDBusProxy.html" title="GDBusProxy"><span class="type">GDBusProxy</span></a> facilities, one can use
+      the generated methods such as
+      <code class="function"><code class="function">my_app_frobber_call_hello_world()</code></code> to invoke
+      the <code class="function">net.Corp.MyApp.Frobber.HelloWorld()</code>
+      D-Bus method, connect to the the
+      <code class="function">::notification</code> GObject signal to receive
+      the <code class="function">net.Corp.MyApp.Frobber::Notication</code>
+      D-Bus signal and get/set the
+      <em class="parameter"><code>net.Corp.MyApp.Frobber:Verbose</code></em> D-Bus
+      Property using either the GObject property
+      <em class="parameter"><code>:verbose</code></em> or the
+      <code class="function"><code class="function">my_app_get_verbose()</code></code> and
+      <code class="function"><code class="function">my_app_set_verbose()</code></code> methods. Use the
+      standard <a href="../gobject/gobject-The-Base-Object-Type.html#GObject-notify"><span class="type">“notify”</span></a> signal to listen to property changes.
+    </p>
+<p>
+      Note that all property access is via <a class="link" href="GDBusProxy.html" title="GDBusProxy"><span class="type">GDBusProxy</span></a>'s
+      property cache so no I/O is ever done when reading properties.
+      Also note that setting a property will cause the
+      <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
+      called on the remote object. This call, however, is asynchronous
+      so setting a property won't block. Further, the change is
+      delayed and no error checking is possible.
+    </p>
+</div>
+<hr>
+<div class="refsect2">
+<a name="id-1.4.24.7.10.11"></a><h3>Server-side usage</h3>
+<p>
+      The generated <span class="type">MyAppFrobber</span> interface is designed so
+      it is easy to implement it in a <a href="../gobject/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a>
+      subclass. For example, to handle
+      <code class="function"><code class="function">HelloWorld()</code></code> method invocations, set the
+      vfunc for <code class="function"><code class="function">handle_hello_hello_world()</code></code> in the
+      <span class="type">MyAppFrobberIface</span> structure. Similary, to handle
+      the <em class="parameter"><code>net.Corp.MyApp.Frobber:Verbose</code></em>
+      property override the <em class="parameter"><code>:verbose</code></em> <a href="../gobject/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a>
+      property from the subclass. To emit a signal, use
+      e.g. <code class="function"><code class="function">my_app_emit_signal()</code></code> or
+      <a href="../gobject/gobject-Signals.html#g-signal-emit-by-name"><code class="function">g_signal_emit_by_name()</code></a>.
+    </p>
+<p>
+      Instead of subclassing, it is often easier to use the generated
+      <span class="type">MyAppFrobberSkeleton</span> subclass. To handle incoming
+      method calls, use <code class="function"><a href="../gobject/gobject-Signals.html#g-signal-connect"><code class="function">g_signal_connect()</code></a></code> with
+      the <code class="function">::handle-*</code> signals and instead of
+      overriding <a href="../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> and
+      <code class="function"><code class="function">set_property()</code></code> vfuncs, use
+      <a href="../gobject/gobject-The-Base-Object-Type.html#g-object-get"><code class="function">g_object_get()</code></a> and
+      <a href="../gobject/gobject-The-Base-Object-Type.html#g-object-set"><code class="function">g_object_set()</code></a> or the generated property
+      getters and setters (the generated class has an internal
+      property bag implementation).
+    </p>
+<div class="informalexample">
+  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
+    <tbody>
+      <tr>
+        <td class="listing_lines" align="right"><pre>1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
+33
+34
+35
+36
+37
+38
+39
+40
+41
+42
+43
+44</pre></td>
+        <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> <a href="../glib/glib-Basic-Types.html#gboolean">gboolean</a></span>
+<span class="function">on_handle_hello_world</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MyAppFrobber</span><span class="normal">           </span><span class="symbol">*</span><span class="normal">interface</span><span class="symbol">,</span>
+<span class="normal">                       </span><span class="usertype">GDBusMethodInvocation</span><span class="normal">  </span><span class="symbol">*</span><span class="normal">invocation</span><span class="symbol">,</span>
+<span class="normal">                       </span><span class="keyword">const</span><span class="normal"> </span><span class="usertype">gchar</span><span class="normal">            </span><span class="symbol">*</span><span class="normal">greeting</span><span class="symbol">,</span>
+<span class="normal">                       </span><span class="usertype">gpointer</span><span class="normal">                user_data</span><span class="symbol">)</span>
+<span class="cbracket">{</span>
+<span class="normal">  </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="../glib/glib-String-Utility-Functions.html#g-strcmp0">g_strcmp0</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">greeting</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"Boo"</span><span class="symbol">)</span><span class="normal"> </span><span class="symbol">!=</span><span class="normal"> </span><span class="number">0</span><span class="symbol">)</span>
+<span class="normal">    </span><span class="cbracket">{</span>
+<span class="normal">      </span><span class="usertype">gchar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">response</span><span class="symbol">;</span>
+<span class="normal">      response </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="../glib/glib-String-Utility-Functions.html#g-strdup-printf">g_strdup_printf</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"Word! You said `%s'."</span><span class="symbol">,</span><span class="normal"> greeting</span><span class="symbol">);</span>
+<span class="normal">      </span><span class="function">my_app_complete_hello_world</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">interface</span><span class="symbol">,</span><span class="normal"> invocation</span><span class="symbol">,</span><span class="normal"> response</span><span class="symbol">);</span>
+<span class="normal">      </span><span class="function"><a href="../glib/glib-Memory-Allocation.html#g-free">g_free</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">response</span><span class="symbol">);</span>
+<span class="normal">    </span><span class="cbracket">}</span>
+<span class="normal">  </span><span class="keyword">else</span>
+<span class="normal">    </span><span class="cbracket">{</span>
+<span class="normal">      </span><span class="function"><a href="GDBusMethodInvocation.html#g-dbus-method-invocation-return-error">g_dbus_method_invocation_return_error</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">invocation</span><span class="symbol">,</span>
+<span class="normal">                 MY_APP_ERROR</span><span class="symbol">,</span>
+<span class="normal">                 MY_APP_ERROR_NO_WHINING</span><span class="symbol">,</span>
+<span class="normal">                 </span><span class="string">"Hey, %s, there will be no whining!"</span><span class="symbol">,</span>
+<span class="normal">                 </span><span class="function"><a href="GDBusMethodInvocation.html#g-dbus-method-invocation-get-sender">g_dbus_method_invocation_get_sender</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">invocation</span><span class="symbol">));</span>
+<span class="normal">    </span><span class="cbracket">}</span>
+<span class="normal">  </span><span class="keyword">return</span><span class="normal"> <a href="../glib/glib-Standard-Macros.html#TRUE:CAPS">TRUE</a></span><span class="symbol">;</span>
+<span class="cbracket">}</span>
+<span class="normal">  </span><span class="symbol">[...]</span>
+<span class="normal">  interface </span><span class="symbol">=</span><span class="normal"> </span><span class="function">my_app_frobber_skeleton_new</span><span class="normal"> </span><span class="symbol">();</span>
+<span class="normal">  </span><span class="function">my_app_frobber_set_verbose</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">interface</span><span class="symbol">,</span><span class="normal"> <a href="../glib/glib-Standard-Macros.html#TRUE:CAPS">TRUE</a></span><span class="symbol">);</span>
+<span class="normal">  </span><span class="function"><a href="../gobject/gobject-Signals.html#g-signal-connect">g_signal_connect</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">interface</span><span class="symbol">,</span>
+<span class="normal">                    </span><span class="string">"handle-hello-world"</span><span class="symbol">,</span>
+<span class="normal">                    </span><span class="function"><a href="../gobject/gobject-Closures.html#G-CALLBACK:CAPS">G_CALLBACK</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">on_handle_hello_world</span><span class="symbol">),</span>
+<span class="normal">                    some_user_data</span><span class="symbol">);</span>
+<span class="normal">  </span><span class="symbol">[...]</span>
+<span class="normal">  error </span><span class="symbol">=</span><span class="normal"> <a href="../glib/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span>
+<span class="normal">  </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="function"><a href="GDBusInterfaceSkeleton.html#g-dbus-interface-skeleton-export">g_dbus_interface_skeleton_export</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">G_DBUS_INTERFACE_SKELETON</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">interface</span><span class="symbol">),</span>
+<span class="normal">                                         connection</span><span class="symbol">,</span>
+<span class="normal">                                         </span><span class="string">"/path/of/dbus_object"</span><span class="symbol">,</span>
+<span class="normal">                                         </span><span class="symbol">&amp;</span><span class="normal">error</span><span class="symbol">))</span>
+<span class="normal">    </span><span class="cbracket">{</span>
+<span class="normal">      </span><span class="comment">/* handle error */</span>
+<span class="normal">    </span><span class="cbracket">}</span></pre></td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+<p>
+      To facilitate atomic changesets (multiple properties changing at
+      the same time), <a href="../gobject/gobject-The-Base-Object-Type.html#GObject-notify"><span class="type">“notify”</span></a> signals are queued up when
+      received. The queue is drained in an idle handler (which is called from the
+      <a href="../glib/glib-The-Main-Event-Loop.html#g-main-context-push-thread-default">thread-default main loop</a>
+      of the thread where the skeleton object was
+      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>
+      signal with all the properties that have changed. Use
+      <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
+      <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
+      immediately. Use <a href="../gobject/gobject-The-Base-Object-Type.html#g-object-freeze-notify"><code class="function">g_object_freeze_notify()</code></a> and
+      <a href="../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
+      thread.
+    </p>
+</div>
+</div>
+<div class="refsect1">
+<a name="id-1.4.24.7.11"></a><h2>C Type Mapping</h2>
+<p>
+    Scalar types
+    (type-strings
+    <a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</a>,
+    <a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-BYTE:CAPS">'y'</a>,
+    <a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-INT16:CAPS">'n'</a>,
+    <a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-UINT16:CAPS">'q'</a>,
+    <a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-INT32:CAPS">'i'</a>,
+    <a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-UINT32:CAPS">'u'</a>,
+    <a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-INT64:CAPS">'x'</a>,
+    <a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-UINT64:CAPS">'t'</a> and
+    <a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-DOUBLE:CAPS">'d'</a>)
+    ),
+    strings (type-strings
+    <a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-STRING:CAPS">'s'</a>,
+    <a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</a>,
+    <a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-OBJECT-PATH:CAPS">'o'</a> and
+    <a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-SIGNATURE:CAPS">'g'</a>) and
+    arrays of string (type-strings
+    <a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-STRING-ARRAY:CAPS">'as'</a>,
+    <a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-OBJECT-PATH-ARRAY:CAPS">'ao'</a> and
+    <a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-BYTESTRING-ARRAY:CAPS">'aay'</a>)
+    are mapped to the natural types,
+    e.g. <a href="../glib/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a>, <a href="../glib/glib-Basic-Types.html#gdouble"><span class="type">gdouble</span></a>, <a href="../glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a>, <a href="../gobject/gobject-Standard-Parameter-and-Value-Types.html#gchararray">gchar*</a>,
+    <a href="../gobject/gobject-Boxed-Types.html#GStrv">gchar**</a> and
+    so on. Everything else is mapped to the <a href="../glib/glib-GVariant.html#GVariant"><span class="type">GVariant</span></a>
+    type.
+  </p>
+<p>
+    This automatic mapping can be turned off by using the annotation
+    <code class="literal">org.gtk.GDBus.C.ForceGVariant</code> - if used then a
+    <a href="../glib/glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> is always exchanged instead of the
+    corresponding native C type. This annotation may be convenient to
+    use when using
+    bytestrings (type-string <a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</a>)
+    for data that could have embedded NUL bytes.
+  </p>
+</div>
+<div class="refsect1">
+<a name="gdbus-code-stability"></a><h2>Stability Guarantees</h2>
+<p>
+    The generated C functions are guaranteed to not change their ABI
+    that is, if a method, signal or property does not change its
+    signature in the introspection XML, the generated C functions will
+    not change its C ABI either. The ABI of the generated instance and
+    class structures will be preserved as well.
+  </p>
+<p>
+    The ABI of the generated <a href="../gobject/gobject-Type-Information.html#GType"><span class="type">GType</span></a>s will be preserved only if
+    the <code class="literal">org.gtk.GDBus.Since</code> annotation is used
+    judiciously — this is because the VTable for the <span class="type">GInterface</span>
+    relies on functions pointers for signal handlers. Specifically, if
+    a D-Bus method, property or signal or is added to a D-Bus
+    interface, then ABI of the generated <span class="type">GInterface</span> type is preserved
+    if, and only if, each added method, property signal is annotated
+    with they <code class="literal">org.gtk.GDBus.Since</code> annotation using
+    a greater version number than previous versions.
+  </p>
+<p>
+    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://wiki.gnome.org/Projects/GObjectIntrospection" target="_top">GObject
+    Introspection</a> comments / annotations. The layout and
+    contents might change in the future so no guarantees about
+    e.g. <code class="literal">SECTION</code> usage etc. is given.
+  </p>
+<p>
+    While the generated Docbook for D-Bus interfaces isn't expected to
+    change, no guarantees are given at this point.
+  </p>
+<p>
+    It is important to note that the generated code should not be
+    checked into revision control systems, nor it should be included
+    in distributed source archives.
+  </p>
+</div>
+<div class="refsect1">
+<a name="id-1.4.24.7.13"></a><h2>Bugs</h2>
+<p>
+    Please send bug reports to either the distribution bug tracker
+    or the upstream bug tracker at
+    <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>.
+  </p>
+</div>
+<div class="refsect1">
+<a name="id-1.4.24.7.14"></a><h2>See also</h2>
+<p>
+    <span class="citerefentry"><span class="refentrytitle">gdbus</span>(1)</span>
+  </p>
+</div>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.21.1</div>
+</body>
+</html>