path: root/doc/dbus-specification.sgml

<!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>