1GDBUS-CODEGEN(1)                 User Commands                GDBUS-CODEGEN(1)
2
3
4

NAME

6       gdbus-codegen - D-Bus code and documentation generator
7

SYNOPSIS

9       gdbus-codegen [-h, --help] [--interface-prefix org.project.Prefix]
10                     [--generate-c-code OUTFILES] [--c-namespace YourProject]
11                     [--c-generate-object-manager]
12                     [--c-generate-autocleanup none|objects|all]
13                     [--output-directory OUTDIR] [--generate-docbook OUTFILES]
14                     [--pragma-once] [--xml-files FILE] [--header] [--body]
15                     [--interface-info-header] [--interface-info-body]
16                     [--symbol-decorator DECORATOR]
17                     [--symbol-decorator-header HEADER]
18                     [--symbol-decorator-define DEFINE] [--output OUTFILE]
19                     [--annotate ELEMENT KEY VALUE]...
20                     [--glib-min-required VERSION]
21                     [--glib-max-allowed VERSION] FILE [FILE...]
22

DESCRIPTION

24       gdbus-codegen is used to generate code and/or documentation for one or
25       more D-Bus interfaces.
26
27       gdbus-codegen reads D-Bus Introspection XML[1] from files passed as
28       additional arguments on the command line and generates output files. It
29       currently supports generating C source code (via --body) or header (via
30       --header) and Docbook XML (via --generate-docbook). Alternatively, more
31       restricted C source code and headers can be generated, which just
32       contain the interface information (as GDBusInterfaceInfo structures)
33       using --interface-info-body and --interface-info-header.
34

GENERATING C CODE

36       When generating C code, a #GInterface -derived type is generated for
37       each D-Bus interface. Additionally, for every generated type, FooBar,
38       two concrete instantiable types, FooBarProxy and FooBarSkeleton,
39       implementing said interface are also generated. The former is derived
40       from #GDBusProxy and intended for use on the client side while the
41       latter is derived from the #GDBusInterfaceSkeleton type making it easy
42       to export on a #GDBusConnection either directly or via a
43       #GDBusObjectManagerServer instance.
44
45       For C code generation either --body that generates source code,
46       --header that generates headers, --interface-info-body that generates
47       interface information source code, or --interface-info-header that
48       generates interface information headers, can be used. These options
49       must be used along with --output, which is used to specify the file to
50       output to.
51
52       Both files can be generated at the same time by using
53       --generate-c-code, but this option is deprecated. In this case --output
54       cannot be used due to the generation of multiple files. Instead pass
55       --output-directory to specify the directory to put the output files in.
56       By default the current directory will be used.
57
58       The name of each generated C type is derived from the D-Bus interface
59       name stripped with the prefix given with --interface-prefix and with
60       the dots removed and initial characters capitalized. For example, for
61       the D-Bus interface com.acme.Coyote the name used is ComAcmeCoyote. For
62       the D-Bus interface org.project.Bar.Frobnicator with --interface-prefix
63       org.project., the name used is BarFrobnicator.
64
65       For methods, signals and properties, if not specified, the name
66       defaults to the name of the method, signal or property.
67
68       Two forms of the name are used - the CamelCase form and the lower-case
69       form. The CamelCase form is used for the #GType and struct name, while
70       lower-case form is used in function names. The lower-case form is
71       calculated by converting from CamelCase to lower-case and inserting
72       underscores at word boundaries (using certain heuristics).
73
74       If the value given by the org.gtk.GDBus.C.Name annotation or the
75       --c-namespace option contains an underscore (sometimes called
76       Ugly_Case), then the camel-case name is derived by removing all
77       underscores, and the lower-case name is derived by lower-casing the
78       string. This is useful in some situations where abbreviations are used.
79       For example, if the annotation is used on the interface
80       net.MyCorp.MyApp.iSCSITarget with the value iSCSI_Target the CamelCase
81       form is iSCSITarget while the lower-case form is iscsi_target. If the
82       annotation is used on the method EjectTheiPod with the value
83       Eject_The_iPod, the lower-case form is eject_the_ipod.
84

GENERATING DOCBOOK DOCUMENTATION

86       Each generated Docbook XML file (see the --generate-docbook option for
87       details) is a RefEntry[2] article describing the D-Bus interface.
88

OPTIONS

