1<refentry id="gdbus-codegen" lang="en"> 2 3<refentryinfo> 4 <title>gdbus</title> 5 <productname>GIO</productname> 6 <authorgroup> 7 <author> 8 <contrib>Developer</contrib> 9 <firstname>David</firstname> 10 <surname>Zeuthen</surname> 11 <email>zeuthen@gmail.com</email> 12 </author> 13 </authorgroup> 14</refentryinfo> 15 16<refmeta> 17 <refentrytitle>gdbus-codegen</refentrytitle> 18 <manvolnum>1</manvolnum> 19 <refmiscinfo class="manual">User Commands</refmiscinfo> 20</refmeta> 21 22<refnamediv> 23 <refname>gdbus-codegen</refname> 24 <refpurpose>D-Bus code and documentation generator</refpurpose> 25</refnamediv> 26 27<refsynopsisdiv> 28 <cmdsynopsis> 29 <command>gdbus-codegen</command> 30 <arg><option>-h</option>, <option>--help</option></arg> 31 <arg><option>--interface-prefix</option> <replaceable>org.project.Prefix</replaceable></arg> 32 <arg><option>--generate-c-code</option> <replaceable>OUTFILES</replaceable></arg> 33 <arg><option>--c-namespace</option> <replaceable>YourProject</replaceable></arg> 34 <arg><option>--c-generate-object-manager</option></arg> 35 <arg><option>--c-generate-autocleanup</option> none|objects|all</arg> 36 <arg><option>--output-directory</option> <replaceable>OUTDIR</replaceable></arg> 37 <arg><option>--generate-docbook</option> <replaceable>OUTFILES</replaceable></arg> 38 <arg><option>--pragma-once</option></arg> 39 <arg><option>--xml-files</option> <replaceable>FILE</replaceable></arg> 40 <arg><option>--header</option></arg> 41 <arg><option>--body</option></arg> 42 <arg><option>--interface-info-header</option></arg> 43 <arg><option>--interface-info-body</option></arg> 44 <arg><option>--symbol-decorator</option> <replaceable>DECORATOR</replaceable></arg> 45 <arg><option>--symbol-decorator-header</option> <replaceable>HEADER</replaceable></arg> 46 <arg><option>--symbol-decorator-define</option> <replaceable>DEFINE</replaceable></arg> 47 <arg><option>--output</option> <replaceable>OUTFILE</replaceable></arg> 48 <group choice="plain" rep="repeat"> 49 <arg> 50 <option>--annotate</option> 51 <replaceable>ELEMENT</replaceable> 52 <replaceable>KEY</replaceable> 53 <replaceable>VALUE</replaceable> 54 </arg> 55 </group> 56 <arg><option>--glib-min-required</option> <replaceable>VERSION</replaceable></arg> 57 <arg><option>--glib-max-allowed</option> <replaceable>VERSION</replaceable></arg> 58 <arg choice="plain">FILE</arg> 59 <arg> 60 <arg choice="plain" rep="repeat">FILE</arg> 61 </arg> 62 </cmdsynopsis> 63</refsynopsisdiv> 64 65<refsect1> 66 <title>Description</title> 67 <para> 68 <command>gdbus-codegen</command> is used to generate code and/or 69 documentation for one or more D-Bus interfaces. 70 </para> 71 <para> 72 <command>gdbus-codegen</command> reads 73 <ulink 74 url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus 75 Introspection XML</ulink> from files passed as additional 76 arguments on the command line and generates output files. 77 It currently supports generating C source code (via 78 <option>--body</option>) or header (via <option>--header</option>) 79 and Docbook XML (via <option>--generate-docbook</option>). Alternatively, 80 more restricted C source code and headers can be generated, which just 81 contain the interface information (as <type>GDBusInterfaceInfo</type> 82 structures) using <option>--interface-info-body</option> and 83 <option>--interface-info-header</option>. 84 </para> 85</refsect1> 86 87<refsect1> 88 <title>Generating C code</title> 89 <para> 90 When generating C code, a 91 #GInterface<!-- -->-derived type is generated for each D-Bus 92 interface. Additionally, for every generated type, 93 <type>FooBar</type>, two concrete instantiatable types, 94 <type>FooBarProxy</type> and <type>FooBarSkeleton</type>, implementing 95 said interface are also generated. The former is derived from 96 #GDBusProxy and intended for use on the client side 97 while the latter is derived from the 98 #GDBusInterfaceSkeleton type making it easy to export on a 99 #GDBusConnection either directly or via a 100 #GDBusObjectManagerServer instance. 101 </para> 102 <para> 103 For C code generation either <option>--body</option> that 104 generates source code, <option>--header</option> that 105 generates headers, <option>--interface-info-body</option> that generates 106 interface information source code, or 107 <option>--interface-info-header</option> that generates interface information 108 headers, can be used. These options must be used along with 109 <option>--output</option>, which is used to specify the file to output to. 110 </para> 111 <para> 112 Both files can be generated at the same time by using 113 <option>--generate-c-code</option>, but this option is deprecated. 114 In this case <option>--output</option> cannot be used due to the 115 generation of multiple files. Instead pass 116 <option>--output-directory</option> to specify the directory to put 117 the output files in. By default the current directory will be used. 118 </para> 119 <para> 120 The name of each generated C type is derived from the D-Bus 121 interface name stripped with the prefix given with 122 <option>--interface-prefix</option> and with the dots removed and 123 initial characters capitalized. For example, for the D-Bus 124 interface <literal>com.acme.Coyote</literal> the name used is 125 <literal>ComAcmeCoyote</literal>. For the D-Bus interface 126 <literal>org.project.Bar.Frobnicator</literal> with 127 <option>--interface-prefix</option> 128 <literal>org.project.</literal>, the name used is 129 <literal>BarFrobnicator</literal>. 130 </para> 131 <para> 132 For methods, signals and properties, if not specified, the name 133 defaults to the name of the method, signal or property. 134 </para> 135 <para> 136 Two forms of the name are used - the CamelCase form and the 137 lower-case form. The CamelCase form is used for the #GType and 138 struct name, while lower-case form is used in function names. The 139 lower-case form is calculated by converting from CamelCase to 140 lower-case and inserting underscores at word boundaries (using 141 certain heuristics). 142 </para> 143 <para> 144 If the value given by the <literal>org.gtk.GDBus.C.Name</literal> 145 annotation or the <option>--c-namespace</option> option contains 146 an underscore (sometimes called <emphasis>Ugly_Case</emphasis>), 147 then the camel-case name is derived by removing all underscores, 148 and the lower-case name is derived by lower-casing the 149 string. This is useful in some situations where abbreviations are 150 used. For example, if the annotation is used on the interface 151 <literal>net.MyCorp.MyApp.iSCSITarget</literal> with the value 152 <literal>iSCSI_Target</literal> the CamelCase form is 153 <literal>iSCSITarget</literal> while the lower-case form is 154 <literal>iscsi_target</literal>. If the annotation is used on the 155 method <literal>EjectTheiPod</literal> with the value 156 <literal>Eject_The_iPod</literal>, the lower-case form is 157 <literal>eject_the_ipod</literal>. 158 </para> 159</refsect1> 160 161<refsect1> 162 <title>Generating Docbook documentation</title> 163 <para> 164 Each generated Docbook XML file (see the 165 <option>--generate-docbook</option> option for details) is a <ulink 166 url="http://www.docbook.org/tdg/en/html/refentry.html"><literal>RefEntry</literal></ulink> 167 article describing the D-Bus interface. 168 </para> 169</refsect1> 170 171<refsect1> 172 <title>Options</title> 173 <para> 174 The following options are supported: 175 </para> 176 <variablelist> 177 178 <varlistentry> 179 <term><option>-h</option>, <option>--help</option></term> 180 <listitem> 181 <para> 182 Show help and exit. 183 </para> 184 </listitem> 185 </varlistentry> 186 187 <varlistentry> 188 <term><option>--xml-files</option> <replaceable>FILE</replaceable></term> 189 <listitem> 190 <para> 191 This option is deprecated; use positional arguments instead. 192 The D-Bus introspection XML file. 193 </para> 194 </listitem> 195 </varlistentry> 196 197 <varlistentry> 198 <term><option>--interface-prefix</option> <replaceable>org.project.Prefix.</replaceable></term> 199 <listitem> 200 <para> 201 A prefix to strip from all D-Bus interface names when 202 calculating the typename for the C binding and the Docbook 203 <ulink 204 url="http://www.docbook.org/tdg/en/html/primary.html">sortas 205 attribute</ulink>. 206 </para> 207 </listitem> 208 </varlistentry> 209 210 <varlistentry> 211 <term><option>--generate-docbook</option> <replaceable>OUTFILES</replaceable></term> 212 <listitem> 213 <para> 214 Generate Docbook Documentation for each D-Bus interface and 215 put it in <filename>OUTFILES-NAME.xml</filename> where 216 <literal>NAME</literal> is a place-holder for the interface 217 name, e.g. <literal>net.Corp.FooBar</literal> and so on. 218 </para> 219 <para> 220 Pass <option>--output-directory</option> to specify the directory 221 to put the output files in. By default the current directory 222 will be used. 223 </para> 224 </listitem> 225 </varlistentry> 226 227 <varlistentry> 228 <term><option>--generate-c-code</option> <replaceable>OUTFILES</replaceable></term> 229 <listitem> 230 <para> 231 Generate C code for all D-Bus interfaces and put it in 232 <filename>OUTFILES.c</filename> and 233 <filename>OUTFILES.h</filename> including any sub-directories. If you want the files to 234 be output in a different location use <option>--output-directory</option> as <filename>OUTFILES.h</filename> 235 including sub-directories will be referenced from <filename>OUTFILES.c</filename>. 236 </para> 237 <para> 238 The full paths would then be <literal>$(OUTDIR)/$(dirname $OUTFILES)/$(basename $OUTFILES).{c,h}</literal>. 239 </para> 240 </listitem> 241 </varlistentry> 242 243 <varlistentry> 244 <term><option>--c-namespace</option> <replaceable>YourProject</replaceable></term> 245 <listitem> 246 <para> 247 The namespace to use for generated C code. This is expected 248 to be in <ulink 249 url="http://en.wikipedia.org/wiki/CamelCase">CamelCase</ulink> 250 or <emphasis>Ugly_Case</emphasis> (see above). 251 </para> 252 </listitem> 253 </varlistentry> 254 255 <varlistentry> 256 <term><option>--pragma-once</option></term> 257 <listitem> 258 <para> 259 If this option is passed, the 260 <ulink url="https://en.wikipedia.org/wiki/Pragma_once">#pragma once</ulink> 261 preprocessor directive is used instead of include guards. 262 </para> 263 </listitem> 264 </varlistentry> 265 266 <varlistentry> 267 <term><option>--c-generate-object-manager</option></term> 268 <listitem> 269 <para> 270 If this option is passed, suitable #GDBusObject, 271 #GDBusObjectProxy, #GDBusObjectSkeleton and 272 #GDBusObjectManagerClient subclasses are generated. 273 </para> 274 </listitem> 275 </varlistentry> 276 277 <varlistentry> 278 <term><option>--c-generate-autocleanup</option> none|objects|all</term> 279 <listitem> 280 <para> 281 This option influences what types autocleanup functions are 282 generated for. 'none' means to not generate any autocleanup functions. 283 'objects' means to generate them for object types, and 'all' means to 284 generate them for object types and interfaces. The default is 'objects' 285 due to a corner case in backwards compatibility with a few projects, 286 but you should likely switch your project to use 'all'. 287 This option was added in GLib 2.50. 288 </para> 289 </listitem> 290 </varlistentry> 291 292 <varlistentry> 293 <term><option>--output-directory</option> <replaceable>OUTDIR</replaceable></term> 294 <listitem> 295 <para> 296 Directory to output generated source to. Equivalent to changing directory before generation. 297 </para> 298 <para> 299 This option cannot be used with <option>--body</option>, 300 <option>--header</option>, <option>--interface-info-body</option> or 301 <option>--interface-info-header</option>; and 302 <option>--output</option> must be used. 303 </para> 304 305 </listitem> 306 </varlistentry> 307 308 <varlistentry> 309 <term><option>--header</option></term> 310 <listitem> 311 <para> 312 If this option is passed, it will generate the header code and write it to the disk by 313 using the path and file name provided by <option>--output</option>. 314 </para> 315 <para> 316 Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or 317 <option>--output-directory</option> are not allowed to be used along with 318 <option>--header</option> and <option>--body</option> options, because these options 319 are used to generate only one file. 320 </para> 321 </listitem> 322 </varlistentry> 323 324 <varlistentry> 325 <term><option>--body</option></term> 326 <listitem> 327 <para> 328 If this option is passed, it will generate the source code and write it to the disk by 329 using the path and file name provided by <option>--output</option>. 330 </para> 331 <para> 332 Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or 333 <option>--output-directory</option> are not allowed to be used along with 334 <option>--header</option> and <option>--body</option> options, because these options 335 are used to generate only one file. 336 </para> 337 </listitem> 338 </varlistentry> 339 340 <varlistentry> 341 <term><option>--interface-info-header</option></term> 342 <listitem> 343 <para> 344 If this option is passed, it will generate the header code for the 345 <type>GDBusInterfaceInfo</type> structures only and will write it to 346 the disk by using the path and file name provided by 347 <option>--output</option>. 348 </para> 349 <para> 350 Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or 351 <option>--output-directory</option> are not allowed to be used along with 352 the <option>--interface-info-header</option> and 353 <option>--interface-info-body</option> options, because these options 354 are used to generate only one file. 355 </para> 356 </listitem> 357 </varlistentry> 358 359 <varlistentry> 360 <term><option>--interface-info-body</option></term> 361 <listitem> 362 <para> 363 If this option is passed, it will generate the source code for the 364 <type>GDBusInterfaceInfo</type> structures only and will write it to 365 the disk by using the path and file name provided by 366 <option>--output</option>. 367 </para> 368 <para> 369 Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or 370 <option>--output-directory</option> are not allowed to be used along with 371 the <option>--interface-info-header</option> and 372 <option>--interface-info-body</option> options, because these options 373 are used to generate only one file. 374 </para> 375 </listitem> 376 </varlistentry> 377 378 <varlistentry> 379 <term><option>--symbol-decorator</option> <replaceable>DECORATOR</replaceable></term> 380 <listitem> 381 <para> 382 If a <literal>DECORATOR</literal> is passed in with this option, all the 383 generated function prototypes in the generated header will be marked with 384 <literal>DECORATOR</literal>. This can be used, for instance, to export 385 symbols from code generated with <command>gdbus-codegen</command>. 386 This option is added in GLib-2.66 387 </para> 388 </listitem> 389 </varlistentry> 390 391 <varlistentry> 392 <term><option>--symbol-decorator-header</option> <replaceable>HEADER</replaceable></term> 393 <listitem> 394 <para> 395 If a <literal>HEADER</literal> is passed in with this option, the 396 generated header will put a <literal>#include HEADER</literal> before the rest of the 397 items, except for the inclusion guards or <literal>#pragma once</literal> 398 (if <option>--pragma-once</option> is used). This is used if using another header file is 399 needed for the decorator passed in via <option>--symbol-decorator</option> to be defined. 400 This option is added in GLib-2.66. 401 </para> 402 <para> 403 This option can only be used if <option>--symbol-decorator</option> is used. 404 </para> 405 </listitem> 406 </varlistentry> 407 408 <varlistentry> 409 <term><option>--symbol-decorator-define</option> <replaceable>DEFINE</replaceable></term> 410 <listitem> 411 <para> 412 If a <literal>DEFINE</literal> is passed in with this option, the 413 generated source will add a <literal>#define DEFINE</literal> before the rest of the 414 items. This is used if a particular macro is needed to ensure the decorator 415 passed in via <option>--symbol-decorator</option> uses the correct definition when the 416 generated source is being compiled. This option is added in GLib-2.66. 417 </para> 418 <para> 419 This option can only be used if <option>--symbol-decorator</option> is used. 420 </para> 421 </listitem> 422 </varlistentry> 423 424 <varlistentry> 425 <term><option>--output</option> <replaceable>OUTFILE</replaceable></term> 426 <listitem> 427 <para> 428 The full path where the header (<option>--header</option>, 429 <option>--interface-info-header</option>) or the source code 430 (<option>--body</option>, <option>--interface-info-body</option>) will 431 be written, using the path and filename provided by 432 <option>--output</option>. The full path could be something like 433 <literal>$($OUTFILE).{c,h}</literal>. 434 </para> 435 <para> 436 Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or 437 <option>--output-directory</option> is not allowed along with 438 <option>--output</option>, because the latter is used to generate only one file. 439 </para> 440 </listitem> 441 </varlistentry> 442 443 <varlistentry> 444 <term><option>--annotate</option> <replaceable>ELEMENT</replaceable> <replaceable>KEY</replaceable> <replaceable>VALUE</replaceable></term> 445 <listitem> 446 <para> 447 Used to inject D-Bus annotations into the given XML 448 files. It can be used with interfaces, methods, signals, 449 properties and arguments in the following way: 450 </para> 451<informalexample><programlisting><![CDATA[ 452gdbus-codegen --c-namespace MyApp \ 453 --generate-c-code myapp-generated \ 454 --annotate "org.project.InterfaceName" \ 455 org.gtk.GDBus.C.Name MyFrobnicator \ 456 --annotate "org.project.InterfaceName:Property" \ 457 bar bat \ 458 --annotate "org.project.InterfaceName.Method()" \ 459 org.freedesktop.DBus.Deprecated true \ 460 --annotate "org.project.InterfaceName.Method()[arg_name]" \ 461 snake hiss \ 462 --annotate "org.project.InterfaceName::Signal" \ 463 cat meow \ 464 --annotate "org.project.InterfaceName::Signal[arg_name]" \ 465 dog wuff \ 466 myapp-dbus-interfaces.xml 467]]></programlisting></informalexample> 468 <para> 469 Any UTF-8 string can be used for <replaceable>KEY</replaceable> and <replaceable>VALUE</replaceable>. 470 </para> 471 </listitem> 472 </varlistentry> 473 474 <varlistentry> 475 <term><option>--glib-min-required</option> <replaceable>VERSION</replaceable></term> 476 <listitem> 477 <para> 478 Specifies the minimum version of GLib which the code generated by 479 <command>gdbus-codegen</command> can depend on. This may be used to 480 make backwards-incompatible changes in the output or behaviour of 481 <command>gdbus-codegen</command> in future, which users may opt in to 482 by increasing the value they pass for <option>--glib-min-required</option>. 483 If this option is not passed, the output from <command>gdbus-codegen</command> 484 is guaranteed to be compatible with all versions of GLib from 2.30 485 upwards, as that is when <command>gdbus-codegen</command> was first 486 released. 487 </para> 488 <para> 489 Note that some version parameters introduce incompatible changes: all callers 490 of the generated code might need to be updated, and if the generated code is part of 491 a library's API or ABI, then increasing the version parameter can result in an API 492 or ABI break. 493 </para> 494 <para> 495 The version number must be of the form 496 <literal><replaceable>MAJOR</replaceable>.<replaceable>MINOR</replaceable>.<replaceable>MICRO</replaceable></literal>, 497 where all parts are integers. <replaceable>MINOR</replaceable> and 498 <replaceable>MICRO</replaceable> are optional. The version number may not be smaller 499 than <literal>2.30</literal>. 500 </para> 501 <para> 502 If the version number is <literal>2.64</literal> or greater, the generated code will 503 have the following features: (1) If a method has <literal>h</literal> (file 504 descriptor) parameter(s), a <type>GUnixFDList</type> parameter will exist in the 505 generated code for it (whereas previously the annotation 506 <literal>org.gtk.GDBus.C.UnixFD</literal> was required), and (2) Method call functions will 507 have two additional arguments to allow the user to specify <type>GDBusCallFlags</type> 508 and a timeout value, as is possible when using <function>g_dbus_proxy_call()</function>. 509 </para> 510 </listitem> 511 </varlistentry> 512 513 <varlistentry> 514 <term><option>--glib-max-allowed</option> <replaceable>VERSION</replaceable></term> 515 <listitem> 516 <para> 517 Specifies the maximum version of GLib which the code generated by 518 <command>gdbus-codegen</command> can depend on. This may be used to 519 ensure that code generated by <command>gdbus-codegen</command> is 520 compilable with specific older versions of GLib that your software has 521 to support. 522 </para> 523 <para> 524 The version number must be of the form 525 <literal><replaceable>MAJOR</replaceable>.<replaceable>MINOR</replaceable>.<replaceable>MICRO</replaceable></literal>, 526 where all parts are integers. <replaceable>MINOR</replaceable> and 527 <replaceable>MICRO</replaceable> are optional. The version number must 528 be greater than or equal to that passed to <option>--glib-min-required</option>. 529 It defaults to the version of GLib which provides this <command>gdbus-codegen</command>. 530 </para> 531 </listitem> 532 </varlistentry> 533 534 </variablelist> 535</refsect1> 536 537<refsect1> 538 <title>Supported D-Bus Annotations</title> 539 <para> 540 The following D-Bus annotations are supported by 541 <command>gdbus-codegen</command>: 542 </para> 543 544 <variablelist> 545 546 <varlistentry> 547 <term><literal>org.freedesktop.DBus.Deprecated</literal></term> 548 <listitem> 549 <para> 550 Can be used on any <literal><interface></literal>, 551 <literal><method></literal>, 552 <literal><signal></literal> and 553 <literal><property></literal> element to specify that 554 the element is deprecated if its value is 555 <literal>true</literal>. Note that this annotation is 556 defined in the <ulink 557 url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus 558 specification</ulink> and can only assume the values 559 <literal>true</literal> and <literal>false</literal>. In 560 particular, you cannot specify the version that the element 561 was deprecated in nor any helpful deprecation message. Such 562 information should be added to the element documentation 563 instead. 564 </para> 565 <para> 566 When generating C code, this annotation is used to add 567 #G_GNUC_DEPRECATED to generated functions for the element. 568 </para> 569 <para> 570 When generating Docbook XML, a deprecation warning will 571 appear along the documentation for the element. 572 </para> 573 </listitem> 574 </varlistentry> 575 576 <varlistentry> 577 <term><literal>org.gtk.GDBus.Since</literal></term> 578 <listitem> 579 <para> 580 Can be used on any <literal><interface></literal>, 581 <literal><method></literal>, 582 <literal><signal></literal> and 583 <literal><property></literal> element to specify the 584 version (any free-form string but compared using a 585 version-aware sort function) the element appeared in. 586 </para> 587 <para> 588 When generating C code, this field is used to ensure 589 function pointer order for preserving ABI/API, see <xref 590 linkend="gdbus-code-stability"/>. 591 </para> 592 <para> 593 When generating Docbook XML, the value of this tag appears 594 in the documentation. 595 </para> 596 </listitem> 597 </varlistentry> 598 599 <varlistentry> 600 <term><literal>org.gtk.GDBus.DocString</literal></term> 601 <listitem> 602 <para> 603 A string with Docbook content for documentation. This annotation can 604 be used on <literal><interface></literal>, 605 <literal><method></literal>, 606 <literal><signal></literal>, 607 <literal><property></literal> and 608 <literal><arg></literal> elements. 609 </para> 610 </listitem> 611 </varlistentry> 612 613 <varlistentry> 614 <term><literal>org.gtk.GDBus.DocString.Short</literal></term> 615 <listitem> 616 <para> 617 A string with Docbook content for short/brief 618 documentation. This annotation can only be used on 619 <literal><interface></literal> elements. 620 </para> 621 </listitem> 622 </varlistentry> 623 624 <varlistentry> 625 <term><literal>org.gtk.GDBus.C.Name</literal></term> 626 <listitem> 627 <para> 628 Can be used on any <literal><interface></literal>, 629 <literal><method></literal>, 630 <literal><signal></literal> and 631 <literal><property></literal> element to specify the 632 name to use when generating C code. The value is expected to 633 be in <ulink 634 url="http://en.wikipedia.org/wiki/CamelCase">CamelCase</ulink> 635 or <emphasis>Ugly_Case</emphasis> (see above). 636 </para> 637 </listitem> 638 </varlistentry> 639 640 <varlistentry> 641 <term><literal>org.gtk.GDBus.C.ForceGVariant</literal></term> 642 <listitem> 643 <para> 644 If set to a non-empty string, a #GVariant instance will 645 be used instead of the natural C type. This annotation can 646 be used on any <literal><arg></literal> and 647 <literal><property></literal> element. 648 </para> 649 </listitem> 650 </varlistentry> 651 652 <varlistentry> 653 <term><literal>org.gtk.GDBus.C.UnixFD</literal></term> 654 <listitem> 655 <para> 656 If set to a non-empty string, the generated code will 657 include parameters to exchange file descriptors using the 658 #GUnixFDList type. This annotation can be used on 659 <literal><method></literal> elements. 660 </para> 661 </listitem> 662 </varlistentry> 663 664 </variablelist> 665 666 <para> 667 As an easier alternative to using the 668 <literal>org.gtk.GDBus.DocString</literal> annotation, note that 669 parser used by <command>gdbus-codegen</command> parses XML 670 comments in a way similar to <ulink 671 url="http://www.gtk.org/gtk-doc/">gtk-doc</ulink>: 672<informalexample><programlisting><![CDATA[ 673<!-- 674 net.Corp.Bar: 675 @short_description: A short description 676 677 A <emphasis>longer</emphasis> description. 678 679 This is a new paragraph. 680--> 681<interface name="net.corp.Bar"> 682 <!-- 683 FooMethod: 684 @greeting: The docs for greeting parameter. 685 @response: The docs for response parameter. 686 687 The docs for the actual method. 688 --> 689 <method name="FooMethod"> 690 <arg name="greeting" direction="in" type="s"/> 691 <arg name="response" direction="out" type="s"/> 692 </method> 693 694 <!-- 695 BarSignal: 696 @blah: The docs for blah parameter. 697 @boo: The docs for boo parameter. 698 @since: 2.30 699 700 The docs for the actual signal. 701 --> 702 <signal name="BarSignal"> 703 <arg name="blah" type="s"/> 704 <arg name="boo" type="s"/> 705 </signal> 706 707 <!-- BazProperty: The docs for the property. --> 708 <property name="BazProperty" type="s" access="read"/> 709</interface> 710]]></programlisting></informalexample> 711 </para> 712 <para> 713 Note that <literal><![CDATA[@since]]></literal> can be used in any inline 714 documentation bit (e.g. for interfaces, methods, signals and 715 properties) to set the <literal>org.gtk.GDBus.Since</literal> 716 annotation. For the <literal>org.gtk.GDBus.DocString</literal> 717 annotation (and inline comments), note that substrings of the form 718 <literal><![CDATA[#net.Corp.Bar]]></literal>, 719 <literal><![CDATA[net.Corp.Bar.FooMethod()]]></literal>, 720 <literal><![CDATA[#net.Corp.Bar::BarSignal]]></literal> and 721 <literal><![CDATA[#net.Corp.InlineDocs:BazProperty]]></literal> are all 722 expanded to links to the respective interface, method, signal and 723 property. 724 Additionally, substrings starting with <literal>@</literal> and <literal>%</literal> characters are rendered as 725 <ulink url="http://www.docbook.org/tdg/en/html/parameter.html">parameter</ulink> and 726 <ulink url="http://www.docbook.org/tdg/en/html/constant.html">constant</ulink> respectively. 727 </para> 728 <para> 729 If both XML comments and 730 <literal>org.gtk.GDBus.DocString</literal> or 731 <literal>org.gtk.GDBus.DocString.Short</literal> annotations are 732 present, the latter wins. 733 </para> 734</refsect1> 735 736<refsect1> 737 <title>Example</title> 738 <para> 739 Consider the following D-Bus Introspection XML. 740 </para> 741 <informalexample><programlisting><![CDATA[ 742<node> 743 <interface name="net.Corp.MyApp.Frobber"> 744 <method name="HelloWorld"> 745 <arg name="greeting" direction="in" type="s"/> 746 <arg name="response" direction="out" type="s"/> 747 </method> 748 749 <signal name="Notification"> 750 <arg name="icon_blob" type="ay"/> 751 <arg name="height" type="i"/> 752 <arg name="messages" type="as"/> 753 </signal> 754 755 <property name="Verbose" type="b" access="readwrite"/> 756 </interface> 757</node> 758]]></programlisting> 759 </informalexample> 760 <para> 761 If <command>gdbus-codegen</command> is used on this file like this: 762 </para> 763<informalexample><programlisting><![CDATA[ 764gdbus-codegen --generate-c-code myapp-generated \ 765 --c-namespace MyApp \ 766 --interface-prefix net.corp.MyApp. \ 767 net.Corp.MyApp.Frobber.xml 768]]></programlisting></informalexample> 769 <para> 770 two files called 771 <filename>myapp-generated.[ch]</filename> are 772 generated. The files provide an abstract 773 #GTypeInterface<!-- -->-derived type called 774 <type>MyAppFrobber</type> as well as two instantiatable types with 775 the same name but suffixed with <type>Proxy</type> and 776 <type>Skeleton</type>. The generated file, roughly, contains the 777 following facilities: 778 </para> 779<informalexample><programlisting><![CDATA[ 780/* GType macros for the three generated types */ 781#define MY_APP_TYPE_FROBBER (my_app_frobber_get_type ()) 782#define MY_APP_TYPE_FROBBER_SKELETON (my_app_frobber_skeleton_get_type ()) 783#define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ()) 784 785typedef struct _MyAppFrobber MyAppFrobber; /* Dummy typedef */ 786 787typedef struct 788{ 789 GTypeInterface parent_iface; 790 791 /* Signal handler for the ::notification signal */ 792 void (*notification) (MyAppFrobber *proxy, 793 GVariant *icon_blob, 794 gint height, 795 const gchar* const *messages); 796 797 /* Signal handler for the ::handle-hello-world signal */ 798 gboolean (*handle_hello_world) (MyAppFrobber *proxy, 799 GDBusMethodInvocation *invocation, 800 const gchar *greeting); 801} MyAppFrobberIface; 802 803/* Asynchronously calls HelloWorld() */ 804void 805my_app_frobber_call_hello_world (MyAppFrobber *proxy, 806 const gchar *greeting, 807 GCancellable *cancellable, 808 GAsyncReadyCallback callback, 809 gpointer user_data); 810gboolean 811my_app_frobber_call_hello_world_finish (MyAppFrobber *proxy, 812 gchar **out_response, 813 GAsyncResult *res, 814 GError **error); 815 816/* Synchronously calls HelloWorld(). Blocks calling thread. */ 817gboolean 818my_app_frobber_call_hello_world_sync (MyAppFrobber *proxy, 819 const gchar *greeting, 820 gchar **out_response, 821 GCancellable *cancellable, 822 GError **error); 823 824/* Completes handling the HelloWorld() method call */ 825void 826my_app_frobber_complete_hello_world (MyAppFrobber *object, 827 GDBusMethodInvocation *invocation, 828 const gchar *response); 829 830/* Emits the ::notification signal / Notification() D-Bus signal */ 831void 832my_app_frobber_emit_notification (MyAppFrobber *object, 833 GVariant *icon_blob, 834 gint height, 835 const gchar* const *messages); 836 837/* Gets the :verbose GObject property / Verbose D-Bus property. 838 * Does no blocking I/O. 839 */ 840gboolean my_app_frobber_get_verbose (MyAppFrobber *object); 841 842/* Sets the :verbose GObject property / Verbose D-Bus property. 843 * Does no blocking I/O. 844 */ 845void my_app_frobber_set_verbose (MyAppFrobber *object, 846 gboolean value); 847 848/* Gets the interface info */ 849GDBusInterfaceInfo *my_app_frobber_interface_info (void); 850 851/* Creates a new skeleton object, ready to be exported */ 852MyAppFrobber *my_app_frobber_skeleton_new (void); 853 854/* Client-side proxy constructors. 855 * 856 * Additionally, _new_for_bus(), _new_for_bus_finish() and 857 * _new_for_bus_sync() proxy constructors are also generated. 858 */ 859void 860my_app_frobber_proxy_new (GDBusConnection *connection, 861 GDBusProxyFlags flags, 862 const gchar *name, 863 const gchar *object_path, 864 GCancellable *cancellable, 865 GAsyncReadyCallback callback, 866 gpointer user_data); 867MyAppFrobber * 868my_app_frobber_proxy_new_finish (GAsyncResult *res, 869 GError **error); 870MyAppFrobber * 871my_app_frobber_proxy_new_sync (GDBusConnection *connection, 872 GDBusProxyFlags flags, 873 const gchar *name, 874 const gchar *object_path, 875 GCancellable *cancellable, 876 GError **error); 877]]></programlisting></informalexample> 878 <para> 879 Thus, for every D-Bus method, there will be three C functions for 880 calling the method, one #GObject signal for handling an incoming 881 call and one C function for completing an incoming call. For every 882 D-Bus signal, there's one #GObject signal and one C function for 883 emitting it. For every D-Bus property, two C functions are 884 generated (one setter, one getter) and one #GObject property. The 885 following table summarizes the generated facilities and where they 886 are applicable: 887 </para> 888 <informaltable> 889 <tgroup cols="3"> 890 <thead> 891 <row> 892 <entry></entry> 893 <entry>Client</entry> 894 <entry>Server</entry> 895 </row> 896 </thead> 897 <tbody> 898 <row> 899 <entry>Types</entry> 900 <entry>Use <type>MyAppFrobberProxy</type></entry> 901 <entry>Any type implementing the <type>MyAppFrobber</type> interface</entry> 902 </row> 903 <row> 904 <entry>Methods</entry> 905 <entry>Use <function>m_a_f_hello_world()</function> to call.</entry> 906 <entry>Receive via the <function>handle_hello_world()</function> signal handler. Complete the call with <function>m_a_f_complete_hello_world()</function></entry> 907 </row> 908 <row> 909 <entry>Signals</entry> 910 <entry>Connect to the <function>::notification</function> GObject signal.</entry> 911 <entry>Use <function>m_a_f_emit_notification()</function> to emit signal.</entry> 912 </row> 913 <row> 914 <entry>Properties (Reading)</entry> 915 <entry>Use <function>m_a_f_get_verbose()</function> or <parameter>:verbose</parameter>.</entry> 916 <entry>Implement #GObject<!-- -->'s <function>get_property()</function> vfunc.</entry> 917 </row> 918 <row> 919 <entry>Properties (writing)</entry> 920 <entry>Use <function>m_a_f_set_verbose()</function> or <parameter>:verbose</parameter>.</entry> 921 <entry>Implement #GObject<!-- -->'s <function>set_property()</function> vfunc.</entry> 922 </row> 923 </tbody> 924 </tgroup> 925 </informaltable> 926 927 <refsect2> 928 <title>Client-side usage</title> 929 <para> 930 You can use the generated proxy type with the generated 931 constructors: 932 </para> 933 <informalexample><programlisting><![CDATA[ 934 MyAppFrobber *proxy; 935 GError *error; 936 937 error = NULL; 938 proxy = my_app_frobber_proxy_new_for_bus_sync ( 939 G_BUS_TYPE_SESSION, 940 G_DBUS_PROXY_FLAGS_NONE, 941 "net.Corp.MyApp", /* bus name */ 942 "/net/Corp/MyApp/SomeFrobber", /* object */ 943 NULL, /* GCancellable* */ 944 &error); 945 /* do stuff with proxy */ 946 g_object_unref (proxy); 947]]></programlisting></informalexample> 948 <para> 949 Instead of using the generic #GDBusProxy facilities, one can use 950 the generated methods such as 951 <function>my_app_frobber_call_hello_world()</function> to invoke 952 the <function>net.Corp.MyApp.Frobber.HelloWorld()</function> 953 D-Bus method, connect to the 954 <function>::notification</function> GObject signal to receive 955 the <function>net.Corp.MyApp.Frobber::Notification</function> 956 D-Bus signal and get/set the 957 <parameter>net.Corp.MyApp.Frobber:Verbose</parameter> D-Bus 958 Property using either the GObject property 959 <parameter>:verbose</parameter> or the 960 <function>my_app_get_verbose()</function> and 961 <function>my_app_set_verbose()</function> methods. Use the 962 standard #GObject::notify signal to listen to property changes. 963 </para> 964 <para> 965 Note that all property access is via #GDBusProxy<!-- -->'s 966 property cache so no I/O is ever done when reading properties. 967 Also note that setting a property will cause the 968 <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties.Set</ulink> method to be 969 called on the remote object. This call, however, is asynchronous 970 so setting a property won't block. Further, the change is 971 delayed and no error checking is possible. 972 </para> 973 </refsect2> 974 975 <refsect2> 976 <title>Server-side usage</title> 977 <para> 978 The generated <type>MyAppFrobber</type> interface is designed so 979 it is easy to implement it in a #GObject 980 subclass. For example, to handle 981 <function>HelloWorld()</function> method invocations, set the 982 vfunc for <function>handle_hello_hello_world()</function> in the 983 <type>MyAppFrobberIface</type> structure. Similarly, to handle 984 the <parameter>net.Corp.MyApp.Frobber:Verbose</parameter> 985 property override the <parameter>:verbose</parameter> #GObject 986 property from the subclass. To emit a signal, use 987 e.g. <function>my_app_emit_signal()</function> or 988 g_signal_emit_by_name(). 989 </para> 990 <para> 991 Instead of subclassing, it is often easier to use the generated 992 <type>MyAppFrobberSkeleton</type> subclass. To handle incoming 993 method calls, use <function>g_signal_connect()</function> with 994 the <function>::handle-*</function> signals and instead of 995 overriding #GObject<!-- -->'s 996 <function>get_property()</function> and 997 <function>set_property()</function> vfuncs, use 998 g_object_get() and 999 g_object_set() or the generated property 1000 getters and setters (the generated class has an internal 1001 property bag implementation). 1002 </para> 1003 <informalexample><programlisting><![CDATA[ 1004static gboolean 1005on_handle_hello_world (MyAppFrobber *interface, 1006 GDBusMethodInvocation *invocation, 1007 const gchar *greeting, 1008 gpointer user_data) 1009{ 1010 if (g_strcmp0 (greeting, "Boo") != 0) 1011 { 1012 gchar *response; 1013 response = g_strdup_printf ("Word! You said `%s'.", greeting); 1014 my_app_complete_hello_world (interface, invocation, response); 1015 g_free (response); 1016 } 1017 else 1018 { 1019 g_dbus_method_invocation_return_error (invocation, 1020 MY_APP_ERROR, 1021 MY_APP_ERROR_NO_WHINING, 1022 "Hey, %s, there will be no whining!", 1023 g_dbus_method_invocation_get_sender (invocation)); 1024 } 1025 return TRUE; 1026} 1027 1028 [...] 1029 1030 interface = my_app_frobber_skeleton_new (); 1031 my_app_frobber_set_verbose (interface, TRUE); 1032 1033 g_signal_connect (interface, 1034 "handle-hello-world", 1035 G_CALLBACK (on_handle_hello_world), 1036 some_user_data); 1037 1038 [...] 1039 1040 error = NULL; 1041 if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface), 1042 connection, 1043 "/path/of/dbus_object", 1044 &error)) 1045 { 1046 /* handle error */ 1047 } 1048]]></programlisting></informalexample> 1049 <para> 1050 To facilitate atomic changesets (multiple properties changing at 1051 the same time), #GObject::notify signals are queued up when 1052 received. The queue is drained in an idle handler (which is called from the 1053 <link linkend="g-main-context-push-thread-default">thread-default main loop</link> 1054 of the thread where the skeleton object was 1055 constructed) and will cause emissions of the <ulink 1056 url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties::PropertiesChanged</ulink> 1057 signal with all the properties that have changed. Use 1058 g_dbus_interface_skeleton_flush() or 1059 g_dbus_object_skeleton_flush() to empty the queue 1060 immediately. Use g_object_freeze_notify() and 1061 g_object_thaw_notify() for atomic changesets if on a different 1062 thread. 1063 </para> 1064 </refsect2> 1065</refsect1> 1066 1067<refsect1> 1068 <title>C Type Mapping</title> 1069 <para> 1070 Scalar types 1071 (type-strings 1072 <link linkend="G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</link>, 1073 <link linkend="G-VARIANT-TYPE-BYTE:CAPS">'y'</link>, 1074 <link linkend="G-VARIANT-TYPE-INT16:CAPS">'n'</link>, 1075 <link linkend="G-VARIANT-TYPE-UINT16:CAPS">'q'</link>, 1076 <link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link>, 1077 <link linkend="G-VARIANT-TYPE-UINT32:CAPS">'u'</link>, 1078 <link linkend="G-VARIANT-TYPE-INT64:CAPS">'x'</link>, 1079 <link linkend="G-VARIANT-TYPE-UINT64:CAPS">'t'</link> and 1080 <link linkend="G-VARIANT-TYPE-DOUBLE:CAPS">'d'</link>) 1081 ), 1082 strings (type-strings 1083 <link linkend="G-VARIANT-TYPE-STRING:CAPS">'s'</link>, 1084 <link linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link>, 1085 <link linkend="G-VARIANT-TYPE-OBJECT-PATH:CAPS">'o'</link> and 1086 <link linkend="G-VARIANT-TYPE-SIGNATURE:CAPS">'g'</link>) and 1087 arrays of string (type-strings 1088 <link linkend="G-VARIANT-TYPE-STRING-ARRAY:CAPS">'as'</link>, 1089 <link linkend="G-VARIANT-TYPE-OBJECT-PATH-ARRAY:CAPS">'ao'</link> and 1090 <link linkend="G-VARIANT-TYPE-BYTESTRING-ARRAY:CAPS">'aay'</link>) 1091 are mapped to the natural types, 1092 e.g. #gboolean, #gdouble, #gint, <link linkend="gchararray">gchar*</link>, 1093 <link linkend="GStrv">gchar**</link> and 1094 so on. Everything else is mapped to the #GVariant 1095 type. 1096 </para> 1097 <para> 1098 This automatic mapping can be turned off by using the annotation 1099 <literal>org.gtk.GDBus.C.ForceGVariant</literal> - if used then a 1100 #GVariant is always exchanged instead of the 1101 corresponding native C type. This annotation may be convenient to 1102 use when using 1103 bytestrings (type-string <link linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link>) 1104 for data that could have embedded NUL bytes. 1105 </para> 1106</refsect1> 1107 1108<refsect1 id="gdbus-code-stability"> 1109 <title>Stability Guarantees</title> 1110 <para> 1111 The generated C functions are guaranteed to not change their ABI 1112 that is, if a method, signal or property does not change its 1113 signature in the introspection XML, the generated C functions will 1114 not change its C ABI either. The ABI of the generated instance and 1115 class structures will be preserved as well. 1116 </para> 1117 <para> 1118 The ABI of the generated #GType<!-- -->s will be preserved only if 1119 the <literal>org.gtk.GDBus.Since</literal> annotation is used 1120 judiciously — this is because the VTable for the #GInterface 1121 relies on functions pointers for signal handlers. Specifically, if 1122 a D-Bus method, property or signal or is added to a D-Bus 1123 interface, then ABI of the generated #GInterface type is preserved 1124 if, and only if, each added method, property signal is annotated 1125 with they <literal>org.gtk.GDBus.Since</literal> annotation using 1126 a greater version number than previous versions. 1127 </para> 1128 <para> 1129 The generated C code currently happens to be annotated with <ulink 1130 url="http://www.gtk.org/gtk-doc/">gtk-doc</ulink> / <ulink 1131 url="https://wiki.gnome.org/Projects/GObjectIntrospection">GObject 1132 Introspection</ulink> comments / annotations. The layout and 1133 contents might change in the future so no guarantees about 1134 e.g. <literal>SECTION</literal> usage etc. is given. 1135 </para> 1136 <para> 1137 While the generated Docbook for D-Bus interfaces isn't expected to 1138 change, no guarantees are given at this point. 1139 </para> 1140 <para> 1141 It is important to note that the generated code should not be 1142 checked into revision control systems, nor it should be included 1143 in distributed source archives. 1144 </para> 1145</refsect1> 1146 1147<refsect1> 1148 <title>Bugs</title> 1149 <para> 1150 Please send bug reports to either the distribution bug tracker 1151 or the upstream bug tracker at 1152 <ulink url="https://gitlab.gnome.org/GNOME/glib/issues/new">https://gitlab.gnome.org/GNOME/glib/issues/new</ulink>. 1153 </para> 1154</refsect1> 1155 1156<refsect1> 1157 <title>See also</title> 1158 <para> 1159 <citerefentry> 1160 <refentrytitle>gdbus</refentrytitle><manvolnum>1</manvolnum> 1161 </citerefentry> 1162 </para> 1163</refsect1> 1164 1165</refentry> 1166