| <refentry id="gdbus-codegen" lang="en"> |
| |
| <refentryinfo> |
| <title>gdbus</title> |
| <productname>GIO</productname> |
| <authorgroup> |
| <author> |
| <contrib>Developer</contrib> |
| <firstname>David</firstname> |
| <surname>Zeuthen</surname> |
| <email>zeuthen@gmail.com</email> |
| </author> |
| </authorgroup> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>gdbus-codegen</refentrytitle> |
| <manvolnum>1</manvolnum> |
| <refmiscinfo class="manual">User Commands</refmiscinfo> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>gdbus-codegen</refname> |
| <refpurpose>D-Bus code and documentation generator</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <cmdsynopsis> |
| <command>gdbus-codegen</command> |
| <arg><option>-h</option>, <option>--help</option></arg> |
| <arg><option>--interface-prefix</option> <replaceable>org.project.Prefix</replaceable></arg> |
| <arg><option>--generate-c-code</option> <replaceable>OUTFILES</replaceable></arg> |
| <arg><option>--c-namespace</option> <replaceable>YourProject</replaceable></arg> |
| <arg><option>--c-generate-object-manager</option></arg> |
| <arg><option>--c-generate-autocleanup</option> none|objects|all</arg> |
| <arg><option>--output-directory</option> <replaceable>OUTDIR</replaceable></arg> |
| <arg><option>--generate-docbook</option> <replaceable>OUTFILES</replaceable></arg> |
| <arg><option>--pragma-once</option></arg> |
| <arg><option>--xml-files</option> <replaceable>FILE</replaceable></arg> |
| <arg><option>--header</option></arg> |
| <arg><option>--body</option></arg> |
| <arg><option>--interface-info-header</option></arg> |
| <arg><option>--interface-info-body</option></arg> |
| <arg><option>--symbol-decorator</option> <replaceable>DECORATOR</replaceable></arg> |
| <arg><option>--symbol-decorator-header</option> <replaceable>HEADER</replaceable></arg> |
| <arg><option>--symbol-decorator-define</option> <replaceable>DEFINE</replaceable></arg> |
| <arg><option>--output</option> <replaceable>OUTFILE</replaceable></arg> |
| <group choice="plain" rep="repeat"> |
| <arg> |
| <option>--annotate</option> |
| <replaceable>ELEMENT</replaceable> |
| <replaceable>KEY</replaceable> |
| <replaceable>VALUE</replaceable> |
| </arg> |
| </group> |
| <arg><option>--glib-min-required</option> <replaceable>VERSION</replaceable></arg> |
| <arg><option>--glib-max-allowed</option> <replaceable>VERSION</replaceable></arg> |
| <arg choice="plain">FILE</arg> |
| <arg> |
| <arg choice="plain" rep="repeat">FILE</arg> |
| </arg> |
| </cmdsynopsis> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Description</title> |
| <para> |
| <command>gdbus-codegen</command> is used to generate code and/or |
| documentation for one or more D-Bus interfaces. |
| </para> |
| <para> |
| <command>gdbus-codegen</command> reads |
| <ulink |
| url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus |
| Introspection XML</ulink> from files passed as additional |
| arguments on the command line and generates output files. |
| It currently supports generating C source code (via |
| <option>--body</option>) or header (via <option>--header</option>) |
| and Docbook XML (via <option>--generate-docbook</option>). Alternatively, |
| more restricted C source code and headers can be generated, which just |
| contain the interface information (as <type>GDBusInterfaceInfo</type> |
| structures) using <option>--interface-info-body</option> and |
| <option>--interface-info-header</option>. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Generating C code</title> |
| <para> |
| When generating C code, a |
| #GInterface<!-- -->-derived type is generated for each D-Bus |
| interface. Additionally, for every generated type, |
| <type>FooBar</type>, two concrete instantiatable types, |
| <type>FooBarProxy</type> and <type>FooBarSkeleton</type>, implementing |
| said interface are also generated. The former is derived from |
| #GDBusProxy and intended for use on the client side |
| while the latter is derived from the |
| #GDBusInterfaceSkeleton type making it easy to export on a |
| #GDBusConnection either directly or via a |
| #GDBusObjectManagerServer instance. |
| </para> |
| <para> |
| For C code generation either <option>--body</option> that |
| generates source code, <option>--header</option> that |
| generates headers, <option>--interface-info-body</option> that generates |
| interface information source code, or |
| <option>--interface-info-header</option> that generates interface information |
| headers, can be used. These options must be used along with |
| <option>--output</option>, which is used to specify the file to output to. |
| </para> |
| <para> |
| Both files can be generated at the same time by using |
| <option>--generate-c-code</option>, but this option is deprecated. |
| In this case <option>--output</option> cannot be used due to the |
| generation of multiple files. Instead pass |
| <option>--output-directory</option> to specify the directory to put |
| the output files in. By default the current directory will be used. |
| </para> |
| <para> |
| The name of each generated C type is derived from the D-Bus |
| interface name stripped with the prefix given with |
| <option>--interface-prefix</option> and with the dots removed and |
| initial characters capitalized. For example, for the D-Bus |
| interface <literal>com.acme.Coyote</literal> the name used is |
| <literal>ComAcmeCoyote</literal>. For the D-Bus interface |
| <literal>org.project.Bar.Frobnicator</literal> with |
| <option>--interface-prefix</option> |
| <literal>org.project.</literal>, the name used is |
| <literal>BarFrobnicator</literal>. |
| </para> |
| <para> |
| For methods, signals and properties, if not specified, the name |
| defaults to the name of the method, signal or property. |
| </para> |
| <para> |
| 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). |
| </para> |
| <para> |
| If the value given by the <literal>org.gtk.GDBus.C.Name</literal> |
| annotation or the <option>--c-namespace</option> option contains |
| an underscore (sometimes called <emphasis>Ugly_Case</emphasis>), |
| 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 |
| <literal>net.MyCorp.MyApp.iSCSITarget</literal> with the value |
| <literal>iSCSI_Target</literal> the CamelCase form is |
| <literal>iSCSITarget</literal> while the lower-case form is |
| <literal>iscsi_target</literal>. If the annotation is used on the |
| method <literal>EjectTheiPod</literal> with the value |
| <literal>Eject_The_iPod</literal>, the lower-case form is |
| <literal>eject_the_ipod</literal>. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Generating Docbook documentation</title> |
| <para> |
| Each generated Docbook XML file (see the |
| <option>--generate-docbook</option> option for details) is a <ulink |
| url="http://www.docbook.org/tdg/en/html/refentry.html"><literal>RefEntry</literal></ulink> |
| article describing the D-Bus interface. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Options</title> |
| <para> |
| The following options are supported: |
| </para> |
| <variablelist> |
| |
| <varlistentry> |
| <term><option>-h</option>, <option>--help</option></term> |
| <listitem> |
| <para> |
| Show help and exit. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--xml-files</option> <replaceable>FILE</replaceable></term> |
| <listitem> |
| <para> |
| This option is deprecated; use positional arguments instead. |
| The D-Bus introspection XML file. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--interface-prefix</option> <replaceable>org.project.Prefix.</replaceable></term> |
| <listitem> |
| <para> |
| A prefix to strip from all D-Bus interface names when |
| calculating the typename for the C binding and the Docbook |
| <ulink |
| url="http://www.docbook.org/tdg/en/html/primary.html">sortas |
| attribute</ulink>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--generate-docbook</option> <replaceable>OUTFILES</replaceable></term> |
| <listitem> |
| <para> |
| Generate Docbook Documentation for each D-Bus interface and |
| put it in <filename>OUTFILES-NAME.xml</filename> where |
| <literal>NAME</literal> is a place-holder for the interface |
| name, e.g. <literal>net.Corp.FooBar</literal> and so on. |
| </para> |
| <para> |
| Pass <option>--output-directory</option> to specify the directory |
| to put the output files in. By default the current directory |
| will be used. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--generate-c-code</option> <replaceable>OUTFILES</replaceable></term> |
| <listitem> |
| <para> |
| Generate C code for all D-Bus interfaces and put it in |
| <filename>OUTFILES.c</filename> and |
| <filename>OUTFILES.h</filename> including any sub-directories. If you want the files to |
| be output in a different location use <option>--output-directory</option> as <filename>OUTFILES.h</filename> |
| including sub-directories will be referenced from <filename>OUTFILES.c</filename>. |
| </para> |
| <para> |
| The full paths would then be <literal>$(OUTDIR)/$(dirname $OUTFILES)/$(basename $OUTFILES).{c,h}</literal>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--c-namespace</option> <replaceable>YourProject</replaceable></term> |
| <listitem> |
| <para> |
| The namespace to use for generated C code. This is expected |
| to be in <ulink |
| url="http://en.wikipedia.org/wiki/CamelCase">CamelCase</ulink> |
| or <emphasis>Ugly_Case</emphasis> (see above). |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--pragma-once</option></term> |
| <listitem> |
| <para> |
| If this option is passed, the |
| <ulink url="https://en.wikipedia.org/wiki/Pragma_once">#pragma once</ulink> |
| preprocessor directive is used instead of include guards. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--c-generate-object-manager</option></term> |
| <listitem> |
| <para> |
| If this option is passed, suitable #GDBusObject, |
| #GDBusObjectProxy, #GDBusObjectSkeleton and |
| #GDBusObjectManagerClient subclasses are generated. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--c-generate-autocleanup</option> none|objects|all</term> |
| <listitem> |
| <para> |
| 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. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--output-directory</option> <replaceable>OUTDIR</replaceable></term> |
| <listitem> |
| <para> |
| Directory to output generated source to. Equivalent to changing directory before generation. |
| </para> |
| <para> |
| This option cannot be used with <option>--body</option>, |
| <option>--header</option>, <option>--interface-info-body</option> or |
| <option>--interface-info-header</option>; and |
| <option>--output</option> must be used. |
| </para> |
| |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--header</option></term> |
| <listitem> |
| <para> |
| 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 <option>--output</option>. |
| </para> |
| <para> |
| Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or |
| <option>--output-directory</option> are not allowed to be used along with |
| <option>--header</option> and <option>--body</option> options, because these options |
| are used to generate only one file. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--body</option></term> |
| <listitem> |
| <para> |
| 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 <option>--output</option>. |
| </para> |
| <para> |
| Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or |
| <option>--output-directory</option> are not allowed to be used along with |
| <option>--header</option> and <option>--body</option> options, because these options |
| are used to generate only one file. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--interface-info-header</option></term> |
| <listitem> |
| <para> |
| If this option is passed, it will generate the header code for the |
| <type>GDBusInterfaceInfo</type> structures only and will write it to |
| the disk by using the path and file name provided by |
| <option>--output</option>. |
| </para> |
| <para> |
| Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or |
| <option>--output-directory</option> are not allowed to be used along with |
| the <option>--interface-info-header</option> and |
| <option>--interface-info-body</option> options, because these options |
| are used to generate only one file. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--interface-info-body</option></term> |
| <listitem> |
| <para> |
| If this option is passed, it will generate the source code for the |
| <type>GDBusInterfaceInfo</type> structures only and will write it to |
| the disk by using the path and file name provided by |
| <option>--output</option>. |
| </para> |
| <para> |
| Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or |
| <option>--output-directory</option> are not allowed to be used along with |
| the <option>--interface-info-header</option> and |
| <option>--interface-info-body</option> options, because these options |
| are used to generate only one file. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--symbol-decorator</option> <replaceable>DECORATOR</replaceable></term> |
| <listitem> |
| <para> |
| If a <literal>DECORATOR</literal> is passed in with this option, all the |
| generated function prototypes in the generated header will be marked with |
| <literal>DECORATOR</literal>. This can be used, for instance, to export |
| symbols from code generated with <command>gdbus-codegen</command>. |
| This option is added in GLib-2.66 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--symbol-decorator-header</option> <replaceable>HEADER</replaceable></term> |
| <listitem> |
| <para> |
| If a <literal>HEADER</literal> is passed in with this option, the |
| generated header will put a <literal>#include HEADER</literal> before the rest of the |
| items, except for the inclusion guards or <literal>#pragma once</literal> |
| (if <option>--pragma-once</option> is used). This is used if using another header file is |
| needed for the decorator passed in via <option>--symbol-decorator</option> to be defined. |
| This option is added in GLib-2.66. |
| </para> |
| <para> |
| This option can only be used if <option>--symbol-decorator</option> is used. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--symbol-decorator-define</option> <replaceable>DEFINE</replaceable></term> |
| <listitem> |
| <para> |
| If a <literal>DEFINE</literal> is passed in with this option, the |
| generated source will add a <literal>#define DEFINE</literal> before the rest of the |
| items. This is used if a particular macro is needed to ensure the decorator |
| passed in via <option>--symbol-decorator</option> uses the correct definition when the |
| generated source is being compiled. This option is added in GLib-2.66. |
| </para> |
| <para> |
| This option can only be used if <option>--symbol-decorator</option> is used. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--output</option> <replaceable>OUTFILE</replaceable></term> |
| <listitem> |
| <para> |
| The full path where the header (<option>--header</option>, |
| <option>--interface-info-header</option>) or the source code |
| (<option>--body</option>, <option>--interface-info-body</option>) will |
| be written, using the path and filename provided by |
| <option>--output</option>. The full path could be something like |
| <literal>$($OUTFILE).{c,h}</literal>. |
| </para> |
| <para> |
| Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or |
| <option>--output-directory</option> is not allowed along with |
| <option>--output</option>, because the latter is used to generate only one file. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--annotate</option> <replaceable>ELEMENT</replaceable> <replaceable>KEY</replaceable> <replaceable>VALUE</replaceable></term> |
| <listitem> |
| <para> |
| 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: |
| </para> |
| <informalexample><programlisting><![CDATA[ |
| 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 |
| ]]></programlisting></informalexample> |
| <para> |
| Any UTF-8 string can be used for <replaceable>KEY</replaceable> and <replaceable>VALUE</replaceable>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--glib-min-required</option> <replaceable>VERSION</replaceable></term> |
| <listitem> |
| <para> |
| Specifies the minimum version of GLib which the code generated by |
| <command>gdbus-codegen</command> can depend on. This may be used to |
| make backwards-incompatible changes in the output or behaviour of |
| <command>gdbus-codegen</command> in future, which users may opt in to |
| by increasing the value they pass for <option>--glib-min-required</option>. |
| If this option is not passed, the output from <command>gdbus-codegen</command> |
| is guaranteed to be compatible with all versions of GLib from 2.30 |
| upwards, as that is when <command>gdbus-codegen</command> was first |
| released. |
| </para> |
| <para> |
| 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. |
| </para> |
| <para> |
| The version number must be of the form |
| <literal><replaceable>MAJOR</replaceable>.<replaceable>MINOR</replaceable>.<replaceable>MICRO</replaceable></literal>, |
| where all parts are integers. <replaceable>MINOR</replaceable> and |
| <replaceable>MICRO</replaceable> are optional. The version number may not be smaller |
| than <literal>2.30</literal>. |
| </para> |
| <para> |
| If the version number is <literal>2.64</literal> or greater, the generated code will |
| have the following features: (1) If a method has <literal>h</literal> (file |
| descriptor) parameter(s), a <type>GUnixFDList</type> parameter will exist in the |
| generated code for it (whereas previously the annotation |
| <literal>org.gtk.GDBus.C.UnixFD</literal> was required), and (2) Method call functions will |
| have two additional arguments to allow the user to specify <type>GDBusCallFlags</type> |
| and a timeout value, as is possible when using <function>g_dbus_proxy_call()</function>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--glib-max-allowed</option> <replaceable>VERSION</replaceable></term> |
| <listitem> |
| <para> |
| Specifies the maximum version of GLib which the code generated by |
| <command>gdbus-codegen</command> can depend on. This may be used to |
| ensure that code generated by <command>gdbus-codegen</command> is |
| compilable with specific older versions of GLib that your software has |
| to support. |
| </para> |
| <para> |
| The version number must be of the form |
| <literal><replaceable>MAJOR</replaceable>.<replaceable>MINOR</replaceable>.<replaceable>MICRO</replaceable></literal>, |
| where all parts are integers. <replaceable>MINOR</replaceable> and |
| <replaceable>MICRO</replaceable> are optional. The version number must |
| be greater than or equal to that passed to <option>--glib-min-required</option>. |
| It defaults to the version of GLib which provides this <command>gdbus-codegen</command>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| </variablelist> |
| </refsect1> |
| |
| <refsect1> |
| <title>Supported D-Bus Annotations</title> |
| <para> |
| The following D-Bus annotations are supported by |
| <command>gdbus-codegen</command>: |
| </para> |
| |
| <variablelist> |
| |
| <varlistentry> |
| <term><literal>org.freedesktop.DBus.Deprecated</literal></term> |
| <listitem> |
| <para> |
| Can be used on any <literal><interface></literal>, |
| <literal><method></literal>, |
| <literal><signal></literal> and |
| <literal><property></literal> element to specify that |
| the element is deprecated if its value is |
| <literal>true</literal>. Note that this annotation is |
| defined in the <ulink |
| url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus |
| specification</ulink> and can only assume the values |
| <literal>true</literal> and <literal>false</literal>. 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. |
| </para> |
| <para> |
| When generating C code, this annotation is used to add |
| #G_GNUC_DEPRECATED to generated functions for the element. |
| </para> |
| <para> |
| When generating Docbook XML, a deprecation warning will |
| appear along the documentation for the element. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>org.gtk.GDBus.Since</literal></term> |
| <listitem> |
| <para> |
| Can be used on any <literal><interface></literal>, |
| <literal><method></literal>, |
| <literal><signal></literal> and |
| <literal><property></literal> element to specify the |
| version (any free-form string but compared using a |
| version-aware sort function) the element appeared in. |
| </para> |
| <para> |
| When generating C code, this field is used to ensure |
| function pointer order for preserving ABI/API, see <xref |
| linkend="gdbus-code-stability"/>. |
| </para> |
| <para> |
| When generating Docbook XML, the value of this tag appears |
| in the documentation. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>org.gtk.GDBus.DocString</literal></term> |
| <listitem> |
| <para> |
| A string with Docbook content for documentation. This annotation can |
| be used on <literal><interface></literal>, |
| <literal><method></literal>, |
| <literal><signal></literal>, |
| <literal><property></literal> and |
| <literal><arg></literal> elements. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>org.gtk.GDBus.DocString.Short</literal></term> |
| <listitem> |
| <para> |
| A string with Docbook content for short/brief |
| documentation. This annotation can only be used on |
| <literal><interface></literal> elements. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>org.gtk.GDBus.C.Name</literal></term> |
| <listitem> |
| <para> |
| Can be used on any <literal><interface></literal>, |
| <literal><method></literal>, |
| <literal><signal></literal> and |
| <literal><property></literal> element to specify the |
| name to use when generating C code. The value is expected to |
| be in <ulink |
| url="http://en.wikipedia.org/wiki/CamelCase">CamelCase</ulink> |
| or <emphasis>Ugly_Case</emphasis> (see above). |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>org.gtk.GDBus.C.ForceGVariant</literal></term> |
| <listitem> |
| <para> |
| 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 <literal><arg></literal> and |
| <literal><property></literal> element. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>org.gtk.GDBus.C.UnixFD</literal></term> |
| <listitem> |
| <para> |
| If set to a non-empty string, the generated code will |
| include parameters to exchange file descriptors using the |
| #GUnixFDList type. This annotation can be used on |
| <literal><method></literal> elements. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| </variablelist> |
| |
| <para> |
| As an easier alternative to using the |
| <literal>org.gtk.GDBus.DocString</literal> annotation, note that |
| parser used by <command>gdbus-codegen</command> parses XML |
| comments in a way similar to <ulink |
| url="http://www.gtk.org/gtk-doc/">gtk-doc</ulink>: |
| <informalexample><programlisting><![CDATA[ |
| <!-- |
| 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> |
| |
| <!-- BazProperty: The docs for the property. --> |
| <property name="BazProperty" type="s" access="read"/> |
| </interface> |
| ]]></programlisting></informalexample> |
| </para> |
| <para> |
| Note that <literal><![CDATA[@since]]></literal> can be used in any inline |
| documentation bit (e.g. for interfaces, methods, signals and |
| properties) to set the <literal>org.gtk.GDBus.Since</literal> |
| annotation. For the <literal>org.gtk.GDBus.DocString</literal> |
| annotation (and inline comments), note that substrings of the form |
| <literal><![CDATA[#net.Corp.Bar]]></literal>, |
| <literal><![CDATA[net.Corp.Bar.FooMethod()]]></literal>, |
| <literal><![CDATA[#net.Corp.Bar::BarSignal]]></literal> and |
| <literal><![CDATA[#net.Corp.InlineDocs:BazProperty]]></literal> are all |
| expanded to links to the respective interface, method, signal and |
| property. |
| Additionally, substrings starting with <literal>@</literal> and <literal>%</literal> characters are rendered as |
| <ulink url="http://www.docbook.org/tdg/en/html/parameter.html">parameter</ulink> and |
| <ulink url="http://www.docbook.org/tdg/en/html/constant.html">constant</ulink> respectively. |
| </para> |
| <para> |
| If both XML comments and |
| <literal>org.gtk.GDBus.DocString</literal> or |
| <literal>org.gtk.GDBus.DocString.Short</literal> annotations are |
| present, the latter wins. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Example</title> |
| <para> |
| Consider the following D-Bus Introspection XML. |
| </para> |
| <informalexample><programlisting><![CDATA[ |
| <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> |
| |
| <signal name="Notification"> |
| <arg name="icon_blob" type="ay"/> |
| <arg name="height" type="i"/> |
| <arg name="messages" type="as"/> |
| </signal> |
| |
| <property name="Verbose" type="b" access="readwrite"/> |
| </interface> |
| </node> |
| ]]></programlisting> |
| </informalexample> |
| <para> |
| If <command>gdbus-codegen</command> is used on this file like this: |
| </para> |
| <informalexample><programlisting><![CDATA[ |
| gdbus-codegen --generate-c-code myapp-generated \ |
| --c-namespace MyApp \ |
| --interface-prefix net.corp.MyApp. \ |
| net.Corp.MyApp.Frobber.xml |
| ]]></programlisting></informalexample> |
| <para> |
| two files called |
| <filename>myapp-generated.[ch]</filename> are |
| generated. The files provide an abstract |
| #GTypeInterface<!-- -->-derived type called |
| <type>MyAppFrobber</type> as well as two instantiatable types with |
| the same name but suffixed with <type>Proxy</type> and |
| <type>Skeleton</type>. The generated file, roughly, contains the |
| following facilities: |
| </para> |
| <informalexample><programlisting><![CDATA[ |
| /* 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); |
| ]]></programlisting></informalexample> |
| <para> |
| 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: |
| </para> |
| <informaltable> |
| <tgroup cols="3"> |
| <thead> |
| <row> |
| <entry></entry> |
| <entry>Client</entry> |
| <entry>Server</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry>Types</entry> |
| <entry>Use <type>MyAppFrobberProxy</type></entry> |
| <entry>Any type implementing the <type>MyAppFrobber</type> interface</entry> |
| </row> |
| <row> |
| <entry>Methods</entry> |
| <entry>Use <function>m_a_f_hello_world()</function> to call.</entry> |
| <entry>Receive via the <function>handle_hello_world()</function> signal handler. Complete the call with <function>m_a_f_complete_hello_world()</function></entry> |
| </row> |
| <row> |
| <entry>Signals</entry> |
| <entry>Connect to the <function>::notification</function> GObject signal.</entry> |
| <entry>Use <function>m_a_f_emit_notification()</function> to emit signal.</entry> |
| </row> |
| <row> |
| <entry>Properties (Reading)</entry> |
| <entry>Use <function>m_a_f_get_verbose()</function> or <parameter>:verbose</parameter>.</entry> |
| <entry>Implement #GObject<!-- -->'s <function>get_property()</function> vfunc.</entry> |
| </row> |
| <row> |
| <entry>Properties (writing)</entry> |
| <entry>Use <function>m_a_f_set_verbose()</function> or <parameter>:verbose</parameter>.</entry> |
| <entry>Implement #GObject<!-- -->'s <function>set_property()</function> vfunc.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| |
| <refsect2> |
| <title>Client-side usage</title> |
| <para> |
| You can use the generated proxy type with the generated |
| constructors: |
| </para> |
| <informalexample><programlisting><![CDATA[ |
| 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); |
| ]]></programlisting></informalexample> |
| <para> |
| Instead of using the generic #GDBusProxy facilities, one can use |
| the generated methods such as |
| <function>my_app_frobber_call_hello_world()</function> to invoke |
| the <function>net.Corp.MyApp.Frobber.HelloWorld()</function> |
| D-Bus method, connect to the |
| <function>::notification</function> GObject signal to receive |
| the <function>net.Corp.MyApp.Frobber::Notification</function> |
| D-Bus signal and get/set the |
| <parameter>net.Corp.MyApp.Frobber:Verbose</parameter> D-Bus |
| Property using either the GObject property |
| <parameter>:verbose</parameter> or the |
| <function>my_app_get_verbose()</function> and |
| <function>my_app_set_verbose()</function> methods. Use the |
| standard #GObject::notify signal to listen to property changes. |
| </para> |
| <para> |
| Note that all property access is via #GDBusProxy<!-- -->'s |
| property cache so no I/O is ever done when reading properties. |
| Also note that setting a property will cause the |
| <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties.Set</ulink> 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. |
| </para> |
| </refsect2> |
| |
| <refsect2> |
| <title>Server-side usage</title> |
| <para> |
| The generated <type>MyAppFrobber</type> interface is designed so |
| it is easy to implement it in a #GObject |
| subclass. For example, to handle |
| <function>HelloWorld()</function> method invocations, set the |
| vfunc for <function>handle_hello_hello_world()</function> in the |
| <type>MyAppFrobberIface</type> structure. Similarly, to handle |
| the <parameter>net.Corp.MyApp.Frobber:Verbose</parameter> |
| property override the <parameter>:verbose</parameter> #GObject |
| property from the subclass. To emit a signal, use |
| e.g. <function>my_app_emit_signal()</function> or |
| g_signal_emit_by_name(). |
| </para> |
| <para> |
| Instead of subclassing, it is often easier to use the generated |
| <type>MyAppFrobberSkeleton</type> subclass. To handle incoming |
| method calls, use <function>g_signal_connect()</function> with |
| the <function>::handle-*</function> signals and instead of |
| overriding #GObject<!-- -->'s |
| <function>get_property()</function> and |
| <function>set_property()</function> vfuncs, use |
| g_object_get() and |
| g_object_set() or the generated property |
| getters and setters (the generated class has an internal |
| property bag implementation). |
| </para> |
| <informalexample><programlisting><![CDATA[ |
| 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 */ |
| } |
| ]]></programlisting></informalexample> |
| <para> |
| To facilitate atomic changesets (multiple properties changing at |
| the same time), #GObject::notify signals are queued up when |
| received. The queue is drained in an idle handler (which is called from the |
| <link linkend="g-main-context-push-thread-default">thread-default main loop</link> |
| of the thread where the skeleton object was |
| constructed) and will cause emissions of the <ulink |
| url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties::PropertiesChanged</ulink> |
| signal with all the properties that have changed. Use |
| g_dbus_interface_skeleton_flush() or |
| g_dbus_object_skeleton_flush() to empty the queue |
| immediately. Use g_object_freeze_notify() and |
| g_object_thaw_notify() for atomic changesets if on a different |
| thread. |
| </para> |
| </refsect2> |
| </refsect1> |
| |
| <refsect1> |
| <title>C Type Mapping</title> |
| <para> |
| Scalar types |
| (type-strings |
| <link linkend="G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</link>, |
| <link linkend="G-VARIANT-TYPE-BYTE:CAPS">'y'</link>, |
| <link linkend="G-VARIANT-TYPE-INT16:CAPS">'n'</link>, |
| <link linkend="G-VARIANT-TYPE-UINT16:CAPS">'q'</link>, |
| <link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link>, |
| <link linkend="G-VARIANT-TYPE-UINT32:CAPS">'u'</link>, |
| <link linkend="G-VARIANT-TYPE-INT64:CAPS">'x'</link>, |
| <link linkend="G-VARIANT-TYPE-UINT64:CAPS">'t'</link> and |
| <link linkend="G-VARIANT-TYPE-DOUBLE:CAPS">'d'</link>) |
| ), |
| strings (type-strings |
| <link linkend="G-VARIANT-TYPE-STRING:CAPS">'s'</link>, |
| <link linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link>, |
| <link linkend="G-VARIANT-TYPE-OBJECT-PATH:CAPS">'o'</link> and |
| <link linkend="G-VARIANT-TYPE-SIGNATURE:CAPS">'g'</link>) and |
| arrays of string (type-strings |
| <link linkend="G-VARIANT-TYPE-STRING-ARRAY:CAPS">'as'</link>, |
| <link linkend="G-VARIANT-TYPE-OBJECT-PATH-ARRAY:CAPS">'ao'</link> and |
| <link linkend="G-VARIANT-TYPE-BYTESTRING-ARRAY:CAPS">'aay'</link>) |
| are mapped to the natural types, |
| e.g. #gboolean, #gdouble, #gint, <link linkend="gchararray">gchar*</link>, |
| <link linkend="GStrv">gchar**</link> and |
| so on. Everything else is mapped to the #GVariant |
| type. |
| </para> |
| <para> |
| This automatic mapping can be turned off by using the annotation |
| <literal>org.gtk.GDBus.C.ForceGVariant</literal> - 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 <link linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link>) |
| for data that could have embedded NUL bytes. |
| </para> |
| </refsect1> |
| |
| <refsect1 id="gdbus-code-stability"> |
| <title>Stability Guarantees</title> |
| <para> |
| 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. |
| </para> |
| <para> |
| The ABI of the generated #GType<!-- -->s will be preserved only if |
| the <literal>org.gtk.GDBus.Since</literal> 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 <literal>org.gtk.GDBus.Since</literal> annotation using |
| a greater version number than previous versions. |
| </para> |
| <para> |
| The generated C code currently happens to be annotated with <ulink |
| url="http://www.gtk.org/gtk-doc/">gtk-doc</ulink> / <ulink |
| url="https://wiki.gnome.org/Projects/GObjectIntrospection">GObject |
| Introspection</ulink> comments / annotations. The layout and |
| contents might change in the future so no guarantees about |
| e.g. <literal>SECTION</literal> usage etc. is given. |
| </para> |
| <para> |
| While the generated Docbook for D-Bus interfaces isn't expected to |
| change, no guarantees are given at this point. |
| </para> |
| <para> |
| 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. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Bugs</title> |
| <para> |
| Please send bug reports to either the distribution bug tracker |
| or the upstream bug tracker at |
| <ulink url="https://gitlab.gnome.org/GNOME/glib/issues/new">https://gitlab.gnome.org/GNOME/glib/issues/new</ulink>. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>See also</title> |
| <para> |
| <citerefentry> |
| <refentrytitle>gdbus</refentrytitle><manvolnum>1</manvolnum> |
| </citerefentry> |
| </para> |
| </refsect1> |
| |
| </refentry> |
