Default page

Edit File: gdbus-codegen.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>gdbus-codegen: GIO Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.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.32 (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>gdbus-codegen</h2>
gdbus-codegen — D-Bus code and documentation generator
</td>
<td class="gallery_image" valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<div class="cmdsynopsis"><code class="command">gdbus-codegen</code> [<code class="option">-h</code>, <code class="option">--help</code>] [<code class="option">--interface-prefix</code> <code>org.project.Prefix</code>] [<code class="option">--generate-c-code</code> <code>OUTFILES</code>] [<code class="option">--c-namespace</code> <code>YourProject</code>] [<code class="option">--c-generate-object-manager</code>] [<code class="option">--c-generate-autocleanup</code> none|objects|all] [<code class="option">--output-directory</code> <code>OUTDIR</code>] [<code class="option">--generate-docbook</code> <code>OUTFILES</code>] [<code class="option">--pragma-once</code>] [<code class="option">--xml-files</code> <code>FILE</code>] [<code class="option">--header</code>] [<code class="option">--body</code>] [<code class="option">--interface-info-header</code>] [<code class="option">--interface-info-body</code>] [<code class="option">--output</code> <code>OUTFILE</code>] [
 <code class="option">--annotate</code>
 <code>ELEMENT</code>
 <code>KEY</code>
 <code>VALUE</code>
 ]... [<code class="option">--glib-min-required</code> <code>VERSION</code>] [<code class="option">--glib-max-allowed</code> <code>VERSION</code>] FILE [
 FILE... 
 ]</div>
</div>
<div class="refsect1">
<a name="id-1.4.25.7.5"></a><h2>Description</h2>

 gdbus-codegen is used to generate code and/or
 documentation for one or more D-Bus interfaces.
 

 gdbus-codegen reads
 <a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format" target="_top">D-Bus
 Introspection XML</a> from files passed as additional
 arguments on the command line and generates output files.
 It currently supports generating C source code (via
 <code class="option">--body</code>) or header (via <code class="option">--header</code>)
 and Docbook XML (via <code class="option">--generate-docbook</code>). Alternatively,
 more restricted C source code and headers can be generated, which just
 contain the interface information (as GDBusInterfaceInfo
 structures) using <code class="option">--interface-info-body</code> and
 <code class="option">--interface-info-header</code>.
 
</div>
<div class="refsect1">
<a name="id-1.4.25.7.6"></a><h2>Generating C code</h2>

 When generating C code, a
 GInterface-derived type is generated for each D-Bus
 interface. Additionally, for every generated type,
 FooBar, two concrete instantiable types,
 FooBarProxy and FooBarSkeleton, implementing
 said interface are also generated. The former is derived from
 <a class="link" href="GDBusProxy.html" title="GDBusProxy">GDBusProxy</a> and intended for use on the client side
 while the latter is derived from the
 <a class="link" href="GDBusInterfaceSkeleton.html" title="GDBusInterfaceSkeleton">GDBusInterfaceSkeleton</a> type making it easy to export on a
 <a class="link" href="GDBusConnection.html" title="GDBusConnection">GDBusConnection</a> either directly or via a
 <a class="link" href="GDBusObjectManagerServer.html" title="GDBusObjectManagerServer">GDBusObjectManagerServer</a> instance.
 

 For C code generation either <code class="option">--body</code> that
 generates source code, <code class="option">--header</code> that
 generates headers, <code class="option">--interface-info-body</code> that generates
 interface information source code, or
 <code class="option">--interface-info-header</code> that generates interface information
 headers, can be used. These options must be used along with
 <code class="option">--output</code>, which is used to specify the file to output to.
 

 Both files can be generated at the same time by using
 <code class="option">--generate-c-code</code>, but this option is deprecated.
 In this case <code class="option">--output</code> cannot be used due to the
 generation of multiple files. Instead pass
 <code class="option">--output-directory</code> to specify the directory to put
 the output files in. By default the current directory will be used.
 

 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>.
 

 For methods, signals and properties, if not specified, the name
 defaults to the name of the method, signal or property.
 

 Two forms of the name are used - the CamelCase form and the
 lower-case form. The CamelCase form is used for the GType 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).
 

 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 Ugly_Case),
 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>.
 
