From 05e7b44f445e0383fedb31d0dacf98bd6ee12852 Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Thu, 2 Oct 2003 22:34:17 +0000 Subject: 2003-10-02 Havoc Pennington * doc/dbus-tutorial.xml: write some stuff --- doc/dbus-tutorial.xml | 415 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 407 insertions(+), 8 deletions(-) (limited to 'doc') diff --git a/doc/dbus-tutorial.xml b/doc/dbus-tutorial.xml index 10cfc79f..a42605d4 100644 --- a/doc/dbus-tutorial.xml +++ b/doc/dbus-tutorial.xml @@ -8,7 +8,7 @@ D-BUS Tutorial Version 0.1 - 29 September 2003 + 02 October 2003 Havoc @@ -23,28 +23,427 @@ - - Introduction + + What is D-BUS? - D-BUS blah blah blah + D-BUS is a system for interprocess communication + (IPC). Architecturally, it has several layers: + - foo + A library, libdbus, that allows two applications to connect + to each other and exchange messages. + + + + + A message bus daemon executable, built on libdbus, that multiple + applications can connect to. The daemon can route messages + from one application to zero or more other applications. - bar + Wrapper libraries based on particular application frameworks. + For example, libdbus-glib and libdbus-qt. There are also + bindings to languages such as Python. These wrapper libraries + are the API most people should use, as they simplify the + details of D-BUS programming. + + + libdbus only supports one-to-one connections, just like a raw network + socket. However, rather than sending byte streams over the connection, you + send messages. Messages have a header identifying + the kind of message, and a body containing a data payload. libdbus also + abstracts the exact transport used (sockets vs. whatever else), and + handles details such as authentication. + + - blah blah blah + The message bus daemon has multiple instances on a typical computer. The + first instance is a machine-global singleton, that is, a system daemon + similar to sendmail or Apache. This instance has heavy security + restrictions on what messages it will accept, and is used for systemwide + communication. The other instances are created one per user login session. + These instances allow applications in the user's session to communicate + with one another. + - blah blah blah + The systemwide and per-user daemons are separate. Normal within-session + IPC does not involve the systemwide message bus process and vice versa. + + + D-BUS applications + + There are many, many technologies in the world that have "Inter-process + communication" or "networking" in their stated purpose: MBUS, CORBA, XML-RPC, SOAP, and probably hundreds + more. Each of these is tailored for particular kinds of application. + D-BUS is designed for two specific cases: + + + + Communication between desktop applications in the same desktop + session; to allow integration of the desktop session as a whole, + and address issues of process lifecycle (when do desktop components + start and stop running). + + + + + Communication between the desktop session and the operating system, + where the operating system would typically include the kernel + and any system daemons or processes. + + + + + + For the within-desktop-session use case, the GNOME and KDE desktops + have significant previous experience with different IPC solutions + such as CORBA and DCOP. D-BUS is built on that experience and + carefully tailored to meet the needs of these desktop projects + in particular. + + + The problem solved by the systemwide or communication-with-the-OS case + is explained well by the following text from the Linux Hotplug project: +
+ + A gap in current Linux support is that policies with any sort of + dynamic "interact with user" component aren't currently + supported. For example, that's often needed the first time a network + adapter or printer is connected, and to determine appropriate places + to mount disk drives. It would seem that such actions could be + supported for any case where a responsible human can be identified: + single user workstations, or any system which is remotely + administered. + + + + This is a classic "remote sysadmin" problem, where in this case + hotplugging needs to deliver an event from one security domain + (operating system kernel, in this case) to another (desktop for + logged-in user, or remote sysadmin). Any effective response must go + the other way: the remote domain taking some action that lets the + kernel expose the desired device capabilities. (The action can often + be taken asynchronously, for example letting new hardware be idle + until a meeting finishes.) At this writing, Linux doesn't have + widely adopted solutions to such problems. However, the new D-Bus + work may begin to solve that problem. + +
+ + + D-BUS may happen to be useful for purposes other than the one it was + designed for. Its general properties that distinguish it from + other forms of IPC are: + + + + Binary protocol designed to be used asynchronously + (similar in spirit to the X Window System protocol). + + + + + Stateful, reliable connections held open over time. + + + + + The message bus is a daemon, not a "swarm" or + distributed architecture. + + + + + Many implementation and deployment issues are specified rather + than left ambiguous. + + + + + Semantics are similar to the existing DCOP system, allowing + KDE to adopt it more easily. + + + + + Security features to support the systemwide mode of the + message bus. + + + + + + + Concepts + + Some basic concepts apply no matter what application framework you're + using to write a D-BUS application. The exact code you write will be + different for GLib vs. Qt vs. Python applications, however. + + + + Objects and Object Paths + + Each application using D-BUS contains objects, + which generally map to GObject, QObject, C++ objects, or Python objects + (but need not). An object is an instance rather + than a type. When messages are received over a D-BUS connection, they + are sent to a specific object, not to the application as a whole. + + + To allow messages to specify their destination object, there has to be a + way to refer to an object. In your favorite programming language, this + is normally called a pointer or + reference. However, these references are + implemented as memory addresses relative to the address space of your + application, and thus can't be passed from one application to another. + + + To solve this, D-BUS introduces a name for each object. The name + looks like a filesystem path, for example an object could be + named /org/kde/kspread/sheets/3/cells/4/5. + Human-readable paths are nice, but you are free to create an + object named /com/mycompany/c5yo817y0c1y1c5b + if it makes sense for your application. + + + Namespacing object paths is smart, by starting them with the components + of a domain name you own (e.g. /org/kde). This + keeps different code modules in the same process from stepping + on one another's toes. + + + + + Interfaces + + Each object supports one or more interfaces. + Think of an interface as a named group of methods and signals, + just as it is in GLib or Qt. Interfaces define the + type of an object instance. + + + + + Message Types + + Messages are not all the same; in particular, D-BUS has + 4 built-in message types: + + + + Method call messages ask to invoke a method + on an object. + + + + + Method return messages return the results + of invoking a method. + + + + + Error messages return an exception caused by + invoking a method. + + + + + Signal messages are notifications that a given signal + has been emitted (that an event has occurred). + You could also think of these as "event" messages. + + + + + + A method call maps very simply to messages, then: you send a method call + message, and receive either a method return message or an error message + in reply. + + + + + Services + + + Object paths, interfaces, and messages exist on the level of + libdbus and the D-BUS protocol; they are used even in the + 1-to-1 case with no message bus involved. + + + + Services, on the other hand, are a property of the message bus daemon. + A service is simply a name mapped to + some application connected to the message bus daemon. + These names are used to specify the origin and destination + of messages passing through the message bus. When a name is mapped + to a particular application, the application is said to + own that service. + + + + On connecting to the bus daemon, each application immediately owns a + special name called the base service. A base + service begins with a ':' (colon) character; no other services are + allowed to begin with that character. Base services are special because + each one is unique. They are created dynamically, and are never re-used + during the lifetime of the same bus daemon. You know that a given + base service name will have the same owner at all times. + + + + Applications may ask to own additional well-known + services. For example, you could write a specification to + define a service called com.mycompany.TextEditor. + Your definition could specify that to own this service, an application + should have an object at the path + /com/mycompany/TextFileManager supporting the + interface org.freedesktop.FileHandler. + + + + Applications could then send messages to this service, + object, and interface to execute method calls. + + + + Services have another important use, other than routing messages. They + are used to track lifecycle. When an application exits (or crashes), its + connection to the message bus will be closed by the operating system + kernel. The message bus then sends out notification messages telling + remaining applications that the application's services have lost their + owner. By tracking these notifications, your application can reliably + monitor the lifetime of other applications. + + + + + + Addresses + + + Applications using D-BUS are either servers or clients. A server + listens for incoming connections; a client connects to a server. Once + the connection is established, it is a symmetric flow of messages; the + client-server distinction only matters when setting up the + connection. + + + + A D-BUS address specifies where a server will + listen, and where a client will connect. For example, the address + unix:path=/tmp/abcdef specifies that the server will + listen on a UNIX domain socket at the path + /tmp/abcdef and the client will connect to that + socket. An address can also specify TCP/IP sockets, or any other + transport defined in future iterations of the D-BUS specification. + + + + When using D-BUS with a message bus, the bus daemon is a server + and all other applications are clients of the bus daemon. + libdbus automatically discovers the address of the per-session bus + daemon by reading an environment variable. It discovers the + systemwide bus daemon by checking a well-known UNIX domain socket path + (though you can override this address with an environment variable). + + + + If you're using D-BUS without a bus daemon, it's up to you to + define which application will be the server and which will be + the client, and specify a mechanism for them to agree on + the server's address. + + + + + + Big Conceptual Picture + + + Pulling all these concepts together, to specify a particular + method call on a particular object instance, a number of + nested components have to be named: + + Address -> [Service] -> Path -> Interface -> Method + + The service is in brackets to indicate that it's optional -- you only + provide a service name to route the method call to the right application + when using the bus daemon. If you have a direct connection to another + application, services aren't used. + + + + The interface is also optional, primarily for historical + reasons; DCOP does not require specifying the interface, + instead simply forbidding duplicate method names + on the same object instance. D-BUS will thus let you + omit the interface, but if your method name is ambiguous + it is undefined which method will be invoked. + + + + + + + + GLib API: Using Remote Objects + + + + + + + GLib API: Implementing Objects + + + + + + + Qt API: Using Remote Objects + + + + + + + Qt API: Implementing Objects + + + + + + + + Python API: Using Remote Objects + + + + + + + Python API: Implementing Objects + + + + + -- cgit