<article id="index">
<articleinfo>
<title>D-Bus Specification</title>
- <releaseinfo>Version 0.19</releaseinfo>
- <date>2012-02-21</date>
+ <releaseinfo>Version 0.21</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.21</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.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>
</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
not be left uninitialized (it can't contain garbage), and more padding
than required must not be used.
</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>
<sect2>
<title>Marshalling containers</title>
- <para>... to be written ...</para>
+ <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>
<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
projects / platform / upstream / dbus.git / blobdiff