| .. _gdbus-codegen(1): | |
| .. meta:: | |
| :copyright: Copyright 2011, 2013, 2016 Red Hat, Inc. | |
| :copyright: Copyright 2013, 2022 Emmanuele Bassi | |
| :copyright: Copyright 2017 Patrick Griffis | |
| :copyright: Copyright 2018 Iñigo Martínez | |
| :copyright: Copyright 2018, 2019 Endless Mobile, Inc. | |
| :copyright: Copyright 2020 Endless OS Foundation, LLC | |
| :copyright: Copyright 2020 Chun-wei Fan | |
| :license: LGPL-2.1-or-later | |
| .. | |
| This has to be duplicated from above to make it machine-readable by `reuse`: | |
| SPDX-FileCopyrightText: 2011, 2013, 2016 Red Hat, Inc. | |
| SPDX-FileCopyrightText: 2013, 2022 Emmanuele Bassi | |
| SPDX-FileCopyrightText: 2017 Patrick Griffis | |
| SPDX-FileCopyrightText: 2018 Iñigo Martínez | |
| SPDX-FileCopyrightText: 2018, 2019 Endless Mobile, Inc. | |
| SPDX-FileCopyrightText: 2020 Endless OS Foundation, LLC | |
| SPDX-FileCopyrightText: 2020 Chun-wei Fan | |
| SPDX-License-Identifier: LGPL-2.1-or-later | |
| ============= | |
| gdbus-codegen | |
| ============= | |
| -------------------------------------- | |
| D-Bus code and documentation generator | |
| -------------------------------------- | |
| SYNOPSIS | |
| -------- | |
| | **gdbus-codegen** | |
| | [--help] | |
| | [--interface-prefix *org.project.Prefix*] | |
| | [--header | --body | --interface-info-header | --interface-info-body | --generate-c-code *OUTFILES*] | |
| | [--c-namespace *YourProject*] | |
| | [--c-generate-object-manager] | |
| | [--c-generate-autocleanup none|objects|all] | |
| | [--output-directory *OUTDIR* | --output *OUTFILE*] | |
| | [--generate-docbook *OUTFILES*] | |
| | [--generate-rst *OUTFILES*] | |
| | [--pragma-once] | |
| | [--xml-files *FILE*] | |
| | [--symbol-decorator *DECORATOR* [--symbol-decorator-header *HEADER*] [--symbol-decorator-define *DEFINE*]] | |
| | [--annotate *ELEMENT* *KEY* *VALUE*]… | |
| | [--glib-min-required *VERSION*] | |
| | [--glib-max-allowed *VERSION*] | |
| | *FILE*… | |
| DESCRIPTION | |
| ----------- | |
| ``gdbus-codegen`` is used to generate code and/or documentation for one or more | |
| D-Bus interfaces. | |
| ``gdbus-codegen`` reads | |
| `D-Bus Introspection XML <https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format>`_ | |
| from files passed as additional arguments on the command line and generates | |
| output files. It currently supports generating C source code (via ``--body``) or | |
| header (via ``--header``) and DocBook XML (via ``--generate-docbook``). | |
| Alternatively, more restricted C source code and headers can be generated, which | |
| just contain the interface information (as ``GDBusInterfaceInfo`` structures) | |
| using ``--interface-info-body`` and ``--interface-info-header``. | |
| GENERATING C CODE | |
| ----------------- | |
| When generating C code, a ``GInterface`` derived type is generated for each | |
| D-Bus interface. Additionally, for every generated type, ``FooBar``, two | |
| concrete instantiatable types, ``FooBarProxy`` and ``FooBarSkeleton``, | |
| 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. | |
| For C code generation either ``--body`` that generates source code, ``--header`` | |
| that generates headers, ``--interface-info-body`` that generates interface | |
| information source code, or ``--interface-info-header`` that generates interface | |
| information headers, can be used. These options must be used along with | |
| ``--output``, which is used to specify the file to output to. | |
| Both files can be generated at the same time by using ``--generate-c-code``, but | |
| this option is deprecated. In this case ``--output`` cannot be used due to the | |
| generation of multiple files. Instead pass ``--output-directory`` 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 ``--interface-prefix`` and with the dots | |
| removed and initial characters capitalized. For example, for the D-Bus | |
| interface ``com.acme.Coyote`` the name used is ``ComAcmeCoyote``. For the D-Bus | |
| interface ``org.project.Bar.Frobnicator`` with ``--interface-prefix`` set to | |
| ``org.project.``, the name used is ``BarFrobnicator``. | |
| 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 ``org.gtk.GDBus.C.Name`` annotation or the | |
| ``--c-namespace`` 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 ``net.MyCorp.MyApp.iSCSITarget`` with the value | |
| ``iSCSI_Target`` the CamelCase form is ``iSCSITarget`` while the lower-case form | |
| is ``iscsi_target``. If the annotation is used on the method ``EjectTheiPod`` | |
| with the value ``Eject_The_iPod``, the lower-case form is ``eject_the_ipod``. | |
| GENERATING DOCBOOK DOCUMENTATION | |
| -------------------------------- | |
| Each generated DocBook XML file (see the ``--generate-docbook`` option for | |
| details) is a ``RefEntry`` article describing the D-Bus interface. (See the | |
| `DocBook documentation <https://tdg.docbook.org/tdg/4.5/refentry.html>`_.) | |
| GENERATING RESTRUCTUREDTEXT DOCUMENTATION | |
| ----------------------------------------- | |
| Each generated reStructuredText file (see the ``--generate-rst`` option for | |
| details) is a plain text | |
| `reStructuredText <https://docutils.sourceforge.io/rst.html>`_ document | |
| describing the D-Bus interface. | |
| OPTIONS | |
| ------- | |
| The following options are supported: | |
| ``-h``, ``--help`` | |
| Show help and exit. | |
| ``--xml-files`` *FILE* | |
| This option is deprecated; use positional arguments instead. The D-Bus | |
| introspection XML file. | |
| ``--interface-prefix`` *org.project.Prefix.* | |
| A prefix to strip from all D-Bus interface names when | |
| calculating the type name for the C binding and the DocBook ``sortas`` | |
| `attribute <https://tdg.docbook.org/tdg/4.5/primary.html>`_. | |
| ``--generate-docbook`` *OUTFILES* | |
| Generate DocBook Documentation for each D-Bus interface and put it in | |
| ``OUTFILES-NAME.xml`` where ``NAME`` is a placeholder for the interface | |
| name, e.g. ``net.Corp.FooBar`` and so on. | |
| Pass ``--output-directory`` to specify the directory to put the output files | |
| in. By default the current directory will be used. | |
| ``--generate-rst`` *OUTFILES* | |
| Generate reStructuredText Documentation for each D-Bus interface and put it in | |
| ``OUTFILES-NAME.rst`` where ``NAME`` is a placeholder for the interface | |
| name, e.g. ``net.Corp.FooBar`` and so on. | |
| Pass ``--output-directory`` to specify the directory to put the output files | |
| in. By default the current directory will be used. | |
| ``--generate-c-code`` *OUTFILES* | |
| Generate C code for all D-Bus interfaces and put it in ``OUTFILES.c`` and | |
| ``OUTFILES.h`` including any sub-directories. If you want the files to be | |
| output in a different location use ``--output-directory`` as ``OUTFILES.h`` | |
| including sub-directories will be referenced from ``OUTFILES.c``. | |
| The full paths would then be | |
| ``$(OUTDIR)/$(dirname $OUTFILES)/$(basename $OUTFILES).{c,h}``. | |
| ``--c-namespace`` *YourProject* | |
| The namespace to use for generated C code. This is expected to be in | |
| `CamelCase <https://en.wikipedia.org/wiki/Camel_case>`_ or *Ugly_Case* (see | |
| above). | |
| ``--pragma-once`` | |
| If this option is passed, the | |
| `#pragma once <https://en.wikipedia.org/wiki/Pragma_once>`_ preprocessor | |
| directive is used instead of include guards. | |
| ``--c-generate-object-manager`` | |
| If this option is passed, suitable ``GDBusObject``, ``GDBusObjectProxy``, | |
| ``GDBusObjectSkeleton`` and ``GDBusObjectManagerClient`` subclasses are | |
| generated. | |
| ``--c-generate-autocleanup`` none|objects|all | |
| 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. | |
| ``--output-directory`` *OUTDIR* | |
| Directory to output generated source to. Equivalent to changing directory | |
| before generation. | |
| This option cannot be used with ``--body``, ``--header``, | |
| ``--interface-info-body`` or ``--interface-info-header``; and ``--output`` | |
| must be used. | |
| ``--header`` | |
| 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 ``--output``. | |
| Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory`` | |
| are not allowed to be used along with ``--header`` and ``--body`` options, | |
| because these options are used to generate only one file. | |
| ``--body`` | |
| 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 ``--output``. | |
| Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory`` | |
| are not allowed to be used along with ``--header`` and ``--body`` options, | |
| because these options are used to generate only one file. | |
| ``--interface-info-header`` | |
| 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 ``--output``. | |
| Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory`` | |
| are not allowed to be used along with the ``--interface-info-header`` and | |
| ``--interface-info-body`` options, because these options are used to generate | |
| only one file. | |
| ``--interface-info-body`` | |
| 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 ``--output``. | |
| Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory`` | |
| are not allowed to be used along with the ``--interface-info-header`` and | |
| ``--interface-info-body`` options, because these options are used to generate | |
| only one file. | |
| ``--symbol-decorator`` *DECORATOR* | |
| If a ``DECORATOR`` is passed in with this option, all the generated function | |
| prototypes in the generated header will be marked with ``DECORATOR``. This can | |
| be used, for instance, to export symbols from code generated with | |
| ``gdbus-codegen``. | |
| This option was added in GLib 2.66. | |
| ``--symbol-decorator-header`` *HEADER* | |
| If a ``HEADER`` is passed in with this option, the generated header will put a | |
| ``#include HEADER`` before the rest of the items, except for the inclusion | |
| guards or ``#pragma once`` (if ``--pragma-once`` is used). This is used if | |
| using another header file is needed for the decorator passed in via | |
| ``--symbol-decorator`` to be defined. | |
| This option was added in GLib 2.66. | |
| This option can only be used if ``--symbol-decorator`` is used. | |
| ``--symbol-decorator-define`` *DEFINE* | |
| If a ``DEFINE`` is passed in with this option, the generated source will add a | |
| ``#define DEFINE`` before the rest of the items. This is used if a particular | |
| macro is needed to ensure the decorator passed in via ``--symbol-decorator`` | |
| uses the correct definition when the generated source is being compiled. | |
| This option was added in GLib 2.66. | |
| This option can only be used if ``--symbol-decorator`` is used. | |
| ``--output`` *OUTFILE* | |
| The full path where the header (``--header``, ``--interface-info-header``) or | |
| the source code (``--body``, ``--interface-info-body``) will be written, using | |
| the path and filename provided by ``--output``. The full path could be | |
| something like ``$($OUTFILE).{c,h}``. | |
| Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory`` | |
| is not allowed along with ``--output``, because the latter is used to generate | |
| only one file. | |
| Since GLib 2.80, if *OUTFILE* is the literal string ``-``, the header | |
| or source code will be written to standard output. | |
| For ``--body`` and ``--interface-info-body``, the generated code will not | |
| automatically ``#include`` a corresponding header file when writing to | |
| standard output, because there is no obvious name for that header file. | |
| This might make it necessary to use ``cc -include foo.h``, or generate a | |
| filename like ``foo-impl.h`` and ``#include`` it into a wrapper ``.c`` file. | |
| For ``--header`` and ``--interface-info-header``, there is no obvious | |
| name for a traditional multiple-inclusion guard when writing to standard | |
| output, so using the ``--pragma-once`` option is recommended. | |
| In the rare situation that the intended output filename starts with ``-``, | |
| it should be prefixed with ``./``. | |
| ``--annotate`` *ELEMENT* *KEY* *VALUE* | |
| 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:: | |
| 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 | |
| Any UTF-8 string can be used for *KEY* and *VALUE*. | |
| ``--glib-min-required`` *VERSION* | |
| 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 | |
| ``--glib-min-required``. 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 ``MAJOR.MINOR.MICRO``, where all parts | |
| are integers. ``MINOR`` and ``MICRO`` are optional. The version number may not | |
| be smaller than ``2.30``. | |
| If the version number is ``2.64`` or greater, the generated code will | |
| have the following features: | |
| 1. If a method has ``h`` (file descriptor) parameter(s), a ``GUnixFDList`` | |
| parameter will exist in the generated code for it (whereas previously the | |
| annotation ``org.gtk.GDBus.C.UnixFD`` 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 ``g_dbus_proxy_call()``. | |
| ``--glib-max-allowed`` *VERSION* | |
| 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 ``MAJOR.MINOR.MICRO``, where all parts | |
| are integers. ``MINOR`` and ``MICRO`` are optional. The version number must be | |
| greater than or equal to that passed to ``--glib-min-required``. | |
| It defaults to the version of GLib which provides this ``gdbus-codegen``. | |
| SUPPORTED D-BUS ANNOTATIONS | |
| --------------------------- | |
| The following D-Bus annotations are supported by ``gdbus-codegen``: | |
| ``org.freedesktop.DBus.Deprecated`` | |
| Can be used on any ``<interface>``, ``<method>``, ``<signal>`` and | |
| ``<property>`` element to specify that the element is deprecated if its value | |
| is ``true``. Note that this annotation is defined in the | |
| `D-Bus specification <https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format>`_ | |
| and can only assume the values ``true`` and ``false``. 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. | |
| ``org.gtk.GDBus.Since`` | |
| Can be used on any ``<interface>``, ``<method>``, ``<signal>`` and | |
| ``<property>`` 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 ‘STABILITY GUARANTEES’. | |
| When generating DocBook XML, the value of this tag appears in the | |
| documentation. | |
| ``org.gtk.GDBus.DocString`` | |
| A string with DocBook content for documentation. This annotation can | |
| be used on ``<interface>``, ``<method>``, ``<signal>``, ``<property>`` and | |
| ``<arg>`` elements. | |
| ``org.gtk.GDBus.DocString.Short`` | |
| A string with DocBook content for short/brief documentation. This annotation | |
| can only be used on ``<interface>`` elements. | |
| ``org.gtk.GDBus.C.Name`` | |
| Can be used on any ``<interface>``, ``<method>``, ``<signal>`` and | |
| ``<property>`` element to specify the name to use when generating C code. The | |
| value is expected to be in | |
| `CamelCase <https://en.wikipedia.org/wiki/Camel_case>`_ or *Ugly_Case* (see | |
| above). | |
| ``org.gtk.GDBus.C.ForceGVariant`` | |
| 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 ``<arg>`` and | |
| ``<property>`` element. | |
| ``org.gtk.GDBus.C.UnixFD`` | |
| 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 ``<method>`` elements. | |
| As an easier alternative to using the ``org.gtk.GDBus.DocString`` annotation, | |
| note that parser used by ``gdbus-codegen`` parses XML comments in a way similar | |
| to `gtk-doc <https://gitlab.gnome.org/GNOME/gtk-doc/>`_:: | |
| <!-- | |
| 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> | |
| Note that ``@since`` can be used in any inline documentation bit (e.g. for | |
| interfaces, methods, signals and properties) to set the ``org.gtk.GDBus.Since`` | |
| annotation. For the ``org.gtk.GDBus.DocString`` annotation (and inline | |
| comments), note that substrings of the form ``#net.Corp.Bar``, | |
| ``net.Corp.Bar.FooMethod()``, ``#net.Corp.Bar::BarSignal`` and | |
| ``#net.Corp.InlineDocs:BazProperty`` are all expanded to links to the respective | |
| interface, method, signal and property. Additionally, substrings starting with | |
| ``@`` and ``%`` characters are rendered as | |
| `parameter <https://tdg.docbook.org/tdg/4.5/parameter.html>`_ and | |
| `constant <https://tdg.docbook.org/tdg/4.5/constant.html>`_ respectively. | |
| If both XML comments and ``org.gtk.GDBus.DocString`` or | |
| ``org.gtk.GDBus.DocString.Short`` annotations are present, the latter wins. | |
| EXAMPLE | |
| ------- | |
| Consider the following D-Bus Introspection XML:: | |
| <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> | |
| If ``gdbus-codegen`` is used on this file like this:: | |
| gdbus-codegen --generate-c-code myapp-generated \ | |
| --c-namespace MyApp \ | |
| --interface-prefix net.corp.MyApp. \ | |
| net.Corp.MyApp.Frobber.xml | |
| two files called ``myapp-generated.[ch]`` are generated. The files provide an | |
| abstract ``GTypeInterface`` derived type called ``MyAppFrobber`` as well as two | |
| instantiatable types with the same name but suffixed with ``Proxy`` and | |
| ``Skeleton``. The generated file, roughly, contains the following facilities:: | |
| /* 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, | |
| gp ointer 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); | |
| 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: | |
| .. table:: | |
| :widths: auto | |
| ==================== ========================================================= ================================================================================================================= | |
| Symbol type Client Server | |
| ==================== ========================================================= ================================================================================================================= | |
| Types Use ``MyAppFrobberProxy``. Any type implementing the ``MyAppFrobber`` interface. | |
| Methods Use ``m_a_f_hello_world()`` to call. Receive via the ``handle_hello_world()`` signal handler. Complete the call with ``m_a_f_complete_hello_world()``. | |
| Signals Connect to the ``::notification`` signal. Use ``m_a_f_emit_notification()`` to emit signal. | |
| Properties (Reading) Use ``m_a_f_get_verbose()`` or the ``:verbose`` property. Implement the ``get_property()`` vfunc of ``GObject``. | |
| Properties (writing) Use ``m_a_f_set_verbose()`` or the ``:verbose`` property. Implement the ``set_property()`` vfunc of ``GObject``. | |
| ==================== ========================================================= ================================================================================================================= | |
| Client-side usage | |
| ^^^^^^^^^^^^^^^^^ | |
| You can use the generated proxy type with the generated constructors:: | |
| 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); | |
| Instead of using the generic ``GDBusProxy`` facilities, one can use the | |
| generated methods such as ``my_app_frobber_call_hello_world()`` to invoke | |
| the ``net.Corp.MyApp.Frobber.HelloWorld()`` D-Bus method, connect to the | |
| ``::notification`` ``GObject`` signal to receive the | |
| ``net.Corp.MyApp.Frobber::Notification`` D-Bus signal and get/set the | |
| ``net.Corp.MyApp.Frobber:Verbose`` D-Bus Property using either the ``GObject`` | |
| property ``:verbose`` or the ``my_app_get_verbose()`` and | |
| ``my_app_set_verbose()`` methods. Use the standard ``GObject::notify`` signal to | |
| listen to property changes. | |
| Note that all property access is via the ``GDBusProxy`` property cache so no I/O | |
| is ever done when reading properties. Also note that setting a property will | |
| cause the ``org.freedesktop.DBus.Properties.Set`` method | |
| (`documentation <https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties>`_) | |
| 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. | |
| Server-side usage | |
| ^^^^^^^^^^^^^^^^^ | |
| The generated ``MyAppFrobber`` interface is designed so it is easy to implement | |
| it in a ``GObject`` subclass. For example, to handle ``HelloWorld()`` method | |
| invocations, set the vfunc for ``handle_hello_hello_world()`` in the | |
| ``MyAppFrobberIface`` structure. Similarly, to handle the | |
| ``net.Corp.MyApp.Frobber:Verbose`` property override the ``:verbose`` | |
| ``GObject`` property from the subclass. To emit a signal, use e.g. | |
| ``my_app_emit_signal()`` or ``g_signal_emit_by_name()``. | |
| Instead of subclassing, it is often easier to use the generated | |
| ``MyAppFrobberSkeleton`` subclass. To handle incoming method calls, use | |
| ``g_signal_connect()`` with the ``::handle-*`` signals and instead of | |
| overriding the ``get_property()`` and ``set_property()`` vfuncs from | |
| ``GObject``, use ``g_object_get()`` and ``g_object_set()`` or the generated | |
| property getters and setters (the generated class has an internal property bag | |
| implementation). | |
| For example:: | |
| 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 */ | |
| } | |
| 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 thread-default main loop of the thread | |
| where the skeleton object was constructed) and will cause emissions of the | |
| ``org.freedesktop.DBus.Properties::PropertiesChanged`` | |
| (`documentation <https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties>`_) | |
| 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. | |
| C TYPE MAPPING | |
| -------------- | |
| 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 strings (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 | |
| ``org.gtk.GDBus.C.ForceGVariant`` — 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. | |
| STABILITY GUARANTEES | |
| -------------------- | |
| 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 their C ABI either. The ABI of | |
| the generated instance and class structures will be preserved as well. | |
| The ABI of the generated ``GType`` instances will be preserved only if the | |
| ``org.gtk.GDBus.Since`` annotation is used judiciously — this is because the | |
| VTable for the ``GInterface`` relies on function 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 the | |
| ``org.gtk.GDBus.Since`` annotation using a greater version number than previous | |
| versions. | |
| The generated C code currently happens to be annotated with | |
| `gtk-doc <https://gitlab.gnome.org/GNOME/gtk-doc/>`_ and | |
| `GObject Introspection <https://gi.readthedocs.io/en/latest/>`_ comments and | |
| annotations. The layout and contents might change in the future so no guarantees | |
| about e.g. ``SECTION`` usage etc. are 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 | |
| version control systems, nor it should be included in distributed source | |
| archives. | |
| BUGS | |
| ---- | |
| Please send bug reports to either the distribution bug tracker or the | |
| `upstream bug tracker <https://gitlab.gnome.org/GNOME/glib/issues/new>`_. | |
| SEE ALSO | |
| -------- | |
| `gdbus(1) <man:gdbus(1)>`_ |