doc/dbus-tutorial.xml

   1 <?xml version="1.0" standalone="no"?>
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
   4 [
   5 ]>
   6
   7 <article id="index">
   8   <articleinfo>
   9     <title>D-Bus Tutorial</title>
  10     <releaseinfo>Version 0.5.0</releaseinfo>
  11     <date>20 August 2006</date>
  12     <authorgroup>
  13       <author>
  14         <firstname>Havoc</firstname>
  15         <surname>Pennington</surname>
  16         <affiliation>
  17           <orgname>Red Hat, Inc.</orgname>
  18           <address><email>hp@pobox.com</email></address>
  19         </affiliation>
  20       </author>
  21       <author>
  22         <firstname>David</firstname>
  23         <surname>Wheeler</surname>
  24       </author>
  25       <author>
  26         <firstname>John</firstname>
  27         <surname>Palmieri</surname>
  28         <affiliation>
  29           <orgname>Red Hat, Inc.</orgname>
  30           <address><email>johnp@redhat.com</email></address>
  31         </affiliation>
  32       </author>
  33       <author>
  34         <firstname>Colin</firstname>
  35         <surname>Walters</surname>
  36         <affiliation>
  37           <orgname>Red Hat, Inc.</orgname>
  38           <address><email>walters@redhat.com</email></address>
  39         </affiliation>
  40       </author>
  41     </authorgroup>
  42   </articleinfo>
  43
  44   <sect1 id="meta">
  45     <title>Tutorial Work In Progress</title>
  46
  47     <para>
  48       This tutorial is not complete; it probably contains some useful information, but
  49       also has plenty of gaps. Right now, you'll also need to refer to the D-Bus specification,
  50       Doxygen reference documentation, and look at some examples of how other apps use D-Bus.
  51     </para>
  52
  53     <para>
  54       Enhancing the tutorial is definitely encouraged - send your patches or suggestions to the
  55       mailing list. If you create a D-Bus binding, please add a section to the tutorial for your
  56       binding, if only a short section with a couple of examples.
  57     </para>
  58
  59   </sect1>
  60
  61   <sect1 id="whatis">
  62     <title>What is D-Bus?</title>
  63     <para>
  64       D-Bus is a system for <firstterm>interprocess communication</firstterm>
  65       (IPC). Architecturally, it has several layers:
  66
  67       <itemizedlist>
  68         <listitem>
  69           <para>
  70             A library, <firstterm>libdbus</firstterm>, that allows two
  71             applications to connect to each other and exchange messages.
  72           </para>
  73         </listitem>
  74         <listitem>
  75           <para>
  76             A <firstterm>message bus daemon</firstterm> executable, built on
  77             libdbus, that multiple applications can connect to. The daemon can
  78             route messages from one application to zero or more other
  79             applications.
  80           </para>
  81         </listitem>
  82         <listitem>
  83           <para>
  84             <firstterm>Wrapper libraries</firstterm> or <firstterm>bindings</firstterm>
  85             based on particular application frameworks.  For example, libdbus-glib and
  86             libdbus-qt. There are also bindings to languages such as
  87             Python. These wrapper libraries are the API most people should use,
  88             as they simplify the details of D-Bus programming. libdbus is
  89             intended to be a low-level backend for the higher level bindings.
  90             Much of the libdbus API is only useful for binding implementation.
  91           </para>
  92         </listitem>
  93       </itemizedlist>
  94     </para>
  95
  96     <para>
  97       libdbus only supports one-to-one connections, just like a raw network
  98       socket. However, rather than sending byte streams over the connection, you
  99       send <firstterm>messages</firstterm>. Messages have a header identifying
 100       the kind of message, and a body containing a data payload. libdbus also
 101       abstracts the exact transport used (sockets vs. whatever else), and
 102       handles details such as authentication.
 103     </para>
 104
 105     <para>
 106       The message bus daemon forms the hub of a wheel. Each spoke of the wheel
 107       is a one-to-one connection to an application using libdbus.  An
 108       application sends a message to the bus daemon over its spoke, and the bus
 109       daemon forwards the message to other connected applications as
 110       appropriate. Think of the daemon as a router.
 111     </para>
 112
 113     <para>
 114       The bus daemon has multiple instances on a typical computer.  The
 115       first instance is a machine-global singleton, that is, a system daemon
 116       similar to sendmail or Apache. This instance has heavy security
 117       restrictions on what messages it will accept, and is used for systemwide
 118       communication. The other instances are created one per user login session.
 119       These instances allow applications in the user's session to communicate
 120       with one another.
 121     </para>
 122
 123     <para>
 124       The systemwide and per-user daemons are separate.  Normal within-session
 125       IPC does not involve the systemwide message bus process and vice versa.
 126     </para>
 127
 128     <sect2 id="uses">
 129       <title>D-Bus applications</title>
 130       <para>
 131         There are many, many technologies in the world that have "Inter-process
 132         communication" or "networking" in their stated purpose: <ulink
 133         url="http://www.omg.org">CORBA</ulink>, <ulink
 134         url="http://www.opengroup.org/dce/">DCE</ulink>, <ulink
 135         url="http://www.microsoft.com/com/">DCOM</ulink>, <ulink
 136         url="http://developer.kde.org/documentation/library/kdeqt/dcop.html">DCOP</ulink>, <ulink
 137         url="http://www.xmlrpc.com">XML-RPC</ulink>, <ulink
 138         url="http://www.w3.org/TR/SOAP/">SOAP</ulink>, <ulink
 139         url="http://www.mbus.org/">MBUS</ulink>, <ulink
 140         url="http://www.zeroc.com/ice.html">Internet Communications Engine (ICE)</ulink>,
 141         and probably hundreds more.
 142         Each of these is tailored for particular kinds of application.
 143         D-Bus is designed for two specific cases:
 144         <itemizedlist>
 145           <listitem>
 146             <para>
 147               Communication between desktop applications in the same desktop
 148               session; to allow integration of the desktop session as a whole,
 149               and address issues of process lifecycle (when do desktop components
 150               start and stop running).
 151             </para>
 152           </listitem>
 153           <listitem>
 154             <para>
 155               Communication between the desktop session and the operating system,
 156               where the operating system would typically include the kernel
 157               and any system daemons or processes.
 158             </para>
 159           </listitem>
 160         </itemizedlist>
 161       </para>
 162       <para>
 163         For the within-desktop-session use case, the GNOME and KDE desktops
 164         have significant previous experience with different IPC solutions
 165         such as CORBA and DCOP. D-Bus is built on that experience and
 166         carefully tailored to meet the needs of these desktop projects
 167         in particular. D-Bus may or may not be appropriate for other
 168         applications; the FAQ has some comparisons to other IPC systems.
 169       </para>
 170       <para>
 171         The problem solved by the systemwide or communication-with-the-OS case
 172         is explained well by the following text from the Linux Hotplug project:
 173         <blockquote>
 174           <para>
 175            A gap in current Linux support is that policies with any sort of
 176            dynamic "interact with user" component aren't currently
 177            supported. For example, that's often needed the first time a network
 178            adapter or printer is connected, and to determine appropriate places
 179            to mount disk drives. It would seem that such actions could be
 180            supported for any case where a responsible human can be identified:
 181            single user workstations, or any system which is remotely
 182            administered.
 183           </para>
 184
 185           <para>
 186             This is a classic "remote sysadmin" problem, where in this case
 187             hotplugging needs to deliver an event from one security domain
 188             (operating system kernel, in this case) to another (desktop for
 189             logged-in user, or remote sysadmin). Any effective response must go
 190             the other way: the remote domain taking some action that lets the
 191             kernel expose the desired device capabilities. (The action can often
 192             be taken asynchronously, for example letting new hardware be idle
 193             until a meeting finishes.) At this writing, Linux doesn't have
 194             widely adopted solutions to such problems. However, the new D-Bus
 195             work may begin to solve that problem.
 196           </para>
 197         </blockquote>
 198       </para>
 199       <para>
 200         D-Bus may happen to be useful for purposes other than the one it was
 201         designed for. Its general properties that distinguish it from
 202         other forms of IPC are:
 203         <itemizedlist>
 204           <listitem>
 205             <para>
 206               Binary protocol designed to be used asynchronously
 207               (similar in spirit to the X Window System protocol).
 208             </para>
 209           </listitem>
 210           <listitem>
 211             <para>
 212               Stateful, reliable connections held open over time.
 213             </para>
 214           </listitem>
 215           <listitem>
 216             <para>
 217               The message bus is a daemon, not a "swarm" or
 218               distributed architecture.
 219             </para>
 220           </listitem>
 221           <listitem>
 222             <para>
 223               Many implementation and deployment issues are specified rather
 224               than left ambiguous/configurable/pluggable.
 225             </para>
 226           </listitem>
 227           <listitem>
 228             <para>
 229               Semantics are similar to the existing DCOP system, allowing
 230               KDE to adopt it more easily.
 231             </para>
 232           </listitem>
 233           <listitem>
 234             <para>
 235               Security features to support the systemwide mode of the
 236               message bus.
 237             </para>
 238           </listitem>
 239         </itemizedlist>
 240       </para>
 241     </sect2>
 242   </sect1>
 243   <sect1 id="concepts">
 244     <title>Concepts</title>
 245     <para>
 246       Some basic concepts apply no matter what application framework you're
 247       using to write a D-Bus application. The exact code you write will be
 248       different for GLib vs. Qt vs. Python applications, however.
 249     </para>
 250
 251     <para>
 252       Here is a diagram (<ulink url="diagram.png">png</ulink> <ulink
 253       url="diagram.svg">svg</ulink>) that may help you visualize the concepts
 254       that follow.
 255     </para>
 256
 257     <sect2 id="objects">
 258       <title>Native Objects and Object Paths</title>
 259       <para>
 260         Your programming framework probably defines what an "object" is like;
 261         usually with a base class. For example: java.lang.Object, GObject, QObject,
 262         python's base Object, or whatever. Let's call this a <firstterm>native object</firstterm>.
 263       </para>
 264       <para>
 265         The low-level D-Bus protocol, and corresponding libdbus API, does not care about native objects.
 266         However, it provides a concept called an
 267         <firstterm>object path</firstterm>. The idea of an object path is that
 268         higher-level bindings can name native object instances, and allow remote applications
 269         to refer to them.
 270       </para>
 271       <para>
 272         The object path
 273         looks like a filesystem path, for example an object could be
 274         named <literal>/org/kde/kspread/sheets/3/cells/4/5</literal>.
 275         Human-readable paths are nice, but you are free to create an
 276         object named <literal>/com/mycompany/c5yo817y0c1y1c5b</literal>
 277         if it makes sense for your application.
 278       </para>
 279       <para>
 280         Namespacing object paths is smart, by starting them with the components
 281         of a domain name you own (e.g. <literal>/org/kde</literal>). This
 282         keeps different code modules in the same process from stepping
 283         on one another's toes.
 284       </para>
 285     </sect2>
 286
 287     <sect2 id="members">
 288       <title>Methods and Signals</title>
 289
 290       <para>
 291         Each object has <firstterm>members</firstterm>; the two kinds of member
 292         are <firstterm>methods</firstterm> and
 293         <firstterm>signals</firstterm>. Methods are operations that can be
 294         invoked on an object, with optional input (aka arguments or "in
 295         parameters") and output (aka return values or "out parameters").
 296         Signals are broadcasts from the object to any interested observers
 297         of the object; signals may contain a data payload.
 298       </para>
 299
 300       <para>
 301         Both methods and signals are referred to by name, such as
 302         "Frobate" or "OnClicked".
 303       </para>
 304
 305     </sect2>
 306
 307     <sect2 id="interfaces">
 308       <title>Interfaces</title>
 309       <para>
 310         Each object supports one or more <firstterm>interfaces</firstterm>.
 311         Think of an interface as a named group of methods and signals,
 312         just as it is in GLib or Qt or Java. Interfaces define the
 313         <emphasis>type</emphasis> of an object instance.
 314       </para>
 315       <para>
 316         DBus identifies interfaces with a simple namespaced string,
 317         something like <literal>org.freedesktop.Introspectable</literal>.
 318         Most bindings will map these interface names directly to
 319         the appropriate programming language construct, for example
 320         to Java interfaces or C++ pure virtual classes.
 321       </para>
 322     </sect2>
 323
 324     <sect2 id="proxies">
 325       <title>Proxies</title>
 326       <para>
 327         A <firstterm>proxy object</firstterm> is a convenient native object created to
 328         represent a remote object in another process. The low-level DBus API involves manually creating
 329         a method call message, sending it, then manually receiving and processing
 330         the method reply message. Higher-level bindings provide proxies as an alternative.
 331         Proxies look like a normal native object; but when you invoke a method on the proxy
 332         object, the binding converts it into a DBus method call message, waits for the reply
 333         message, unpacks the return value, and returns it from the native method..
 334       </para>
 335       <para>
 336         In pseudocode, programming without proxies might look like this:
 337         <programlisting>
 338           Message message = new Message("/remote/object/path", "MethodName", arg1, arg2);
 339           Connection connection = getBusConnection();
 340           connection.send(message);
 341           Message reply = connection.waitForReply(message);
 342           if (reply.isError()) {
 343
 344           } else {
 345              Object returnValue = reply.getReturnValue();
 346           }
 347         </programlisting>
 348       </para>
 349       <para>
 350         Programming with proxies might look like this:
 351         <programlisting>
 352           Proxy proxy = new Proxy(getBusConnection(), "/remote/object/path");
 353           Object returnValue = proxy.MethodName(arg1, arg2);
 354         </programlisting>
 355       </para>
 356     </sect2>
 357
 358     <sect2 id="bus-names">
 359       <title>Bus Names</title>
 360
 361       <para>
 362         When each application connects to the bus daemon, the daemon immediately
 363         assigns it a name, called the <firstterm>unique connection name</firstterm>.
 364         A unique name begins with a ':' (colon) character. These names are never
 365         reused during the lifetime of the bus daemon - that is, you know
 366         a given name will always refer to the same application.
 367         An example of a unique name might be
 368         <literal>:34-907</literal>. The numbers after the colon have
 369         no meaning other than their uniqueness.
 370       </para>
 371
 372       <para>
 373         When a name is mapped
 374         to a particular application's connection, that application is said to
 375         <firstterm>own</firstterm> that name.
 376       </para>
 377
 378       <para>
 379         Applications may ask to own additional <firstterm>well-known
 380         names</firstterm>. For example, you could write a specification to
 381         define a name called <literal>com.mycompany.TextEditor</literal>.
 382         Your definition could specify that to own this name, an application
 383         should have an object at the path
 384         <literal>/com/mycompany/TextFileManager</literal> supporting the
 385         interface <literal>org.freedesktop.FileHandler</literal>.
 386       </para>
 387
 388       <para>
 389         Applications could then send messages to this bus name,
 390         object, and interface to execute method calls.
 391       </para>
 392
 393       <para>
 394         You could think of the unique names as IP addresses, and the
 395         well-known names as domain names. So
 396         <literal>com.mycompany.TextEditor</literal> might map to something like
 397         <literal>:34-907</literal> just as <literal>mycompany.com</literal> maps
 398         to something like <literal>192.168.0.5</literal>.
 399       </para>
 400
 401       <para>
 402         Names have a second important use, other than routing messages.  They
 403         are used to track lifecycle. When an application exits (or crashes), its
 404         connection to the message bus will be closed by the operating system
 405         kernel. The message bus then sends out notification messages telling
 406         remaining applications that the application's names have lost their
 407         owner. By tracking these notifications, your application can reliably
 408         monitor the lifetime of other applications.
 409       </para>
 410
 411       <para>
 412         Bus names can also be used to coordinate single-instance applications.
 413         If you want to be sure only one
 414         <literal>com.mycompany.TextEditor</literal> application is running for
 415         example, have the text editor application exit if the bus name already
 416         has an owner.
 417       </para>
 418
 419     </sect2>
 420
 421     <sect2 id="addresses">
 422       <title>Addresses</title>
 423
 424       <para>
 425         Applications using D-Bus are either servers or clients.  A server
 426         listens for incoming connections; a client connects to a server. Once
 427         the connection is established, it is a symmetric flow of messages; the
 428         client-server distinction only matters when setting up the
 429         connection.
 430       </para>
 431
 432       <para>
 433         If you're using the bus daemon, as you probably are, your application
 434         will be a client of the bus daemon. That is, the bus daemon listens
 435         for connections and your application initiates a connection to the bus
 436         daemon.
 437       </para>
 438
 439       <para>
 440         A D-Bus <firstterm>address</firstterm> specifies where a server will
 441         listen, and where a client will connect.  For example, the address
 442         <literal>unix:path=/tmp/abcdef</literal> specifies that the server will
 443         listen on a UNIX domain socket at the path
 444         <literal>/tmp/abcdef</literal> and the client will connect to that
 445         socket. An address can also specify TCP/IP sockets, or any other
 446         transport defined in future iterations of the D-Bus specification.
 447       </para>
 448
 449       <para>
 450         When using D-Bus with a message bus daemon,
 451         libdbus automatically discovers the address of the per-session bus
 452         daemon by reading an environment variable. It discovers the
 453         systemwide bus daemon by checking a well-known UNIX domain socket path
 454         (though you can override this address with an environment variable).
 455       </para>
 456
 457       <para>
 458         If you're using D-Bus without a bus daemon, it's up to you to
 459         define which application will be the server and which will be
 460         the client, and specify a mechanism for them to agree on
 461         the server's address. This is an unusual case.
 462       </para>
 463
 464     </sect2>
 465
 466     <sect2 id="bigpicture">
 467       <title>Big Conceptual Picture</title>
 468
 469       <para>
 470         Pulling all these concepts together, to specify a particular
 471         method call on a particular object instance, a number of
 472         nested components have to be named:
 473         <programlisting>
 474           Address -&gt; [Bus Name] -&gt; Path -&gt; Interface -&gt; Method
 475         </programlisting>
 476         The bus name is in brackets to indicate that it's optional -- you only
 477         provide a name to route the method call to the right application
 478         when using the bus daemon. If you have a direct connection to another
 479         application, bus names aren't used; there's no bus daemon.
 480       </para>
 481
 482       <para>
 483         The interface is also optional, primarily for historical
 484         reasons; DCOP does not require specifying the interface,
 485         instead simply forbidding duplicate method names
 486         on the same object instance. D-Bus will thus let you
 487         omit the interface, but if your method name is ambiguous
 488         it is undefined which method will be invoked.
 489       </para>
 490
 491     </sect2>
 492
 493     <sect2 id="messages">
 494       <title>Messages - Behind the Scenes</title>
 495       <para>
 496         D-Bus works by sending messages between processes. If you're using
 497         a sufficiently high-level binding, you may never work with messages directly.
 498       </para>
 499       <para>
 500         There are 4 message types:
 501         <itemizedlist>
 502           <listitem>
 503             <para>
 504               Method call messages ask to invoke a method
 505               on an object.
 506             </para>
 507           </listitem>
 508           <listitem>
 509             <para>
 510               Method return messages return the results
 511               of invoking a method.
 512             </para>
 513           </listitem>
 514           <listitem>
 515             <para>
 516               Error messages return an exception caused by
 517               invoking a method.
 518             </para>
 519           </listitem>
 520           <listitem>
 521             <para>
 522               Signal messages are notifications that a given signal
 523               has been emitted (that an event has occurred).
 524               You could also think of these as "event" messages.
 525             </para>
 526           </listitem>
 527         </itemizedlist>
 528       </para>
 529       <para>
 530         A method call maps very simply to messages: you send a method call
 531         message, and receive either a method return message or an error message
 532         in reply.
 533       </para>
 534       <para>
 535         Each message has a <firstterm>header</firstterm>, including <firstterm>fields</firstterm>,
 536         and a <firstterm>body</firstterm>, including <firstterm>arguments</firstterm>. You can think
 537         of the header as the routing information for the message, and the body as the payload.
 538         Header fields might include the sender bus name, destination bus name, method or signal name,
 539         and so forth. One of the header fields is a <firstterm>type signature</firstterm> describing the
 540         values found in the body. For example, the letter "i" means "32-bit integer" so the signature
 541         "ii" means the payload has two 32-bit integers.
 542       </para>
 543     </sect2>
 544
 545     <sect2 id="callprocedure">
 546       <title>Calling a Method - Behind the Scenes</title>
 547
 548       <para>
 549         A method call in DBus consists of two messages; a method call message sent from process A to process B,
 550         and a matching method reply message sent from process B to process A. Both the call and the reply messages
 551         are routed through the bus daemon. The caller includes a different serial number in each call message, and the
 552         reply message includes this number to allow the caller to match replies to calls.
 553       </para>
 554
 555       <para>
 556         The call message will contain any arguments to the method.
 557         The reply message may indicate an error, or may contain data returned by the method.
 558       </para>
 559
 560       <para>
 561         A method invocation in DBus happens as follows:
 562         <itemizedlist>
 563           <listitem>
 564             <para>
 565               The language binding may provide a proxy, such that invoking a method on
 566               an in-process object invokes a method on a remote object in another process. If so, the
 567               application calls a method on the proxy, and the proxy
 568               constructs a method call message to send to the remote process.
 569             </para>
 570           </listitem>
 571           <listitem>
 572             <para>
 573               For more low-level APIs, the application may construct a method call message itself, without
 574               using a proxy.
 575             </para>
 576           </listitem>
 577           <listitem>
 578             <para>
 579               In either case, the method call message contains: a bus name belonging to the remote process; the name of the method;
 580               the arguments to the method; an object path inside the remote process; and optionally the name of the
 581               interface that specifies the method.
 582             </para>
 583           </listitem>
 584           <listitem>
 585             <para>
 586               The method call message is sent to the bus daemon.
 587             </para>
 588           </listitem>
 589           <listitem>
 590             <para>
 591               The bus daemon looks at the destination bus name. If a process owns that name,
 592               the bus daemon forwards the method call to that process. Otherwise, the bus daemon
 593               creates an error message and sends it back as the reply to the method call message.
 594             </para>
 595           </listitem>
 596           <listitem>
 597             <para>
 598               The receiving process unpacks the method call message. In a simple low-level API situation, it
 599               may immediately run the method and send a method reply message to the bus daemon.
 600               When using a high-level binding API, the binding might examine the object path, interface,
 601               and method name, and convert the method call message into an invocation of a method on
 602               a native object (GObject, java.lang.Object, QObject, etc.), then convert the return
 603               value from the native method into a method reply message.
 604             </para>
 605           </listitem>
 606           <listitem>
 607             <para>
 608               The bus daemon receives the method reply message and sends it to the process that
 609               made the method call.
 610             </para>
 611           </listitem>
 612           <listitem>
 613             <para>
 614               The process that made the method call looks at the method reply and makes use of any
 615               return values included in the reply. The reply may also indicate that an error occurred.
 616               When using a binding, the method reply message may be converted into the return value of
 617               of a proxy method, or into an exception.
 618             </para>
 619           </listitem>
 620         </itemizedlist>
 621       </para>
 622
 623       <para>
 624         The bus daemon never reorders messages. That is, if you send two method call messages to the same recipient,
 625         they will be received in the order they were sent. The recipient is not required to reply to the calls
 626         in order, however; for example, it may process each method call in a separate thread, and return reply messages
 627         in an undefined order depending on when the threads complete. Method calls have a unique serial
 628         number used by the method caller to match reply messages to call messages.
 629       </para>
 630
 631     </sect2>
 632
 633     <sect2 id="signalprocedure">
 634       <title>Emitting a Signal - Behind the Scenes</title>
 635
 636       <para>
 637         A signal in DBus consists of a single message, sent by one process to any number of other processes.
 638         That is, a signal is a unidirectional broadcast. The signal may contain arguments (a data payload), but
 639         because it is a broadcast, it never has a "return value." Contrast this with a method call
 640         (see <xref linkend="callprocedure"/>) where the method call message has a matching method reply message.
 641       </para>
 642
 643       <para>
 644         The emitter (aka sender) of a signal has no knowledge of the signal recipients. Recipients register
 645         with the bus daemon to receive signals based on "match rules" - these rules would typically include the sender and
 646         the signal name. The bus daemon sends each signal only to recipients who have expressed interest in that
 647         signal.
 648       </para>
 649
 650       <para>
 651         A signal in DBus happens as follows:
 652         <itemizedlist>
 653           <listitem>
 654             <para>
 655               A signal message is created and sent to the bus daemon. When using the low-level API this may be
 656               done manually, with certain bindings it may be done for you by the binding when a native object
 657               emits a native signal or event.
 658             </para>
 659           </listitem>
 660           <listitem>
 661             <para>
 662               The signal message contains the name of the interface that specifies the signal;
 663               the name of the signal; the bus name of the process sending the signal; and
 664               any arguments
 665             </para>
 666           </listitem>
 667           <listitem>
 668             <para>
 669               Any process on the message bus can register "match rules" indicating which signals it
 670               is interested in. The bus has a list of registered match rules.
 671             </para>
 672           </listitem>
 673           <listitem>
 674             <para>
 675               The bus daemon examines the signal and determines which processes are interested in it.
 676               It sends the signal message to these processes.
 677             </para>
 678           </listitem>
 679           <listitem>
 680             <para>
 681               Each process receiving the signal decides what to do with it; if using a binding,
 682               the binding may choose to emit a native signal on a proxy object. If using the
 683               low-level API, the process may just look at the signal sender and name and decide
 684               what to do based on that.
 685             </para>
 686           </listitem>
 687         </itemizedlist>
 688       </para>
 689
 690     </sect2>
 691
 692     <sect2 id="introspection">
 693       <title>Introspection</title>
 694
 695       <para>
 696         D-Bus objects may support the interface <literal>org.freedesktop.DBus.Introspectable</literal>.
 697         This interface has one method <literal>Introspect</literal> which takes no arguments and returns
 698         an XML string. The XML string describes the interfaces, methods, and signals of the object.
 699         See the D-Bus specification for more details on this introspection format.
 700       </para>
 701
 702     </sect2>
 703
 704   </sect1>
 705
 706   <sect1 id="glib-client">
 707     <title>GLib API: Using Remote Objects</title>
 708
 709     <para>
 710       The GLib binding is defined in the header file
 711       <literal>&lt;dbus/dbus-glib.h&gt;</literal>.
 712     </para>
 713
 714     <sect2 id="glib-typemappings">
 715       <title>D-Bus - GLib type mappings</title>
 716       <para>
 717         The heart of the GLib bindings for D-Bus is the mapping it
 718         provides between D-Bus "type signatures" and GLib types
 719         (<literal>GType</literal>). The D-Bus type system is composed of
 720         a number of "basic" types, along with several "container" types.
 721       </para>
 722       <sect3 id="glib-basic-typemappings">
 723         <title>Basic type mappings</title>
 724         <para>
 725           Below is a list of the basic types, along with their associated
 726           mapping to a <literal>GType</literal>.
 727           <informaltable>
 728             <tgroup cols="4">
 729               <thead>
 730                 <row>
 731                   <entry>D-Bus basic type</entry>
 732                   <entry>GType</entry>
 733                   <entry>Free function</entry>
 734                   <entry>Notes</entry>
 735                 </row>
 736               </thead>
 737               <tbody>
 738                 <row>
 739                   <entry><literal>BYTE</literal></entry>
 740                   <entry><literal>G_TYPE_UCHAR</literal></entry>
 741                   <entry></entry>
 742                   <entry></entry>
 743                   </row><row>
 744                   <entry><literal>BOOLEAN</literal></entry>
 745                   <entry><literal>G_TYPE_BOOLEAN</literal></entry>
 746                   <entry></entry>
 747                   <entry></entry>
 748                   </row><row>
 749                   <entry><literal>INT16</literal></entry>
 750                   <entry><literal>G_TYPE_INT</literal></entry>
 751                   <entry></entry>
 752                   <entry>Will be changed to a <literal>G_TYPE_INT16</literal> once GLib has it</entry>
 753                   </row><row>
 754                   <entry><literal>UINT16</literal></entry>
 755                   <entry><literal>G_TYPE_UINT</literal></entry>
 756                   <entry></entry>
 757                   <entry>Will be changed to a <literal>G_TYPE_UINT16</literal> once GLib has it</entry>
 758                   </row><row>
 759                   <entry><literal>INT32</literal></entry>
 760                   <entry><literal>G_TYPE_INT</literal></entry>
 761                   <entry></entry>
 762                   <entry>Will be changed to a <literal>G_TYPE_INT32</literal> once GLib has it</entry>
 763                   </row><row>
 764                   <entry><literal>UINT32</literal></entry>
 765                   <entry><literal>G_TYPE_UINT</literal></entry>
 766                   <entry></entry>
 767                   <entry>Will be changed to a <literal>G_TYPE_UINT32</literal> once GLib has it</entry>
 768                   </row><row>
 769                   <entry><literal>INT64</literal></entry>
 770                   <entry><literal>G_TYPE_GINT64</literal></entry>
 771                   <entry></entry>
 772                   <entry></entry>
 773                   </row><row>
 774                   <entry><literal>UINT64</literal></entry>
 775                   <entry><literal>G_TYPE_GUINT64</literal></entry>
 776                   <entry></entry>
 777                   <entry></entry>
 778                   </row><row>
 779                   <entry><literal>DOUBLE</literal></entry>
 780                   <entry><literal>G_TYPE_DOUBLE</literal></entry>
 781                   <entry></entry>
 782                   <entry></entry>
 783                   </row><row>
 784                   <entry><literal>STRING</literal></entry>
 785                   <entry><literal>G_TYPE_STRING</literal></entry>
 786                   <entry><literal>g_free</literal></entry>
 787                   <entry></entry>
 788                   </row><row>
 789                   <entry><literal>OBJECT_PATH</literal></entry>
 790                   <entry><literal>DBUS_TYPE_G_PROXY</literal></entry>
 791                   <entry><literal>g_object_unref</literal></entry>
 792                   <entry>The returned proxy does not have an interface set; use <literal>dbus_g_proxy_set_interface</literal> to invoke methods</entry>
 793                 </row>
 794               </tbody>
 795             </tgroup>
 796           </informaltable>
 797           As you can see, the basic mapping is fairly straightforward.
 798         </para>
 799       </sect3>
 800       <sect3 id="glib-container-typemappings">
 801         <title>Container type mappings</title>
 802         <para>
 803           The D-Bus type system also has a number of "container"
 804           types, such as <literal>DBUS_TYPE_ARRAY</literal> and
 805           <literal>DBUS_TYPE_STRUCT</literal>.  The D-Bus type system
 806           is fully recursive, so one can for example have an array of
 807           array of strings (i.e. type signature
 808           <literal>aas</literal>).
 809         </para>
 810         <para>
 811           However, not all of these types are in common use; for
 812           example, at the time of this writing the author knows of no
 813           one using <literal>DBUS_TYPE_STRUCT</literal>, or a
 814           <literal>DBUS_TYPE_ARRAY</literal> containing any non-basic
 815           type.  The approach the GLib bindings take is pragmatic; try
 816           to map the most common types in the most obvious way, and
 817           let using less common and more complex types be less
 818           "natural".
 819         </para>
 820         <para>
 821           First, D-Bus type signatures which have an "obvious"
 822           corresponding built-in GLib type are mapped using that type:
 823           <informaltable>
 824             <tgroup cols="6">
 825               <thead>
 826                 <row>
 827                   <entry>D-Bus type signature</entry>
 828                   <entry>Description</entry>
 829                   <entry>GType</entry>
 830                   <entry>C typedef</entry>
 831                   <entry>Free function</entry>
 832                   <entry>Notes</entry>
 833                 </row>
 834               </thead>
 835               <tbody>
 836                 <row>
 837                   <entry><literal>as</literal></entry>
 838                   <entry>Array of strings</entry>
 839                   <entry><literal>G_TYPE_STRV</literal></entry>
 840                   <entry><literal>char **</literal></entry>
 841                   <entry><literal>g_strfreev</literal></entry>
 842                   <entry></entry>
 843                   </row><row>
 844                   <entry><literal>v</literal></entry>
 845                   <entry>Generic value container</entry>
 846                   <entry><literal>G_TYPE_VALUE</literal></entry>
 847                   <entry><literal>GValue *</literal></entry>
 848                   <entry><literal>g_value_unset</literal></entry>
 849                   <entry>The calling conventions for values expect that method callers have allocated return values; see below.</entry>
 850                 </row>
 851               </tbody>
 852             </tgroup>
 853           </informaltable>
 854         </para>
 855         <para>
 856           The next most common recursive type signatures are arrays of
 857           basic values.  The most obvious mapping for arrays of basic
 858           types is a <literal>GArray</literal>.  Now, GLib does not
 859           provide a builtin <literal>GType</literal> for
 860           <literal>GArray</literal>.  However, we actually need more than
 861           that - we need a "parameterized" type which includes the
 862           contained type.  Why we need this we will see below.
 863         </para>
 864         <para>
 865           The approach taken is to create these types in the D-Bus GLib
 866           bindings; however, there is nothing D-Bus specific about them.
 867           In the future, we hope to include such "fundamental" types in GLib
 868           itself.
 869           <informaltable>
 870             <tgroup cols="6">
 871               <thead>
 872                 <row>
 873                   <entry>D-Bus type signature</entry>
 874                   <entry>Description</entry>
 875                   <entry>GType</entry>
 876                   <entry>C typedef</entry>
 877                   <entry>Free function</entry>
 878                   <entry>Notes</entry>
 879                 </row>
 880               </thead>
 881               <tbody>
 882                 <row>
 883                   <entry><literal>ay</literal></entry>
 884                   <entry>Array of bytes</entry>
 885                   <entry><literal>DBUS_TYPE_G_BYTE_ARRAY</literal></entry>
 886                   <entry><literal>GArray *</literal></entry>
 887                   <entry>g_array_free</entry>
 888                   <entry></entry>
 889                 </row>
 890                 <row>
 891                   <entry><literal>au</literal></entry>
 892                   <entry>Array of uint</entry>
 893                   <entry><literal>DBUS_TYPE_G_UINT_ARRAY</literal></entry>
 894                   <entry><literal>GArray *</literal></entry>
 895                   <entry>g_array_free</entry>
 896                   <entry></entry>
 897                 </row>
 898                 <row>
 899                   <entry><literal>ai</literal></entry>
 900                   <entry>Array of int</entry>
 901                   <entry><literal>DBUS_TYPE_G_INT_ARRAY</literal></entry>
 902                   <entry><literal>GArray *</literal></entry>
 903                   <entry>g_array_free</entry>
 904                   <entry></entry>
 905                 </row>
 906                 <row>
 907                   <entry><literal>ax</literal></entry>
 908                   <entry>Array of int64</entry>
 909                   <entry><literal>DBUS_TYPE_G_INT64_ARRAY</literal></entry>
 910                   <entry><literal>GArray *</literal></entry>
 911                   <entry>g_array_free</entry>
 912                   <entry></entry>
 913                 </row>
 914                 <row>
 915                   <entry><literal>at</literal></entry>
 916                   <entry>Array of uint64</entry>
 917                   <entry><literal>DBUS_TYPE_G_UINT64_ARRAY</literal></entry>
 918                   <entry><literal>GArray *</literal></entry>
 919                   <entry>g_array_free</entry>
 920                   <entry></entry>
 921                 </row>
 922                 <row>
 923                   <entry><literal>ad</literal></entry>
 924                   <entry>Array of double</entry>
 925                   <entry><literal>DBUS_TYPE_G_DOUBLE_ARRAY</literal></entry>
 926                   <entry><literal>GArray *</literal></entry>
 927                   <entry>g_array_free</entry>
 928                   <entry></entry>
 929                 </row>
 930                 <row>
 931                   <entry><literal>ab</literal></entry>
 932                   <entry>Array of boolean</entry>
 933                   <entry><literal>DBUS_TYPE_G_BOOLEAN_ARRAY</literal></entry>
 934                   <entry><literal>GArray *</literal></entry>
 935                   <entry>g_array_free</entry>
 936                   <entry></entry>
 937                 </row>
 938               </tbody>
 939             </tgroup>
 940           </informaltable>
 941         </para>
 942         <para>
 943           D-Bus also includes a special type DBUS_TYPE_DICT_ENTRY which
 944           is only valid in arrays.  It's intended to be mapped to a "dictionary"
 945           type by bindings.  The obvious GLib mapping here is GHashTable.  Again,
 946           however, there is no builtin <literal>GType</literal> for a GHashTable.
 947           Moreover, just like for arrays, we need a parameterized type so that
 948           the bindings can communiate which types are contained in the hash table.
 949         </para>
 950         <para>
 951           At present, only strings are supported.  Work is in progress to
 952           include more types.
 953           <informaltable>
 954             <tgroup cols="6">
 955               <thead>
 956                 <row>
 957                   <entry>D-Bus type signature</entry>
 958                   <entry>Description</entry>
 959                   <entry>GType</entry>
 960                   <entry>C typedef</entry>
 961                   <entry>Free function</entry>
 962                   <entry>Notes</entry>
 963                 </row>
 964               </thead>
 965               <tbody>
 966                 <row>
 967                   <entry><literal>a{ss}</literal></entry>
 968                   <entry>Dictionary mapping strings to strings</entry>
 969                   <entry><literal>DBUS_TYPE_G_STRING_STRING_HASHTABLE</literal></entry>
 970                   <entry><literal>GHashTable *</literal></entry>
 971                   <entry>g_hash_table_destroy</entry>
 972                   <entry></entry>
 973                 </row>
 974               </tbody>
 975             </tgroup>
 976           </informaltable>
 977         </para>
 978       </sect3>
 979       <sect3 id="glib-generic-typemappings">
 980         <title>Arbitrarily recursive type mappings</title>
 981         <para>
 982           Finally, it is possible users will want to write or invoke D-Bus
 983           methods which have arbitrarily complex type signatures not
 984           directly supported by these bindings.  For this case, we have a
 985           <literal>DBusGValue</literal> which acts as a kind of special
 986           variant value which may be iterated over manually.  The
 987           <literal>GType</literal> associated is
 988           <literal>DBUS_TYPE_G_VALUE</literal>.
 989         </para>
 990         <para>
 991           TODO insert usage of <literal>DBUS_TYPE_G_VALUE</literal> here.
 992         </para>
 993       </sect3>
 994     </sect2>
 995     <sect2 id="sample-program-1">
 996       <title>A sample program</title>
 997       <para>Here is a D-Bus program using the GLib bindings.
 998 <programlisting>
 999 int
1000 main (int argc, char **argv)
1001 {
1002   DBusGConnection *connection;
1003   GError *error;
1004   DBusGProxy *proxy;
1005   char **name_list;
1006   char **name_list_ptr;
1007
1008   g_type_init ();
1009
1010   error = NULL;
1011   connection = dbus_g_bus_get (DBUS_BUS_SESSION,
1012                                &amp;error);
1013   if (connection == NULL)
1014     {
1015       g_printerr ("Failed to open connection to bus: %s\n",
1016                   error-&gt;message);
1017       g_error_free (error);
1018       exit (1);
1019     }
1020
1021   /* Create a proxy object for the "bus driver" (name "org.freedesktop.DBus") */
1022
1023   proxy = dbus_g_proxy_new_for_name (connection,
1024                                      DBUS_SERVICE_DBUS,
1025                                      DBUS_PATH_DBUS,
1026                                      DBUS_INTERFACE_DBUS);
1027
1028   /* Call ListNames method, wait for reply */
1029   error = NULL;
1030   if (!dbus_g_proxy_call (proxy, "ListNames", &amp;error, G_TYPE_INVALID,
1031                           G_TYPE_STRV, &amp;name_list, G_TYPE_INVALID))
1032     {
1033       /* Just do demonstrate remote exceptions versus regular GError */
1034       if (error->domain == DBUS_GERROR &amp;&amp; error->code == DBUS_GERROR_REMOTE_EXCEPTION)
1035         g_printerr ("Caught remote method exception %s: %s",
1036                     dbus_g_error_get_name (error),
1037                     error-&gt;message);
1038       else
1039         g_printerr ("Error: %s\n", error-&gt;message);
1040       g_error_free (error);
1041       exit (1);
1042     }
1043
1044   /* Print the results */
1045
1046   g_print ("Names on the message bus:\n");
1047
1048   for (name_list_ptr = name_list; *name_list_ptr; name_list_ptr++)
1049     {
1050       g_print ("  %s\n", *name_list_ptr);
1051     }
1052   g_strfreev (name_list);
1053
1054   g_object_unref (proxy);
1055
1056   return 0;
1057 }
1058 </programlisting>
1059     </para>
1060     </sect2>
1061     <sect2 id="glib-program-setup">
1062       <title>Program initalization</title>
1063       <para>
1064         A connection to the bus is acquired using
1065         <literal>dbus_g_bus_get</literal>.  Next, a proxy
1066         is created for the object "/org/freedesktop/DBus" with
1067         interface <literal>org.freedesktop.DBus</literal>
1068         on the service <literal>org.freedesktop.DBus</literal>.
1069         This is a proxy for the message bus itself.
1070       </para>
1071     </sect2>
1072     <sect2 id="glib-method-invocation">
1073       <title>Understanding method invocation</title>
1074       <para>
1075         You have a number of choices for method invocation.  First, as
1076         used above, <literal>dbus_g_proxy_call</literal> sends a
1077         method call to the remote object, and blocks until a reply is
1078         recieved.  The outgoing arguments are specified in the varargs
1079         array, terminated with <literal>G_TYPE_INVALID</literal>.
1080         Next, pointers to return values are specified, followed again
1081         by <literal>G_TYPE_INVALID</literal>.
1082       </para>
1083       <para>
1084         To invoke a method asynchronously, use
1085         <literal>dbus_g_proxy_begin_call</literal>.  This returns a
1086         <literal>DBusGPendingCall</literal> object; you may then set a
1087         notification function using
1088         <literal>dbus_g_pending_call_set_notify</literal>.
1089       </para>
1090     </sect2>
1091     <sect2 id="glib-signal-connection">
1092       <title>Connecting to object signals</title>
1093       <para>
1094         You may connect to signals using
1095         <literal>dbus_g_proxy_add_signal</literal> and
1096         <literal>dbus_g_proxy_connect_signal</literal>.  You must
1097         invoke <literal>dbus_g_proxy_add_signal</literal> to specify
1098         the signature of your signal handlers; you may then invoke
1099         <literal>dbus_g_proxy_connect_signal</literal> multiple times.
1100       </para>
1101       <para>
1102         Note that it will often be the case that there is no builtin
1103         marshaller for the type signature of a remote signal.  In that
1104         case, you must generate a marshaller yourself by using
1105         <application>glib-genmarshal</application>, and then register
1106         it using <literal>dbus_g_object_register_marshaller</literal>.
1107       </para>
1108     </sect2>
1109     <sect2 id="glib-error-handling">
1110       <title>Error handling and remote exceptions</title>
1111       <para>
1112         All of the GLib binding methods such as
1113         <literal>dbus_g_proxy_end_call</literal> return a
1114         <literal>GError</literal>.  This <literal>GError</literal> can
1115         represent two different things:
1116       <itemizedlist>
1117         <listitem>
1118           <para>
1119             An internal D-Bus error, such as an out-of-memory
1120             condition, an I/O error, or a network timeout.  Errors
1121             generated by the D-Bus library itself have the domain
1122             <literal>DBUS_GERROR</literal>, and a corresponding code
1123             such as <literal>DBUS_GERROR_NO_MEMORY</literal>.  It will
1124             not be typical for applications to handle these errors
1125             specifically.
1126           </para>
1127         </listitem>
1128         <listitem>
1129           <para>
1130             A remote D-Bus exception, thrown by the peer, bus, or
1131             service.  D-Bus remote exceptions have both a textual
1132             "name" and a "message".  The GLib bindings store this
1133             information in the <literal>GError</literal>, but some
1134             special rules apply.
1135           </para>
1136           <para>
1137             The set error will have the domain
1138             <literal>DBUS_GERROR</literal> as above, and will also
1139             have the code
1140             <literal>DBUS_GERROR_REMOTE_EXCEPTION</literal>.  In order
1141             to access the remote exception name, you must use a
1142             special accessor, such as
1143             <literal>dbus_g_error_has_name</literal> or
1144             <literal>dbus_g_error_get_name</literal>.  The remote
1145             exception detailed message is accessible via the regular
1146             GError <literal>message</literal> member.
1147           </para>
1148         </listitem>
1149       </itemizedlist>
1150       </para>
1151     </sect2>
1152     <sect2 id="glib-more-examples">
1153       <title>More examples of method invocation</title>
1154       <sect3 id="glib-sending-stuff">
1155         <title>Sending an integer and string, receiving an array of bytes</title>
1156         <para>
1157 <programlisting>
1158   GArray *arr;
1159
1160   error = NULL;
1161   if (!dbus_g_proxy_call (proxy, "Foobar", &amp;error,
1162                           G_TYPE_INT, 42, G_TYPE_STRING, "hello",
1163                           G_TYPE_INVALID,
1164                           DBUS_TYPE_G_UCHAR_ARRAY, &amp;arr, G_TYPE_INVALID))
1165     {
1166       /* Handle error */
1167     }
1168    g_assert (arr != NULL);
1169    printf ("got back %u values", arr->len);
1170 </programlisting>
1171         </para>
1172       </sect3>
1173       <sect3 id="glib-sending-hash">
1174         <title>Sending a GHashTable</title>
1175         <para>
1176 <programlisting>
1177   GHashTable *hash = g_hash_table_new (g_str_hash, g_str_equal);
1178   guint32 ret;
1179
1180   g_hash_table_insert (hash, "foo", "bar");
1181   g_hash_table_insert (hash, "baz", "whee");
1182
1183   error = NULL;
1184   if (!dbus_g_proxy_call (proxy, "HashSize", &amp;error,
1185                           DBUS_TYPE_G_STRING_STRING_HASH, hash, G_TYPE_INVALID,
1186                           G_TYPE_UINT, &amp;ret, G_TYPE_INVALID))
1187     {
1188       /* Handle error */
1189     }
1190   g_assert (ret == 2);
1191   g_hash_table_destroy (hash);
1192 </programlisting>
1193         </para>
1194       </sect3>
1195       <sect3 id="glib-receiving-bool-int">
1196         <title>Receiving a boolean and a string</title>
1197         <para>
1198 <programlisting>
1199   gboolean boolret;
1200   char *strret;
1201
1202   error = NULL;
1203   if (!dbus_g_proxy_call (proxy, "GetStuff", &amp;error,
1204                           G_TYPE_INVALID,
1205                           G_TYPE_BOOLEAN, &amp;boolret,
1206                           G_TYPE_STRING, &amp;strret,
1207                           G_TYPE_INVALID))
1208     {
1209       /* Handle error */
1210     }
1211   printf ("%s %s", boolret ? "TRUE" : "FALSE", strret);
1212   g_free (strret);
1213 </programlisting>
1214         </para>
1215       </sect3>
1216       <sect3 id="glib-sending-str-arrays">
1217         <title>Sending two arrays of strings</title>
1218         <para>
1219 <programlisting>
1220   /* NULL terminate */
1221   char *strs_static[] = {"foo", "bar", "baz", NULL};
1222   /* Take pointer to array; cannot pass array directly */
1223   char **strs_static_p = strs_static;
1224   char **strs_dynamic;
1225
1226   strs_dynamic = g_new (char *, 4);
1227   strs_dynamic[0] = g_strdup ("hello");
1228   strs_dynamic[1] = g_strdup ("world");
1229   strs_dynamic[2] = g_strdup ("!");
1230   /* NULL terminate */
1231   strs_dynamic[3] = NULL;
1232
1233   error = NULL;
1234   if (!dbus_g_proxy_call (proxy, "TwoStrArrays", &amp;error,
1235                           G_TYPE_STRV, strs_static_p,
1236                           G_TYPE_STRV, strs_dynamic,
1237                           G_TYPE_INVALID,
1238                           G_TYPE_INVALID))
1239     {
1240       /* Handle error */
1241     }
1242    g_strfreev (strs_dynamic);
1243 </programlisting>
1244         </para>
1245       </sect3>
1246       <sect3 id="glib-getting-str-array">
1247         <title>Sending a boolean, receiving an array of strings</title>
1248         <para>
1249 <programlisting>
1250   char **strs;
1251   char **strs_p;
1252   gboolean blah;
1253
1254   error = NULL;
1255   blah = TRUE;
1256   if (!dbus_g_proxy_call (proxy, "GetStrs", &amp;error,
1257                           G_TYPE_BOOLEAN, blah,
1258                           G_TYPE_INVALID,
1259                           G_TYPE_STRV, &amp;strs,
1260                           G_TYPE_INVALID))
1261     {
1262       /* Handle error */
1263     }
1264    for (strs_p = strs; *strs_p; strs_p++)
1265      printf ("got string: \"%s\"", *strs_p);
1266    g_strfreev (strs);
1267 </programlisting>
1268         </para>
1269       </sect3>
1270       <sect3 id="glib-sending-variant">
1271         <title>Sending a variant</title>
1272         <para>
1273 <programlisting>
1274   GValue val = {0, };
1275
1276   g_value_init (&amp;val, G_TYPE_STRING);
1277   g_value_set_string (&amp;val, "hello world");
1278
1279   error = NULL;
1280   if (!dbus_g_proxy_call (proxy, "SendVariant", &amp;error,
1281                           G_TYPE_VALUE, &amp;val, G_TYPE_INVALID,
1282                           G_TYPE_INVALID))
1283     {
1284       /* Handle error */
1285     }
1286   g_assert (ret == 2);
1287   g_value_unset (&amp;val);
1288 </programlisting>
1289         </para>
1290       </sect3>
1291       <sect3 id="glib-receiving-variant">
1292         <title>Receiving a variant</title>
1293         <para>
1294 <programlisting>
1295   GValue val = {0, };
1296
1297   error = NULL;
1298   if (!dbus_g_proxy_call (proxy, "GetVariant", &amp;error, G_TYPE_INVALID,
1299                           G_TYPE_VALUE, &amp;val, G_TYPE_INVALID))
1300     {
1301       /* Handle error */
1302     }
1303   if (G_VALUE_TYPE (&amp;val) == G_TYPE_STRING)
1304     printf ("%s\n", g_value_get_string (&amp;val));
1305   else if (G_VALUE_TYPE (&amp;val) == G_TYPE_INT)
1306     printf ("%d\n", g_value_get_int (&amp;val));
1307   else
1308     ...
1309   g_value_unset (&amp;val);
1310 </programlisting>
1311         </para>
1312       </sect3>
1313     </sect2>
1314
1315     <sect2 id="glib-generated-bindings">
1316       <title>Generated Bindings</title>
1317       <para>
1318         By using the Introspection XML files, convenient client-side bindings
1319         can be automatically created to ease the use of a remote DBus object.
1320       </para>
1321       <para>
1322         Here is a sample XML file which describes an object that exposes
1323         one method, named <literal>ManyArgs</literal>.
1324         <programlisting>
1325 &lt;?xml version="1.0" encoding="UTF-8" ?&gt;
1326 &lt;node name="/com/example/MyObject"&gt;
1327   &lt;interface name="com.example.MyObject"&gt;
1328     &lt;method name="ManyArgs"&gt;
1329       &lt;arg type="u" name="x" direction="in" /&gt;
1330       &lt;arg type="s" name="str" direction="in" /&gt;
1331       &lt;arg type="d" name="trouble" direction="in" /&gt;
1332       &lt;arg type="d" name="d_ret" direction="out" /&gt;
1333       &lt;arg type="s" name="str_ret" direction="out" /&gt;
1334     &lt;/method&gt;
1335   &lt;/interface&gt;
1336 &lt;/node&gt;
1337 </programlisting>
1338       </para>
1339       <para>
1340         Run <literal>dbus-binding-tool --mode=glib-client
1341           <replaceable>FILENAME</replaceable> &gt;
1342           <replaceable>HEADER_NAME</replaceable></literal> to generate the header
1343         file.  For example: <command>dbus-binding-tool --mode=glib-client
1344           my-object.xml &gt; my-object-bindings.h</command>.  This will generate
1345         inline functions with the following prototypes:
1346         <programlisting>
1347 /* This is a blocking call */
1348 gboolean
1349 com_example_MyObject_many_args (DBusGProxy *proxy, const guint IN_x,
1350                                 const char * IN_str, const gdouble IN_trouble,
1351                                 gdouble* OUT_d_ret, char ** OUT_str_ret,
1352                                 GError **error);
1353
1354 /* This is a non-blocking call */
1355 DBusGProxyCall*
1356 com_example_MyObject_many_args_async (DBusGProxy *proxy, const guint IN_x,
1357                                       const char * IN_str, const gdouble IN_trouble,
1358                                       com_example_MyObject_many_args_reply callback,
1359                                       gpointer userdata);
1360
1361 /* This is the typedef for the non-blocking callback */
1362 typedef void
1363 (*com_example_MyObject_many_args_reply)
1364 (DBusGProxy *proxy, gdouble OUT_d_ret, char * OUT_str_ret,
1365  GError *error, gpointer userdata);
1366 </programlisting>
1367         The first argument in all functions is a <literal>DBusGProxy
1368         *</literal>, which you should create with the usual
1369         <literal>dbus_g_proxy_new_*</literal> functions.  Following that are the
1370         "in" arguments, and then either the "out" arguments and a
1371         <literal>GError *</literal> for the synchronous (blocking) function, or
1372         callback and user data arguments for the asynchronous (non-blocking)
1373         function.  The callback in the asynchronous function passes the
1374         <literal>DBusGProxy *</literal>, the returned "out" arguments, an
1375         <literal>GError *</literal> which is set if there was an error otherwise
1376         <literal>NULL</literal>, and the user data.
1377       </para>
1378       <para>
1379         As with the server-side bindings support (see <xref
1380         linkend="glib-server"/>), the exact behaviour of the client-side
1381         bindings can be manipulated using "annotations".  Currently the only
1382         annotation used by the client bindings is
1383         <literal>org.freedesktop.DBus.GLib.NoReply</literal>, which sets the
1384         flag indicating that the client isn't expecting a reply to the method
1385         call, so a reply shouldn't be sent.  This is often used to speed up
1386         rapid method calls where there are no "out" arguments, and not knowing
1387         if the method succeeded is an acceptable compromise to half the traffic
1388         on the bus.
1389       </para>
1390     </sect2>
1391   </sect1>
1392
1393   <sect1 id="glib-server">
1394     <title>GLib API: Implementing Objects</title>
1395     <para>
1396       At the moment, to expose a GObject via D-Bus, you must
1397       write XML by hand which describes the methods exported
1398       by the object.  In the future, this manual step will
1399       be obviated by the upcoming GLib introspection support.
1400     </para>
1401     <para>
1402       Here is a sample XML file which describes an object that exposes
1403       one method, named <literal>ManyArgs</literal>.
1404 <programlisting>
1405 &lt;?xml version="1.0" encoding="UTF-8" ?&gt;
1406
1407 &lt;node name="/com/example/MyObject"&gt;
1408
1409   &lt;interface name="com.example.MyObject"&gt;
1410     &lt;annotation name="org.freedesktop.DBus.GLib.CSymbol" value="my_object"/&gt;
1411     &lt;method name="ManyArgs"&gt;
1412       &lt;!-- This is optional, and in this case is redunundant --&gt;
1413       &lt;annotation name="org.freedesktop.DBus.GLib.CSymbol" value="my_object_many_args"/&gt;
1414       &lt;arg type="u" name="x" direction="in" /&gt;
1415       &lt;arg type="s" name="str" direction="in" /&gt;
1416       &lt;arg type="d" name="trouble" direction="in" /&gt;
1417       &lt;arg type="d" name="d_ret" direction="out" /&gt;
1418       &lt;arg type="s" name="str_ret" direction="out" /&gt;
1419     &lt;/method&gt;
1420   &lt;/interface&gt;
1421 &lt;/node&gt;
1422 </programlisting>
1423     </para>
1424     <para>
1425       This XML is in the same format as the D-Bus introspection XML
1426       format. Except we must include an "annotation" which give the C
1427       symbols corresponding to the object implementation prefix
1428       (<literal>my_object</literal>).  In addition, if particular
1429       methods symbol names deviate from C convention
1430       (i.e. <literal>ManyArgs</literal> -&gt;
1431       <literal>many_args</literal>), you may specify an annotation
1432       giving the C symbol.
1433     </para>
1434     <para>
1435       Once you have written this XML, run <literal>dbus-binding-tool --mode=glib-server <replaceable>FILENAME</replaceable> &gt; <replaceable>HEADER_NAME</replaceable>.</literal> to
1436       generate a header file.  For example: <command>dbus-binding-tool --mode=glib-server my-object.xml &gt; my-object-glue.h</command>.
1437     </para>
1438     <para>
1439       Next, include the generated header in your program, and invoke
1440       <literal>dbus_g_object_class_install_info</literal> in the class
1441       initializer, passing the object class and "object info" included in the
1442       header.  For example:
1443       <programlisting>
1444         dbus_g_object_type_install_info (COM_FOO_TYPE_MY_OBJECT, &amp;com_foo_my_object_info);
1445       </programlisting>
1446       This should be done exactly once per object class.
1447     </para>
1448     <para>
1449       To actually implement the method, just define a C function named e.g.
1450       <literal>my_object_many_args</literal> in the same file as the info
1451       header is included.  At the moment, it is required that this function
1452       conform to the following rules:
1453       <itemizedlist>
1454         <listitem>
1455           <para>
1456             The function must return a value of type <literal>gboolean</literal>;
1457             <literal>TRUE</literal> on success, and <literal>FALSE</literal>
1458             otherwise.
1459           </para>
1460         </listitem>
1461         <listitem>
1462           <para>
1463             The first parameter is a pointer to an instance of the object.
1464           </para>
1465         </listitem>
1466         <listitem>
1467           <para>
1468             Following the object instance pointer are the method
1469             input values.
1470           </para>
1471         </listitem>
1472         <listitem>
1473           <para>
1474             Following the input values are pointers to return values.
1475           </para>
1476         </listitem>
1477         <listitem>
1478           <para>
1479             The final parameter must be a <literal>GError **</literal>.
1480             If the function returns <literal>FALSE</literal> for an
1481             error, the error parameter must be initalized with
1482             <literal>g_set_error</literal>.
1483           </para>
1484         </listitem>
1485       </itemizedlist>
1486     </para>
1487     <para>
1488       Finally, you can export an object using <literal>dbus_g_connection_register_g_object</literal>.  For example:
1489       <programlisting>
1490           dbus_g_connection_register_g_object (connection,
1491                                                "/com/foo/MyObject",
1492                                                obj);
1493       </programlisting>
1494     </para>
1495
1496     <sect2 id="glib-annotations">
1497       <title>Server-side Annotations</title>
1498       <para>
1499         There are several annotations that are used when generating the
1500         server-side bindings.  The most common annotation is
1501         <literal>org.freedesktop.DBus.GLib.CSymbol</literal> but there are other
1502         annotations which are often useful.
1503         <variablelist>
1504           <varlistentry>
1505             <term><literal>org.freedesktop.DBus.GLib.CSymbol</literal></term>
1506             <listitem>
1507               <para>
1508                 This annotation is used to specify the C symbol names for
1509                 the various types (interface, method, etc), if it differs from the
1510                 name DBus generates.
1511               </para>
1512             </listitem>
1513           </varlistentry>
1514           <varlistentry>
1515             <term><literal>org.freedesktop.DBus.GLib.Async</literal></term>
1516             <listitem>
1517               <para>
1518                 This annotation marks the method implementation as an
1519                 asynchronous function, which doesn't return a response straight
1520                 away but will send the response at some later point to complete
1521                 the call.  This is used to implement non-blocking services where
1522                 method calls can take time.
1523               </para>
1524               <para>
1525                 When a method is asynchronous, the function prototype is
1526                 different. It is required that the function conform to the
1527                 following rules:
1528                 <itemizedlist>
1529                   <listitem>
1530                     <para>
1531                       The function must return a value of type <literal>gboolean</literal>;
1532                       <literal>TRUE</literal> on success, and <literal>FALSE</literal>
1533                       otherwise. TODO: the return value is currently ignored.
1534                     </para>
1535                   </listitem>
1536                   <listitem>
1537                     <para>
1538                       The first parameter is a pointer to an instance of the object.
1539                     </para>
1540                   </listitem>
1541                   <listitem>
1542                     <para>
1543                       Following the object instance pointer are the method
1544                       input values.
1545                     </para>
1546                   </listitem>
1547                   <listitem>
1548                     <para>
1549                       The final parameter must be a
1550                       <literal>DBusGMethodInvocation *</literal>.  This is used
1551                       when sending the response message back to the client, by
1552                       calling <literal>dbus_g_method_return</literal> or
1553                       <literal>dbus_g_method_return_error</literal>.
1554                     </para>
1555                   </listitem>
1556                 </itemizedlist>
1557               </para>
1558             </listitem>
1559           </varlistentry>
1560           <varlistentry>
1561             <term><literal>org.freedesktop.DBus.GLib.Const</literal></term>
1562             <listitem>
1563               <para>This attribute can only be applied to "out"
1564               <literal>&lt;arg&gt;</literal> nodes, and specifies that the
1565               parameter isn't being copied when returned.  For example, this
1566               turns a 's' argument from a <literal>char **</literal> to a
1567               <literal>const char **</literal>, and results in the argument not
1568               being freed by DBus after the message is sent.
1569               </para>
1570             </listitem>
1571           </varlistentry>
1572           <varlistentry>
1573             <term><literal>org.freedesktop.DBus.GLib.ReturnVal</literal></term>
1574             <listitem>
1575               <para>
1576                 This attribute can only be applied to "out"
1577                 <literal>&lt;arg&gt;</literal> nodes, and alters the expected
1578                 function signature.  It currently can be set to two values:
1579                 <literal>""</literal> or <literal>"error"</literal>.  The
1580                 argument marked with this attribute is not returned via a
1581                 pointer argument, but by the function's return value.  If the
1582                 attribute's value is the empty string, the <literal>GError
1583                 *</literal> argument is also omitted so there is no standard way
1584                 to return an error value.  This is very useful for interfacing
1585                 with existing code, as it is possible to match existing APIs.
1586                 If the attribute's value is <literal>"error"</literal>, then the
1587                 final argument is a <literal>GError *</literal> as usual.
1588               </para>
1589               <para>
1590                 Some examples to demonstrate the usage. This introspection XML:
1591                 <programlisting>
1592 &lt;method name="Increment"&gt;
1593   &lt;arg type="u" name="x" /&gt;
1594   &lt;arg type="u" direction="out" /&gt;
1595 &lt;/method&gt;
1596                 </programlisting>
1597                 Expects the following function declaration:
1598                 <programlisting>
1599 gboolean
1600 my_object_increment (MyObject *obj, gint32 x, gint32 *ret, GError **error);
1601                 </programlisting>
1602               </para>
1603               <para>
1604                 This introspection XML:
1605                 <programlisting>
1606 &lt;method name="IncrementRetval"&gt;
1607   &lt;arg type="u" name="x" /&gt;
1608   &lt;arg type="u" direction="out" &gt;
1609     &lt;annotation name="org.freedesktop.DBus.GLib.ReturnVal" value=""/&gt;
1610   &lt;/arg&gt;
1611 &lt;/method&gt;
1612                 </programlisting>
1613                 Expects the following function declaration:
1614                 <programlisting>
1615 gint32
1616 my_object_increment_retval (MyObject *obj, gint32 x)
1617                 </programlisting>
1618               </para>
1619               <para>
1620                 This introspection XML:
1621                 <programlisting>
1622 &lt;method name="IncrementRetvalError"&gt;
1623   &lt;arg type="u" name="x" /&gt;
1624   &lt;arg type="u" direction="out" &gt;
1625     &lt;annotation name="org.freedesktop.DBus.GLib.ReturnVal" value="error"/&gt;
1626   &lt;/arg&gt;
1627 &lt;/method&gt;
1628                 </programlisting>
1629                 Expects the following function declaration:
1630                 <programlisting>
1631 gint32
1632 my_object_increment_retval_error (MyObject *obj, gint32 x, GError **error)
1633                 </programlisting>
1634               </para>
1635             </listitem>
1636           </varlistentry>
1637         </variablelist>
1638       </para>
1639     </sect2>
1640   </sect1>
1641
1642   <sect1 id="python-client">
1643     <title>Python API</title>
1644     <para>
1645       The Python API, dbus-python, is now documented separately in
1646       <ulink url="http://dbus.freedesktop.org/doc/dbus-python/doc/tutorial.html">the dbus-python tutorial</ulink> (also available in doc/tutorial.txt,
1647       and doc/tutorial.html if built with python-docutils, in the dbus-python
1648       source distribution).
1649     </para>
1650   </sect1>
1651
1652   <sect1 id="qt-client">
1653     <title>Qt API: Using Remote Objects</title>
1654     <para>
1655
1656       The Qt bindings are not yet documented.
1657
1658     </para>
1659   </sect1>
1660
1661   <sect1 id="qt-server">
1662     <title>Qt API: Implementing Objects</title>
1663     <para>
1664       The Qt bindings are not yet documented.
1665     </para>
1666   </sect1>
1667 </article>