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