<?xml version="1.0" standalone="no" ?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
[
]>
<article id="index">
<articleinfo>
<title>D-Bus Specification</title>
- <releaseinfo>Version 0.19</releaseinfo>
- <date>2012-02-21</date>
+ <releaseinfo>Version 0.22</releaseinfo>
+ <date>(not yet released)</date>
<authorgroup>
<author>
<firstname>Havoc</firstname>
</authorgroup>
<revhistory>
<revision>
- <revnumber>current</revnumber>
- <date><ulink url='http://cgit.freedesktop.org/dbus/dbus/log/doc/dbus-specification.xml'>commit log</ulink></date>
+ <revnumber>0.22</revnumber>
+ <date>not yet released (<ulink url='http://cgit.freedesktop.org/dbus/dbus/log/doc/dbus-specification.xml'>commit log</ulink>)</date>
<authorinitials></authorinitials>
<revremark></revremark>
</revision>
<revision>
+ <revnumber>0.21</revnumber>
+ <date>2013-04-25</date>
+ <authorinitials>smcv</authorinitials>
+ <revremark>allow Unicode noncharacters in UTF-8 (Unicode
+ Corrigendum #9)</revremark>
+ </revision>
+ <revision>
+ <revnumber>0.20</revnumber>
+ <date>22 February 2013</date>
+ <authorinitials>smcv, walters</authorinitials>
+ <revremark>reorganise for clarity, remove false claims about
+ basic types, mention /o/fd/DBus</revremark>
+ </revision>
+ <revision>
<revnumber>0.19</revnumber>
<date>20 February 2012</date>
<authorinitials>smcv/lp</authorinitials>
are basic types with a variable length. The value of any string-like
type is conceptually 0 or more Unicode codepoints encoded in UTF-8,
none of which may be U+0000. The UTF-8 text must be validated
- strictly: in particular, it must not contain overlong sequences,
- noncharacters such as U+FFFE, or codepoints above U+10FFFF.
+ strictly: in particular, it must not contain overlong sequences
+ or codepoints above U+10FFFF.
+ </para>
+
+ <para>
+ Since D-Bus Specification version 0.21, in accordance with Unicode
+ Corrigendum #9, the "noncharacters" U+FDD0..U+FDEF, U+nFFFE and
+ U+nFFFF are allowed in UTF-8 strings (but note that older versions of
+ D-Bus rejected these noncharacters).
</para>
<para>
</informaltable>
</para>
+ <sect3 id="message-protocol-marshaling-object-path">
+ <title>Valid Object Paths</title>
+
+ <para>
+ An object path is a name used to refer to an object instance.
+ Conceptually, each participant in a D-Bus message exchange may have
+ any number of object instances (think of C++ or Java objects) and each
+ such instance will have a path. Like a filesystem, the object
+ instances in an application form a hierarchical tree.
+ </para>
+
+ <para>
+ Object paths are often namespaced by starting with a reversed
+ domain name and containing an interface version number, in the
+ same way as
+ <link linkend="message-protocol-names-interface">interface
+ names</link> and
+ <link linkend="message-protocol-names-bus">well-known
+ bus names</link>.
+ This makes it possible to implement more than one service, or
+ more than one version of a service, in the same process,
+ even if the services share a connection but cannot otherwise
+ co-operate (for instance, if they are implemented by different
+ plugins).
+ </para>
+
+ <para>
+ For instance, if the owner of <literal>example.com</literal> is
+ developing a D-Bus API for a music player, they might use the
+ hierarchy of object paths that start with
+ <literal>/com/example/MusicPlayer1</literal> for its objects.
+ </para>
+
+ <para>
+ The following rules define a valid object path. Implementations must
+ not send or accept messages with invalid object paths.
+ <itemizedlist>
+ <listitem>
+ <para>
+ The path may be of any length.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The path must begin with an ASCII '/' (integer 47) character,
+ and must consist of elements separated by slash characters.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Each element must only contain the ASCII characters
+ "[A-Z][a-z][0-9]_"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ No element may be the empty string.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Multiple '/' characters cannot occur in sequence.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A trailing '/' character is not allowed unless the
+ path is the root path (a single '/' character).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect3>
+
+ <sect3 id="message-protocol-marshaling-signature">
+ <title>Valid Signatures</title>
+ <para>
+ An implementation must not send or accept invalid signatures.
+ Valid signatures will conform to the following rules:
+ <itemizedlist>
+ <listitem>
+ <para>
+ The signature is a list of single complete types.
+ Arrays must have element types, and structs must
+ have both open and close parentheses.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Only type codes, open and close parentheses, and open and
+ close curly brackets are allowed in the signature. The
+ <literal>STRUCT</literal> type code
+ is not allowed in signatures, because parentheses
+ are used instead. Similarly, the
+ <literal>DICT_ENTRY</literal> type code is not allowed in
+ signatures, because curly brackets are used instead.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The maximum depth of container type nesting is 32 array type
+ codes and 32 open parentheses. This implies that the maximum
+ total depth of recursion is 64, for an "array of array of array
+ of ... struct of struct of struct of ..." where there are 32
+ array and 32 struct.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The maximum length of a signature is 255.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ When signatures appear in messages, the marshalling format
+ guarantees that they will be followed by a nul byte (which can
+ be interpreted as either C-style string termination or the INVALID
+ type-code), but this is not conceptually part of the signature.
+ </para>
+ </sect3>
+
</sect2>
<sect2 id="container-types">
</para>
<para>
+ Unlike a message signature, the variant signature can
+ contain only a single complete type. So "i", "ai"
+ or "(ii)" is OK, but "ii" is not. Use of variants may not
+ cause a total message depth to be larger than 64, including
+ other container types such as structures.
+ </para>
+
+ <para>
A <literal>DICT_ENTRY</literal> works exactly like a struct, but rather
than parentheses it uses curly braces, and it has more restrictions.
The restrictions are: it occurs only as an array element type; it has
</para>
</sect2>
+ </sect1>
+
+ <sect1 id="message-protocol-marshaling">
+ <title>Marshaling (Wire Format)</title>
- <sect2 id="message-protocol-marshaling">
- <title>Marshaling (Wire Format)</title>
+ <para>
+ D-Bus defines a marshalling format for its type system, which is
+ used in D-Bus messages. This is not the only possible marshalling
+ format for the type system: for instance, GVariant (part of GLib)
+ re-uses the D-Bus type system but implements an alternative marshalling
+ format.
+ </para>
+
+ <sect2>
+ <title>Byte order and alignment</title>
<para>
Given a type signature, a block of bytes can be converted into typed
</para>
<para>
- A block of bytes has an associated byte order. The byte order
- has to be discovered in some way; for D-Bus messages, the
- byte order is part of the message header as described in
- <xref linkend="message-protocol-messages"/>. For now, assume
- that the byte order is known to be either little endian or big
+ A block of bytes has an associated byte order. The byte order
+ has to be discovered in some way; for D-Bus messages, the
+ byte order is part of the message header as described in
+ <xref linkend="message-protocol-messages"/>. For now, assume
+ that the byte order is known to be either little endian or big
endian.
</para>
</para>
<para>
+ As an exception to natural alignment, <literal>STRUCT</literal> and
+ <literal>DICT_ENTRY</literal> values are always aligned to an 8-byte
+ boundary, regardless of the alignments of their contents.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Marshalling basic types</title>
+
+ <para>
To marshal and unmarshal fixed types, you simply read one value
from the data block corresponding to each type code in the signature.
All signed integer values are encoded in two's complement, DOUBLE
byte. As a result, alignment padding is never required before a
SIGNATURE.
</para>
+ </sect2>
+
+ <sect2>
+ <title>Marshalling containers</title>
+
+ <para>
+ Arrays are marshalled as a <literal>UINT32</literal>
+ <varname>n</varname> giving the length of the array data in bytes,
+ followed by alignment padding to the alignment boundary of the array
+ element type, followed by the <varname>n</varname> bytes of the
+ array elements marshalled in sequence. <varname>n</varname> does not
+ include the padding after the length, or any padding after the
+ last element.
+ </para>
+
+ <para>
+ For instance, if the current position in the message is a multiple
+ of 8 bytes and the byte-order is big-endian, an array containing only
+ the 64-bit integer 5 would be marshalled as:
+
+ <screen>
+00 00 00 08 <lineannotation>8 bytes of data</lineannotation>
+00 00 00 00 <lineannotation>padding to 8-byte boundary</lineannotation>
+00 00 00 00 00 00 00 05 <lineannotation>first element = 5</lineannotation>
+ </screen>
+ </para>
+
+ <para>
+ Arrays have a maximum length defined to be 2 to the 26th power or
+ 67108864. Implementations must not send or accept arrays exceeding this
+ length.
+ </para>
+
+ <para>
+ Structs and dict entries are marshalled in the same way as their
+ contents, but their alignment is always to an 8-byte boundary,
+ even if their contents would normally be less strictly aligned.
+ </para>
+
+ <para>
+ Variants are marshalled as the <literal>SIGNATURE</literal> of
+ the contents (which must be a single complete type), followed by a
+ marshalled value with the type given by that signature. The
+ variant has the same 1-byte alignment as the signature, which means
+ that alignment padding before a variant is never needed.
+ Use of variants may not cause a total message depth to be larger
+ than 64, including other container types such as structures.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Summary of D-Bus marshalling</title>
<para>
Given all this, the types are marshaled on the wire as follows:
</row><row>
<entry><literal>OBJECT_PATH</literal></entry>
<entry>Exactly the same as <literal>STRING</literal> except the
- content must be a valid object path (see below).
+ content must be a valid object path (see above).
</entry>
<entry>
4 (for the length)
<entry><literal>SIGNATURE</literal></entry>
<entry>The same as <literal>STRING</literal> except the length is a single
byte (thus signatures have a maximum length of 255)
- and the content must be a valid signature (see below).
+ and the content must be a valid signature (see above).
</entry>
<entry>
1
<entry><literal>ARRAY</literal></entry>
<entry>
A <literal>UINT32</literal> giving the length of the array data in bytes, followed by
- alignment padding to the alignment boundary of the array element type,
- followed by each array element. The array length is from the
- end of the alignment padding to the end of the last element,
- i.e. it does not include the padding after the length,
- or any padding after the last element.
- Arrays have a maximum length defined to be 2 to the 26th power or
- 67108864. Implementations must not send or accept arrays exceeding this
- length.
+ alignment padding to the alignment boundary of the array element type,
+ followed by each array element.
</entry>
<entry>
4 (for the length)
</row><row>
<entry><literal>VARIANT</literal></entry>
<entry>
- A variant type has a marshaled
- <literal>SIGNATURE</literal> followed by a marshaled
- value with the type given in the signature. Unlike
- a message signature, the variant signature can
- contain only a single complete type. So "i", "ai"
- or "(ii)" is OK, but "ii" is not. Use of variants may not
- cause a total message depth to be larger than 64, including
- other container types such as structures.
+ The marshaled <literal>SIGNATURE</literal> of a single
+ complete type, followed by a marshaled value with the type
+ given in the signature.
</entry>
<entry>
1 (alignment of the signature)
</tgroup>
</informaltable>
</para>
-
- <sect3 id="message-protocol-marshaling-object-path">
- <title>Valid Object Paths</title>
-
- <para>
- An object path is a name used to refer to an object instance.
- Conceptually, each participant in a D-Bus message exchange may have
- any number of object instances (think of C++ or Java objects) and each
- such instance will have a path. Like a filesystem, the object
- instances in an application form a hierarchical tree.
- </para>
-
- <para>
- The following rules define a valid object path. Implementations must
- not send or accept messages with invalid object paths.
- <itemizedlist>
- <listitem>
- <para>
- The path may be of any length.
- </para>
- </listitem>
- <listitem>
- <para>
- The path must begin with an ASCII '/' (integer 47) character,
- and must consist of elements separated by slash characters.
- </para>
- </listitem>
- <listitem>
- <para>
- Each element must only contain the ASCII characters
- "[A-Z][a-z][0-9]_"
- </para>
- </listitem>
- <listitem>
- <para>
- No element may be the empty string.
- </para>
- </listitem>
- <listitem>
- <para>
- Multiple '/' characters cannot occur in sequence.
- </para>
- </listitem>
- <listitem>
- <para>
- A trailing '/' character is not allowed unless the
- path is the root path (a single '/' character).
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Object paths are often namespaced by starting with a reversed
- domain name and containing an interface version number, in the
- same way as
- <link linkend="message-protocol-names-interface">interface
- names</link> and
- <link linkend="message-protocol-names-bus">well-known
- bus names</link>.
- This makes it possible to implement more than one service, or
- more than one version of a service, in the same process,
- even if the services share a connection but cannot otherwise
- co-operate (for instance, if they are implemented by different
- plugins).
- </para>
-
- <para>
- For instance, if the owner of <literal>example.com</literal> is
- developing a D-Bus API for a music player, they might use the
- hierarchy of object paths that start with
- <literal>/com/example/MusicPlayer1</literal> for its objects.
- </para>
- </sect3>
-
- <sect3 id="message-protocol-marshaling-signature">
- <title>Valid Signatures</title>
- <para>
- An implementation must not send or accept invalid signatures.
- Valid signatures will conform to the following rules:
- <itemizedlist>
- <listitem>
- <para>
- The signature ends with a nul byte.
- </para>
- </listitem>
- <listitem>
- <para>
- The signature is a list of single complete types.
- Arrays must have element types, and structs must
- have both open and close parentheses.
- </para>
- </listitem>
- <listitem>
- <para>
- Only type codes and open and close parentheses are
- allowed in the signature. The <literal>STRUCT</literal> type code
- is not allowed in signatures, because parentheses
- are used instead.
- </para>
- </listitem>
- <listitem>
- <para>
- The maximum depth of container type nesting is 32 array type
- codes and 32 open parentheses. This implies that the maximum
- total depth of recursion is 64, for an "array of array of array
- of ... struct of struct of struct of ..." where there are 32
- array and 32 struct.
- </para>
- </listitem>
- <listitem>
- <para>
- The maximum length of a signature is 255.
- </para>
- </listitem>
- <listitem>
- <para>
- Signatures must be nul-terminated.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </sect3>
-
</sect2>
</sect1>
</listitem>
<listitem>
<para>
- Receive REJECT [mechs] → send AUTH [next mech],
+ Receive REJECTED [mechs] → send AUTH [next mech],
goto <emphasis>WaitingForData</emphasis> or
<emphasis>WaitingForOK</emphasis>
</para>
<itemizedlist>
<listitem>
<para>
- Receive REJECT [mechs] → send AUTH [next mech],
+ Receive REJECTED [mechs] → send AUTH [next mech],
goto <emphasis>WaitingForData</emphasis> or
<emphasis>WaitingForOK</emphasis>
</para>
<listitem>
<para>
- REJECT means that the client failed to authenticate or
+ REJECTED means that the client failed to authenticate or
there was an error in RESP.
</para>
</listitem>
</member>
<member>
- MECH(RESP) returns REJECT → send REJECTED
+ MECH(RESP) returns REJECTED → send REJECTED
[mechs], goto
<emphasis>WaitingForAuth</emphasis>
</member>
</member>
<member>
- MECH(RESP) returns REJECT → send REJECTED
+ MECH(RESP) returns REJECTED → send REJECTED
[mechs], goto
<emphasis>WaitingForAuth</emphasis>
</member>
that connection is said to <firstterm>own</firstterm> the name.
</para>
<para>
- The bus itself owns a special name, <literal>org.freedesktop.DBus</literal>.
- This name routes messages to the bus, allowing applications to make
- administrative requests. For example, applications can ask the bus
- to assign a name to a connection.
+ The bus itself owns a special name,
+ <literal>org.freedesktop.DBus</literal>, with an object
+ located at <literal>/org/freedesktop/DBus</literal> that
+ implements the <literal>org.freedesktop.DBus</literal>
+ interface. This service allows applications to make
+ administrative requests of the bus itself. For example,
+ applications can ask the bus to assign a name to a connection.
</para>
<para>
Each name may have <firstterm>queued owners</firstterm>. When an
</para>
<para>
The following table describes the keys that can be used to create
- a match rule:
- The following table summarizes the D-Bus types.
+ a match rule.
<informaltable>
<tgroup cols="3">
<thead>