<articleinfo>
<title>D-Bus Specification</title>
<releaseinfo>Version 0.19</releaseinfo>
- <date>UNRELEASED</date>
+ <date>2012-02-21</date>
<authorgroup>
<author>
<firstname>Havoc</firstname>
<revremark></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>
- 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.
- </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>
As a simple example, the type code for 32-bit integer (<literal>INT32</literal>) is
</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
+ All fixed types work like
+ <literal>INT32</literal> in this example: to marshal and unmarshal
+ fixed types, you simply read one value from the data
block corresponding to each type code in the signature.
+ </para>
+ </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
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.
[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>
projects / platform / upstream / dbus.git / blobdiff