<?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>UNRELEASED</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>
+ <revremark>formally define unique connection names and well-known
+ bus names; document best practices for interface, bus, member and
+ error names, and object paths; document the search path for session
+ and system services on Unix; document the systemd transport</revremark>
+ </revision>
+ <revision>
<revnumber>0.18</revnumber>
<date>29 July 2011</date>
<authorinitials>smcv</authorinitials>
it back from the wire format is <firstterm>unmarshaling</firstterm>.
</para>
- <sect2 id="message-protocol-signatures">
- <title>Type Signatures</title>
+ <para>
+ The D-Bus protocol does not include type tags in the marshaled data; a
+ block of marshaled values must have a known <firstterm>type
+ signature</firstterm>. The type signature is made up of zero or more
+ <firstterm id="term-single-complete-type">single complete
+ types</firstterm>, each made up of one or more
+ <firstterm>type codes</firstterm>.
+ </para>
+
+ <para>
+ A type code is an ASCII character representing the
+ type of a value. Because ASCII characters are used, the type signature
+ will always form a valid ASCII string. A simple string compare
+ determines whether two type signatures are equivalent.
+ </para>
+
+ <para>
+ A single complete type is a sequence of type codes that fully describes
+ one type: either a basic type, or a single fully-described container type.
+ A single complete type is a basic type code, a variant type code,
+ an array with its element type, or a struct with its fields (all of which
+ are defined below). So the following signatures are not single complete
+ types:
+ <programlisting>
+ "aa"
+ </programlisting>
+ <programlisting>
+ "(ii"
+ </programlisting>
+ <programlisting>
+ "ii)"
+ </programlisting>
+ And the following signatures contain multiple complete types:
+ <programlisting>
+ "ii"
+ </programlisting>
+ <programlisting>
+ "aiai"
+ </programlisting>
+ <programlisting>
+ "(ii)(ii)"
+ </programlisting>
+ Note however that a single complete type may <emphasis>contain</emphasis>
+ multiple other single complete types, by containing a struct or dict
+ entry.
+ </para>
+
+ <sect2 id="basic-types">
+ <title>Basic types</title>
+
+ <para>
+ The simplest type codes are the <firstterm id="term-basic-type">basic
+ types</firstterm>, which are the types whose structure is entirely
+ defined by their 1-character type code. Basic types consist of
+ fixed types and string-like types.
+ </para>
<para>
- The D-Bus protocol does not include type tags in the marshaled data; a
- block of marshaled values must have a known <firstterm>type
- signature</firstterm>. The type signature is made up of <firstterm>type
- codes</firstterm>. A type code is an ASCII character representing the
- type of a value. Because ASCII characters are used, the type signature
- will always form a valid ASCII string. A simple string compare
- determines whether two type signatures are equivalent.
+ The <firstterm id="term-fixed-type">fixed types</firstterm>
+ are basic types whose values have a fixed length, namely BYTE,
+ BOOLEAN, DOUBLE, UNIX_FD, and signed or unsigned integers of length
+ 16, 32 or 64 bits.
</para>
<para>
</para>
<para>
- All <firstterm>basic</firstterm> types work like
- <literal>INT32</literal> in this example. To marshal and unmarshal
- basic types, you simply read one value from the data
- block corresponding to each type code in the signature.
+ The characteristics of the fixed types are listed in this table.
+
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Conventional name</entry>
+ <entry>ASCII type-code</entry>
+ <entry>Encoding</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>BYTE</literal></entry>
+ <entry><literal>y</literal> (121)</entry>
+ <entry>Unsigned 8-bit integer</entry>
+ </row>
+ <row>
+ <entry><literal>BOOLEAN</literal></entry>
+ <entry><literal>b</literal> (98)</entry>
+ <entry>Boolean value: 0 is false, 1 is true, any other value
+ allowed by the marshalling format is invalid</entry>
+ </row>
+ <row>
+ <entry><literal>INT16</literal></entry>
+ <entry><literal>n</literal> (110)</entry>
+ <entry>Signed (two's complement) 16-bit integer</entry>
+ </row>
+ <row>
+ <entry><literal>UINT16</literal></entry>
+ <entry><literal>q</literal> (113)</entry>
+ <entry>Unsigned 16-bit integer</entry>
+ </row>
+ <row>
+ <entry><literal>INT32</literal></entry>
+ <entry><literal>i</literal> (105)</entry>
+ <entry>Signed (two's complement) 32-bit integer</entry>
+ </row>
+ <row>
+ <entry><literal>UINT32</literal></entry>
+ <entry><literal>u</literal> (117)</entry>
+ <entry>Unsigned 32-bit integer</entry>
+ </row>
+ <row>
+ <entry><literal>INT64</literal></entry>
+ <entry><literal>x</literal> (120)</entry>
+ <entry>Signed (two's complement) 64-bit integer
+ (mnemonic: x and t are the first characters in "sixty" not
+ already used for something more common)</entry>
+ </row>
+ <row>
+ <entry><literal>UINT64</literal></entry>
+ <entry><literal>t</literal> (116)</entry>
+ <entry>Unsigned 64-bit integer</entry>
+ </row>
+ <row>
+ <entry><literal>DOUBLE</literal></entry>
+ <entry><literal>d</literal> (100)</entry>
+ <entry>IEEE 754 double-precision floating point</entry>
+ </row>
+ <row>
+ <entry><literal>UNIX_FD</literal></entry>
+ <entry><literal>h</literal> (104)</entry>
+ <entry>Unsigned 32-bit integer representing an index into an
+ out-of-band array of file descriptors, transferred via some
+ platform-specific mechanism (mnemonic: h for handle)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ <para>
+ The <firstterm id="term-string-like-type">string-like types</firstterm>
+ 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
+ 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>
+ The marshalling formats for the string-like types all end with a
+ single zero (NUL) byte, but that byte is not considered to be part of
+ the text.
+ </para>
+
+ <para>
+ The characteristics of the string-like types are listed in this table.
+
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Conventional name</entry>
+ <entry>ASCII type-code</entry>
+ <entry>Validity constraints</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>STRING</literal></entry>
+ <entry><literal>s</literal> (115)</entry>
+ <entry>No extra constraints</entry>
+ </row>
+ <row>
+ <entry><literal>OBJECT_PATH</literal></entry>
+ <entry><literal>o</literal> (111)</entry>
+ <entry>Must be
+ <link linkend="message-protocol-marshaling-object-path">a
+ syntactically valid object path</link></entry>
+ </row>
+ <row>
+ <entry><literal>SIGNATURE</literal></entry>
+ <entry><literal>g</literal> (103)</entry>
+ <entry>Zero or more
+ <firstterm linkend="term-single-complete-type">single
+ complete types</firstterm></entry>
+ </row>
+ </tbody>
+ </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>
+ 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">
+ <title>Container types</title>
+
+ <para>
In addition to basic types, there are four <firstterm>container</firstterm>
types: <literal>STRUCT</literal>, <literal>ARRAY</literal>, <literal>VARIANT</literal>,
and <literal>DICT_ENTRY</literal>.
</para>
<para>
- The phrase <firstterm>single complete type</firstterm> deserves some
- definition. A single complete type is a basic type code, a variant type code,
- an array with its element type, or a struct with its fields.
- So the following signatures are not single complete types:
- <programlisting>
- "aa"
- </programlisting>
- <programlisting>
- "(ii"
- </programlisting>
- <programlisting>
- "ii)"
- </programlisting>
- And the following signatures contain multiple complete types:
- <programlisting>
- "ii"
- </programlisting>
- <programlisting>
- "aiai"
- </programlisting>
- <programlisting>
- "(ii)(ii)"
- </programlisting>
- Note however that a single complete type may <emphasis>contain</emphasis>
- multiple other single complete types.
- </para>
-
- <para>
<literal>VARIANT</literal> has ASCII character 'v' as its type code. A marshaled value of
type <literal>VARIANT</literal> will have the signature of a single complete type as part
of the <emphasis>value</emphasis>. This signature will be followed by a
</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
In most languages, an array of dict entry would be represented as a
map, hash table, or dict object.
</para>
+ </sect2>
+
+ <sect2>
+ <title>Summary of types</title>
<para>
The following table summarizes the D-Bus types.
</para>
</sect2>
+ </sect1>
+
+ <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 id="message-protocol-marshaling">
- <title>Marshaling (Wire Format)</title>
+ <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
+ values are IEEE 754 double-precision floating-point, and BOOLEAN
+ values are encoded in 32 bits (of which only the least significant
+ bit is used).
+ </para>
+
+ <para>
+ The string-like types are all marshalled as a
+ fixed-length unsigned integer <varname>n</varname> giving the
+ length of the variable part, followed by <varname>n</varname>
+ nonzero bytes of UTF-8 text, followed by a single zero (nul) byte
+ which is not considered to be part of the text. The alignment
+ of the string-like type is the same as the alignment of
+ <varname>n</varname>.
+ </para>
+
+ <para>
+ For the STRING and OBJECT_PATH types, <varname>n</varname> is
+ encoded in 4 bytes, leading to 4-byte alignment.
+ For the SIGNATURE type, <varname>n</varname> is encoded as a single
+ 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:
<informaltable>
<tgroup cols="3">
</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)
<entry>4</entry>
</row>
</tbody>
- </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>
-
- </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>
-
+ </tgroup>
+ </informaltable>
+ </para>
+
</sect2>
</sect1>
<listitem><para>Interface names must not exceed the maximum name length.</para></listitem>
</itemizedlist>
</para>
+
+ <para>
+ Interface names should start with the reversed DNS domain name of
+ the author of the interface (in lower-case), like interface names
+ in Java. It is conventional for the rest of the interface name
+ to consist of words run together, with initial capital letters
+ on all words ("CamelCase"). Several levels of hierarchy can be used.
+ It is also a good idea to include the major version of the interface
+ in the name, and increment it if incompatible changes are made;
+ this way, a single object can implement several versions of an
+ interface in parallel, if necessary.
+ </para>
+
+ <para>
+ For instance, if the owner of <literal>example.com</literal> is
+ developing a D-Bus API for a music player, they might define
+ interfaces called <literal>com.example.MusicPlayer1</literal>,
+ <literal>com.example.MusicPlayer1.Track</literal> and
+ <literal>com.example.MusicPlayer1.Seekable</literal>.
+ </para>
+
+ <para>
+ D-Bus does not distinguish between the concepts that would be
+ called classes and interfaces in Java: either can be identified on
+ D-Bus by an interface name.
+ </para>
</sect3>
<sect3 id="message-protocol-names-bus">
<title>Bus names</title>
<para>
Connections have one or more bus names associated with them.
- A connection has exactly one bus name that is a unique connection
- name. The unique connection name remains with the connection for
- its entire lifetime.
+ A connection has exactly one bus name that is a <firstterm>unique
+ connection name</firstterm>. The unique connection name remains
+ with the connection for its entire lifetime.
A bus name is of type <literal>STRING</literal>,
meaning that it must be valid UTF-8. However, there are also
some additional restrictions that apply to bus names
specifically:
<itemizedlist>
<listitem><para>Bus names that start with a colon (':')
- character are unique connection names.
+ character are unique connection names. Other bus names
+ are called <firstterm>well-known bus names</firstterm>.
</para>
</listitem>
<listitem><para>Bus names are composed of 1 or more elements separated by
Note that the hyphen ('-') character is allowed in bus names but
not in interface names.
</para>
+
+ <para>
+ Like <link linkend="message-protocol-names-interface">interface
+ names</link>, well-known bus names should start with the
+ reversed DNS domain name of the author of the interface (in
+ lower-case), and it is conventional for the rest of the well-known
+ bus name to consist of words run together, with initial
+ capital letters. As with interface names, including a version
+ number in well-known bus names is a good idea; it's possible to
+ have the well-known bus name for more than one version
+ simultaneously if backwards compatibility is required.
+ </para>
+
+ <para>
+ If a well-known bus name implies the presence of a "main" interface,
+ that "main" interface is often given the same name as
+ the well-known bus name, and situated at the corresponding object
+ path. For instance, if the owner of <literal>example.com</literal>
+ is developing a D-Bus API for a music player, they might define
+ that any application that takes the well-known name
+ <literal>com.example.MusicPlayer1</literal> should have an object
+ at the object path <literal>/com/example/MusicPlayer1</literal>
+ which implements the interface
+ <literal>com.example.MusicPlayer1</literal>.
+ </para>
</sect3>
<sect3 id="message-protocol-names-member">
<title>Member names</title>
<listitem><para>Must be at least 1 byte in length.</para></listitem>
</itemizedlist>
</para>
+
+ <para>
+ It is conventional for member names on D-Bus to consist of
+ capitalized words with no punctuation ("camel-case").
+ Method names should usually be verbs, such as
+ <literal>GetItems</literal>, and signal names should usually be
+ a description of an event, such as <literal>ItemsChanged</literal>.
+ </para>
</sect3>
<sect3 id="message-protocol-names-error">
<title>Error names</title>
<para>
Error names have the same restrictions as interface names.
</para>
+
+ <para>
+ Error names have the same naming conventions as interface
+ names, and often contain <literal>.Error.</literal>; for instance,
+ the owner of <literal>example.com</literal> might define the
+ errors <literal>com.example.MusicPlayer.Error.FileNotFound</literal>
+ and <literal>com.example.MusicPlayer.Error.OutOfMemory</literal>.
+ The errors defined by D-Bus itself, such as
+ <literal>org.freedesktop.DBus.Error.Failed</literal>, follow a
+ similar pattern.
+ </para>
</sect3>
</sect2>
</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>
[FIXME we need to specify in detail each transport and its possible arguments]
Current transports include: unix domain sockets (including
- abstract namespace on linux), launchd, TCP/IP, and a debug/testing transport
+ abstract namespace on linux), launchd, systemd, TCP/IP, an executed subprocess and a debug/testing transport
using in-process pipes. Future possible transports include one that
tunnels over X11 protocol.
</para>
would be padded by Nul bytes.
</para>
<para>
- Unix domain sockets are not available on windows.
+ Unix domain sockets are not available on Windows.
</para>
<sect3 id="transports-unix-domain-sockets-addresses">
<title>Server Address Format</title>
<sect2 id="transports-launchd">
<title>launchd</title>
<para>
- launchd is a open-source server management system that replaces init, inetd
+ launchd is an open-source server management system that replaces init, inetd
and cron on Apple Mac OS X versions 10.4 and above. It provides a common session
bus address for each user and deprecates the X11-enabled D-Bus launcher on OSX.
</para>
</informaltable>
</sect3>
</sect2>
+ <sect2 id="transports-systemd">
+ <title>systemd</title>
+ <para>
+ systemd is an open-source server management system that
+ replaces init and inetd on newer Linux systems. It supports
+ socket activation. The D-Bus systemd transport is used to acquire
+ socket activation file descriptors from systemd and use them
+ as D-Bus transport when the current process is spawned by
+ socket activation from it.
+ </para>
+ <para>
+ The systemd transport accepts only one or more Unix domain or
+ TCP streams sockets passed in via socket activation.
+ </para>
+ <para>
+ The systemd transport is not available on non-Linux operating systems.
+ </para>
+ <para>
+ The systemd transport defines no parameter keys.
+ </para>
+ </sect2>
<sect2 id="transports-tcp-sockets">
<title>TCP Sockets</title>
<para>
over a network is unsecure.
</para>
<para>
- Windows notes: Because of the tcp stack on windows does not provide sending
+ Windows notes: Because of the tcp stack on Windows does not provide sending
credentials over a tcp connection, the EXTERNAL authentification
mechanismus does not work.
</para>
</informaltable>
</sect3>
</sect2>
+ <sect2 id="transports-exec">
+ <title>Executed Subprocesses on Unix</title>
+ <para>
+ This transport forks off a process and connects its standard
+ input and standard output with an anonymous Unix domain
+ socket. This socket is then used for communication by the
+ transport. This transport may be used to use out-of-process
+ forwarder programs as basis for the D-Bus protocol.
+ </para>
+ <para>
+ The forked process will inherit the standard error output and
+ process group from the parent process.
+ </para>
+ <para>
+ Executed subprocesses are not available on Windows.
+ </para>
+ <sect3 id="transports-exec-addresses">
+ <title>Server Address Format</title>
+ <para>
+ Executed subprocess addresses are identified by the "unixexec:" prefix
+ and support the following key/value pairs:
+ </para>
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Values</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>path</entry>
+ <entry>(path)</entry>
+ <entry>Path of the binary to execute, either an absolute
+ path or a binary name that is searched for in the default
+ search path of the OS. This corresponds to the first
+ argument of execlp(). This key is mandatory.</entry>
+ </row>
+ <row>
+ <entry>argv0</entry>
+ <entry>(string)</entry>
+ <entry>The program name to use when executing the
+ binary. If omitted the same value as specified for path=
+ will be used. This corresponds to the second argument of
+ execlp().</entry>
+ </row>
+ <row>
+ <entry>argv1, argv2, ...</entry>
+ <entry>(string)</entry>
+ <entry>Arguments to pass to the binary. This corresponds
+ to the third and later arguments of execlp(). If a
+ specific argvX is not specified no further argvY for Y > X
+ are taken into account.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect3>
+ </sect2>
</sect1>
<sect1 id="meta-transports">
<title>Meta Transports</title>
</sect3>
</sect2>
</sect1>
- <sect1 id="naming-conventions">
- <title>Naming Conventions</title>
-
- <para>
- D-Bus namespaces are all lowercase and correspond to reversed domain
- names, as with Java. e.g. "org.freedesktop"
- </para>
- <para>
- Interface, signal, method, and property names are "WindowsStyleCaps", note
- that the first letter is capitalized, unlike Java.
- </para>
- <para>
- Object paths are normally all lowercase with underscores used rather than
- hyphens.
- </para>
- </sect1>
<sect1 id="uuids">
<title>UUIDs</title>
</programlisting>
</para>
<para>
+ It is conventional to give D-Bus properties names consisting of
+ capitalized words without punctuation ("CamelCase"), like
+ <link linkend="message-protocol-names-member">member names</link>.
+ For instance, the GObject property
+ <literal>connection-status</literal> or the Qt property
+ <literal>connectionStatus</literal> could be represented on D-Bus
+ as <literal>ConnectionStatus</literal>.
+ </para>
+ <para>
+ Strictly speaking, D-Bus property names are not required to follow
+ the same naming restrictions as member names, but D-Bus property
+ names that would not be valid member names (in particular,
+ GObject-style dash-separated property names) can cause interoperability
+ problems and should be avoided.
+ </para>
+ <para>
The available properties and whether they are writable can be determined
by calling <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>,
see <xref linkend="standard-interfaces-introspectable"/>.
<programlisting>
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
- <node name="/org/freedesktop/sample_object">
- <interface name="org.freedesktop.SampleInterface">
+ <node name="/com/example/sample_object">
+ <interface name="com.example.SampleInterface">
<method name="Frobate">
<arg name="foo" type="i" direction="in"/>
<arg name="bar" type="s" direction="out"/>
unique-for-the-lifetime-of-the-bus name automatically assigned.
Applications may request additional names for a connection. Additional
names are usually "well-known names" such as
- "org.freedesktop.TextEditor". When a name is bound to a connection,
+ "com.example.TextEditor". When a name is bound to a connection,
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>
This feature causes the right thing to happen if you start two text
- editors for example; the first one may request "org.freedesktop.TextEditor",
+ editors for example; the first one may request "com.example.TextEditor",
and the second will be queued as a possible owner of that name. When
the first exits, the second will take over.
</para>
</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>
<para>
With D-Bus, starting a service is normally done by name. That is,
applications ask the message bus to start some program that will own a
- well-known name, such as <literal>org.freedesktop.TextEditor</literal>.
- This implies a contract documented along with the name
- <literal>org.freedesktop.TextEditor</literal> for which objects
+ well-known name, such as <literal>com.example.TextEditor</literal>.
+ This implies a contract documented along with the name
+ <literal>com.example.TextEditor</literal> for which object
the owner of that name will provide, and what interfaces those
objects will have.
</para>
<programlisting>
# Sample service description file
[D-BUS Service]
- Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf;
- Exec=/usr/libexec/gconfd-2
+ Name=com.example.ConfigurationDatabase
+ Exec=/usr/bin/sample-configd
</programlisting>
</figure>
</para>
<sect4>
<title></title>
<para>
- [FIXME specify location of .service files, probably using
- DESKTOP_DIRS etc. from basedir specification, though login session
- bus is not really desktop-specific]
+ On Unix systems, the session bus should search for .service files
+ in <literal>$XDG_DATA_DIRS/dbus-1/services</literal> as defined
+ by the
+ <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG Base Directory Specification</ulink>.
+ Implementations may also search additional locations, which
+ should be searched with lower priority than anything in
+ XDG_DATA_HOME, XDG_DATA_DIRS or their respective defaults;
+ for example, the reference implementation also
+ looks in <literal>${datadir}/dbus-1/services</literal> as
+ set at compile time.
+ </para>
+ <para>
+ As described in the XDG Base Directory Specification, software
+ packages should install their session .service files to their
+ configured <literal>${datadir}/dbus-1/services</literal>,
+ where <literal>${datadir}</literal> is as defined by the GNU
+ coding standards. System administrators or users can arrange
+ for these service files to be read by setting XDG_DATA_DIRS or by
+ symlinking them into the default locations.
</para>
</sect4>
</sect3>
</footnote>
</para>
<para>
- [FIXME specify location of system bus .service files]
+ On Unix systems, the system bus should default to searching
+ for .service files in
+ <literal>/usr/local/share/dbus-1/system-services</literal>,
+ <literal>/usr/share/dbus-1/system-services</literal> and
+ <literal>/lib/dbus-1/system-services</literal>, with that order
+ of precedence. It may also search other implementation-specific
+ locations, but should not vary these locations based on environment
+ variables.
+ <footnote>
+ <para>
+ The system bus is security-sensitive and is typically executed
+ by an init system with a clean environment. Its launch helper
+ process is particularly security-sensitive, and specifically
+ clears its own environment.
+ </para>
+ </footnote>
+ </para>
+ <para>
+ Software packages should install their system .service
+ files to their configured
+ <literal>${datadir}/dbus-1/system-services</literal>,
+ where <literal>${datadir}</literal> is as defined by the GNU
+ coding standards. System administrators can arrange
+ for these service files to be read by editing the system bus'
+ configuration file or by symlinking them into the default
+ locations.
</para>
</sect3>
</sect2>
</para>
</sect3>
+ <sect3 id="bus-messages-get-connection-credentials">
+ <title><literal>org.freedesktop.DBus.GetConnectionCredentials</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ DICT<STRING,VARIANT> GetConnectionCredentials (in STRING bus_name)
+ </programlisting>
+ Message arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>STRING</entry>
+ <entry>Unique or well-known bus name of the connection to
+ query, such as <literal>:12.34</literal> or
+ <literal>com.example.tea</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ Reply arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>DICT<STRING,VARIANT></entry>
+ <entry>Credentials</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ <para>
+ Returns as many credentials as possible for the process connected to
+ the server. If unable to determine certain credentials (for instance,
+ because the process is not on the same machine as the bus daemon,
+ or because this version of the bus daemon does not support a
+ particular security framework), or if the values of those credentials
+ cannot be represented as documented here, then those credentials
+ are omitted.
+ </para>
+
+ <para>
+ Keys in the returned dictionary not containing "." are defined
+ by this specification. Bus daemon implementors supporting
+ credentials frameworks not mentioned in this document should either
+ contribute patches to this specification, or use keys containing
+ "." and starting with a reversed domain name.
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Key</entry>
+ <entry>Value type</entry>
+ <entry>Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>UnixUserID</entry>
+ <entry>UINT32</entry>
+ <entry>The numeric Unix user ID, as defined by POSIX</entry>
+ </row>
+ <row>
+ <entry>ProcessID</entry>
+ <entry>UINT32</entry>
+ <entry>The numeric process ID, on platforms that have
+ this concept. On Unix, this is the process ID defined by
+ POSIX.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ <para>
+ This method was added in D-Bus 1.7 to reduce the round-trips
+ required to list a process's credentials. In older versions, calling
+ this method will fail: applications should recover by using the
+ separate methods such as
+ <xref linkend="bus-messages-get-connection-unix-user"/>
+ instead.
+ </para>
+ </sect3>
+
+ <sect3 id="bus-messages-get-adt-audit-session-data">
+ <title><literal>org.freedesktop.DBus.GetAdtAuditSessionData</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ ARRAY of BYTE GetAdtAuditSessionData (in STRING bus_name)
+ </programlisting>
+ Message arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>STRING</entry>
+ <entry>Unique or well-known bus name of the connection to
+ query, such as <literal>:12.34</literal> or
+ <literal>com.example.tea</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ Reply arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>ARRAY of BYTE</entry>
+ <entry>auditing data as returned by
+ adt_export_session_data()</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ Returns auditing data used by Solaris ADT, in an unspecified
+ binary format. If you know what this means, please contribute
+ documentation via the D-Bus bug tracking system.
+ This method is on the core DBus interface for historical reasons;
+ the same information should be made available via
+ <xref linkend="bus-messages-get-connection-credentials"/>
+ in future.
+ </para>
+ </sect3>
+
+ <sect3 id="bus-messages-get-connection-selinux-security-context">
+ <title><literal>org.freedesktop.DBus.GetConnectionSELinuxSecurityContext</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ ARRAY of BYTE GetConnectionSELinuxSecurityContext (in STRING bus_name)
+ </programlisting>
+ Message arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>STRING</entry>
+ <entry>Unique or well-known bus name of the connection to
+ query, such as <literal>:12.34</literal> or
+ <literal>com.example.tea</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ Reply arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>ARRAY of BYTE</entry>
+ <entry>some sort of string of bytes, not necessarily UTF-8,
+ not including '\0'</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ Returns the security context used by SELinux, in an unspecified
+ format. If you know what this means, please contribute
+ documentation via the D-Bus bug tracking system.
+ This method is on the core DBus interface for historical reasons;
+ the same information should be made available via
+ <xref linkend="bus-messages-get-connection-credentials"/>
+ in future.
+ </para>
+ </sect3>
+
+
<sect3 id="bus-messages-add-match">
<title><literal>org.freedesktop.DBus.AddMatch</literal></title>
<para>
can be thought of as "well-known names" and are
used to find applications that offer specific functionality.
</para>
+
+ <para>
+ See <xref linkend="message-protocol-names-bus"/> for details of
+ the syntax and naming conventions for bus names.
+ </para>
</glossdef>
</glossentry>
<glossentry id="namespace"><glossterm>Namespace</glossterm>
<glossdef>
- <para>
- Used to prevent collisions when defining new interfaces or bus
- names. The convention used is the same one Java uses for defining
- classes: a reversed domain name.
+ <para>
+ Used to prevent collisions when defining new interfaces, bus names
+ etc. The convention used is the same one Java uses for defining
+ classes: a reversed domain name.
+ See <xref linkend="message-protocol-names-bus"/>,
+ <xref linkend="message-protocol-names-interface"/>,
+ <xref linkend="message-protocol-names-error"/>,
+ <xref linkend="message-protocol-marshaling-object-path"/>.
</para>
</glossdef>
</glossentry>
A service is an executable that can be launched by the bus daemon.
Services normally guarantee some particular features, for example they
may guarantee that they will request a specific name such as
- "org.freedesktop.Screensaver", have a singleton object
- "/org/freedesktop/Application", and that object will implement the
- interface "org.freedesktop.ScreensaverControl".
+ "com.example.Screensaver", have a singleton object
+ "/com/example/Application", and that object will implement the
+ interface "com.example.Screensaver.Control".
</para>
</glossdef>
</glossentry>
projects / platform / upstream / dbus.git / blobdiff