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.3</releaseinfo>
  11     <date>18 January 2005</date>
  12     <authorgroup>
  13       <author>
  14         <firstname>Havoc</firstname>
  15         <surname>Pennington</surname>
  16         <affiliation>
  17           <orgname>Red Hat, Inc.</orgname>
  18           <address>
  19             <email>hp@pobox.com</email>
  20           </address>
  21         </affiliation>
  22       </author>
  23       <author>
  24         <firstname>David</firstname>
  25         <surname>Wheeler</surname>
  26       </author>
  27     </authorgroup>
  28   </articleinfo>
  29
  30   <sect1 id="whatis">
  31     <title>What is D-BUS?</title>
  32     <para>
  33       D-BUS is a system for <firstterm>interprocess communication</firstterm>
  34       (IPC). Architecturally, it has several layers:
  35
  36       <itemizedlist>
  37         <listitem>
  38           <para>
  39             A library, <firstterm>libdbus</firstterm>, that allows two
  40             applications to connect to each other and exchange messages.
  41           </para>
  42         </listitem>
  43         <listitem>
  44           <para>
  45             A <firstterm>message bus daemon</firstterm> executable, built on
  46             libdbus, that multiple applications can connect to. The daemon can
  47             route messages from one application to zero or more other
  48             applications.
  49           </para>
  50         </listitem>
  51         <listitem>
  52           <para>
  53             <firstterm>Wrapper libraries</firstterm> based on particular
  54             application frameworks.  For example, libdbus-glib and
  55             libdbus-qt. There are also bindings to languages such as
  56             Python. These wrapper libraries are the API most people should use,
  57             as they simplify the details of D-BUS programming. libdbus is
  58             intended to be a low-level backend for the higher level bindings.
  59             Much of the libdbus API is only useful for binding implementation.
  60           </para>
  61         </listitem>
  62       </itemizedlist>
  63     </para>
  64
  65     <para>
  66       If you just want to use D-BUS and don't care how it works, jump directly
  67       to <xref linkend="concepts"/>.
  68       Otherwise, read on.
  69     </para>
  70
  71     <para>
  72       libdbus only supports one-to-one connections, just like a raw network
  73       socket. However, rather than sending byte streams over the connection, you
  74       send <firstterm>messages</firstterm>. Messages have a header identifying
  75       the kind of message, and a body containing a data payload. libdbus also
  76       abstracts the exact transport used (sockets vs. whatever else), and
  77       handles details such as authentication.
  78     </para>
  79
  80     <para>
  81       The message bus daemon forms the hub of a wheel. Each spoke of the wheel
  82       is a one-to-one connection to an application using libdbus.  An
  83       application sends a message to the bus daemon over its spoke, and the bus
  84       daemon forwards the message to other connected applications as
  85       appropriate. Think of the daemon as a router.
  86     </para>
  87
  88     <para>
  89       The bus daemon has multiple instances on a typical computer.  The
  90       first instance is a machine-global singleton, that is, a system daemon
  91       similar to sendmail or Apache. This instance has heavy security
  92       restrictions on what messages it will accept, and is used for systemwide
  93       communication. The other instances are created one per user login session.
  94       These instances allow applications in the user's session to communicate
  95       with one another.
  96     </para>
  97
  98     <para>
  99       The systemwide and per-user daemons are separate.  Normal within-session
 100       IPC does not involve the systemwide message bus process and vice versa.
 101     </para>
 102
 103     <sect2 id="uses">
 104       <title>D-BUS applications</title>
 105       <para>
 106         There are many, many technologies in the world that have "Inter-process
 107         communication" or "networking" in their stated purpose: <ulink
 108         url="http://www.omg.org">CORBA</ulink>, <ulink
 109         url="http://www.opengroup.org/dce/">DCE</ulink>, <ulink
 110         url="http://www.microsoft.com/com/">DCOM</ulink>, <ulink
 111         url="http://developer.kde.org/documentation/library/kdeqt/dcop.html">DCOP</ulink>, <ulink
 112         url="http://www.xmlrpc.com">XML-RPC</ulink>, <ulink
 113         url="http://www.w3.org/TR/SOAP/">SOAP</ulink>, <ulink
 114         url="http://www.mbus.org/">MBUS</ulink>, <ulink
 115         url="http://www.zeroc.com/ice.html">Internet Communications Engine (ICE)</ulink>,
 116         and probably hundreds more.
 117         Each of these is tailored for particular kinds of application.
 118         D-BUS is designed for two specific cases:
 119         <itemizedlist>
 120           <listitem>
 121             <para>
 122               Communication between desktop applications in the same desktop
 123               session; to allow integration of the desktop session as a whole,
 124               and address issues of process lifecycle (when do desktop components
 125               start and stop running).
 126             </para>
 127           </listitem>
 128           <listitem>
 129             <para>
 130               Communication between the desktop session and the operating system,
 131               where the operating system would typically include the kernel
 132               and any system daemons or processes.
 133             </para>
 134           </listitem>
 135         </itemizedlist>
 136       </para>
 137       <para>
 138         For the within-desktop-session use case, the GNOME and KDE desktops
 139         have significant previous experience with different IPC solutions
 140         such as CORBA and DCOP. D-BUS is built on that experience and
 141         carefully tailored to meet the needs of these desktop projects
 142         in particular. D-BUS may or may not be appropriate for other
 143         applications; the FAQ has some comparisons to other IPC systems.
 144       </para>
 145       <para>
 146         The problem solved by the systemwide or communication-with-the-OS case
 147         is explained well by the following text from the Linux Hotplug project:
 148         <blockquote>
 149           <para>
 150            A gap in current Linux support is that policies with any sort of
 151            dynamic "interact with user" component aren't currently
 152            supported. For example, that's often needed the first time a network
 153            adapter or printer is connected, and to determine appropriate places
 154            to mount disk drives. It would seem that such actions could be
 155            supported for any case where a responsible human can be identified:
 156            single user workstations, or any system which is remotely
 157            administered.
 158           </para>
 159
 160           <para>
 161             This is a classic "remote sysadmin" problem, where in this case
 162             hotplugging needs to deliver an event from one security domain
 163             (operating system kernel, in this case) to another (desktop for
 164             logged-in user, or remote sysadmin). Any effective response must go
 165             the other way: the remote domain taking some action that lets the
 166             kernel expose the desired device capabilities. (The action can often
 167             be taken asynchronously, for example letting new hardware be idle
 168             until a meeting finishes.) At this writing, Linux doesn't have
 169             widely adopted solutions to such problems. However, the new D-Bus
 170             work may begin to solve that problem.
 171           </para>
 172         </blockquote>
 173       </para>
 174       <para>
 175         D-BUS may happen to be useful for purposes other than the one it was
 176         designed for. Its general properties that distinguish it from
 177         other forms of IPC are:
 178         <itemizedlist>
 179           <listitem>
 180             <para>
 181               Binary protocol designed to be used asynchronously
 182               (similar in spirit to the X Window System protocol).
 183             </para>
 184           </listitem>
 185           <listitem>
 186             <para>
 187               Stateful, reliable connections held open over time.
 188             </para>
 189           </listitem>
 190           <listitem>
 191             <para>
 192               The message bus is a daemon, not a "swarm" or
 193               distributed architecture.
 194             </para>
 195           </listitem>
 196           <listitem>
 197             <para>
 198               Many implementation and deployment issues are specified rather
 199               than left ambiguous.
 200             </para>
 201           </listitem>
 202           <listitem>
 203             <para>
 204               Semantics are similar to the existing DCOP system, allowing
 205               KDE to adopt it more easily.
 206             </para>
 207           </listitem>
 208           <listitem>
 209             <para>
 210               Security features to support the systemwide mode of the
 211               message bus.
 212             </para>
 213           </listitem>
 214         </itemizedlist>
 215       </para>
 216     </sect2>
 217   </sect1>
 218   <sect1 id="concepts">
 219     <title>Concepts</title>
 220     <para>
 221       Some basic concepts apply no matter what application framework you're
 222       using to write a D-BUS application. The exact code you write will be
 223       different for GLib vs. Qt vs. Python applications, however.
 224     </para>
 225
 226     <para>
 227       Here is a diagram (<ulink url="diagram.png">png</ulink> <ulink
 228       url="diagram.svg">svg</ulink>) that may help you visualize the concepts
 229       that follow.
 230     </para>
 231
 232     <sect2 id="objects">
 233       <title>Objects and Object Paths</title>
 234       <para>
 235         Each application using D-BUS contains <firstterm>objects</firstterm>,
 236         which generally map to GObject, QObject, C++ objects, or Python objects
 237         (but need not).  An object is an <emphasis>instance</emphasis> rather
 238         than a type.  When messages are received over a D-BUS connection, they
 239         are sent to a specific object, not to the application as a whole.
 240       </para>
 241       <para>
 242         To allow messages to specify their destination object, there has to be a
 243         way to refer to an object. In your favorite programming language, this
 244         is normally called a <firstterm>pointer</firstterm> or
 245         <firstterm>reference</firstterm>. However, these references are
 246         implemented as memory addresses relative to the address space of your
 247         application, and thus can't be passed from one application to another.
 248       </para>
 249       <para>
 250         To solve this, D-BUS introduces a name for each object. The name
 251         looks like a filesystem path, for example an object could be
 252         named <literal>/org/kde/kspread/sheets/3/cells/4/5</literal>.
 253         Human-readable paths are nice, but you are free to create an
 254         object named <literal>/com/mycompany/c5yo817y0c1y1c5b</literal>
 255         if it makes sense for your application.
 256       </para>
 257       <para>
 258         Namespacing object paths is smart, by starting them with the components
 259         of a domain name you own (e.g. <literal>/org/kde</literal>). This
 260         keeps different code modules in the same process from stepping
 261         on one another's toes.
 262       </para>
 263     </sect2>
 264
 265     <sect2 id="interfaces">
 266       <title>Interfaces</title>
 267       <para>
 268         Each object supports one or more <firstterm>interfaces</firstterm>.
 269         Think of an interface as a named group of methods and signals,
 270         just as it is in GLib or Qt or Java. Interfaces define the
 271         <emphasis>type</emphasis> of an object instance.
 272       </para>
 273     </sect2>
 274
 275     <sect2 id="messages">
 276       <title>Message Types</title>
 277       <para>
 278         Messages are not all the same; in particular, D-BUS has
 279         4 built-in message types:
 280         <itemizedlist>
 281           <listitem>
 282             <para>
 283               Method call messages ask to invoke a method
 284               on an object.
 285             </para>
 286           </listitem>
 287           <listitem>
 288             <para>
 289               Method return messages return the results
 290               of invoking a method.
 291             </para>
 292           </listitem>
 293           <listitem>
 294             <para>
 295               Error messages return an exception caused by
 296               invoking a method.
 297             </para>
 298           </listitem>
 299           <listitem>
 300             <para>
 301               Signal messages are notifications that a given signal
 302               has been emitted (that an event has occurred).
 303               You could also think of these as "event" messages.
 304             </para>
 305           </listitem>
 306         </itemizedlist>
 307       </para>
 308       <para>
 309         A method call maps very simply to messages, then: you send a method call
 310         message, and receive either a method return message or an error message
 311         in reply.
 312       </para>
 313     </sect2>
 314
 315     <sect2 id="bus-names">
 316       <title>Bus Names</title>
 317
 318       <para>
 319         Object paths, interfaces, and messages exist on the level of
 320         libdbus and the D-BUS protocol; they are used even in the
 321         1-to-1 case with no message bus involved.
 322       </para>
 323
 324       <para>
 325         Bus names, on the other hand, are a property of the message bus daemon.
 326         The bus maintains a mapping from names to message bus connections.
 327         These names are used to specify the origin and destination
 328         of messages passing through the message bus. When a name is mapped
 329         to a particular application's connection, that application is said to
 330         <firstterm>own</firstterm> that name.
 331       </para>
 332
 333       <para>
 334         On connecting to the bus daemon, each application immediately owns a
 335         special name called the <firstterm>unique connection name</firstterm>.
 336         A unique name begins with a ':' (colon) character; no other names are
 337         allowed to begin with that character. Unique names are special because
 338         they are created dynamically, and are never re-used during the lifetime
 339         of the same bus daemon. You know that a given unique name will have the
 340         same owner at all times.  An example of a unique name might be
 341         <literal>:34-907</literal>. The numbers after the colon have
 342         no meaning other than their uniqueness.
 343       </para>
 344
 345       <para>
 346         Applications may ask to own additional <firstterm>well-known
 347         names</firstterm>. For example, you could write a specification to
 348         define a name called <literal>com.mycompany.TextEditor</literal>.
 349         Your definition could specify that to own this name, an application
 350         should have an object at the path
 351         <literal>/com/mycompany/TextFileManager</literal> supporting the
 352         interface <literal>org.freedesktop.FileHandler</literal>.
 353       </para>
 354
 355       <para>
 356         Applications could then send messages to this bus name,
 357         object, and interface to execute method calls.
 358       </para>
 359
 360       <para>
 361         You could think of the unique names as IP addresses, and the
 362         well-known names as domain names. So
 363         <literal>com.mycompany.TextEditor</literal> might map to something like
 364         <literal>:34-907</literal> just as <literal>mycompany.com</literal> maps
 365         to something like <literal>192.168.0.5</literal>.
 366       </para>
 367
 368       <para>
 369         Names have a second important use, other than routing messages.  They
 370         are used to track lifecycle. When an application exits (or crashes), its
 371         connection to the message bus will be closed by the operating system
 372         kernel. The message bus then sends out notification messages telling
 373         remaining applications that the application's names have lost their
 374         owner. By tracking these notifications, your application can reliably
 375         monitor the lifetime of other applications.
 376       </para>
 377
 378     </sect2>
 379
 380     <sect2 id="addresses">
 381       <title>Addresses</title>
 382
 383       <para>
 384         Applications using D-BUS are either servers or clients.  A server
 385         listens for incoming connections; a client connects to a server. Once
 386         the connection is established, it is a symmetric flow of messages; the
 387         client-server distinction only matters when setting up the
 388         connection.
 389       </para>
 390
 391       <para>
 392         A D-BUS <firstterm>address</firstterm> specifies where a server will
 393         listen, and where a client will connect.  For example, the address
 394         <literal>unix:path=/tmp/abcdef</literal> specifies that the server will
 395         listen on a UNIX domain socket at the path
 396         <literal>/tmp/abcdef</literal> and the client will connect to that
 397         socket. An address can also specify TCP/IP sockets, or any other
 398         transport defined in future iterations of the D-BUS specification.
 399       </para>
 400
 401       <para>
 402         When using D-BUS with a message bus, the bus daemon is a server
 403         and all other applications are clients of the bus daemon.
 404         libdbus automatically discovers the address of the per-session bus
 405         daemon by reading an environment variable. It discovers the
 406         systemwide bus daemon by checking a well-known UNIX domain socket path
 407         (though you can override this address with an environment variable).
 408       </para>
 409
 410       <para>
 411         If you're using D-BUS without a bus daemon, it's up to you to
 412         define which application will be the server and which will be
 413         the client, and specify a mechanism for them to agree on
 414         the server's address.
 415       </para>
 416
 417     </sect2>
 418
 419     <sect2 id="bigpicture">
 420       <title>Big Conceptual Picture</title>
 421
 422       <para>
 423         Pulling all these concepts together, to specify a particular
 424         method call on a particular object instance, a number of
 425         nested components have to be named:
 426         <programlisting>
 427           Address -&gt; [Bus Name] -&gt; Path -&gt; Interface -&gt; Method
 428         </programlisting>
 429         The bus name is in brackets to indicate that it's optional -- you only
 430         provide a name to route the method call to the right application
 431         when using the bus daemon. If you have a direct connection to another
 432         application, bus names aren't used; there's no bus daemon.
 433       </para>
 434
 435       <para>
 436         The interface is also optional, primarily for historical
 437         reasons; DCOP does not require specifying the interface,
 438         instead simply forbidding duplicate method names
 439         on the same object instance. D-BUS will thus let you
 440         omit the interface, but if your method name is ambiguous
 441         it is undefined which method will be invoked.
 442       </para>
 443
 444     </sect2>
 445
 446   </sect1>
 447
 448   <sect1 id="glib-client">
 449     <title>GLib API: Using Remote Objects</title>
 450
 451     <para>
 452       The GLib binding is defined in the header file
 453       &lt;dbus/dbus-glib.h&gt;.
 454     </para>
 455
 456     <sect2 id="glib-typemappings">
 457       <title>D-BUS - GLib type mappings</title>
 458       <para>
 459         The heart of the GLib bindings for D-BUS is the mapping it
 460         provides between D-BUS "type signatures" and GLib types
 461         (<literal>GType</literal>). The D-BUS type system is composed of
 462         a number of "basic" types, along with several "container" types.
 463       </para>
 464       <sect3 id="glib-basic-typemappings">
 465         <title>Basic type mappings</title>
 466         <para>
 467           Below is a list of the basic types, along with their associated
 468           mapping to a <literal>GType</literal>.
 469           <informaltable>
 470             <tgroup cols="4">
 471               <thead>
 472                 <row>
 473                   <entry>D-BUS basic type</entry>
 474                   <entry>GType</entry>
 475                   <entry>Free function</entry>
 476                   <entry>Notes</entry>
 477                 </row>
 478               </thead>
 479               <tbody>
 480                 <row>
 481                   <entry><literal>BYTE</literal></entry>
 482                   <entry><literal>G_TYPE_UCHAR</literal></entry>
 483                   <entry></entry>
 484                   <entry></entry>
 485                   </row><row>
 486                   <entry><literal>BOOLEAN</literal></entry>
 487                   <entry><literal>G_TYPE_BOOLEAN</literal></entry>
 488                   <entry></entry>
 489                   <entry></entry>
 490                   </row><row>
 491                   <entry><literal>INT16</literal></entry>
 492                   <entry><literal>G_TYPE_INT</literal></entry>
 493                   <entry></entry>
 494                   <entry>Will be changed to a G_TYPE_INT16 once GLib has it</entry>
 495                   </row><row>
 496                   <entry><literal>UINT16</literal></entry>
 497                   <entry><literal>G_TYPE_UINT</literal></entry>
 498                   <entry></entry>
 499                   <entry>Will be changed to a G_TYPE_UINT16 once GLib has it</entry>
 500                   </row><row>
 501                   <entry><literal>INT32</literal></entry>
 502                   <entry><literal>G_TYPE_INT</literal></entry>
 503                   <entry></entry>
 504                   <entry>Will be changed to a G_TYPE_INT32 once GLib has it</entry>
 505                   </row><row>
 506                   <entry><literal>UINT32</literal></entry>
 507                   <entry><literal>G_TYPE_UINT</literal></entry>
 508                   <entry></entry>
 509                   <entry>Will be changed to a G_TYPE_UINT32 once GLib has it</entry>
 510                   </row><row>
 511                   <entry><literal>INT64</literal></entry>
 512                   <entry><literal>G_TYPE_GINT64</literal></entry>
 513                   <entry></entry>
 514                   <entry></entry>
 515                   </row><row>
 516                   <entry><literal>UINT64</literal></entry>
 517                   <entry><literal>G_TYPE_GUINT64</literal></entry>
 518                   <entry></entry>
 519                   <entry></entry>
 520                   </row><row>
 521                   <entry><literal>DOUBLE</literal></entry>
 522                   <entry><literal>G_TYPE_DOUBLE</literal></entry>
 523                   <entry></entry>
 524                   <entry></entry>
 525                   </row><row>
 526                   <entry><literal>STRING</literal></entry>
 527                   <entry><literal>G_TYPE_STRING</literal></entry>
 528                   <entry>g_free</entry>
 529                   <entry></entry>
 530                   </row><row>
 531                   <entry><literal>OBJECT_PATH</literal></entry>
 532                   <entry><literal>DBUS_TYPE_G_PROXY</literal></entry>
 533                   <entry>g_object_unref</entry>
 534                   <entry>The returned proxy does not have an interface set; use <literal>dbus_g_proxy_set_interface</literal> to invoke methods</entry>
 535                 </row>
 536               </tbody>
 537             </tgroup>
 538           </informaltable>
 539           As you can see, the basic mapping is fairly straightforward.
 540         </para>
 541       </sect3>
 542       <sect3 id="glib-container-typemappings">
 543         <title>Container type mappings</title>
 544         <para>
 545           The D-BUS type system also has a number of "container"
 546           types, such as <literal>DBUS_TYPE_ARRAY</literal> and
 547           <literal>DBUS_TYPE_STRUCT</literal>.  The D-BUS type system
 548           is fully recursive, so one can for example have an array of
 549           array of strings (i.e. type signature
 550           <literal>aas</literal>).
 551         </para>
 552         <para>
 553           However, not all of these types are in common use; for
 554           example, at the time of this writing the author knows of no
 555           one using <literal>DBUS_TYPE_STRUCT</literal>, or a
 556           <literal>DBUS_TYPE_ARRAY</literal> containing any non-basic
 557           type.  The approach the GLib bindings take is pragmatic; try
 558           to map the most common types in the most obvious way, and
 559           let using less common and more complex types be less
 560           "natural".
 561         </para>
 562         <para>
 563           First, D-BUS type signatures which have an "obvious"
 564           corresponding builtin GLib type are mapped using that type:
 565           <informaltable>
 566             <tgroup cols="6">
 567               <thead>
 568                 <row>
 569                   <entry>D-BUS type signature</entry>
 570                   <entry>Description</entry>
 571                   <entry>GType</entry>
 572                   <entry>C typedef</entry>
 573                   <entry>Free function</entry>
 574                   <entry>Notes</entry>
 575                 </row>
 576               </thead>
 577               <tbody>
 578                 <row>
 579                   <entry><literal>as</literal></entry>
 580                   <entry>Array of strings</entry>
 581                   <entry><literal>G_TYPE_STRV</literal></entry>
 582                   <entry><literal>char **</literal></entry>
 583                   <entry>g_strfreev</entry>
 584                   <entry></entry>
 585                   </row><row>
 586                   <entry><literal>v</literal></entry>
 587                   <entry>Generic value container</entry>
 588                   <entry><literal>G_TYPE_VALUE</literal></entry>
 589                   <entry><literal>GValue *</literal></entry>
 590                   <entry>g_value_unset</entry>
 591                   <entry>The calling conventions for values expect that method callers have allocated return values; see below.</entry>
 592                 </row>
 593               </tbody>
 594             </tgroup>
 595           </informaltable>
 596         </para>
 597         <para>
 598           The next most common recursive type signatures are arrays of
 599           basic values.  The most obvious mapping for arrays of basic
 600           types is a <literal>GArray</literal>.  Now, GLib does not
 601           provide a builtin <literal>GType</literal> for
 602           <literal>GArray</literal>.  However, we actually need more than
 603           that - we need a "parameterized" type which includes the
 604           contained type.  Why we need this we will see below.
 605         </para>
 606         <para>
 607           The approach taken is to create these types in the D-BUS GLib
 608           bindings; however, there is nothing D-BUS specific about them.
 609           In the future, we hope to include such "fundamental" types in GLib
 610           itself.
 611           <informaltable>
 612             <tgroup cols="6">
 613               <thead>
 614                 <row>
 615                   <entry>D-BUS type signature</entry>
 616                   <entry>Description</entry>
 617                   <entry>GType</entry>
 618                   <entry>C typedef</entry>
 619                   <entry>Free function</entry>
 620                   <entry>Notes</entry>
 621                 </row>
 622               </thead>
 623               <tbody>
 624                 <row>
 625                   <entry><literal>ay</literal></entry>
 626                   <entry>Array of bytes</entry>
 627                   <entry><literal>DBUS_TYPE_G_BYTE_ARRAY</literal></entry>
 628                   <entry><literal>GArray *</literal></entry>
 629                   <entry>g_array_free</entry>
 630                   <entry></entry>
 631                 </row>
 632                 <row>
 633                   <entry><literal>au</literal></entry>
 634                   <entry>Array of uint</entry>
 635                   <entry><literal>DBUS_TYPE_G_UINT_ARRAY</literal></entry>
 636                   <entry><literal>GArray *</literal></entry>
 637                   <entry>g_array_free</entry>
 638                   <entry></entry>
 639                 </row>
 640                 <row>
 641                   <entry><literal>ai</literal></entry>
 642                   <entry>Array of int</entry>
 643                   <entry><literal>DBUS_TYPE_G_INT_ARRAY</literal></entry>
 644                   <entry><literal>GArray *</literal></entry>
 645                   <entry>g_array_free</entry>
 646                   <entry></entry>
 647                 </row>
 648                 <row>
 649                   <entry><literal>ax</literal></entry>
 650                   <entry>Array of int64</entry>
 651                   <entry><literal>DBUS_TYPE_G_INT64_ARRAY</literal></entry>
 652                   <entry><literal>GArray *</literal></entry>
 653                   <entry>g_array_free</entry>
 654                   <entry></entry>
 655                 </row>
 656                 <row>
 657                   <entry><literal>at</literal></entry>
 658                   <entry>Array of uint64</entry>
 659                   <entry><literal>DBUS_TYPE_G_UINT64_ARRAY</literal></entry>
 660                   <entry><literal>GArray *</literal></entry>
 661                   <entry>g_array_free</entry>
 662                   <entry></entry>
 663                 </row>
 664                 <row>
 665                   <entry><literal>ad</literal></entry>
 666                   <entry>Array of double</entry>
 667                   <entry><literal>DBUS_TYPE_G_DOUBLE_ARRAY</literal></entry>
 668                   <entry><literal>GArray *</literal></entry>
 669                   <entry>g_array_free</entry>
 670                   <entry></entry>
 671                 </row>
 672                 <row>
 673                   <entry><literal>ab</literal></entry>
 674                   <entry>Array of boolean</entry>
 675                   <entry><literal>DBUS_TYPE_G_BOOLEAN_ARRAY</literal></entry>
 676                   <entry><literal>GArray *</literal></entry>
 677                   <entry>g_array_free</entry>
 678                   <entry></entry>
 679                 </row>
 680               </tbody>
 681             </tgroup>
 682           </informaltable>
 683         </para>
 684         <para>
 685           D-BUS also includes a special type DBUS_TYPE_DICT_ENTRY which
 686           is only valid in arrays.  It's intended to be mapped to a "dictionary"
 687           type by bindings.  The obvious GLib mapping here is GHashTable.  Again,
 688           however, there is no builtin <literal>GType</literal> for a GHashTable.
 689           Moreover, just like for arrays, we need a parameterized type so that
 690           the bindings can communiate which types are contained in the hash table.
 691         </para>
 692         <para>
 693           At present, only strings are supported.  Work is in progress to
 694           include more types.
 695           <informaltable>
 696             <tgroup cols="6">
 697               <thead>
 698                 <row>
 699                   <entry>D-BUS type signature</entry>
 700                   <entry>Description</entry>
 701                   <entry>GType</entry>
 702                   <entry>C typedef</entry>
 703                   <entry>Free function</entry>
 704                   <entry>Notes</entry>
 705                 </row>
 706               </thead>
 707               <tbody>
 708                 <row>
 709                   <entry><literal>a{ss}</literal></entry>
 710                   <entry>Dictionary mapping strings to strings</entry>
 711                   <entry><literal>DBUS_TYPE_G_STRING_STRING_HASHTABLE</literal></entry>
 712                   <entry><literal>GHashTable *</literal></entry>
 713                   <entry>g_hash_table_destroy</entry>
 714                   <entry></entry>
 715                 </row>
 716               </tbody>
 717             </tgroup>
 718           </informaltable>
 719         </para>
 720       </sect3>
 721       <sect3 id="glib-generic-typemappings">
 722         <title>Arbitrarily recursive type mappings</title>
 723         <para>
 724           Finally, it is possible users will want to write or invoke D-BUS
 725           methods which have arbitrarily complex type signatures not
 726           directly supported by these bindings.  For this case, we have a
 727           <literal>DBusGValue</literal> which acts as a kind of special
 728           variant value which may be iterated over manually.  The
 729           <literal>GType</literal> associated is
 730           <literal>DBUS_TYPE_G_VALUE</literal>.
 731         </para>
 732         <para>
 733           TODO insert usage of <literal>DBUS_TYPE_G_VALUE</literal> here.
 734         </para>
 735       </sect3>
 736     </sect2>
 737     <sect2 id="sample-program-1">
 738       <title>A sample program</title>
 739       <para>Here is a D-BUS program using the GLib bindings.
 740 <programlisting>
 741 int
 742 main (int argc, char **argv)
 743 {
 744   DBusGConnection *connection;
 745   GError *error;
 746   DBusGProxy *proxy;
 747   char **name_list;
 748   char **name_list_ptr;
 749
 750   g_type_init ();
 751
 752   error = NULL;
 753   connection = dbus_g_bus_get (DBUS_BUS_SESSION,
 754                                &amp;error);
 755   if (connection == NULL)
 756     {
 757       g_printerr ("Failed to open connection to bus: %s\n",
 758                   error-&gt;message);
 759       g_error_free (error);
 760       exit (1);
 761     }
 762
 763   /* Create a proxy object for the "bus driver" (name "org.freedesktop.DBus") */
 764
 765   proxy = dbus_g_proxy_new_for_name (connection,
 766                                      DBUS_SERVICE_ORG_FREEDESKTOP_DBUS,
 767                                      DBUS_PATH_ORG_FREEDESKTOP_DBUS,
 768                                      DBUS_INTERFACE_ORG_FREEDESKTOP_DBUS);
 769
 770   /* Call ListNames method, wait for reply */
 771   error = NULL;
 772   if (!dbus_g_proxy_invoke (proxy, "ListNames", &amp;error, G_TYPE_INVALID,
 773                             G_TYPE_STRV, &amp;name_list, G_TYPE_INVALID))
 774     {
 775       g_printerr ("Failed to complete ListNames call: %s\n",
 776                   error-&gt;message);
 777       g_error_free (error);
 778       exit (1);
 779     }
 780
 781   /* Print the results */
 782
 783   g_print ("Names on the message bus:\n");
 784
 785   for (name_list_ptr = name_list; *name_list_ptr; name_list_ptr++)
 786     {
 787       g_print ("  %s\n", *name_list_ptr);
 788     }
 789   g_strfreev (name_list);
 790
 791   g_object_unref (proxy);
 792
 793   return 0;
 794 }
 795 </programlisting>
 796     </para>
 797     </sect2>
 798     <sect2 id="glib-program-setup">
 799       <title>Program initalization</title>
 800       <para>
 801         A connection to the bus is acquired using
 802         <literal>dbus_g_bus_get</literal>.  Next, a proxy
 803         is created for the object "/org/freedesktop/DBus" with
 804         interface <literal>org.freedesktop.DBus</literal>
 805         on the service <literal>org.freedesktop.DBus</literal>.
 806         This is a proxy for the message bus itself.
 807       </para>
 808     </sect2>
 809     <sect2 id="glib-method-invocation">
 810       <title>Understanding method invocation</title>
 811       <para>
 812         You have a number of choices for method invocation.  First, as
 813         used above, <literal>dbus_g_proxy_invoke</literal> sends a
 814         method call to the remote object, and blocks until reply is
 815         recieved.  The outgoing arguments are specified in the varargs
 816         array, terminated with <literal>G_TYPE_INVALID</literal>.
 817         Next, pointers to return values are specified, followed again
 818         by <literal>G_TYPE_INVALID</literal>.
 819       </para>
 820       <para>
 821         To invoke a method asynchronously, use
 822         <literal>dbus_g_proxy_begin_call</literal>.  This returns a
 823         <literal>DBusGPendingCall</literal> object; you may then set a
 824         notification function using
 825         <literal>dbus_g_pending_call_set_notify</literal>.
 826       </para>
 827     </sect2>
 828     <sect2 id="glib-signal-connection">
 829       <title>Connecting to object signals</title>
 830       <para>
 831         You may connect to signals using
 832         <literal>dbus_g_proxy_add_signal</literal> and
 833         <literal>dbus_g_proxy_connect_signal</literal>.  At the
 834         moment, <literal>dbus_g_proxy_add_signal</literal> requires
 835         the D-BUS types of the remote object; this will likely be
 836         changed later.
 837       </para>
 838     </sect2>
 839     <sect2 id="glib-more-examples">
 840       <title>More examples of method invocation</title>
 841       <sect3 id="glib-sending-stuff">
 842         <title>Sending an integer and string, receiving an array of bytes</title>
 843         <para>
 844 <programlisting>
 845   GArray *arr;
 846
 847   error = NULL;
 848   if (!dbus_g_proxy_invoke (proxy, "Foobar", &amp;error,
 849                             G_TYPE_INT, 42, G_TYPE_STRING, "hello",
 850                             G_TYPE_INVALID,
 851                             DBUS_TYPE_G_UCHAR_ARRAY, &amp;arr, G_TYPE_INVALID))
 852     {
 853       g_printerr ("Failed to complete Foobar: %s\n",
 854                   error-&gt;message);
 855       g_error_free (error);
 856       exit (1);
 857     }
 858    g_assert (arr != NULL);
 859    printf ("got back %u values", arr->len);
 860 </programlisting>
 861         </para>
 862       </sect3>
 863       <sect3 id="glib-sending-hash">
 864         <title>Sending a GHashTable</title>
 865         <para>
 866 <programlisting>
 867   GHashTable *hash = g_hash_table_new (g_str_hash, g_str_equal);
 868   guint32 ret;
 869
 870   g_hash_table_insert (hash, "foo", "bar");
 871   g_hash_table_insert (hash, "baz", "whee");
 872
 873   error = NULL;
 874   if (!dbus_g_proxy_invoke (proxy, "HashSize", &amp;error,
 875                             DBUS_TYPE_G_STRING_STRING_HASH, hash, G_TYPE_INVALID,
 876                             G_TYPE_UINT, &amp;ret, G_TYPE_INVALID))
 877     {
 878       g_printerr ("Failed to complete HashSize: %s\n",
 879                   error-&gt;message);
 880       g_error_free (error);
 881       exit (1);
 882     }
 883   g_assert (ret == 2);
 884   g_hash_table_destroy (hash);
 885 </programlisting>
 886         </para>
 887       </sect3>
 888       <sect3 id="glib-receiving-bool-int">
 889         <title>Receiving a boolean and a string</title>
 890         <para>
 891 <programlisting>
 892   gboolean boolret;
 893   char *strret;
 894
 895   error = NULL;
 896   if (!dbus_g_proxy_invoke (proxy, "GetStuff", &amp;error,
 897                             G_TYPE_INVALID,
 898                             G_TYPE_BOOLEAN, &amp;boolret,
 899                             G_TYPE_STRING, &amp;strret,
 900                             G_TYPE_INVALID))
 901     {
 902       g_printerr ("Failed to complete GetStuff: %s\n",
 903                   error-&gt;message);
 904       g_error_free (error);
 905       exit (1);
 906     }
 907   printf ("%s %s", boolret ? "TRUE" : "FALSE", strret);
 908   g_free (strret);
 909 </programlisting>
 910         </para>
 911       </sect3>
 912       <sect3 id="glib-sending-str-arrays">
 913         <title>Sending two arrays of strings</title>
 914         <para>
 915 <programlisting>
 916   /* NULL terminate */
 917   char *strs_static[] = {"foo", "bar", "baz", NULL};
 918   /* Take pointer to array; cannot pass array directly */
 919   char **strs_static_p = strs_static;
 920   char **strs_dynamic;
 921
 922   strs_dynamic = g_new (char *, 4);
 923   strs_dynamic[0] = g_strdup ("hello");
 924   strs_dynamic[1] = g_strdup ("world");
 925   strs_dynamic[2] = g_strdup ("!");
 926   /* NULL terminate */
 927   strs_dynamic[3] = NULL;
 928
 929   error = NULL;
 930   if (!dbus_g_proxy_invoke (proxy, "TwoStrArrays", &amp;error,
 931                             G_TYPE_STRV, strs_static_p,
 932                             G_TYPE_STRV, strs_dynamic,
 933                             G_TYPE_INVALID,
 934                             G_TYPE_INVALID))
 935     {
 936       g_printerr ("Failed to complete TwoStrArrays: %s\n",
 937                   error-&gt;message);
 938       g_error_free (error);
 939       exit (1);
 940     }
 941    g_strfreev (strs_dynamic);
 942 </programlisting>
 943         </para>
 944       </sect3>
 945       <sect3 id="glib-getting-str-array">
 946         <title>Sending a boolean, receiving an array of strings</title>
 947         <para>
 948 <programlisting>
 949   char **strs;
 950   char **strs_p;
 951   gboolean blah;
 952
 953   error = NULL;
 954   blah = TRUE;
 955   if (!dbus_g_proxy_invoke (proxy, "GetStrs", &amp;error,
 956                             G_TYPE_BOOLEAN, blah,
 957                             G_TYPE_INVALID,
 958                             G_TYPE_STRV, &amp;strs,
 959                             G_TYPE_INVALID))
 960     {
 961       g_printerr ("Failed to complete GetStrs: %s\n",
 962                   error-&gt;message);
 963       g_error_free (error);
 964       exit (1);
 965     }
 966    for (strs_p = strs; *strs_p; strs_p++)
 967      printf ("got string: \"%s\"", *strs_p);
 968    g_strfreev (strs);
 969 </programlisting>
 970         </para>
 971       </sect3>
 972       <sect3 id="glib-sending-variant">
 973         <title>Sending a variant</title>
 974         <para>
 975 <programlisting>
 976   GValue val = {0, };
 977
 978   g_value_init (&amp;val, G_TYPE_STRING);
 979   g_value_set_string (&amp;val, "hello world");
 980
 981   error = NULL;
 982   if (!dbus_g_proxy_invoke (proxy, "SendVariant", &amp;error,
 983                             G_TYPE_VALUE, &amp;val, G_TYPE_INVALID,
 984                             G_TYPE_INVALID))
 985     {
 986       g_printerr ("Failed to complete SendVariant: %s\n",
 987                   error-&gt;message);
 988       g_error_free (error);
 989       exit (1);
 990     }
 991   g_assert (ret == 2);
 992   g_value_unset (&amp;val);
 993 </programlisting>
 994         </para>
 995       </sect3>
 996       <sect3 id="glib-receiving-variant">
 997         <title>Receiving a variant</title>
 998         <para>
 999 <programlisting>