</div>
<div class="refsect1">
<a name="id-1.4.25.7.7"></a><h2>Generating Docbook documentation</h2>

 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.
 
</div>
<div class="refsect1">
<a name="id-1.4.25.7.8"></a><h2>Options</h2>

 The following options are supported:
 
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><code class="option">-h</code>, <code class="option">--help</code></td>
<td>
 Show help and exit.
 </td>
</tr>
<tr>
<td><code class="option">--xml-files</code> <code>FILE</code></td>
<td>
 This option is deprecated; use positional arguments instead.
 The D-Bus introspection XML file.
 </td>
</tr>
<tr>
<td><code class="option">--interface-prefix</code> <code>org.project.Prefix.</code></td>
<td>
 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>.
 </td>
</tr>
<tr>
<td><code class="option">--generate-docbook</code> <code>OUTFILES</code></td>
<td>

 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.
 

 Pass <code class="option">--output-directory</code> to specify the directory
 to put the output files in. By default the current directory
 will be used.
 
</td>
</tr>
<tr>
<td><code class="option">--generate-c-code</code> <code>OUTFILES</code></td>
<td>

 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> including any sub-directories. If you want the files to
 be output in a different location use <code class="option">--output-directory</code> as <code class="filename">OUTFILES.h</code>
 including sub-directories will be referenced from <code class="filename">OUTFILES.c</code>.
 

 The full paths would then be <code class="literal">$(OUTDIR)/$(dirname $OUTFILES)/$(basename $OUTFILES).{c,h}</code>.
 
</td>
</tr>
<tr>
<td><code class="option">--c-namespace</code> <code>YourProject</code></td>
<td>
 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 Ugly_Case (see above).
 </td>
</tr>
<tr>
<td><code class="option">--pragma-once</code></td>
<td>
 If this option is passed, the
 <a class="ulink" href="https://en.wikipedia.org/wiki/Pragma_once" target="_top">#pragma once</a>
 preprocessor directive is used instead of include guards.
 </td>
</tr>
<tr>
<td><code class="option">--c-generate-object-manager</code></td>
<td>
 If this option is passed, suitable <a class="link" href="GDBusObject.html" title="GDBusObject">GDBusObject</a>,
 <a class="link" href="GDBusObjectProxy.html" title="GDBusObjectProxy">GDBusObjectProxy</a>, <a class="link" href="GDBusObjectSkeleton.html" title="GDBusObjectSkeleton">GDBusObjectSkeleton</a> and
 <a class="link" href="GDBusObjectManagerClient.html" title="GDBusObjectManagerClient">GDBusObjectManagerClient</a> subclasses are generated.
 </td>
</tr>
<tr>
<td><code class="option">--c-generate-autocleanup</code> none|objects|all</td>
<td>
 This option influences what types autocleanup functions are
 generated for. 'none' means to not generate any autocleanup functions.
 'objects' means to generate them for object types, and 'all' means to
 generate them for object types and interfaces. The default is 'objects'
 due to a corner case in backwards compatibility with a few projects,
 but you should likely switch your project to use 'all'.
 This option was added in GLib 2.50.
 </td>
</tr>
<tr>
<td><code class="option">--output-directory</code> <code>OUTDIR</code></td>
<td>

 Directory to output generated source to. Equivalent to changing directory before generation.
 

 This option cannot be used with <code class="option">--body</code>,
 <code class="option">--header</code>, <code class="option">--interface-info-body</code> or
 <code class="option">--interface-info-header</code>; and
 <code class="option">--output</code> must be used.
 
</td>
</tr>
<tr>
<td><code class="option">--header</code></td>
<td>

 If this option is passed, it will generate the header code and write it to the disk by
 using the path and file name provided by <code class="option">--output</code>.
 

 Using <code class="option">--generate-c-code</code>, <code class="option">--generate-docbook</code> or
 <code class="option">--output-directory</code> are not allowed to be used along with
 <code class="option">--header</code> and <code class="option">--body</code> options, because these options
 are used to generate only one file.
 