90       The following options are supported:
91
92       -h, --help
93           Show help and exit.
94
95       --xml-files FILE
96           This option is deprecated; use positional arguments instead. The
97           D-Bus introspection XML file.
98
99       --interface-prefix org.project.Prefix.
100           A prefix to strip from all D-Bus interface names when calculating
101           the typename for the C binding and the Docbook sortas attribute[3].
102
103       --generate-docbook OUTFILES
104           Generate Docbook Documentation for each D-Bus interface and put it
105           in OUTFILES-NAME.xml where NAME is a place-holder for the interface
106           name, e.g.  net.Corp.FooBar and so on.
107
108           Pass --output-directory to specify the directory to put the output
109           files in. By default the current directory will be used.
110
111       --generate-c-code OUTFILES
112           Generate C code for all D-Bus interfaces and put it in OUTFILES.c
113           and OUTFILES.h including any sub-directories. If you want the files
114           to be output in a different location use --output-directory as
115           OUTFILES.h including sub-directories will be referenced from
116           OUTFILES.c.
117
118           The full paths would then be $(OUTDIR)/$(dirname
119           $OUTFILES)/$(basename $OUTFILES).{c,h}.
120
121       --c-namespace YourProject
122           The namespace to use for generated C code. This is expected to be
123           in CamelCase[4] or Ugly_Case (see above).
124
125       --pragma-once
126           If this option is passed, the #pragma once[5] preprocessor
127           directive is used instead of include guards.
128
129       --c-generate-object-manager
130           If this option is passed, suitable #GDBusObject, #GDBusObjectProxy,
131           #GDBusObjectSkeleton and #GDBusObjectManagerClient subclasses are
132           generated.
133
134       --c-generate-autocleanup none|objects|all
135           This option influences what types autocleanup functions are
136           generated for. 'none' means to not generate any autocleanup
137           functions. 'objects' means to generate them for object types, and
138           'all' means to generate them for object types and interfaces. The
139           default is 'objects' due to a corner case in backwards
140           compatibility with a few projects, but you should likely switch
141           your project to use 'all'. This option was added in GLib 2.50.
142
143       --output-directory OUTDIR
144           Directory to output generated source to. Equivalent to changing
145           directory before generation.
146
147           This option cannot be used with --body, --header,
148           --interface-info-body or --interface-info-header; and --output must
149           be used.
150
151       --header
152           If this option is passed, it will generate the header code and
153           write it to the disk by using the path and file name provided by
154           --output.
155
156           Using --generate-c-code, --generate-docbook or --output-directory
157           are not allowed to be used along with --header and --body options,
158           because these options are used to generate only one file.
159
160       --body
161           If this option is passed, it will generate the source code and
162           write it to the disk by using the path and file name provided by
163           --output.
164
165           Using --generate-c-code, --generate-docbook or --output-directory
166           are not allowed to be used along with --header and --body options,
167           because these options are used to generate only one file.
168
169       --interface-info-header
170           If this option is passed, it will generate the header code for the
171           GDBusInterfaceInfo structures only and will write it to the disk by
172           using the path and file name provided by --output.
173
174           Using --generate-c-code, --generate-docbook or --output-directory
175           are not allowed to be used along with the --interface-info-header
176           and --interface-info-body options, because these options are used
177           to generate only one file.
178
179       --interface-info-body
180           If this option is passed, it will generate the source code for the
181           GDBusInterfaceInfo structures only and will write it to the disk by
182           using the path and file name provided by --output.
183
184           Using --generate-c-code, --generate-docbook or --output-directory
185           are not allowed to be used along with the --interface-info-header
186           and --interface-info-body options, because these options are used
187           to generate only one file.
188
189       --symbol-decorator DECORATOR
190           If a DECORATOR is passed in with this option, all the generated
191           function prototypes in the generated header will be marked with
192           DECORATOR. This can be used, for instance, to export symbols from
193           code generated with gdbus-codegen. This option is added in
194           GLib-2.66
195
196       --symbol-decorator-header HEADER
197           If a HEADER is passed in with this option, the generated header
198           will put a #include HEADER before the rest of the items, except for
199           the inclusion guards or #pragma once (if --pragma-once is used).
200           This is used if using another header file is needed for the
201           decorator passed in via --symbol-decorator to be defined. This
202           option is added in GLib-2.66.
203
204           This option can only be used if --symbol-decorator is used.
205
206       --symbol-decorator-define DEFINE
207           If a DEFINE is passed in with this option, the generated source
208           will add a #define DEFINE before the rest of the items. This is
209           used if a particular macro is needed to ensure the decorator passed
210           in via --symbol-decorator uses the correct definition when the
211           generated source is being compiled. This option is added in
212           GLib-2.66.
213
214           This option can only be used if --symbol-decorator is used.
215
216       --output OUTFILE
217           The full path where the header (--header, --interface-info-header)
218           or the source code (--body, --interface-info-body) will be written,
219           using the path and filename provided by --output. The full path
220           could be something like $($OUTFILE).{c,h}.
221
222           Using --generate-c-code, --generate-docbook or --output-directory
223           is not allowed along with --output, because the latter is used to
224           generate only one file.
225
226       --annotate ELEMENT KEY VALUE
227           Used to inject D-Bus annotations into the given XML files. It can
228           be used with interfaces, methods, signals, properties and arguments
229           in the following way:
230
231               gdbus-codegen --c-namespace MyApp                           \
232                 --generate-c-code myapp-generated                         \
233                 --annotate "org.project.InterfaceName"                    \
234                   org.gtk.GDBus.C.Name MyFrobnicator                      \
235                 --annotate "org.project.InterfaceName:Property"           \
236                   bar bat                                                 \
237                 --annotate "org.project.InterfaceName.Method()"           \
238                   org.freedesktop.DBus.Deprecated true                    \
239                 --annotate "org.project.InterfaceName.Method()[arg_name]" \
240                   snake hiss                                              \
241                 --annotate "org.project.InterfaceName::Signal"            \
242                   cat meow                                                \
243                 --annotate "org.project.InterfaceName::Signal[arg_name]"  \
244                   dog wuff                                                \
245                 myapp-dbus-interfaces.xml
246           Any UTF-8 string can be used for KEY and VALUE.
247
248       --glib-min-required VERSION
249           Specifies the minimum version of GLib which the code generated by
250           gdbus-codegen can depend on. This may be used to make
251           backwards-incompatible changes in the output or behaviour of
252           gdbus-codegen in future, which users may opt in to by increasing
253           the value they pass for --glib-min-required. If this option is not
254           passed, the output from gdbus-codegen is guaranteed to be
255           compatible with all versions of GLib from 2.30 upwards, as that is
256           when gdbus-codegen was first released.
257
258           Note that some version parameters introduce incompatible changes:
259           all callers of the generated code might need to be updated, and if
260           the generated code is part of a library's API or ABI, then
261           increasing the version parameter can result in an API or ABI break.
262
263           The version number must be of the form MAJOR.MINOR.MICRO, where all
264           parts are integers.  MINOR and MICRO are optional. The version
265           number may not be smaller than 2.30.
266
267           If the version number is 2.64 or greater, the generated code will
268           have the following features: (1) If a method has h (file
269           descriptor) parameter(s), a GUnixFDList parameter will exist in the
270           generated code for it (whereas previously the annotation
271           org.gtk.GDBus.C.UnixFD was required), and (2) Method call functions
272           will have two additional arguments to allow the user to specify
273           GDBusCallFlags and a timeout value, as is possible when using
274           g_dbus_proxy_call().
275
276       --glib-max-allowed VERSION
277           Specifies the maximum version of GLib which the code generated by
278           gdbus-codegen can depend on. This may be used to ensure that code
279           generated by gdbus-codegen is compilable with specific older
280           versions of GLib that your software has to support.
281
282           The version number must be of the form MAJOR.MINOR.MICRO, where all
283           parts are integers.  MINOR and MICRO are optional. The version
284           number must be greater than or equal to that passed to
285           --glib-min-required. It defaults to the version of GLib which
286           provides this gdbus-codegen.
287