1000   GValue val = {0, };
1001
1002   error = NULL;
1003   if (!dbus_g_proxy_invoke (proxy, "GetVariant", &amp;error, G_TYPE_INVALID,
1004                             G_TYPE_VALUE, &amp;val, G_TYPE_INVALID))
1005     {
1006       g_printerr ("Failed to complete GetVariant: %s\n",
1007                   error-&gt;message);
1008       g_error_free (error);
1009       exit (1);
1010     }
1011   if (G_VALUE_TYPE (&amp;val) == G_TYPE_STRING)
1012     printf ("%s\n", g_value_get_string (&amp;val));
1013   else if (G_VALUE_TYPE (&amp;val) == G_TYPE_INT)
1014     printf ("%d\n", g_value_get_int (&amp;val));
1015   else
1016     ...
1017   g_value_unset (&amp;val);
1018 </programlisting>
1019         </para>
1020       </sect3>
1021     </sect2>
1022   </sect1>
1023
1024   <sect1 id="glib-server">
1025     <title>GLib API: Implementing Objects</title>
1026     <para>
1027       At the moment, to expose a GObject via D-BUS, you must
1028       write XML by hand which describes the methods exported
1029       by the object.  In the future, this manual step will
1030       be obviated by the upcoming GLib introspection support.
1031     </para>
1032     <para>
1033       Here is a sample XML file which describes an object that exposes
1034       one method, named <literal>ManyArgs</literal>.
1035 <programlisting>
1036 &lt;?xml version="1.0" encoding="UTF-8" ?&gt;
1037
1038 &lt;node name="/com/example/MyObject"&gt;
1039
1040   &lt;interface name="com.example.MyObject"&gt;
1041     &lt;annotation name="org.freedesktop.DBus.GLib.CSymbol" value="my_object"/&gt;
1042     &lt;method name="ManyArgs"&gt;
1043       &lt;!-- This is optional, and in this case is redunundant --&gt;
1044       &lt;annotation name="org.freedesktop.DBus.GLib.CSymbol" value="my_object_many_args"/&gt;
1045       &lt;arg type="u" name="x" direction="in" /&gt;
1046       &lt;arg type="s" name="str" direction="in" /&gt;
1047       &lt;arg type="d" name="trouble" direction="in" /&gt;
1048       &lt;arg type="d" name="d_ret" direction="out" /&gt;
1049       &lt;arg type="s" name="str_ret" direction="out" /&gt;
1050     &lt;/method&gt;
1051   &lt;/interface&gt;
1052 &lt;/node&gt;
1053 </programlisting>
1054     </para>
1055     <para>
1056       This XML is in the same format as the D-BUS introspection XML
1057       format. Except we must include an "annotation" which give the C
1058       symbols corresponding to the object implementation prefix
1059       (<literal>my_object</literal>).  In addition, if particular
1060       methods symbol names deviate from C convention
1061       (i.e. <literal>ManyArgs</literal> -&gt;
1062       <literal>many_args</literal>), you may specify an annotation
1063       giving the C symbol.
1064     </para>
1065     <para>
1066       Once you have written this XML, run <literal>dbus-binding-tool --mode=glib-server <replaceable>FILENAME</replaceable> &gt; <replaceable>HEADER_NAME</replaceable>.</literal> to
1067       generate a header file.  For example: <command>dbus-binding-tool --mode=glib-server my-objet.xml &gt; my-object-glue.h</command>.
1068     </para>
1069     <para>
1070       Next, include the generated header in your program, and invoke
1071       <literal>dbus_g_object_class_install_info</literal>, passing the
1072       object class and "object info" included in the header.  For
1073       example:
1074       <programlisting>
1075         dbus_g_object_type_install_info (COM_FOO_TYPE_MY_OBJECT, &amp;com_foo_my_object_info);
1076       </programlisting>
1077       This should be done exactly once per object class.
1078     </para>
1079     <para>
1080       To actually implement the method, just define a C function named e.g.
1081       <literal>my_object_many_args</literal> in the same file as the info
1082       header is included.  At the moment, it is required that this function
1083       conform to the following rules:
1084       <itemizedlist>
1085         <listitem>
1086           <para>
1087             The function must return a value of type <literal>gboolean</literal>;
1088             <literal>TRUE</literal> on success, and <literal>FALSE</literal>
1089             otherwise.
1090           </para>
1091         </listitem>
1092         <listitem>
1093           <para>
1094             The first parameter is a pointer to an instance of the object.
1095           </para>
1096         </listitem>
1097         <listitem>
1098           <para>
1099             Following the object instance pointer are the method
1100             input values.
1101           </para>
1102         </listitem>
1103         <listitem>
1104           <para>
1105             Following the input values are pointers to return values.
1106           </para>
1107         </listitem>
1108         <listitem>
1109           <para>
1110             The final parameter must be a <literal>GError **</literal>.
1111             If the function returns <literal>FALSE</literal> for an
1112             error, the error parameter must be initalized with
1113             <literal>g_set_error</literal>.
1114           </para>
1115         </listitem>
1116       </itemizedlist>
1117     </para>
1118     <para>
1119       Finally, you can export an object using <literal>dbus_g_connection_register_g_object</literal>.  For example:
1120       <programlisting>
1121           dbus_g_connection_register_g_object (connection,
1122                                                "/com/foo/MyObject",
1123                                                obj);
1124       </programlisting>
1125     </para>
1126   </sect1>
1127
1128   <sect1 id="qt-client">
1129     <title>Qt API: Using Remote Objects</title>
1130     <para>
1131
1132       The Qt bindings are not yet documented.
1133
1134     </para>
1135   </sect1>
1136
1137   <sect1 id="qt-server">
1138     <title>Qt API: Implementing Objects</title>
1139     <para>
1140       The Qt bindings are not yet documented.
1141     </para>
1142   </sect1>
1143
1144
1145   <sect1 id="python-client">
1146     <title>Python API: Using Remote Objects</title>
1147     <para>
1148       The Python bindings are not yet documented, but the
1149       bindings themselves are in good shape.
1150     </para>
1151   </sect1>
1152
1153   <sect1 id="python-server">
1154     <title>Python API: Implementing Objects</title>
1155     <para>
1156       The Python bindings are not yet documented, but the
1157       bindings themselves are in good shape.
1158     </para>
1159   </sect1>
1160
1161 </article>