</td>
</tr>
<tr>
<td><code class="option">--body</code></td>
<td>

 If this option is passed, it will generate the source code and write it to the disk by
 using the path and file name provided by <code class="option">--output</code>.
 

 Using <code class="option">--generate-c-code</code>, <code class="option">--generate-docbook</code> or
 <code class="option">--output-directory</code> are not allowed to be used along with
 <code class="option">--header</code> and <code class="option">--body</code> options, because these options
 are used to generate only one file.
 
</td>
</tr>
<tr>
<td><code class="option">--interface-info-header</code></td>
<td>

 If this option is passed, it will generate the header code for the
 GDBusInterfaceInfo structures only and will write it to
 the disk by using the path and file name provided by
 <code class="option">--output</code>.
 

 Using <code class="option">--generate-c-code</code>, <code class="option">--generate-docbook</code> or
 <code class="option">--output-directory</code> are not allowed to be used along with
 the <code class="option">--interface-info-header</code> and
 <code class="option">--interface-info-body</code> options, because these options
 are used to generate only one file.
 
</td>
</tr>
<tr>
<td><code class="option">--interface-info-body</code></td>
<td>

 If this option is passed, it will generate the source code for the
 GDBusInterfaceInfo structures only and will write it to
 the disk by using the path and file name provided by
 <code class="option">--output</code>.
 

 Using <code class="option">--generate-c-code</code>, <code class="option">--generate-docbook</code> or
 <code class="option">--output-directory</code> are not allowed to be used along with
 the <code class="option">--interface-info-header</code> and
 <code class="option">--interface-info-body</code> options, because these options
 are used to generate only one file.
 
</td>
</tr>
<tr>
<td><code class="option">--output</code> <code>OUTFILE</code></td>
<td>

 The full path where the header (<code class="option">--header</code>,
 <code class="option">--interface-info-header</code>) or the source code
 (<code class="option">--body</code>, <code class="option">--interface-info-body</code>) will
 be written, using the path and filename provided by
 <code class="option">--output</code>. The full path could be something like
 <code class="literal">$($OUTFILE).{c,h}</code>.
 

 Using <code class="option">--generate-c-code</code>, <code class="option">--generate-docbook</code> or
 <code class="option">--output-directory</code> is not allowed along with
 <code class="option">--output</code>, because the latter is used to generate only one file.
 
</td>
</tr>
<tr>
<td><code class="option">--annotate</code> <code>ELEMENT</code> <code>KEY</code> <code>VALUE</code></td>
<td>

 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:
 
<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">gdbus-codegen --c-namespace MyApp \
 --generate-c-code myapp-generated \
 --annotate "org.project.InterfaceName" \
 org.gtk.GDBus.C.Name MyFrobnicator \
 --annotate "org.project.InterfaceName:Property" \
 bar bat \
 --annotate "org.project.InterfaceName.Method()" \
 org.freedesktop.DBus.Deprecated true \
 --annotate "org.project.InterfaceName.Method()[arg_name]" \
 snake hiss \
 --annotate "org.project.InterfaceName::Signal" \
 cat meow \
 --annotate "org.project.InterfaceName::Signal[arg_name]" \
 dog wuff \
 myapp-dbus-interfaces.xml</pre></td>
 </tr>
 </tbody>
 </table>
</div>

Any UTF-8 string can be used for <code>KEY</code> and <code>VALUE</code>.
 
</td>
</tr>
<tr>
<td><code class="option">--glib-min-required</code> <code>VERSION</code></td>
<td>

 Specifies the minimum version of GLib which the code generated by
 gdbus-codegen can depend on. This may be used to
 make backwards-incompatible changes in the output or behaviour of
 gdbus-codegen in future, which users may opt in to
 by increasing the value they pass for <code class="option">--glib-min-required</code>.
 If this option is not passed, the output from gdbus-codegen
 is guaranteed to be compatible with all versions of GLib from 2.30
 upwards, as that is when gdbus-codegen was first
 released.
 

 Note that some version parameters introduce incompatible changes: all callers
 of the generated code might need to be updated, and if the generated code is part of
 a library's API or ABI, then increasing the version parameter can result in an API
 or ABI break.
 

 The version number must be of the form
 <code class="literal"><code>MAJOR</code>.<code>MINOR</code>.<code>MICRO</code></code>,
 where all parts are integers. <code>MINOR</code> and
 <code>MICRO</code> are optional. The version number may not be smaller
 than <code class="literal">2.30</code>.
 

 If the version number is <code class="literal">2.64</code> or greater, the generated code will
 have the following features: (1) If a method has <code class="literal">h</code> (file
 descriptor) parameter(s), a GUnixFDList parameter will exist in the
 generated code for it (whereas previously the annotation
 <code class="literal">org.gtk.GDBus.C.UnixFD</code> was required), and (2) Method call functions will
 have two additional arguments to allow the user to specify GDBusCallFlags
 and a timeout value, as is possible when using <code class="function"><a class="link" href="GDBusProxy.html#g-dbus-proxy-call" title="g_dbus_proxy_call ()"><code class="function">g_dbus_proxy_call()</code></a></code>.
 
