From f703c5ddd3b760c9b07384fe1b45adbd790a099d Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Thu, 23 Jan 2003 05:04:03 +0000 Subject: 2003-01-22 Havoc Pennington * doc/dbus-specification.sgml: Start to document the protocol. --- doc/dbus-specification.sgml | 313 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 313 insertions(+) create mode 100644 doc/dbus-specification.sgml (limited to 'doc/dbus-specification.sgml') diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml new file mode 100644 index 00000000..38572149 --- /dev/null +++ b/doc/dbus-specification.sgml @@ -0,0 +1,313 @@ + +
+ + D-BUS Protocol Specification + Version 0.1 + 22 January 2003 + + + Havoc + Pennington + +
+ hp@pobox.com +
+ + + + + + + Introduction + + D-BUS is a system for low-latency, low-overhead, easy to use + interprocess communication (IPC). In more detail: + + + + D-BUS is low-latency because it is designed + to avoid round trips and allow asynchronous operation, much like + the X protocol. + + + + + D-BUS is low-overhead because it is uses a + binary protocol, and does not have to convert to and from a text + format such as XML. Because D-BUS is intended for potentially + high-resolution same-machine IPC, not primarily for Internet IPC, + this is an interesting optimization. + + + + + D-BUS is easy to use because it works in terms + of messages rather than byte streams, and + does not require users to understand any complex concepts such as a + new type system or elaborate APIs. Libraries implementing D-BUS + may choose to abstract messages as "method calls" (see + ). + + + + + + The base D-BUS protocol is a peer-to-peer protocol, specified in . That is, it is a system for one application + to talk to a single other application. However, the primary intended + application of D-BUS is the D-BUS message bus, + specified in . The message bus is a special + application that accepts connections from multiple other applications, and + forwards messages among them. + + + + + Message Protocol + + A message consists of a + header and a body. If you + think of a message as a package, the header is the address, and the body + contains the package contents. The message delivery system uses the header + information to figure out where to send the message and how to interpret + it; the recipient inteprets the body of the message. + + + + The body of the message is made up of zero or more + arguments, which are typed + values, such as an integer or a byte array. + + + + Header Encoding + + [document the required header fields and how they are encoded] + + + + + Header Fields + + In addition to the required header information mentioned + in , + the header may contain zero or more named + header fields. These fields are named to allow + future versions of this protocol specification to + add new fields; implementations must ignore fields + they do not understand. Implementations must not + invent their own header fields; only changes to + this specification may introduce new header fields. + + + + Message Arguments + + The message body is made up of arguments. Each argument + is a type code, followed by the value of the argument + in a type-dependent format. + + + The types are: + + + The types are encoded as follows: + + + + + + Authentication Protocol + + Before the flow of messages begins, two applications + must authenticate. A simple text protocol is used + for authentication; this protocol is a SASL profile, + and maps fairly directly from the SASL specification. + + + [move the dbus-sasl-profile.txt stuff into here and clean it up] + + + + + Server Addresses + + [document the string format of an address, and how it maps + to unix domain sockets, tcp, or whatever] + + + + + Method Call Mapping + + [document how something that looks like a method call is conventionally + represented in terms of messages, for method-call-style API bindings] + + + + + Standard Peer-to-Peer Messages + + + + Ping Protocol + + org.freedesktop.Peer.Ping + generates org.freedesktop.Peer.PingReply + + + + + + Message Bus Specification + + Message Bus Overview + + The message bus accepts connections from one or more applications. + Once connected, applications can send and receive messages from + the message bus, as in the peer-to-peer case. + + + The message bus keeps track of a set of + services. A service is simply a name, such + as com.yoyodyne.Screensaver, which can be + owned by one of the connected applications. + The message bus itself always owns the special service + org.freedesktop.DBus. + + + Messages may have a srvc field (see ). When the message bus + receives a message, if the srvc field is absent, the + message is taken to be a standard peer-to-peer message and interpreted + by the message bus itself. For example, sending + an org.freedesktop.Peer.Ping message with no + srvc will cause the message bus itself to reply + to the ping immediately; the message bus would never make + this message visible to other applications. + + + If the srvc field is present, then it indicates a + request for the message bus to route the message. In the usual case, + messages are routed to the owner of the named service. + Messages may also be broadcast + by sending them to the special service + org.freedesktop.Broadcast. Broadcast messages + are sent to all applications with message matching rules + that match the message. + + + Continuing the org.freedesktop.Peer.Ping example, if + the ping message were sent with a srvc name of + com.yoyodyne.Screensaver, then the ping would be + forwarded, and the Yoyodyne Corporation screensaver application would be + expected to reply to the ping. If + org.freedesktop.Peer.Ping were sent to + org.freedesktop.Broadcast, then multiple applications + might receive the ping, and all would normally reply to it. + + + + Message Bus Messages + + The special message bus service org.freedesktop.DBus + responds to a number of messages, allowing applications to + interact with the message bus. + + + [document the messages here] + + + + Message Bus Service Activation + + [document file format, filesystem locations, etc. for activation] + + + + Finding The Message Bus + + Two standard message bus instances are defined here, along with how + to locate them. + + + Each time a user logs in, a desktop session message + bus may be started. All applications in the user's login + session may interact with one another using this message bus. [specify + how to find the address of the desktop session message bus via + environment variable and/or X property] + + + A computer may have a system message bus, + accessible to all applications on the system. This message bus may be + used to broadcast system events, such as adding new hardware devices. + [specify how to find the address of the system message bus] + + + + + + Implementation notes + + + + + + + + Glossary + + This glossary defines some of the terms used in this specification. + + + Broadcast + + + A message sent to the special org.freedesktop.Broadcast + service; the message bus will forward the broadcast message + to all clients that have expressed interest in it. + + + + + Message + + + A message is the atomic unit of communication via the D-BUS + protocol. It consists of a header and a + body; the body is made up of + arguments. + + + + + Message Bus + + + The message bus is a special application that forwards + or broadcasts messages between a group of applications + connected to the message bus. It also manages + services. + + + + + Service + + + A service is simply a named application that other + applications can refer to. For example, the + hypothetical com.yoyodyne.Screensaver + service might accept messages that affect + a screensaver from Yoyodyne Corporation. + An application is said to own + a service if the message bus has associated the + application with the service name. + + + + + +
+ -- cgit