fdo-mirrors/dbus
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/dbus/dbus.git synced 2026-05-05 01:48:00 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

2003-01-22 Havoc Pennington <hp@pobox.com>

Browse source 
* doc/dbus-specification.sgml: Start to document the protocol.
This commit is contained in:
Havoc Pennington 2003-01-23 05:04:03 +00:00
parent c414488fe6
commit f703c5ddd3
3 changed files with 332 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
ChangeLog
View file

@ -1,3 +1,7 @@
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

15
doc/Makefile.am
View file

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

313
doc/dbus-specification.sgml Normal file
View file

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