1 <?xml version="1.0" standalone="no"?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
9 <title>D-Bus Tutorial</title>
10 <releaseinfo>Version 0.5.0</releaseinfo>
11 <date>20 August 2006</date>
14 <firstname>Havoc</firstname>
15 <surname>Pennington</surname>
17 <orgname>Red Hat, Inc.</orgname>
18 <address><email>hp@pobox.com</email></address>
22 <firstname>David</firstname>
23 <surname>Wheeler</surname>
26 <firstname>John</firstname>
27 <surname>Palmieri</surname>
29 <orgname>Red Hat, Inc.</orgname>
30 <address><email>johnp@redhat.com</email></address>
34 <firstname>Colin</firstname>
35 <surname>Walters</surname>
37 <orgname>Red Hat, Inc.</orgname>
38 <address><email>walters@redhat.com</email></address>
45 <title>Tutorial Work In Progress</title>
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.
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.
62 <title>What is D-Bus?</title>
64 D-Bus is a system for <firstterm>interprocess communication</firstterm>
65 (IPC). Architecturally, it has several layers:
70 A library, <firstterm>libdbus</firstterm>, that allows two
71 applications to connect to each other and exchange messages.
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
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.
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.
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.
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
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.
129 <title>D-Bus applications</title>
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:
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).
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.
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.
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:
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
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.
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:
206 Binary protocol designed to be used asynchronously
207 (similar in spirit to the X Window System protocol).
212 Stateful, reliable connections held open over time.
217 The message bus is a daemon, not a "swarm" or
218 distributed architecture.
223 Many implementation and deployment issues are specified rather
224 than left ambiguous/configurable/pluggable.
229 Semantics are similar to the existing DCOP system, allowing
230 KDE to adopt it more easily.
235 Security features to support the systemwide mode of the
243 <sect1 id="concepts">
244 <title>Concepts</title>
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.
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
258 <title>Native Objects and Object Paths</title>
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>.
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
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.
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.
288 <title>Methods and Signals</title>
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.
301 Both methods and signals are referred to by name, such as
302 "Frobate" or "OnClicked".
307 <sect2 id="interfaces">
308 <title>Interfaces</title>
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.
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.
325 <title>Proxies</title>
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..
336 In pseudocode, programming without proxies might look like this:
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()) {
345 Object returnValue = reply.getReturnValue();
350 Programming with proxies might look like this:
352 Proxy proxy = new Proxy(getBusConnection(), "/remote/object/path");
353 Object returnValue = proxy.MethodName(arg1, arg2);
358 <sect2 id="bus-names">
359 <title>Bus Names</title>
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.
373 When a name is mapped
374 to a particular application's connection, that application is said to
375 <firstterm>own</firstterm> that name.
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>.
389 Applications could then send messages to this bus name,
390 object, and interface to execute method calls.
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>.
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.
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
421 <sect2 id="addresses">
422 <title>Addresses</title>
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
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
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.
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).
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.
466 <sect2 id="bigpicture">
467 <title>Big Conceptual Picture</title>
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:
474 Address -> [Bus Name] -> Path -> Interface -> Method
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.
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.
493 <sect2 id="messages">
494 <title>Messages - Behind the Scenes</title>
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.
500 There are 4 message types:
504 Method call messages ask to invoke a method
510 Method return messages return the results
511 of invoking a method.
516 Error messages return an exception caused by
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.
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
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.
545 <sect2 id="callprocedure">
546 <title>Calling a Method - Behind the Scenes</title>
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.
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.
561 A method invocation in DBus happens as follows:
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.
573 For more low-level APIs, the application may construct a method call message itself, without
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.
586 The method call message is sent to the bus daemon.
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.
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.
608 The bus daemon receives the method reply message and sends it to the process that
609 made the method call.
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.
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.
633 <sect2 id="signalprocedure">
634 <title>Emitting a Signal - Behind the Scenes</title>
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.
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
651 A signal in DBus happens as follows:
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.
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
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.
675 The bus daemon examines the signal and determines which processes are interested in it.
676 It sends the signal message to these processes.
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.
692 <sect2 id="introspection">
693 <title>Introspection</title>
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.
706 <sect1 id="glib-client">
707 <title>GLib APIs</title>
709 The recommended GLib API for D-Bus is GDBus, which has been
710 distributed with GLib since version 2.26. It is not documented here.
711 See <ulink url="https://developer.gnome.org/gio/stable/gdbus-convenience.html">the
712 GLib documentation</ulink> for details of how to use GDBus.
716 An older API, dbus-glib, also exists. It is deprecated and should
717 not be used in new code. Whenever possible, porting existing code
718 from dbus-glib to GDBus is also recommended.
722 <sect1 id="python-client">
723 <title>Python API</title>
725 The Python API, dbus-python, is now documented separately in
726 <ulink url="http://dbus.freedesktop.org/doc/dbus-python/doc/tutorial.html">the dbus-python tutorial</ulink> (also available in doc/tutorial.txt,
727 and doc/tutorial.html if built with python-docutils, in the dbus-python
728 source distribution).
732 <sect1 id="qt-client">
733 <title>Qt API</title>
735 The Qt binding for libdbus, QtDBus, has been distributed with Qt
736 since version 4.2. It is not documented here. See
737 <ulink url="http://qt-project.org/doc/qt-5/qtdbus-index.html">the Qt
738 documentation</ulink> for details of how to use QtDBus.