</td>
</tr>
<tr>
<td><code class="option">--glib-max-allowed</code> <code>VERSION</code></td>
<td>

 Specifies the maximum version of GLib which the code generated by
 gdbus-codegen can depend on. This may be used to
 ensure that code generated by gdbus-codegen is
 compilable with specific older versions of GLib that your software has
 to support.
 

 The version number must be of the form
 <code class="literal"><code>MAJOR</code>.<code>MINOR</code>.<code>MICRO</code></code>,
 where all parts are integers. <code>MINOR</code> and
 <code>MICRO</code> are optional. The version number must
 be greater than or equal to that passed to <code class="option">--glib-min-required</code>.
 It defaults to the version of GLib which provides this gdbus-codegen.
 
</td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect1">
<a name="id-1.4.25.7.9"></a><h2>Supported D-Bus Annotations</h2>

 The following D-Bus annotations are supported by
 gdbus-codegen:
 
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><code class="literal">org.freedesktop.DBus.Deprecated</code></td>
<td>

 Can be used on any <code class="literal"><interface></code>,
 <code class="literal"><method></code>,
 <code class="literal"><signal></code> and
 <code class="literal"><property></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.
 

 When generating C code, this annotation is used to add
 G_GNUC_DEPRECATED to generated functions for the element.
 

 When generating Docbook XML, a deprecation warning will
 appear along the documentation for the element.
 
</td>
</tr>
<tr>
<td><code class="literal">org.gtk.GDBus.Since</code></td>
<td>

 Can be used on any <code class="literal"><interface></code>,
 <code class="literal"><method></code>,
 <code class="literal"><signal></code> and
 <code class="literal"><property></code> element to specify the
 version (any free-form string but compared using a
 version-aware sort function) the element appeared in.
 

 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>.
 

 When generating Docbook XML, the value of this tag appears
 in the documentation.
 
</td>
</tr>
<tr>
<td><code class="literal">org.gtk.GDBus.DocString</code></td>
<td>
 A string with Docbook content for documentation. This annotation can
 be used on <code class="literal"><interface></code>,
 <code class="literal"><method></code>,
 <code class="literal"><signal></code>,
 <code class="literal"><property></code> and
 <code class="literal"><arg></code> elements.
 </td>
</tr>
<tr>
<td><code class="literal">org.gtk.GDBus.DocString.Short</code></td>
<td>
 A string with Docbook content for short/brief
 documentation. This annotation can only be used on
 <code class="literal"><interface></code> elements.
 </td>
</tr>
<tr>
<td><code class="literal">org.gtk.GDBus.C.Name</code></td>
<td>
 Can be used on any <code class="literal"><interface></code>,
 <code class="literal"><method></code>,
 <code class="literal"><signal></code> and
 <code class="literal"><property></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 Ugly_Case (see above).
 </td>
</tr>
<tr>
<td><code class="literal">org.gtk.GDBus.C.ForceGVariant</code></td>
<td>
 If set to a non-empty string, a GVariant instance will
 be used instead of the natural C type. This annotation can
 be used on any <code class="literal"><arg></code> and
 <code class="literal"><property></code> element.
 </td>
</tr>
<tr>
<td><code class="literal">org.gtk.GDBus.C.UnixFD</code></td>
<td>
 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">GUnixFDList</a> type. This annotation can be used on
 <code class="literal"><method></code> elements.
 </td>