SUPPORTED D-BUS ANNOTATIONS

289       The following D-Bus annotations are supported by gdbus-codegen:
290
291       org.freedesktop.DBus.Deprecated
292           Can be used on any <interface>, <method>, <signal> and <property>
293           element to specify that the element is deprecated if its value is
294           true. Note that this annotation is defined in the D-Bus
295           specification[1] and can only assume the values true and false. In
296           particular, you cannot specify the version that the element was
297           deprecated in nor any helpful deprecation message. Such information
298           should be added to the element documentation instead.
299
300           When generating C code, this annotation is used to add
301           #G_GNUC_DEPRECATED to generated functions for the element.
302
303           When generating Docbook XML, a deprecation warning will appear
304           along the documentation for the element.
305
306       org.gtk.GDBus.Since
307           Can be used on any <interface>, <method>, <signal> and <property>
308           element to specify the version (any free-form string but compared
309           using a version-aware sort function) the element appeared in.
310
311           When generating C code, this field is used to ensure function
312           pointer order for preserving ABI/API, see the section called
313           “STABILITY GUARANTEES”.
314
315           When generating Docbook XML, the value of this tag appears in the
316           documentation.
317
318       org.gtk.GDBus.DocString
319           A string with Docbook content for documentation. This annotation
320           can be used on <interface>, <method>, <signal>, <property> and
321           <arg> elements.
322
323       org.gtk.GDBus.DocString.Short
324           A string with Docbook content for short/brief documentation. This
325           annotation can only be used on <interface> elements.
326
327       org.gtk.GDBus.C.Name
328           Can be used on any <interface>, <method>, <signal> and <property>
329           element to specify the name to use when generating C code. The
330           value is expected to be in CamelCase[4] or Ugly_Case (see above).
331
332       org.gtk.GDBus.C.ForceGVariant
333           If set to a non-empty string, a #GVariant instance will be used
334           instead of the natural C type. This annotation can be used on any
335           <arg> and <property> element.
336
337       org.gtk.GDBus.C.UnixFD
338           If set to a non-empty string, the generated code will include
339           parameters to exchange file descriptors using the #GUnixFDList
340           type. This annotation can be used on <method> elements.
341
342       As an easier alternative to using the org.gtk.GDBus.DocString
343       annotation, note that parser used by gdbus-codegen parses XML comments
344       in a way similar to gtk-doc[6]:
345
346       Note that @since can be used in any inline documentation bit (e.g. for
347       interfaces, methods, signals and properties) to set the
348       org.gtk.GDBus.Since annotation. For the org.gtk.GDBus.DocString
349       annotation (and inline comments), note that substrings of the form
350       #net.Corp.Bar, net.Corp.Bar.FooMethod(), #net.Corp.Bar::BarSignal and
351       #net.Corp.InlineDocs:BazProperty are all expanded to links to the
352       respective interface, method, signal and property. Additionally,
353       substrings starting with @ and % characters are rendered as
354       parameter[7] and constant[8] respectively.
355
356       If both XML comments and org.gtk.GDBus.DocString or
357       org.gtk.GDBus.DocString.Short annotations are present, the latter wins.
358

