<?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>
</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>
- <sect2 id="message-protocol-marshaling">
- <title>Marshaling (Wire Format)</title>
+ <sect1 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:
<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)
</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>
projects / platform / upstream / dbus.git / blobdiff