From 6fcd97c08459243a00bf0b790da434cee6dade17 Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Sun, 20 Aug 2006 21:41:42 +0000 Subject: 2006-08-20 Havoc Pennington * doc/dbus-faq.xml, doc/dbus-tutorial.xml: some improvements to the docs --- doc/dbus-tutorial.xml | 412 ++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 328 insertions(+), 84 deletions(-) (limited to 'doc/dbus-tutorial.xml') diff --git a/doc/dbus-tutorial.xml b/doc/dbus-tutorial.xml index 6d814fce..add59e1a 100644 --- a/doc/dbus-tutorial.xml +++ b/doc/dbus-tutorial.xml @@ -7,8 +7,8 @@
D-Bus Tutorial - Version 0.4.1 - 15 July 2005 + Version 0.5.0 + 20 August 2006 Havoc @@ -41,6 +41,23 @@ + + Tutorial Work In Progress + + + This tutorial is not complete; it probably contains some useful information, but + also has plenty of gaps. Right now, you'll also need to refer to the D-Bus specification, + Doxygen reference documentation, and look at some examples of how other apps use D-Bus. + + + + Enhancing the tutorial is definitely encouraged - send your patches or suggestions to the + mailing list. If you create a D-Bus binding, please add a section to the tutorial for your + binding, if only a short section with a couple of examples. + + + + What is D-Bus? @@ -64,8 +81,8 @@ - Wrapper libraries based on particular - application frameworks. For example, libdbus-glib and + Wrapper libraries or bindings + 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 is @@ -76,12 +93,6 @@ - - If you just want to use D-Bus and don't care how it works, jump directly - to . - Otherwise, read on. - - libdbus only supports one-to-one connections, just like a raw network socket. However, rather than sending byte streams over the connection, you @@ -210,7 +221,7 @@ Many implementation and deployment issues are specified rather - than left ambiguous. + than left ambiguous/configurable/pluggable. @@ -244,24 +255,21 @@ - Objects and Object Paths + Native 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. + Your programming framework probably defines what an "object" is like; + usually with a base class. For example: java.lang.Object, GObject, QObject, + python's base Object, or whatever. Let's call this a native object. - 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. + The low-level D-Bus protocol, and corresponding libdbus API, does not care about native objects. + However, it provides a concept called an + object path. The idea of an object path is that + higher-level bindings can name native object instances, and allow remote applications + to refer to them. - To solve this, D-Bus introduces a name for each object. The name + The object path 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 @@ -276,6 +284,26 @@ + + Methods and Signals + + + Each object has members; the two kinds of member + are methods and + signals. Methods are operations that can be + invoked on an object, with optional input (aka arguments or "in + parameters") and output (aka return values or "out parameters"). + Signals are broadcasts from the object to any interested observers + of the object; signals may contain a data payload. + + + + Both methods and signals are referred to by name, such as + "Frobate" or "OnClicked". + + + + Interfaces @@ -284,78 +312,69 @@ just as it is in GLib or Qt or Java. Interfaces define the type of an object instance. + + DBus identifies interfaces with a simple namespaced string, + something like org.freedesktop.Introspectable. + Most bindings will map these interface names directly to + the appropriate programming language construct, for example + to Java interfaces or C++ pure virtual classes. + - - - Message Types + + + Proxies - 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 proxy object is a convenient native object created to + represent a remote object in another process. The low-level DBus API involves manually creating + a method call message, sending it, then manually receiving and processing + the method reply message. Higher-level bindings provide proxies as an alternative. + Proxies look like a normal native object; but when you invoke a method on the proxy + object, the binding converts it into a DBus method call message, waits for the reply + message, unpacks the return value, and returns it from the native method.. - 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. + In pseudocode, programming without proxies might look like this: + + Message message = new Message("/remote/object/path", "MethodName", arg1, arg2); + Connection connection = getBusConnection(); + connection.send(message); + Message reply = connection.waitForReply(message); + if (reply.isError()) { + + } else { + Object returnValue = reply.getReturnValue(); + } + + + + Programming with proxies might look like this: + + Proxy proxy = new Proxy(getBusConnection(), "/remote/object/path"); + Object returnValue = proxy.MethodName(arg1, arg2); + Bus Names - + - 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. + When each application connects to the bus daemon, the daemon immediately + assigns it a name, called the unique connection name. + A unique name begins with a ':' (colon) character. These names are never + reused during the lifetime of the bus daemon - that is, you know + a given name will always refer to the same application. + An example of a unique name might be + :34-907. The numbers after the colon have + no meaning other than their uniqueness. - Bus names, on the other hand, are a property of the message bus daemon. - The bus maintains a mapping from names to message bus connections. - These names are used to specify the origin and destination - of messages passing through the message bus. When a name is mapped + When a name is mapped to a particular application's connection, that application is said to own that name. - - On connecting to the bus daemon, each application immediately owns a - special name called the unique connection name. - A unique name begins with a ':' (colon) character; no other names are - allowed to begin with that character. Unique names are special because - they are created dynamically, and are never re-used during the lifetime - of the same bus daemon. You know that a given unique name will have the - same owner at all times. An example of a unique name might be - :34-907. The numbers after the colon have - no meaning other than their uniqueness. - - Applications may ask to own additional well-known names. For example, you could write a specification to @@ -363,7 +382,7 @@ Your definition could specify that to own this name, an application should have an object at the path /com/mycompany/TextFileManager supporting the - interface org.freedesktop.FileHandler. + interface org.freedesktop.FileHandler. @@ -389,6 +408,14 @@ monitor the lifetime of other applications. + + Bus names can also be used to coordinate single-instance applications. + If you want to be sure only one + com.mycompany.TextEditor application is running for + example, have the text editor application exit if the bus name already + has an owner. + + @@ -402,6 +429,13 @@ connection. + + If you're using the bus daemon, as you probably are, your application + will be a client of the bus daemon. That is, the bus daemon listens + for connections and your application initiates a connection to the bus + daemon. + + A D-Bus address specifies where a server will listen, and where a client will connect. For example, the address @@ -413,8 +447,7 @@ - When using D-Bus with a message bus, the bus daemon is a server - and all other applications are clients of the bus daemon. + When using D-Bus with a message 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 @@ -425,7 +458,7 @@ 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. + the server's address. This is an unusual case. @@ -454,7 +487,218 @@ omit the interface, but if your method name is ambiguous it is undefined which method will be invoked. - + + + + + Messages - Behind the Scenes + + D-Bus works by sending messages between processes. If you're using + a sufficiently high-level binding, you may never work with messages directly. + + + There are 4 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: you send a method call + message, and receive either a method return message or an error message + in reply. + + + Each message has a header, including fields, + and a body, including arguments. You can think + of the header as the routing information for the message, and the body as the payload. + Header fields might include the sender bus name, destination bus name, method or signal name, + and so forth. One of the header fields is a type signature describing the + values found in the body. For example, the letter "i" means "32-bit integer" so the signature + "ii" means the payload has two 32-bit integers. + + + + + Calling a Method - Behind the Scenes + + + A method call in DBus consists of two messages; a method call message sent from process A to process B, + and a matching method reply message sent from process B to process A. Both the call and the reply messages + are routed through the bus daemon. The caller includes a different serial number in each call message, and the + reply message includes this number to allow the caller to match replies to calls. + + + + The call message will contain any arguments to the method. + The reply message may indicate an error, or may contain data returned by the method. + + + + A method invocation in DBus happens as follows: + + + + The language binding may provide a proxy, such that invoking a method on + an in-process object invokes a method on a remote object in another process. If so, the + application calls a method on the proxy, and the proxy + constructs a method call message to send to the remote process. + + + + + For more low-level APIs, the application may construct a method call message itself, without + using a proxy. + + + + + In either case, the method call message contains: a bus name belonging to the remote process; the name of the method; + the arguments to the method; an object path inside the remote process; and optionally the name of the + interface that specifies the method. + + + + + The method call message is sent to the bus daemon. + + + + + The bus daemon looks at the destination bus name. If a process owns that name, + the bus daemon forwards the method call to that process. Otherwise, the bus daemon + creates an error message and sends it back as the reply to the method call message. + + + + + The receiving process unpacks the method call message. In a simple low-level API situation, it + may immediately run the method and send a method reply message to the bus daemon. + When using a high-level binding API, the binding might examine the object path, interface, + and method name, and convert the method call message into an invocation of a method on + a native object (GObject, java.lang.Object, QObject, etc.), then convert the return + value from the native method into a method reply message. + + + + + The bus daemon receives the method reply message and sends it to the process that + made the method call. + + + + + The process that made the method call looks at the method reply and makes use of any + return values included in the reply. The reply may also indicate that an error occurred. + When using a binding, the method reply message may be converted into the return value of + of a proxy method, or into an exception. + + + + + + + The bus daemon never reorders messages. That is, if you send two method call messages to the same recipient, + they will be received in the order they were sent. The recipient is not required to reply to the calls + in order, however; for example, it may process each method call in a separate thread, and return reply messages + in an undefined order depending on when the threads complete. Method calls have a unique serial + number used by the method caller to match reply messages to call messages. + + + + + + Emitting a Signal - Behind the Scenes + + + A signal in DBus consists of a single message, sent by one process to any number of other processes. + That is, a signal is a unidirectional broadcast. The signal may contain arguments (a data payload), but + because it is a broadcast, it never has a "return value." Contrast this with a method call + (see ) where the method call message has a matching method reply message. + + + + The emitter (aka sender) of a signal has no knowledge of the signal recipients. Recipients register + with the bus daemon to receive signals based on "match rules" - these rules would typically include the sender and + the signal name. The bus daemon sends each signal only to recipients who have expressed interest in that + signal. + + + + A signal in DBus happens as follows: + + + + A signal message is created and sent to the bus daemon. When using the low-level API this may be + done manually, with certain bindings it may be done for you by the binding when a native object + emits a native signal or event. + + + + + The signal message contains the name of the interface that specifies the signal; + the name of the signal; the bus name of the process sending the signal; and + any arguments + + + + + Any process on the message bus can register "match rules" indicating which signals it + is interested in. The bus has a list of registered match rules. + + + + + The bus daemon examines the signal and determines which processes are interested in it. + It sends the signal message to these processes. + + + + + Each process receiving the signal decides what to do with it; if using a binding, + the binding may choose to emit a native signal on a proxy object. If using the + low-level API, the process may just look at the signal sender and name and decide + what to do based on that. + + + + + + + + + Introspection + + + D-Bus objects may support the interface org.freedesktop.DBus.Introspectable. + This interface has one method Introspect which takes no arguments and returns + an XML string. The XML string describes the interfaces, methods, and signals of the object. + See the D-Bus specification for more details on this introspection format. + + -- cgit