</tr>
</tbody>
</table></div>

 As an easier alternative to using the
 <code class="literal">org.gtk.GDBus.DocString</code> annotation, note that
 parser used by gdbus-codegen parses XML
 comments in a way similar to <a class="ulink" href="http://www.gtk.org/gtk-doc/" target="_top">gtk-doc</a>:

<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"><!--
 net.Corp.Bar:
 @short_description: A short description

A <emphasis>longer</emphasis> description.

This is a new paragraph.
-->
<interface name="net.corp.Bar">
 <!--
 FooMethod:
 @greeting: The docs for greeting parameter.
 @response: The docs for response parameter.

The docs for the actual method.
 -->
 <method name="FooMethod">
 <arg name="greeting" direction="in" type="s"/>
 <arg name="response" direction="out" type="s"/>
 </method>

<!--
 BarSignal:
 @blah: The docs for blah parameter.
 @boo: The docs for boo parameter.
 @since: 2.30

The docs for the actual signal.
 -->
 <signal name="BarSignal">
 <arg name="blah" type="s"/>
 <arg name="boo" type="s"/>
 </signal>

<property name="BazProperty" type="s" access="read"/>
</interface></pre></td>
 </tr>
 </tbody>
 </table>
</div>

Note that <code class="literal"><parameter>since</parameter></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"><link linkend="net.Corp.Bar"><type>net.Corp.Bar</type></link></code>,
 <code class="literal">net.Corp.Bar.FooMethod()</code>,
 <code class="literal"><link linkend="net.Corp.Bar-BarSignal"><type>“BarSignal”</type></link></code> and
 <code class="literal"><link linkend="net.Corp.InlineDocs--BazProperty"><type>“BazProperty”</type></link></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.
 

 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.
 
</div>
<div class="refsect1">
<a name="id-1.4.25.7.10"></a><h2>Example</h2>

 Consider the following D-Bus Introspection XML.
 
<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"><node>
 <interface name="net.Corp.MyApp.Frobber">
 <method name="HelloWorld">
 <arg name="greeting" direction="in" type="s"/>
 <arg name="response" direction="out" type="s"/>
 </method>

If gdbus-codegen is used on this file like this:
 
<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">gdbus-codegen --generate-c-code myapp-generated \
 --c-namespace MyApp \
 --interface-prefix net.corp.MyApp. \
 net.Corp.MyApp.Frobber.xml</pre></td>
 </tr>
 </tbody>
 </table>
</div>

two files called
 <code class="filename">myapp-generated.[ch]</code> are
 generated. The files provide an abstract
 GTypeInterface-derived type called
 MyAppFrobber as well as two instantiable types with
 the same name but suffixed with Proxy and
 Skeleton. The generated file, roughly, contains the
 following facilities:
 
<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">/* GType macros for the three generated types */
#define MY_APP_TYPE_FROBBER (my_app_frobber_get_type ())
#define MY_APP_TYPE_FROBBER_SKELETON (my_app_frobber_skeleton_get_type ())
#define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ())

typedef struct _MyAppFrobber MyAppFrobber; /* Dummy typedef */

typedef struct
{
 GTypeInterface parent_iface;

/* Signal handler for the ::notification signal */
 void (*notification) (MyAppFrobber *proxy,
 GVariant *icon_blob,
 gint height,
 const gchar* const *messages);

/* Signal handler for the ::handle-hello-world signal */
 gboolean (*handle_hello_world) (MyAppFrobber *proxy,
 GDBusMethodInvocation *invocation,
 const gchar *greeting);
} MyAppFrobberIface;

/* Asynchronously calls HelloWorld() */
void
my_app_frobber_call_hello_world (MyAppFrobber *proxy,
 const gchar *greeting,
 GCancellable *cancellable,
 GAsyncReadyCallback callback,
 gpointer user_data);
gboolean
my_app_frobber_call_hello_world_finish (MyAppFrobber *proxy,
 gchar **out_response,
 GAsyncResult *res,
 GError **error);

/* Synchronously calls HelloWorld(). Blocks calling thread. */
gboolean
my_app_frobber_call_hello_world_sync (MyAppFrobber *proxy,
 const gchar *greeting,
 gchar **out_response,
 GCancellable *cancellable,
 GError **error);

