docs/reference/gio/gdbus-codegen.1

   1 '\" t
   2 .\"     Title: gdbus-codegen
   3 .\"    Author: [see the "Author" section]
   4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
   5 .\"      Date: 05/14/2012
   6 .\"    Manual: User Commands
   7 .\"    Source: User Commands
   8 .\"  Language: English
   9 .\"
  10 .TH "GDBUS\-CODEGEN" "1" "05/14/2012" "User Commands" "User Commands"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 gdbus-codegen \- D\-Bus code and documentation generator
  32 .SH "SYNOPSIS"
  33 .HP \w'\fBgdbus\-codegen\fR\ 'u
  34 \fBgdbus\-codegen\fR [\fB\-\-interface\-prefix\fR\ \fIorg\&.project\&.Prefix\fR] [\fB\-\-generate\-c\-code\fR\ \fIOUTFILES\fR] [\fB\-\-c\-namespace\fR\ \fIYourProject\fR] [\fB\-\-c\-generate\-object\-manager\fR] [\fB\-\-generate\-docbook\fR\ \fIOUTFILES\fR] [\fB\-\-annotate\fR\ \fIELEMENT\fR\ \fIKEY\fR\ \fIVALUE\fR]...  FILE [FILE...]
  35 .SH "DESCRIPTION"
  36 .PP
  37
  38 \fBgdbus\-codegen\fR
  39 is used to generate code and/or documentation for one or more D\-Bus interfaces\&. The tool reads
  40 \m[blue]\fBD\-Bus Introspection XML\fR\m[]\&\s-2\u[1]\d\s+2
  41 files and generates output files\&. The tool currently supports generating C code (via
  42 \fB\-\-generate\-c\-code\fR) and Docbook XML (via
  43 \fB\-\-generate\-docbook\fR)\&.
  44 .SH "GENERATING C CODE"
  45 .PP
  46 When generating C code, a #GInterface
  47 \-derived type is generated for each D\-Bus interface\&. Additionally, for every generated type,
  48 \fBFooBar\fR, two concrete instantiable types,
  49 \fBFooBarProxy\fR
  50 and
  51 \fBFooBarSkeleton\fR, implementing said interface are also generated\&. The former is derived from #GDBusProxy and intended for use on the client side while the latter is derived from the #GDBusInterfaceSkeleton type making it easy to export on a #GDBusConnection either directly or via a #GDBusObjectManagerServer instance\&.
  52 .PP
  53 The name of each generated C type is derived from the D\-Bus interface name stripped with the prefix given with
  54 \fB\-\-interface\-prefix\fR
  55 and with the dots removed and initial characters capitalized\&. For example, for the D\-Bus interface
  56 com\&.acme\&.Coyote
  57 the name used is
  58 ComAcmeCoyote\&. For the D\-Bus interface
  59 org\&.project\&.Bar\&.Frobnicator
  60 with
  61 \fB\-\-interface\-prefix\fR
  62 org\&.project\&., the name used is
  63 BarFrobnicator\&.
  64 .PP
  65 For methods, signals and properties, if not specified, the name defaults to the name of the method, signal or property\&.
  66 .PP
  67 Two forms of the name are used \- the CamelCase form and the lower\-case form\&. The CamelCase form is used for the #GType and struct name, while lower\-case form is used in function names\&. The lower\-case form is calculated by converting from CamelCase to lower\-case and inserting underscores at word boundaries (using certain heuristics)\&.
  68 .PP
  69 If the value given by the
  70 org\&.gtk\&.GDBus\&.C\&.Name
  71 annotation or the
  72 \fB\-\-c\-namespace\fR
  73 option contains an underscore (sometimes called
  74 \fIUgly_Case\fR), then the camel\-case name is derived by removing all underscores, and the lower\-case name is derived by lower\-casing the string\&. This is useful in some situations where abbreviations are used\&. For example, if the annotation is used on the interface
  75 net\&.MyCorp\&.MyApp\&.iSCSITarget
  76 with the value
  77 iSCSI_Target
  78 the CamelCase form is
  79 iSCSITarget
  80 while the lower\-case form is
  81 iscsi_target\&. If the annotation is used on the method
  82 EjectTheiPod
  83 with the value
  84 Eject_The_iPod, the lower\-case form is
  85 eject_the_ipod\&.
  86 .SH "GENERATING DOCBOOK DOCUMENTATION"
  87 .PP
  88 Each generated Docbook XML file (see the
  89 \fB\-\-generate\-docbook\fR
  90 option for details) is a
  91 \m[blue]\fBRefEntry\fR\m[]\&\s-2\u[2]\d\s+2
  92 article describing the D\-Bus interface\&.
  93 .SH "OPTIONS"
  94 .PP
  95 The following options are supported:
  96 .PP
  97 \fB\-\-interface\-prefix\fR \fIorg\&.project\&.Prefix\&.\fR
  98 .RS 4
  99 A prefix to strip from all D\-Bus interface names when calculating the typename for the C binding and the Docbook
 100 \m[blue]\fBsortas attribute\fR\m[]\&\s-2\u[3]\d\s+2\&.
 101 .RE
 102 .PP
 103 \fB\-\-generate\-docbook\fR \fIOUTFILES\fR
 104 .RS 4
 105 Generate Docbook Documentation for each D\-Bus interface and put it in
 106 OUTFILES\-NAME\&.xml
 107 where
 108 NAME
 109 is a place\-holder for the interface name, e\&.g\&.
 110 net\&.Corp\&.FooBar
 111 and so on\&.
 112 .RE
 113 .PP
 114 \fB\-\-generate\-c\-code\fR \fIOUTFILES\fR
 115 .RS 4
 116 Generate C code for all D\-Bus interfaces and put it in
 117 OUTFILES\&.c
 118 and
 119 OUTFILES\&.h\&.
 120 .RE
 121 .PP
 122 \fB\-\-c\-namespace\fR \fIYourProject\fR
 123 .RS 4
 124 The namespace to use for generated C code\&. This is expected to be in
 125 \m[blue]\fBCamelCase\fR\m[]\&\s-2\u[4]\d\s+2
 126 or
 127 \fIUgly_Case\fR
 128 (see above)\&.
 129 .RE
 130 .PP
 131 \fB\-\-c\-generate\-object\-manager\fR
 132 .RS 4
 133 If this option is passed, suitable #GDBusObject, #GDBusObjectProxy, #GDBusObjectSkeleton and #GDBusObjectManagerClient subclasses are generated\&.
 134 .RE
 135 .PP
 136 \fB\-\-annotate\fR \fIELEMENT\fR \fIKEY\fR \fIVALUE\fR
 137 .RS 4
 138 Used to inject D\-Bus annotations into the given XML files\&. It can be used with interfaces, methods, signals, properties and arguments in the following way:
 139 .sp
 140 .if n \{\
 141 .RS 4
 142 .\}
 143 .nf
 144 gdbus\-codegen \-\-c\-namespace MyApp                           \e
 145   \-\-generate\-c\-code myapp\-generated                         \e
 146   \-\-annotate "org\&.project\&.InterfaceName"                    \e
 147     org\&.gtk\&.GDBus\&.C\&.Name MyFrobnicator                      \e
 148   \-\-annotate "org\&.project\&.InterfaceName:Property"           \e
 149     bar bat                                                 \e
 150   \-\-annotate "org\&.project\&.InterfaceName\&.Method()"           \e
 151     org\&.freedesktop\&.DBus\&.Deprecated true                    \e
 152   \-\-annotate "org\&.project\&.InterfaceName\&.Method()[arg_name]" \e
 153     snake hiss                                              \e
 154   \-\-annotate "org\&.project\&.InterfaceName::Signal"            \e
 155     cat meow                                                \e
 156   \-\-annotate "org\&.project\&.InterfaceName::Signal[arg_name]"  \e
 157     dog wuff                                                \e
 158   myapp\-dbus\-interfaces\&.xml
 159 .fi
 160 .if n \{\
 161 .RE
 162 .\}
 163 Any UTF\-8 string can be used for
 164 \fIKEY\fR
 165 and
 166 \fIVALUE\fR\&.
 167 .RE
 168 .SH "SUPPORTED D-BUS ANNOTATIONS"
 169 .PP
 170 The following D\-Bus annotations are supported by
 171 \fBgdbus\-codegen\fR:
 172 .PP
 173 org\&.freedesktop\&.DBus\&.Deprecated
 174 .RS 4
 175 Can be used on any
 176 <interface>,
 177 <method>,
 178 <signal>
 179 and
 180 <property>
 181 element to specify that the element is deprecated if its value is
 182 true\&. Note that this annotation is defined in the
 183 \m[blue]\fBD\-Bus specification\fR\m[]\&\s-2\u[1]\d\s+2
 184 and can only assume the values
 185 true
 186 and
 187 false\&. In particular, you cannot specify the version that the element was deprecated in nor any helpful deprecation message\&. Such information should be added to the element documentation instead\&.
 188 .sp
 189 When generating C code, this annotation is used to add #G_GNUC_DEPRECATED to generated functions for the element\&.
 190 .sp
 191 When generating Docbook XML, a deprecation warning will appear along the documentation for the element\&.
 192 .RE
 193 .PP
 194 org\&.gtk\&.GDBus\&.Since
 195 .RS 4
 196 Can be used on any
 197 <interface>,
 198 <method>,
 199 <signal>
 200 and
 201 <property>
 202 element to specify the version (any free\-form string but compared using a version\-aware sort function) the element appeared in\&.
 203 .sp
 204 When generating C code, this field is used to ensure function pointer order for preserving ABI/API, see
 205 the section called \(lqSTABILITY GUARANTEES\(rq\&.
 206 .sp
 207 When generating Docbook XML, the value of this tag appears in the documentation\&.
 208 .RE
 209 .PP
 210 org\&.gtk\&.GDBus\&.DocString
 211 .RS 4
 212 A string with Docbook content for documentation\&. This annotation can be used on
 213 <interface>,
 214 <method>,
 215 <signal>,
 216 <property>
 217 and
 218 <arg>
 219 elements\&.
 220 .RE
 221 .PP
 222 org\&.gtk\&.GDBus\&.DocString\&.Short
 223 .RS 4
 224 A string with Docbook content for short/brief documentation\&. This annotation can only be used on
 225 <interface>
 226 elements\&.
 227 .RE
 228 .PP
 229 org\&.gtk\&.GDBus\&.C\&.Name
 230 .RS 4
 231 Can be used on any
 232 <interface>,
 233 <method>,
 234 <signal>
 235 and
 236 <property>
 237 element to specify the name to use when generating C code\&. The value is expected to be in
 238 \m[blue]\fBCamelCase\fR\m[]\&\s-2\u[4]\d\s+2
 239 or
 240 \fIUgly_Case\fR
 241 (see above)\&.
 242 .RE
 243 .PP
 244 org\&.gtk\&.GDBus\&.C\&.ForceGVariant
 245 .RS 4
 246 If set to a non\-empty string, a #GVariant instance will be used instead of the natural C type\&. This annotation can be used on any
 247 <arg>
 248 and
 249 <property>
 250 element\&.
 251 .RE
 252 .PP
 253 org\&.gtk\&.GDBus\&.C\&.UnixFD
 254 .RS 4
 255 If set to a non\-empty string, the generated code will include parameters to exchange file descriptors using the #GUnixFDList type\&. This annotation can be used on
 256 <method>
 257 elements\&.
 258 .RE
 259 .PP
 260 As an easier alternative to using the
 261 org\&.gtk\&.GDBus\&.DocString
 262 annotation, note that parser used by
 263 \fBgdbus\-codegen\fR
 264 parses XML comments in a way similar to
 265 \m[blue]\fBgtk\-doc\fR\m[]\&\s-2\u[5]\d\s+2:
 266 .sp .if n \{\ .RS 4 .\} .nf <!\-\- net\&.Corp\&.Bar: @short_description: A short description A <emphasis>longer</emphasis> description\&. This is a new paragraph\&. \-\-> <interface name="net\&.corp\&.Bar"> <!\-\- FooMethod: @greeting: The docs for greeting parameter\&. @response: The docs for response parameter\&. The docs for the actual method\&. \-\-> <method name="FooMethod"> <arg name="greeting" direction="in" type="s"/> <arg name="response" direction="out" type="s"/> </method> <!\-\- BarSignal: @blah: The docs for blah parameter\&. @boo: The docs for boo parameter\&. @since: 2\&.30 The docs for the actual signal\&. \-\-> <signal name="BarSignal"> <arg name="blah" type="s"/> <arg name="boo" type="s"/> </signal> <!\-\- BazProperty: The docs for the property\&. \-\-> <property name="BazProperty" type="s" access="read"/> </interface> .fi .if n \{\ .RE .\}
 267 .PP
 268 Note that
 269 @since
 270 can be used in any inline documentation bit (e\&.g\&. for interfaces, methods, signals and properties) to set the
 271 org\&.gtk\&.GDBus\&.Since
 272 annotation\&. For the
 273 org\&.gtk\&.GDBus\&.DocString
 274 annotation (and inline comments), note that substrings of the form
 275 #net\&.Corp\&.Bar,
 276 net\&.Corp\&.Bar\&.FooMethod(),
 277 #net\&.Corp\&.Bar::BarSignal
 278 and
 279 #net\&.Corp\&.InlineDocs:BazProperty
 280 are all expanded to links to the respective interface, method, signal and property\&. Additionally, substrings starting with
 281 @
 282 and
 283 %
 284 characters are rendered as
 285 \m[blue]\fBparameter\fR\m[]\&\s-2\u[6]\d\s+2
 286 and
 287 \m[blue]\fBconstant\fR\m[]\&\s-2\u[7]\d\s+2
 288 respectively\&.
 289 .PP
 290 If both XML comments and
 291 org\&.gtk\&.GDBus\&.DocString
 292 or
 293 org\&.gtk\&.GDBus\&.DocString\&.Short
 294 annotations are present, the latter wins\&.
 295 .SH "EXAMPLE"
 296 .PP
 297 Consider the following D\-Bus Introspection XML\&.
 298 .sp
 299 .if n \{\
 300 .RS 4
 301 .\}
 302 .nf
 303 <node>
 304   <interface name="net\&.Corp\&.MyApp\&.Frobber">
 305     <method name="HelloWorld">
 306       <arg name="greeting" direction="in" type="s"/>
 307       <arg name="response" direction="out" type="s"/>
 308     </method>
 309
 310     <signal name="Notification">
 311       <arg name="icon_blob" type="ay"/>
 312       <arg name="height" type="i"/>
 313       <arg name="messages" type="as"/>
 314     </signal>
 315
 316     <property name="Verbose" type="b" access="readwrite"/>
 317   </interface>
 318 </node>
 319 .fi
 320 .if n \{\
 321 .RE
 322 .\}
 323 .PP
 324 If
 325 \fBgdbus\-codegen\fR
 326 is used on this file like this:
 327 .sp
 328 .if n \{\
 329 .RS 4
 330 .\}
 331 .nf
 332 gdbus\-codegen \-\-generate\-c\-code myapp\-generated       \e
 333               \-\-c\-namespace MyApp                     \e
 334               \-\-interface\-prefix net\&.corp\&.MyApp\&.      \e
 335               net\&.Corp\&.MyApp\&.Frobber\&.xml
 336 .fi
 337 .if n \{\
 338 .RE
 339 .\}
 340 .PP
 341 two files called
 342 myapp\-generated\&.[ch]
 343 are generated\&. The files provide an abstract #GTypeInterface
 344 \-derived type called
 345 \fBMyAppFrobber\fR
 346 as well as two instantiable types with the same name but suffixed with
 347 \fBProxy\fR
 348 and
 349 \fBSkeleton\fR\&. The generated file, roughly, contains the following facilities:
 350 .sp
 351 .if n \{\
 352 .RS 4
 353 .\}
 354 .nf
 355 /* GType macros for the three generated types */
 356 #define MY_APP_TYPE_FROBBER (my_app_frobber_get_type ())
 357 #define MY_APP_TYPE_FROBBER_SKELETON (my_app_frobber_skeleton_get_type ())
 358 #define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ())
 359
 360 typedef struct _MyAppFrobber MyAppFrobber; /* Dummy typedef */
 361
 362 typedef struct
 363 {
 364   GTypeInterface parent_iface;
 365
 366   /* Signal handler for the ::notification signal */
 367   void (*notification) (MyAppFrobber *proxy,
 368                         GVariant *icon_blob,
 369                         gint height,
 370                         const gchar* const *messages);
 371
 372   /* Signal handler for the ::handle\-hello\-world signal */
 373   gboolean (*handle_hello_world) (MyAppFrobber *proxy,
 374                                   GDBusMethodInvocation *invocation,
 375                                   const gchar *greeting);
 376 } MyAppFrobberIface;
 377
 378 /* Asynchronously calls HelloWorld() */
 379 void
 380 my_app_frobber_call_hello_world (MyAppFrobber *proxy,
 381                                  const gchar *greeting,
 382                                  GCancellable *cancellable,
 383                                  GAsyncReadyCallback callback,
 384                                  gpointer user_data);
 385 gboolean
 386 my_app_frobber_call_hello_world_finish (MyAppFrobber *proxy,
 387                                         gchar **out_response,
 388                                         GAsyncResult *res,
 389                                         GError **error);
 390
 391 /* Synchronously calls HelloWorld()\&. Blocks calling thread\&. */
 392 gboolean
 393 my_app_frobber_call_hello_world_sync (MyAppFrobber *proxy,
 394                                       const gchar *greeting,
 395                                       gchar **out_response,
 396                                       GCancellable *cancellable,
 397                                       GError **error);
 398
 399 /* Completes handling the HelloWorld() method call */
 400 void
 401 my_app_frobber_complete_hello_world (MyAppFrobber *object,
 402                                      GDBusMethodInvocation *invocation,
 403                                      const gchar *response);
 404
 405 /* Emits the ::notification signal / Notification() D\-Bus signal */
 406 void
 407 my_app_frobber_emit_notification (MyAppFrobber *object,
 408                                   GVariant *icon_blob,
 409                                   gint height,
 410                                   const gchar* const *messages);
 411
 412 /* Gets the :verbose GObject property / Verbose D\-Bus property\&.
 413  * Does no blocking I/O\&.
 414  */
 415 gboolean my_app_frobber_get_verbose (MyAppFrobber *object);
 416
 417 /* Sets the :verbose GObject property / Verbose D\-Bus property\&.
 418  * Does no blocking I/O\&.
 419  */
 420 void my_app_frobber_set_verbose (MyAppFrobber *object,
 421                                  gboolean      value);
 422
 423 /* Gets the interface info */
 424 GDBusInterfaceInfo *my_app_frobber_interface_info (void);
 425
 426 /* Creates a new skeleton object, ready to be exported */
 427 MyAppFrobber *my_app_frobber_skeleton_new (void);
 428
 429 /* Client\-side proxy constructors\&.
 430  *
 431  * Additionally, _new_for_bus(), _new_for_bus_finish() and
 432  * _new_for_bus_sync() proxy constructors are also generated\&.
 433  */
 434 void
 435 my_app_frobber_proxy_new        (GDBusConnection     *connection,
 436                                  GDBusProxyFlags      flags,
 437                                  const gchar         *name,
 438                                  const gchar         *object_path,
 439                                  GCancellable        *cancellable,
 440                                  GAsyncReadyCallback  callback,
 441                                  gpointer             user_data);
 442 MyAppFrobber *
 443 my_app_frobber_proxy_new_finish (GAsyncResult        *res,
 444                                  GError             **error);
 445 MyAppFrobber *
 446 my_app_frobber_proxy_new_sync   (GDBusConnection     *connection,
 447                                  GDBusProxyFlags      flags,
 448                                  const gchar         *name,
 449                                  const gchar         *object_path,
 450                                  GCancellable        *cancellable,
 451                                  GError             **error);
 452 .fi
 453 .if n \{\
 454 .RE
 455 .\}
 456 .PP
 457 Thus, for every D\-Bus method, there will be three C functions for calling the method, one #GObject signal for handling an incoming call and one C function for completing an incoming call\&. For every D\-Bus signal, there\*(Aqs one #GObject signal and one C function for emitting it\&. For every D\-Bus property, two C functions are generated (one setter, one getter) and one #GObject property\&. The following table summarizes the generated facilities and where they are applicable:
 458 .TS
 459 allbox tab(:);
 460 lB lB lB.
 461 T{
 462 \ \&
 463 T}:T{
 464 Client
 465 T}:T{
 466 Server
 467 T}
 468 .T&
 469 l l l
 470 l l l
 471 l l l
 472 l l l
 473 l l l.
 474 T{
 475 Types
 476 T}:T{
 477 Use \fBMyAppFrobberProxy\fR
 478 T}:T{
 479 Any type implementing the \fBMyAppFrobber\fR interface
 480 T}
 481 T{
 482 Methods
 483 T}:T{
 484 Use \fBm_a_f_hello_world()\fR to call\&.
 485 T}:T{
 486 Receive via the \fBhandle_hello_world()\fR signal handler\&. Complete the call with \fBm_a_f_complete_hello_world()\fR
 487 T}
 488 T{
 489 Signals
 490 T}:T{
 491 Connect to the \fB::notification\fR GObject signal\&.
 492 T}:T{
 493 Use \fBm_a_f_emit_notification()\fR to emit signal\&.
 494 T}
 495 T{
 496 Properties (Reading)
 497 T}:T{
 498 Use \fBm_a_f_get_verbose()\fR or \fI:verbose\fR\&.
 499 T}:T{
 500 Implement #GObject\*(Aqs \fBget_property()\fR vfunc\&.
 501 T}
 502 T{
 503 Properties (writing)
 504 T}:T{
 505 Use \fBm_a_f_set_verbose()\fR or \fI:verbose\fR\&.
 506 T}:T{
 507 Implement #GObject\*(Aqs \fBset_property()\fR vfunc\&.
 508 T}
 509 .TE
 510 .sp 1
 511 .SS "Client\-side usage"
 512 .PP
 513 You can use the generated proxy type with the generated constructors:
 514 .sp
 515 .if n \{\
 516 .RS 4
 517 .\}
 518 .nf
 519     MyAppFrobber *proxy;
 520     GError *error;
 521
 522     error = NULL;
 523     proxy = my_app_frobber_proxy_new_for_bus_sync (
 524                 G_BUS_TYPE_SESSION,
 525                 G_DBUS_PROXY_FLAGS_NONE,
 526                 "net\&.Corp\&.MyApp",              /* bus name */
 527                 "/net/Corp/MyApp/SomeFrobber", /* object */
 528                 NULL,                          /* GCancellable* */
 529                 &error);
 530     /* do stuff with proxy */
 531     g_object_unref (proxy);
 532 .fi
 533 .if n \{\
 534 .RE
 535 .\}
 536 .PP
 537 Instead of using the generic #GDBusProxy facilities, one can use the generated methods such as
 538 \fBmy_app_frobber_call_hello_world()\fR
 539 to invoke the
 540 \fBnet\&.Corp\&.MyApp\&.Frobber\&.HelloWorld()\fR
 541 D\-Bus method, connect to the the
 542 \fB::notification\fR
 543 GObject signal to receive the
 544 \fBnet\&.Corp\&.MyApp\&.Frobber::Notication\fR
 545 D\-Bus signal and get/set the
 546 \fInet\&.Corp\&.MyApp\&.Frobber:Verbose\fR
 547 D\-Bus Property using either the GObject property
 548 \fI:verbose\fR
 549 or the
 550 \fBmy_app_get_verbose()\fR
 551 and
 552 \fBmy_app_set_verbose()\fR
 553 methods\&. Use the standard #GObject::notify signal to listen to property changes\&.
 554 .PP
 555 Note that all property access is via #GDBusProxy
 556 \*(Aqs property cache so no I/O is ever done when reading properties\&. Also note that setting a property will cause the
 557 \m[blue]\fBorg\&.freedesktop\&.DBus\&.Properties\&.Set\fR\m[]\&\s-2\u[8]\d\s+2
 558 method to be called on the remote object\&. This call, however, is asynchronous so setting a property won\*(Aqt block\&. Further, the change is delayed and no error checking is possible\&.
 559 .SS "Server\-side usage"
 560 .PP
 561 The generated
 562 \fBMyAppFrobber\fR
 563 interface is designed so it is easy to implement it in a #GObject subclass\&. For example, to handle
 564 \fBHelloWorld()\fR
 565 method invocations, set the vfunc for
 566 \fBhandle_hello_hello_world()\fR
 567 in the
 568 \fBMyAppFrobberIface\fR
 569 structure\&. Similary, to handle the
 570 \fInet\&.Corp\&.MyApp\&.Frobber:Verbose\fR
 571 property override the
 572 \fI:verbose\fR
 573 #GObject property from the subclass\&. To emit a signal, use e\&.g\&.
 574 \fBmy_app_emit_signal()\fR
 575 or g_signal_emit_by_name()\&.
 576 .PP
 577 Instead of subclassing, it is often easier to use the generated
 578 \fBMyAppFrobberSkeleton\fR
 579 subclass\&. To handle incoming method calls, use
 580 \fBg_signal_connect()\fR
 581 with the
 582 \fB::handle\-*\fR
 583 signals and instead of overriding #GObject
 584 \*(Aqs
 585 \fBget_property()\fR
 586 and
 587 \fBset_property()\fR
 588 vfuncs, use g_object_get() and g_object_set() or the generated property getters and setters (the generated class has an internal property bag implementation)\&.
 589 .sp
 590 .if n \{\
 591 .RS 4
 592 .\}
 593 .nf
 594 static gboolean
 595 on_handle_hello_world (MyAppFrobber           *interface,
 596                        GDBusMethodInvocation  *invocation,
 597                        const gchar            *greeting,
 598                        gpointer                user_data)
 599 {
 600   if (g_strcmp0 (greeting, "Boo") != 0)
 601     {
 602       gchar *response;
 603       response = g_strdup_printf ("Word! You said `%s\*(Aq\&.", greeting);
 604       my_app_complete_hello_world (interface, invocation, response);
 605       g_free (response);
 606     }
 607   else
 608     {
 609       g_dbus_method_invocation_return_error (MY_APP_ERROR,
 610                  MY_APP_ERROR_NO_WHINING,
 611                  "Hey, %s, there will be no whining!",
 612                  g_dbus_method_invocation_get_sender (invocation));
 613     }
 614   return TRUE;
 615 }
 616
 617   [\&.\&.\&.]
 618
 619   interface = my_app_frobber_skeleton_new ();
 620   my_app_frobber_set_verbose (interface, TRUE);
 621
 622   g_signal_connect (interface,
 623                     "handle\-hello\-world",
 624                     G_CALLBACK (on_handle_hello_world),
 625                     some_user_data);
 626
 627   [\&.\&.\&.]
 628
 629   error = NULL;
 630   if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
 631                                          connection,
 632                                          "/path/of/dbus_object",
 633                                          &error))
 634     {
 635       /* handle error */
 636     }
 637 .fi
 638 .if n \{\
 639 .RE
 640 .\}
 641 .PP
 642 To facilitate atomic changesets (multiple properties changing at the same time), #GObject::notify signals are queued up when received\&. The queue is drained in an idle handler (which is called from the
 643 thread\-default main loop
 644 of the thread where the skeleton object was contructed) and will cause emissions of the
 645 \m[blue]\fBorg\&.freedesktop\&.DBus\&.Properties::PropertiesChanged\fR\m[]\&\s-2\u[8]\d\s+2
 646 signal with all the properties that have changed\&. Use g_dbus_interface_skeleton_flush() or g_dbus_object_skeleton_flush() to empty the queue immediately\&. Use g_object_freeze_notify() and g_object_thaw_notify() for atomic changesets if on a different thread\&.
 647 .SH "C TYPE MAPPING"
 648 .PP
 649 Scalar types (type\-strings
 650 \*(Aqb\*(Aq,
 651 \*(Aqy\*(Aq,
 652 \*(Aqn\*(Aq,
 653 \*(Aqq\*(Aq,
 654 \*(Aqi\*(Aq,
 655 \*(Aqu\*(Aq,
 656 \*(Aqx\*(Aq,
 657 \*(Aqt\*(Aq
 658 and
 659 \*(Aqd\*(Aq) ), strings (type\-strings
 660 \*(Aqs\*(Aq,
 661 \*(Aqay\*(Aq,
 662 \*(Aqo\*(Aq
 663 and
 664 \*(Aqg\*(Aq) and arrays of string (type\-strings
 665 \*(Aqas\*(Aq,
 666 \*(Aqao\*(Aq
 667 and
 668 \*(Aqaay\*(Aq) are mapped to the natural types, e\&.g\&. #gboolean, #gdouble, #gint,
 669 gchar*,
 670 gchar**
 671 and so on\&. Everything else is mapped to the #GVariant type\&.
 672 .PP
 673 This automatic mapping can be turned off by using the annotation
 674 org\&.gtk\&.GDBus\&.C\&.ForceGVariant
 675 \- if used then a #GVariant is always exchanged instead of the corresponding native C type\&. This annotation may be convenient to use when using bytestrings (type\-string
 676 \*(Aqay\*(Aq) for data that could have embedded NUL bytes\&.
 677 .SH "STABILITY GUARANTEES"
 678 .PP
 679 The generated C functions are guaranteed to not change their ABI that is, if a method, signal or property does not change its signature in the introspection XML, the generated C functions will not change its C ABI either\&.
 680 .PP
 681 The ABI of the generated #GType
 682 s will be preserved only if the
 683 org\&.gtk\&.GDBus\&.Since
 684 annotation is used judiciously \(em this is because the VTable for the #GInterface relies on functions pointers for signal handlers\&. Specifically, if a D\-Bus method, property or signal or is added to a D\-Bus interface, then ABI of the generated #GInterface type is preserved if, and only if, each added method, property signal is annotated with they
 685 org\&.gtk\&.GDBus\&.Since
 686 annotation using a greater version number than previous versions\&.
 687 .PP
 688 The generated C code currently happens to be annotated with
 689 \m[blue]\fBgtk\-doc\fR\m[]\&\s-2\u[5]\d\s+2
 690 /
 691 \m[blue]\fBGObject Introspection\fR\m[]\&\s-2\u[9]\d\s+2
 692 comments / annotations\&. The layout and contents might change in the future so no guarantees about e\&.g\&.
 693 SECTION
 694 usage etc\&. is given\&.
 695 .PP
 696 While the generated Docbook for D\-Bus interfaces isn\*(Aqt expected to change, no guarantees are given at this point\&.
 697 .SH "AUTHOR"
 698 .PP
 699 Written by David Zeuthen
 700 zeuthen@gmail\&.com
 701 with a lot of help from many others\&.
 702 .SH "BUGS"
 703 .PP
 704 Please send bug reports to either the distribution bug tracker or the upstream bug tracker at
 705 \m[blue]\fBhttps://bugzilla\&.gnome\&.org/enter_bug\&.cgi?product=glib\fR\m[]\&.
 706 .SH "SEE ALSO"
 707 .PP
 708
 709 \fBgdbus\fR(1)
 710 .SH "NOTES"
 711 .IP " 1." 4
 712 D-Bus Introspection XML
 713 .RS 4
 714 \%http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format
 715 .RE
 716 .IP " 2." 4
 717 RefEntry
 718 .RS 4
 719 \%http://www.docbook.org/tdg/en/html/refentry.html
 720 .RE
 721 .IP " 3." 4
 722 sortas attribute
 723 .RS 4
 724 \%http://www.docbook.org/tdg/en/html/primary.html
 725 .RE
 726 .IP " 4." 4
 727 CamelCase
 728 .RS 4
 729 \%http://en.wikipedia.org/wiki/CamelCase
 730 .RE
 731 .IP " 5." 4
 732 gtk-doc
 733 .RS 4
 734 \%http://www.gtk.org/gtk-doc/
 735 .RE
 736 .IP " 6." 4
 737 parameter
 738 .RS 4
 739 \%http://www.docbook.org/tdg/en/html/parameter.html
 740 .RE
 741 .IP " 7." 4
 742 constant
 743 .RS 4
 744 \%http://www.docbook.org/tdg/en/html/constant.html
 745 .RE
 746 .IP " 8." 4
 747 org.freedesktop.DBus.Properties.Set
 748 .RS 4
 749 \%http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties
 750 .RE
 751 .IP " 9." 4
 752 GObject Introspection
 753 .RS 4
 754 \%https://live.gnome.org/GObjectIntrospection
 755 .RE