diff options
| -rw-r--r-- | ChangeLog | 4 | ||||
| -rw-r--r-- | doc/Makefile.am | 15 | ||||
| -rw-r--r-- | doc/dbus-specification.sgml | 313 |
3 files changed, 332 insertions, 0 deletions
@@ -1,5 +1,9 @@ 2003-01-22 Havoc Pennington <hp@pobox.com> + * doc/dbus-specification.sgml: Start to document the protocol. + +2003-01-22 Havoc Pennington <hp@pobox.com> + * dbus/dbus-connection.c (dbus_connection_send_message_with_reply_and_block): add some @todo diff --git a/doc/Makefile.am b/doc/Makefile.am index a31a8a8f..0802f617 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,19 @@ EXTRA_DIST= \ + dbus-specification.html \ + dbus-specification.sgml \ dcop-howto.txt \ file-boilerplate.c +if MAINTAINER_MODE +all-local: dbus-specification.html +endif + +dbus-specification.html: dbus-specification.sgml + db2html -o . --nochunks dbus-specification.sgml && \ + rm -r dbus-specification/stylesheet-images && \ + rmdir dbus-specification + +maintainer-clean-local: + rm -f dbus-specification.html + rm -rf dbus-specification/stylesheet-images + test -d dbus-specification && rmdir dbus-specification 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 @@ +<!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ +]> +<article id="index"> + <artheader> + <title>D-BUS Protocol Specification</title> + <releaseinfo>Version 0.1</releaseinfo> + <date>22 January 2003</date> + <authorgroup> + <author> + <firstname>Havoc</firstname> + <surname>Pennington</surname> + <affiliation> + <address> + <email>hp@pobox.com</email> + </address> + </affiliation> + </author> + </authorgroup> + </artheader> + + <sect1 id="introduction"> + <title>Introduction</title> + <para> + D-BUS is a system for low-latency, low-overhead, easy to use + interprocess communication (IPC). In more detail: + <itemizedlist> + <listitem> + <para> + D-BUS is <emphasis>low-latency</emphasis> because it is designed + to avoid round trips and allow asynchronous operation, much like + the X protocol. + </para> + </listitem> + <listitem> + <para> + D-BUS is <emphasis>low-overhead</emphasis> 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. + </para> + </listitem> + <listitem> + <para> + D-BUS is <emphasis>easy to use</emphasis> because it works in terms + of <firstterm>messages</firstterm> 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 + <xref linkend="method-conventions">). + </para> + </listitem> + </itemizedlist> + </para> + <para> + The base D-BUS protocol is a peer-to-peer protocol, specified in <xref + linkend="message-protocol">. 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 <firstterm>message bus</firstterm>, + specified in <xref linkend="message-bus">. The message bus is a special + application that accepts connections from multiple other applications, and + forwards messages among them. + </para> + </sect1> + + <sect1 id="message-protocol"> + <title>Message Protocol</title> + <para> + A <firstterm>message</firstterm> consists of a + <firstterm>header</firstterm> and a <firstterm>body</firstterm>. 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. + </para> + + <para> + The body of the message is made up of zero or more + <firstterm>arguments</firstterm>, which are typed + values, such as an integer or a byte array. + </para> + + <sect2 id="message-protocol-header-encoding"> + <title>Header Encoding</title> + <para> + [document the required header fields and how they are encoded] + </para> + </sect2> + + <sect2 id="message-protocol-header-fields"> + <title>Header Fields</title> + <para> + In addition to the required header information mentioned + in <xref linkend="message-protocol-header-encoding">, + 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. + </para> + </sect2> + <sect2 id="message-protocol-arguments"> + <title>Message Arguments</title> + <para> + 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. + </para> + <para> + The types are: + </para> + <para> + The types are encoded as follows: + </para> + </sect2> + </sect1> + + <sect1 id="auth-protocol"> + <title>Authentication Protocol</title> + <para> + 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. + </para> + <para> + [move the dbus-sasl-profile.txt stuff into here and clean it up] + </para> + </sect1> + + <sect1 id="addresses"> + <title>Server Addresses</title> + <para> + [document the string format of an address, and how it maps + to unix domain sockets, tcp, or whatever] + </para> + </sect1> + + <sect1 id="method-conventions"> + <title>Method Call Mapping</title> + <para> + [document how something that looks like a method call is conventionally + represented in terms of messages, for method-call-style API bindings] + </para> + </sect1> + + <sect1 id="standard-messages"> + <title>Standard Peer-to-Peer Messages</title> + <para> + </para> + <sect2 id="standard-messages-ping"> + <title>Ping Protocol</title> + <para> + <literal>org.freedesktop.Peer.Ping</literal> + generates <literal>org.freedesktop.Peer.PingReply</literal> + </para> + </sect2> + </sect1> + + <sect1 id="message-bus"> + <title>Message Bus Specification</title> + <sect2 id="message-bus-overview"> + <title>Message Bus Overview</title> + <para> + 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. + </para> + <para> + The message bus keeps track of a set of + <firstterm>services</firstterm>. A service is simply a name, such + as <literal>com.yoyodyne.Screensaver</literal>, which can be + <firstterm>owned</firstterm> by one of the connected applications. + The message bus itself always owns the special service + <literal>org.freedesktop.DBus</literal>. + </para> + <para> + Messages may have a <literal>srvc</literal> field (see <xref + linkend="message-protocol-header-fields">). When the message bus + receives a message, if the <literal>srvc</literal> 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 <literal>org.freedesktop.Peer.Ping</literal> message with no + <literal>srvc</literal> will cause the message bus itself to reply + to the ping immediately; the message bus would never make + this message visible to other applications. + </para> + <para> + If the <literal>srvc</literal> 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 <firstterm>broadcast</firstterm> + by sending them to the special service + <literal>org.freedesktop.Broadcast</literal>. Broadcast messages + are sent to all applications with <firstterm>message matching rules</firstterm> + that match the message. + </para> + <para> + Continuing the <literal>org.freedesktop.Peer.Ping</literal> example, if + the ping message were sent with a <literal>srvc</literal> name of + <literal>com.yoyodyne.Screensaver</literal>, then the ping would be + forwarded, and the Yoyodyne Corporation screensaver application would be + expected to reply to the ping. If + <literal>org.freedesktop.Peer.Ping</literal> were sent to + <literal>org.freedesktop.Broadcast</literal>, then multiple applications + might receive the ping, and all would normally reply to it. + </para> + </sect2> + <sect2 id="message-bus-messages"> + <title>Message Bus Messages</title> + <para> + The special message bus service <literal>org.freedesktop.DBus</literal> + responds to a number of messages, allowing applications to + interact with the message bus. + </para> + <para> + [document the messages here] + </para> + </sect2> + <sect2 id="message-bus-activation"> + <title>Message Bus Service Activation</title> + <para> + [document file format, filesystem locations, etc. for activation] + </para> + </sect2> + <sect2 id="message-bus-location"> + <title>Finding The Message Bus</title> + <para> + Two standard message bus instances are defined here, along with how + to locate them. + </para> + <para> + Each time a user logs in, a <firstterm>desktop session message + bus</firstterm> 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] + </para> + <para> + A computer may have a <firstterm>system message bus</firstterm>, + 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] + </para> + </sect2> + </sect1> + + <appendix id="implementation-notes"> + <title>Implementation notes</title> + <sect1 id="implementation-notes-subsection"> + <title></title> + <para> + + </para> + </sect1> + </appendix> + <glossary><title>Glossary</title> + <para> + This glossary defines some of the terms used in this specification. + </para> + + <glossentry id="term-broadcast"><glossterm>Broadcast</glossterm> + <glossdef> + <para> + A message sent to the special <literal>org.freedesktop.Broadcast</literal> + service; the message bus will forward the broadcast message + to all clients that have expressed interest in it. + </para> + </glossdef> + </glossentry> + + <glossentry id="term-message"><glossterm>Message</glossterm> + <glossdef> + <para> + A message is the atomic unit of communication via the D-BUS + protocol. It consists of a <firstterm>header</firstterm> and a + <firstterm>body</firstterm>; the body is made up of + <firstterm>arguments</firstterm>. + </para> + </glossdef> + </glossentry> + + <glossentry id="term-message-bus"><glossterm>Message Bus</glossterm> + <glossdef> + <para> + 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 + <firstterm>services</firstterm>. + </para> + </glossdef> + </glossentry> + + <glossentry id="term-service"><glossterm>Service</glossterm> + <glossdef> + <para> + A service is simply a named application that other + applications can refer to. For example, the + hypothetical <literal>com.yoyodyne.Screensaver</literal> + service might accept messages that affect + a screensaver from Yoyodyne Corporation. + An application is said to <firstterm>own</firstterm> + a service if the message bus has associated the + application with the service name. + </para> + </glossdef> + </glossentry> + + </glossary> +</article> + |