/* Completes handling the HelloWorld() method call */
void
my_app_frobber_complete_hello_world (MyAppFrobber *object,
 GDBusMethodInvocation *invocation,
 const gchar *response);

/* Emits the ::notification signal / Notification() D-Bus signal */
void
my_app_frobber_emit_notification (MyAppFrobber *object,
 GVariant *icon_blob,
 gint height,
 const gchar* const *messages);

/* Gets the :verbose GObject property / Verbose D-Bus property.
 * Does no blocking I/O.
 */
gboolean my_app_frobber_get_verbose (MyAppFrobber *object);

/* Sets the :verbose GObject property / Verbose D-Bus property.
 * Does no blocking I/O.
 */
void my_app_frobber_set_verbose (MyAppFrobber *object,
 gboolean value);

/* Gets the interface info */
GDBusInterfaceInfo *my_app_frobber_interface_info (void);

/* Creates a new skeleton object, ready to be exported */
MyAppFrobber *my_app_frobber_skeleton_new (void);

/* Client-side proxy constructors.
 *
 * Additionally, _new_for_bus(), _new_for_bus_finish() and
 * _new_for_bus_sync() proxy constructors are also generated.
 */
void
my_app_frobber_proxy_new (GDBusConnection *connection,
 GDBusProxyFlags flags,
 const gchar *name,
 const gchar *object_path,
 GCancellable *cancellable,
 GAsyncReadyCallback callback,
 gpointer user_data);
MyAppFrobber *
my_app_frobber_proxy_new_finish (GAsyncResult *res,
 GError **error);
MyAppFrobber *
my_app_frobber_proxy_new_sync (GDBusConnection *connection,
 GDBusProxyFlags flags,
 const gchar *name,
 const gchar *object_path,
 GCancellable *cancellable,
 GError **error);</pre></td>
 </tr>
 </tbody>
 </table>
</div>

Thus, for every D-Bus method, there will be three C functions for
 calling the method, one GObject signal for handling an incoming
 call and one C function for completing an incoming call. For every
 D-Bus signal, there's one GObject signal and one C function for
 emitting it. For every D-Bus property, two C functions are
 generated (one setter, one getter) and one GObject property. The
 following table summarizes the generated facilities and where they
 are applicable:
 
<div class="informaltable"><table class="informaltable" 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 MyAppFrobberProxy
</td>
<td>Any type implementing the MyAppFrobber 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 <code>:verbose</code>.</td>
<td>Implement GObject'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 <code>:verbose</code>.</td>
<td>Implement GObject'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.25.7.10.10"></a><h3>Client-side usage</h3>

 You can use the generated proxy type with the generated
 constructors:
 
<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">MyAppFrobber *proxy;
GError *error;

error = NULL;
proxy = my_app_frobber_proxy_new_for_bus_sync (
 G_BUS_TYPE_SESSION,
 G_DBUS_PROXY_FLAGS_NONE,
 "net.Corp.MyApp", /* bus name */
 "/net/Corp/MyApp/SomeFrobber", /* object */
 NULL, /* GCancellable* */
 &error);
/* do stuff with proxy */
g_object_unref (proxy);</pre></td>
 </tr>
 </tbody>
 </table>
</div>

Instead of using the generic <a class="link" href="GDBusProxy.html" title="GDBusProxy">GDBusProxy</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
 <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
 <code>net.Corp.MyApp.Frobber:Verbose</code> D-Bus
 Property using either the GObject property
 <code>:verbose</code> 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 “notify” signal to listen to property changes.
 

 Note that all property access is via <a class="link" href="GDBusProxy.html" title="GDBusProxy">GDBusProxy</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.
 