EXAMPLE

360       Consider the following D-Bus Introspection XML.
361
362           <node>
363             <interface name="net.Corp.MyApp.Frobber">
364               <method name="HelloWorld">
365                 <arg name="greeting" direction="in" type="s"/>
366                 <arg name="response" direction="out" type="s"/>
367               </method>
368
369               <signal name="Notification">
370                 <arg name="icon_blob" type="ay"/>
371                 <arg name="height" type="i"/>
372                 <arg name="messages" type="as"/>
373               </signal>
374
375               <property name="Verbose" type="b" access="readwrite"/>
376             </interface>
377           </node>
378
379       If gdbus-codegen is used on this file like this:
380
381           gdbus-codegen --generate-c-code myapp-generated       \
382                         --c-namespace MyApp                     \
383                         --interface-prefix net.corp.MyApp.      \
384                         net.Corp.MyApp.Frobber.xml
385
386       two files called myapp-generated.[ch] are generated. The files provide
387       an abstract #GTypeInterface -derived type called MyAppFrobber as well
388       as two instantiable types with the same name but suffixed with Proxy
389       and Skeleton. The generated file, roughly, contains the following
390       facilities:
391
392           /* GType macros for the three generated types */
393           #define MY_APP_TYPE_FROBBER (my_app_frobber_get_type ())
394           #define MY_APP_TYPE_FROBBER_SKELETON (my_app_frobber_skeleton_get_type ())
395           #define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ())
396
397           typedef struct _MyAppFrobber MyAppFrobber; /* Dummy typedef */
398
399           typedef struct
400           {
401             GTypeInterface parent_iface;
402
403             /* Signal handler for the ::notification signal */
404             void (*notification) (MyAppFrobber *proxy,
405                                   GVariant *icon_blob,
406                                   gint height,
407                                   const gchar* const *messages);
408
409             /* Signal handler for the ::handle-hello-world signal */
410             gboolean (*handle_hello_world) (MyAppFrobber *proxy,
411                                             GDBusMethodInvocation *invocation,
412                                             const gchar *greeting);
413           } MyAppFrobberIface;
414
415           /* Asynchronously calls HelloWorld() */
416           void
417           my_app_frobber_call_hello_world (MyAppFrobber *proxy,
418                                            const gchar *greeting,
419                                            GCancellable *cancellable,
420                                            GAsyncReadyCallback callback,
421                                            gpointer user_data);
422           gboolean
423           my_app_frobber_call_hello_world_finish (MyAppFrobber *proxy,
424                                                   gchar **out_response,
425                                                   GAsyncResult *res,
426                                                   GError **error);
427
428           /* Synchronously calls HelloWorld(). Blocks calling thread. */
429           gboolean
430           my_app_frobber_call_hello_world_sync (MyAppFrobber *proxy,
431                                                 const gchar *greeting,
432                                                 gchar **out_response,
433                                                 GCancellable *cancellable,
434                                                 GError **error);
435
436           /* Completes handling the HelloWorld() method call */
437           void
438           my_app_frobber_complete_hello_world (MyAppFrobber *object,
439                                                GDBusMethodInvocation *invocation,
440                                                const gchar *response);
441
442           /* Emits the ::notification signal / Notification() D-Bus signal */
443           void
444           my_app_frobber_emit_notification (MyAppFrobber *object,
445                                             GVariant *icon_blob,
446                                             gint height,
447                                             const gchar* const *messages);
448
449           /* Gets the :verbose GObject property / Verbose D-Bus property.
450            * Does no blocking I/O.
451            */
452           gboolean my_app_frobber_get_verbose (MyAppFrobber *object);
453
454           /* Sets the :verbose GObject property / Verbose D-Bus property.
455            * Does no blocking I/O.
456            */
457           void my_app_frobber_set_verbose (MyAppFrobber *object,
458                                            gboolean      value);
459
460           /* Gets the interface info */
461           GDBusInterfaceInfo *my_app_frobber_interface_info (void);
462
463           /* Creates a new skeleton object, ready to be exported */
464           MyAppFrobber *my_app_frobber_skeleton_new (void);
465
466           /* Client-side proxy constructors.
467            *
468            * Additionally, _new_for_bus(), _new_for_bus_finish() and
469            * _new_for_bus_sync() proxy constructors are also generated.
470            */
471           void
472           my_app_frobber_proxy_new        (GDBusConnection     *connection,
473                                            GDBusProxyFlags      flags,
474                                            const gchar         *name,
475                                            const gchar         *object_path,
476                                            GCancellable        *cancellable,
477                                            GAsyncReadyCallback  callback,
478                                            gpointer             user_data);
479           MyAppFrobber *
480           my_app_frobber_proxy_new_finish (GAsyncResult        *res,
481                                            GError             **error);
482           MyAppFrobber *
483           my_app_frobber_proxy_new_sync   (GDBusConnection     *connection,
484                                            GDBusProxyFlags      flags,
485                                            const gchar         *name,
486                                            const gchar         *object_path,
487                                            GCancellable        *cancellable,
488                                            GError             **error);
489
490       Thus, for every D-Bus method, there will be three C functions for
491       calling the method, one #GObject signal for handling an incoming call
492       and one C function for completing an incoming call. For every D-Bus
493       signal, there's one #GObject signal and one C function for emitting it.
494       For every D-Bus property, two C functions are generated (one setter,
495       one getter) and one #GObject property. The following table summarizes
496       the generated facilities and where they are applicable:
497
498       ┌───────────┬─────────────────────┬──────────────────────────────┐
499       │           │ Client              Server                       
500       ├───────────┼─────────────────────┼──────────────────────────────┤
501       │Types      │ Use                 │ Any type                     │
502       │           │ MyAppFrobberProxy   │ implementing the             │
503       │           │                     │ MyAppFrobber                 
504       │           │                     │ interface                    │
505       ├───────────┼─────────────────────┼──────────────────────────────┤
506       │Methods    │ Use                 │ Receive via the              │
507       │           │ m_a_f_hello_world() handle_hello_world()         
508       │           │ to call.            │ signal handler.              │
509       │           │                     │ Complete the call            │
510       │           │                     │ with                         │
511       │           │                     │ m_a_f_complete_hello_world() 
512       ├───────────┼─────────────────────┼──────────────────────────────┤
513       │Signals    │ Connect to the      │ Use                          │
514       │           │ ::notification      m_a_f_emit_notification() to │
515       │           │ GObject signal.     │ emit signal.                 │
516       ├───────────┼─────────────────────┼──────────────────────────────┤
517       │Properties │ Use                 │ Implement #GObject's         │
518       │(Reading)  │ m_a_f_get_verbose() get_property() vfunc.        │
519       │           │ or :verbose.        │                              │
520       ├───────────┼─────────────────────┼──────────────────────────────┤
521       │Properties │ Use                 │ Implement #GObject's         │
522       │(writing)  │ m_a_f_set_verbose() set_property() vfunc.        │
523       │           │ or :verbose.        │                              │
524       └───────────┴─────────────────────┴──────────────────────────────┘
525
526   Client-side usage
527       You can use the generated proxy type with the generated constructors:
528
529               MyAppFrobber *proxy;
530               GError *error;
531
532               error = NULL;
533               proxy = my_app_frobber_proxy_new_for_bus_sync (
534                           G_BUS_TYPE_SESSION,
535                           G_DBUS_PROXY_FLAGS_NONE,
536                           "net.Corp.MyApp",              /* bus name */
537                           "/net/Corp/MyApp/SomeFrobber", /* object */
538                           NULL,                          /* GCancellable* */
539                           &error);
540               /* do stuff with proxy */
541               g_object_unref (proxy);
542
543       Instead of using the generic #GDBusProxy facilities, one can use the
544       generated methods such as my_app_frobber_call_hello_world() to invoke
545       the net.Corp.MyApp.Frobber.HelloWorld() D-Bus method, connect to the
546       ::notification GObject signal to receive the
547       net.Corp.MyApp.Frobber::Notification D-Bus signal and get/set the
548       net.Corp.MyApp.Frobber:Verbose D-Bus Property using either the GObject
549       property :verbose or the my_app_get_verbose() and my_app_set_verbose()
550       methods. Use the standard #GObject::notify signal to listen to property
551       changes.
552
553       Note that all property access is via #GDBusProxy 's property cache so
554       no I/O is ever done when reading properties. Also note that setting a
555       property will cause the org.freedesktop.DBus.Properties.Set[9] method
556       to be called on the remote object. This call, however, is asynchronous
557       so setting a property won't block. Further, the change is delayed and
558       no error checking is possible.
559
560   Server-side usage
561       The generated MyAppFrobber interface is designed so it is easy to
562       implement it in a #GObject subclass. For example, to handle
563       HelloWorld() method invocations, set the vfunc for
564       handle_hello_hello_world() in the MyAppFrobberIface structure.
565       Similarly, to handle the net.Corp.MyApp.Frobber:Verbose property
566       override the :verbose #GObject property from the subclass. To emit a
567       signal, use e.g.  my_app_emit_signal() or g_signal_emit_by_name().
568
569       Instead of subclassing, it is often easier to use the generated
570       MyAppFrobberSkeleton subclass. To handle incoming method calls, use
571       g_signal_connect() with the ::handle-* signals and instead of
572       overriding #GObject 's get_property() and set_property() vfuncs, use
573       g_object_get() and g_object_set() or the generated property getters and
574       setters (the generated class has an internal property bag
575       implementation).
576
577           static gboolean
578           on_handle_hello_world (MyAppFrobber           *interface,
579                                  GDBusMethodInvocation  *invocation,
580                                  const gchar            *greeting,
581                                  gpointer                user_data)
582           {
583             if (g_strcmp0 (greeting, "Boo") != 0)
584               {
585                 gchar *response;
586                 response = g_strdup_printf ("Word! You said `%s'.", greeting);
587                 my_app_complete_hello_world (interface, invocation, response);
588                 g_free (response);
589               }
590             else
591               {
592                 g_dbus_method_invocation_return_error (invocation,
593                            MY_APP_ERROR,
594                            MY_APP_ERROR_NO_WHINING,
595                            "Hey, %s, there will be no whining!",
596                            g_dbus_method_invocation_get_sender (invocation));
597               }
598             return TRUE;
599           }
600
601             [...]
602
603             interface = my_app_frobber_skeleton_new ();
604             my_app_frobber_set_verbose (interface, TRUE);
605
606             g_signal_connect (interface,
607                               "handle-hello-world",
608                               G_CALLBACK (on_handle_hello_world),
609                               some_user_data);
610
611             [...]
612
613             error = NULL;
614             if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
615                                                    connection,
616                                                    "/path/of/dbus_object",
617                                                    &error))
618               {
619                 /* handle error */
620               }
621
622       To facilitate atomic changesets (multiple properties changing at the
623       same time), #GObject::notify signals are queued up when received. The
624       queue is drained in an idle handler (which is called from the
625       thread-default main loop of the thread where the skeleton object was
626       constructed) and will cause emissions of the
627       org.freedesktop.DBus.Properties::PropertiesChanged[9] signal with all
628       the properties that have changed. Use g_dbus_interface_skeleton_flush()
629       or g_dbus_object_skeleton_flush() to empty the queue immediately. Use
630       g_object_freeze_notify() and g_object_thaw_notify() for atomic
631       changesets if on a different thread.
632

C TYPE MAPPING

634       Scalar types (type-strings 'b', 'y', 'n', 'q', 'i', 'u', 'x', 't' and
635       'd') ), strings (type-strings 's', 'ay', 'o' and 'g') and arrays of
636       string (type-strings 'as', 'ao' and 'aay') are mapped to the natural
637       types, e.g. #gboolean, #gdouble, #gint, gchar*, gchar** and so on.
638       Everything else is mapped to the #GVariant type.
639
640       This automatic mapping can be turned off by using the annotation
641       org.gtk.GDBus.C.ForceGVariant - if used then a #GVariant is always
642       exchanged instead of the corresponding native C type. This annotation
643       may be convenient to use when using bytestrings (type-string 'ay') for
644       data that could have embedded NUL bytes.
645

STABILITY GUARANTEES

647       The generated C functions are guaranteed to not change their ABI that
648       is, if a method, signal or property does not change its signature in
649       the introspection XML, the generated C functions will not change its C
650       ABI either. The ABI of the generated instance and class structures will
651       be preserved as well.
652
653       The ABI of the generated #GType s will be preserved only if the
654       org.gtk.GDBus.Since annotation is used judiciously — this is because
655       the VTable for the #GInterface relies on functions pointers for signal
656       handlers. Specifically, if a D-Bus method, property or signal or is
657       added to a D-Bus interface, then ABI of the generated #GInterface type
658       is preserved if, and only if, each added method, property signal is
659       annotated with they org.gtk.GDBus.Since annotation using a greater
660       version number than previous versions.
661
662       The generated C code currently happens to be annotated with gtk-doc[6]
663       / GObject Introspection[10] comments / annotations. The layout and
664       contents might change in the future so no guarantees about e.g.
665       SECTION usage etc. is given.
666
667       While the generated Docbook for D-Bus interfaces isn't expected to
668       change, no guarantees are given at this point.
669
670       It is important to note that the generated code should not be checked
671       into revision control systems, nor it should be included in distributed
672       source archives.
673

BUGS

675       Please send bug reports to either the distribution bug tracker or the
676       upstream bug tracker at https://gitlab.gnome.org/GNOME/glib/issues/new.
677

SEE ALSO

679       gdbus(1)
680

NOTES

682        1. D-Bus Introspection XML
683           http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format
684
685        2. RefEntry
686           http://www.docbook.org/tdg/en/html/refentry.html
687
688        3. sortas attribute
689           http://www.docbook.org/tdg/en/html/primary.html
690
691        4. CamelCase
692           http://en.wikipedia.org/wiki/CamelCase
693
694        5. #pragma once
695           https://en.wikipedia.org/wiki/Pragma_once
696
697        6. gtk-doc
698           http://www.gtk.org/gtk-doc/
699
700        7. parameter
701           http://www.docbook.org/tdg/en/html/parameter.html
702
703        8. constant
704           http://www.docbook.org/tdg/en/html/constant.html
705
706        9. org.freedesktop.DBus.Properties.Set
707           http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties
708
709       10. GObject Introspection
710           https://wiki.gnome.org/Projects/GObjectIntrospection
711
712
713
714GIO                                                           GDBUS-CODEGEN(1)
Impressum