</div>
<hr>
<div class="refsect2">
<a name="id-1.4.25.7.10.11"></a><h3>Server-side usage</h3>

 The generated MyAppFrobber interface is designed so
 it is easy to implement it in a GObject
 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
 MyAppFrobberIface structure. Similarly, to handle
 the <code>net.Corp.MyApp.Frobber:Verbose</code>
 property override the <code>:verbose</code> GObject
 property from the subclass. To emit a signal, use
 e.g. <code class="function"><code class="function">my_app_emit_signal()</code></code> or
 <code class="function">g_signal_emit_by_name()</code>.
 

 Instead of subclassing, it is often easier to use the generated
 MyAppFrobberSkeleton subclass. To handle incoming
 method calls, use <code class="function"><code class="function">g_signal_connect()</code></code> with
 the <code class="function">::handle-*</code> signals and instead of
 overriding GObject's
 <code class="function"><code class="function">get_property()</code></code> and
 <code class="function"><code class="function">set_property()</code></code> vfuncs, use
 <code class="function">g_object_get()</code> and
 <code class="function">g_object_set()</code> or the generated property
 getters and setters (the generated class has an internal
 property bag implementation).
 
<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">static gboolean
on_handle_hello_world (MyAppFrobber *interface,
 GDBusMethodInvocation *invocation,
 const gchar *greeting,
 gpointer user_data)
{
 if (g_strcmp0 (greeting, "Boo") != 0)
 {
 gchar *response;
 response = g_strdup_printf ("Word! You said `%s'.", greeting);
 my_app_complete_hello_world (interface, invocation, response);
 g_free (response);
 }
 else
 {
 g_dbus_method_invocation_return_error (invocation,
 MY_APP_ERROR,
 MY_APP_ERROR_NO_WHINING,
 "Hey, %s, there will be no whining!",
 g_dbus_method_invocation_get_sender (invocation));
 }
 return TRUE;
}

[...]

interface = my_app_frobber_skeleton_new ();
 my_app_frobber_set_verbose (interface, TRUE);

g_signal_connect (interface,
 "handle-hello-world",
 G_CALLBACK (on_handle_hello_world),
 some_user_data);

[...]

error = NULL;
 if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
 connection,
 "/path/of/dbus_object",
 &error))
 {
 /* handle error */
 }</pre></td>
 </tr>
 </tbody>
 </table>
</div>

To facilitate atomic changesets (multiple properties changing at
 the same time), “notify” signals are queued up when
 received. The queue is drained in an idle handler (which is called from the
 thread-default main loop
 of the thread where the skeleton object was
 constructed) 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 <code class="function">g_object_freeze_notify()</code> and
 <code class="function">g_object_thaw_notify()</code> for atomic changesets if on a different
 thread.
 
</div>
</div>
<div class="refsect1">
<a name="id-1.4.25.7.11"></a><h2>C Type Mapping</h2>

 Scalar types
 (type-strings
 'b',
 'y',
 'n',
 'q',
 'i',
 'u',
 'x',
 't' and
 'd')
 ),
 strings (type-strings
 's',
 'ay',
 'o' and
 'g') and
 arrays of string (type-strings
 'as',
 'ao' and
 'aay')
 are mapped to the natural types,
 e.g. gboolean, gdouble, gint, gchar*,
 gchar** and
 so on. Everything else is mapped to the GVariant
 type.
 

 This automatic mapping can be turned off by using the annotation
 <code class="literal">org.gtk.GDBus.C.ForceGVariant</code> - if used then a
 GVariant is always exchanged instead of the
 corresponding native C type. This annotation may be convenient to
 use when using
 bytestrings (type-string 'ay')
 for data that could have embedded NUL bytes.
 
</div>
<div class="refsect1">
<a name="gdbus-code-stability"></a><h2>Stability Guarantees</h2>

 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.
 

 The ABI of the generated GTypes 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 GInterface
 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 GInterface 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.
 

 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.
 

 While the generated Docbook for D-Bus interfaces isn't expected to
 change, no guarantees are given at this point.
 

 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.
 
</div>
<div class="refsect1">
<a name="id-1.4.25.7.13"></a><h2>Bugs</h2>

 Please send bug reports to either the distribution bug tracker
 or the upstream bug tracker at
 <a class="ulink" href="https://gitlab.gnome.org/GNOME/glib/issues/new" target="_top">https://gitlab.gnome.org/GNOME/glib/issues/new</a>.
 
</div>
<div class="refsect1">
<a name="id-1.4.25.7.14"></a><h2>See also</h2>

 gdbus(1)
 
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.32</div>
</body>
</html>