<article id="index">
<articleinfo>
<title>D-Bus Specification</title>
- <releaseinfo>Version 0.23</releaseinfo>
- <date>(not yet released)</date>
+ <releaseinfo>Version 0.27</releaseinfo>
+ <date>2015-12-02</date>
<authorgroup>
<author>
- <firstname>Havoc</firstname>
- <surname>Pennington</surname>
- <affiliation>
- <orgname>Red Hat, Inc.</orgname>
- <address>
- <email>hp@pobox.com</email>
- </address>
- </affiliation>
+ <firstname>Havoc</firstname>
+ <surname>Pennington</surname>
+ <orgname>Red Hat, Inc.</orgname>
+ <email>hp@pobox.com</email>
+ </address>
+ </affiliation>
</author>
<author>
- <firstname>Anders</firstname>
- <surname>Carlsson</surname>
- <affiliation>
- <orgname>CodeFactory AB</orgname>
- <address>
+ <firstname>Anders</firstname>
+ <surname>Carlsson</surname>
+ <orgname>CodeFactory AB</orgname>
<email>andersca@codefactory.se</email>
</address>
- </affiliation>
+ </affiliation>
</author>
<author>
- <firstname>Alexander</firstname>
- <surname>Larsson</surname>
- <affiliation>
- <orgname>Red Hat, Inc.</orgname>
- <address>
+ <firstname>Alexander</firstname>
+ <surname>Larsson</surname>
+ <orgname>Red Hat, Inc.</orgname>
<email>alexl@redhat.com</email>
</address>
- </affiliation>
+ </affiliation>
</author>
<author>
- <firstname>Sven</firstname>
- <surname>Herzberg</surname>
- <affiliation>
- <orgname>Imendio AB</orgname>
- <address>
+ <firstname>Sven</firstname>
+ <surname>Herzberg</surname>
+ <orgname>Imendio AB</orgname>
<email>sven@imendio.com</email>
</address>
- </affiliation>
+ </affiliation>
</author>
<author>
<firstname>Simon</firstname>
<firstname>David</firstname>
<surname>Zeuthen</surname>
<affiliation>
- <orgname>Red Hat, Inc.</orgname>
<address>
- <email>davidz@redhat.com</email>
+ <email>zeuthen@gmail.com</email>
</address>
</affiliation>
</author>
</authorgroup>
<revhistory>
<revision>
+ <revnumber>0.27</revnumber>
+ <date>2015-12-02</date>
+ <authorinitials>LU</authorinitials>
+ <revremark>Services should not send unwanted replies</revremark>
+ </revision>
+ <revision>
+ <revnumber>0.26</revnumber>
+ <date>2015-02-19</date>
+ <authorinitials>smcv, rh</authorinitials>
+ <revremark>
+ GetConnectionCredentials can return LinuxSecurityLabel or
+ WindowsSID; add privileged BecomeMonitor method
+ </revremark>
+ </revision>
+ <revision>
+ <revnumber>0.25</revnumber>
+ <date>2014-11-10</date>
+ <authorinitials>smcv, lennart</authorinitials>
+ <revremark>
+ ALLOW_INTERACTIVE_AUTHORIZATION flag, EmitsChangedSignal=const
+ </revremark>
+ </revision>
+ <revision>
+ <revnumber>0.24</revnumber>
+ <date>2014-10-01</date>
+ <authorinitials>SMcV</authorinitials>
+ <revremark>
+ non-method-calls never expect a reply even without NO_REPLY_EXPECTED;
+ document how to quote match rules
+ </revremark>
+ </revision>
+ <revision>
<revnumber>0.23</revnumber>
- <date>not yet released</date>
- <authorinitials></authorinitials>
+ <date>2014-01-06</date>
+ <authorinitials>SMcV, CY</authorinitials>
<revremark>
- see <ulink url='http://cgit.freedesktop.org/dbus/dbus/log/doc/dbus-specification.xml'>commit log</ulink>
+ method call messages with no INTERFACE may be considered an error;
+ document tcp:bind=... and nonce-tcp:bind=...; define listenable
+ and connectable addresses
</revremark>
</revision>
<revision>
</listitem>
<listitem>
<para>
- A "session bus" used to implement desktop environments such as
+ A "session bus" used to implement desktop environments such as
GNOME and KDE.
</para>
</listitem>
</itemizedlist>
- D-Bus is not intended to be a generic IPC system for any possible
- application, and intentionally omits many features found in other
+ D-Bus is not intended to be a generic IPC system for any possible
+ application, and intentionally omits many features found in other
IPC systems for this reason.
</para>
At the same time, the bus daemons offer a number of features not found in
other IPC systems, such as single-owner "bus names" (similar to X
selections), on-demand startup of services, and security policies.
- In many ways, these features are the primary motivation for developing
+ In many ways, these features are the primary motivation for developing
D-Bus; other systems would have sufficed if IPC were the only goal.
</para>
reference implementation's behavior.
</para>
<para>
- Until this work is complete, any attempt to reimplement D-Bus will
+ Until this work is complete, any attempt to reimplement D-Bus will
probably require looking at the reference implementation and/or asking
- questions on the D-Bus mailing list about intended behavior.
+ questions on the D-Bus mailing list about intended behavior.
Questions on the list are very welcome.
</para>
<para>
- Nonetheless, this document should be a useful starting point and is
+ Nonetheless, this document should be a useful starting point and is
to our knowledge accurate, though incomplete.
</para>
</sect2>
-
+
</sect1>
<sect1 id="type-system">
<para>
As a simple example, the type code for 32-bit integer (<literal>INT32</literal>) is
- the ASCII character 'i'. So the signature for a block of values
+ the ASCII character 'i'. So the signature for a block of values
containing a single <literal>INT32</literal> would be:
<programlisting>
"i"
A block of values containing two <literal>INT32</literal> would have this signature:
<programlisting>
"ii"
- </programlisting>
+ </programlisting>
</para>
<para>
<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>,
+ 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>
- <literal>STRUCT</literal> has a type code, ASCII character 'r', but this type
+ <literal>STRUCT</literal> has a type code, ASCII character 'r', but this type
code does not appear in signatures. Instead, ASCII characters
'(' and ')' are used to mark the beginning and end of the struct.
- So for example, a struct containing two integers would have this
+ So for example, a struct containing two integers would have this
signature:
<programlisting>
"(ii)"
</programlisting>
- Structs can be nested, so for example a struct containing
+ Structs can be nested, so for example a struct containing
an integer and another struct:
<programlisting>
"(i(ii))"
<para>
The <literal>STRUCT</literal> type code 'r' is not currently used in the D-Bus protocol,
- but is useful in code that implements the protocol. This type code
+ but is useful in code that implements the protocol. This type code
is specified to allow such code to interoperate in non-protocol contexts.
</para>
<programlisting>
"ai"
</programlisting>
- which is an array of 32-bit integers. But an array can be of any type,
+ which is an array of 32-bit integers. But an array can be of any type,
such as this array-of-struct-with-two-int32-fields:
<programlisting>
"a(ii)"
fields, and must not accept dict entries with non-basic-typed keys. A
dict entry is always a key-value pair.
</para>
-
+
<para>
The first field in the <literal>DICT_ENTRY</literal> is always the key.
A message is considered corrupt if the same key occurs twice in the same
</para>
<para>
- In most languages, an array of dict entry would be represented as a
+ In most languages, an array of dict entry would be represented as a
map, hash table, or dict object.
</para>
</sect2>
<tgroup cols="3">
<thead>
<row>
+ <entry>Category</entry>
<entry>Conventional Name</entry>
<entry>Code</entry>
<entry>Description</entry>
</thead>
<tbody>
<row>
+ <entry>reserved</entry>
<entry><literal>INVALID</literal></entry>
<entry>0 (ASCII NUL)</entry>
<entry>Not a valid type code, used to terminate signatures</entry>
</row><row>
- <entry><literal>BYTE</literal></entry>
- <entry>121 (ASCII 'y')</entry>
- <entry>8-bit unsigned integer</entry>
+ <entry>fixed, basic</entry>
+ <entry><literal>BYTE</literal></entry>
+ <entry>121 (ASCII 'y')</entry>
+ <entry>8-bit unsigned integer</entry>
</row><row>
- <entry><literal>BOOLEAN</literal></entry>
- <entry>98 (ASCII 'b')</entry>
- <entry>Boolean value, 0 is <literal>FALSE</literal> and 1 is <literal>TRUE</literal>. Everything else is invalid.</entry>
- </row><row>
+ <entry>fixed, basic</entry>
+ <entry><literal>BOOLEAN</literal></entry>
+ <entry>98 (ASCII 'b')</entry>
+ <entry>Boolean value, 0 is <literal>FALSE</literal> and 1 is <literal>TRUE</literal>. Everything else is invalid.</entry>
+ </row><row>
+ <entry>fixed, basic</entry>
<entry><literal>INT16</literal></entry>
<entry>110 (ASCII 'n')</entry>
<entry>16-bit signed integer</entry>
</row><row>
+ <entry>fixed, basic</entry>
<entry><literal>UINT16</literal></entry>
<entry>113 (ASCII 'q')</entry>
<entry>16-bit unsigned integer</entry>
- </row><row>
+ </row><row>
+ <entry>fixed, basic</entry>
<entry><literal>INT32</literal></entry>
<entry>105 (ASCII 'i')</entry>
<entry>32-bit signed integer</entry>
</row><row>
+ <entry>fixed, basic</entry>
<entry><literal>UINT32</literal></entry>
<entry>117 (ASCII 'u')</entry>
<entry>32-bit unsigned integer</entry>
- </row><row>
+ </row><row>
+ <entry>fixed, basic</entry>
<entry><literal>INT64</literal></entry>
<entry>120 (ASCII 'x')</entry>
<entry>64-bit signed integer</entry>
</row><row>
+ <entry>fixed, basic</entry>
<entry><literal>UINT64</literal></entry>
<entry>116 (ASCII 't')</entry>
<entry>64-bit unsigned integer</entry>
</row><row>
+ <entry>fixed, basic</entry>
<entry><literal>DOUBLE</literal></entry>
<entry>100 (ASCII 'd')</entry>
<entry>IEEE 754 double</entry>
</row><row>
+ <entry>string-like, basic</entry>
<entry><literal>STRING</literal></entry>
<entry>115 (ASCII 's')</entry>
<entry>UTF-8 string (<emphasis>must</emphasis> be valid UTF-8). Must be nul terminated and contain no other nul bytes.</entry>
</row><row>
+ <entry>string-like, basic</entry>
<entry><literal>OBJECT_PATH</literal></entry>
<entry>111 (ASCII 'o')</entry>
<entry>Name of an object instance</entry>
</row><row>
+ <entry>string-like, basic</entry>
<entry><literal>SIGNATURE</literal></entry>
<entry>103 (ASCII 'g')</entry>
<entry>A type signature</entry>
</row><row>
+ <entry>container</entry>
<entry><literal>ARRAY</literal></entry>
<entry>97 (ASCII 'a')</entry>
<entry>Array</entry>
</row><row>
+ <entry>container</entry>
<entry><literal>STRUCT</literal></entry>
<entry>114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')')</entry>
<entry>Struct; type code 114 'r' is reserved for use in
concept of a struct, and must not appear in signatures
used on D-Bus.</entry>
</row><row>
+ <entry>container</entry>
<entry><literal>VARIANT</literal></entry>
<entry>118 (ASCII 'v') </entry>
<entry>Variant type (the type of the value is part of the value itself)</entry>
</row><row>
+ <entry>container</entry>
<entry><literal>DICT_ENTRY</literal></entry>
<entry>101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') </entry>
<entry>Entry in a dict or map (array of key-value pairs).
dict or dict-entry, and must not appear in signatures
used on D-Bus.</entry>
</row><row>
+ <entry>fixed, basic</entry>
<entry><literal>UNIX_FD</literal></entry>
<entry>104 (ASCII 'h')</entry>
<entry>Unix file descriptor</entry>
</row>
<row>
+ <entry>reserved</entry>
<entry>(reserved)</entry>
<entry>109 (ASCII 'm')</entry>
<entry>Reserved for <ulink
specified here</entry>
</row>
<row>
+ <entry>reserved</entry>
<entry>(reserved)</entry>
<entry>42 (ASCII '*')</entry>
<entry>Reserved for use in bindings/implementations to
and must not appear in signatures used on D-Bus.</entry>
</row>
<row>
+ <entry>reserved</entry>
<entry>(reserved)</entry>
<entry>63 (ASCII '?')</entry>
<entry>Reserved for use in bindings/implementations to
not appear in signatures used on D-Bus.</entry>
</row>
<row>
+ <entry>reserved</entry>
<entry>(reserved)</entry>
<entry>64 (ASCII '@'), 38 (ASCII '&'),
94 (ASCII '^')</entry>
<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.
+ 67108864 (64 MiB). Implementations must not send or accept arrays
+ exceeding this length.
</para>
<para>
<entry>8</entry>
</row><row>
<entry><literal>STRING</literal></entry>
- <entry>A <literal>UINT32</literal> indicating the string's
- length in bytes excluding its terminating nul, followed by
- non-nul string data of the given length, followed by a terminating nul
+ <entry>A <literal>UINT32</literal> indicating the string's
+ length in bytes excluding its terminating nul, followed by
+ non-nul string data of the given length, followed by a terminating nul
byte.
</entry>
<entry>
</entry>
</row><row>
<entry><literal>OBJECT_PATH</literal></entry>
- <entry>Exactly the same as <literal>STRING</literal> except the
+ <entry>Exactly the same as <literal>STRING</literal> except the
content must be a valid object path (see above).
</entry>
<entry>
</entry>
</row><row>
<entry><literal>SIGNATURE</literal></entry>
- <entry>The same as <literal>STRING</literal> except the length is a single
+ <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 above).
</entry>
</row><row>
<entry><literal>ARRAY</literal></entry>
<entry>
- A <literal>UINT32</literal> giving the length of the array data in bytes, followed by
+ 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.
</entry>
<entry>
8
</entry>
- </row><row>
+ </row><row>
<entry><literal>VARIANT</literal></entry>
<entry>
The marshaled <literal>SIGNATURE</literal> of a single
<entry>
1 (alignment of the signature)
</entry>
- </row><row>
+ </row><row>
<entry><literal>DICT_ENTRY</literal></entry>
<entry>
Identical to STRUCT.
file descriptor in the array of file descriptors that
accompany the message.</entry>
<entry>4</entry>
- </row>
+ </row>
</tbody>
</tgroup>
</informaltable>
information to figure out where to send the message and how to interpret
it; the recipient interprets the body of the message.
</para>
-
+
<para>
The body of the message is made up of zero or more
<firstterm>arguments</firstterm>, which are typed values, such as an
<para>
The length of the header must be a multiple of 8, allowing the body to
begin on an 8-byte boundary when storing the entire message in a single
- buffer. If the header does not naturally end on an 8-byte boundary
+ buffer. If the header does not naturally end on an 8-byte boundary
up to 7 bytes of nul-initialized alignment padding must be added.
</para>
</para>
<para>
- The maximum length of a message, including header, header alignment padding,
- and body is 2 to the 27th power or 134217728. Implementations must not
- send or accept messages exceeding this size.
+ The maximum length of a message, including header, header alignment padding,
+ and body is 2 to the 27th power or 134217728 (128 MiB).
+ Implementations must not send or accept messages exceeding this size.
</para>
-
+
<para>
The signature of the header is:
<programlisting>
<tbody>
<row>
<entry>1st <literal>BYTE</literal></entry>
- <entry>Endianness flag; ASCII 'l' for little-endian
- or ASCII 'B' for big-endian. Both header and body are
+ <entry>Endianness flag; ASCII 'l' for little-endian
+ or ASCII 'B' for big-endian. Both header and body are
in this endianness.</entry>
</row>
<row>
<entry>2nd <literal>BYTE</literal></entry>
- <entry><firstterm>Message type</firstterm>. Unknown types must be ignored.
+ <entry><firstterm>Message type</firstterm>. Unknown types must be ignored.
Currently-defined types are described below.
</entry>
</row>
</row>
<row>
<entry>1st <literal>UINT32</literal></entry>
- <entry>Length in bytes of the message body, starting
- from the end of the header. The header ends after
+ <entry>Length in bytes of the message body, starting
+ from the end of the header. The header ends after
its alignment padding to an 8-boundary.
</entry>
</row>
<row>
<entry>2nd <literal>UINT32</literal></entry>
- <entry>The serial of this message, used as a cookie
+ <entry>The serial of this message, used as a cookie
by the sender to identify the reply corresponding
to this request. This must not be zero.
</entry>
- </row>
+ </row>
<row>
<entry><literal>ARRAY</literal> of <literal>STRUCT</literal> of (<literal>BYTE</literal>,<literal>VARIANT</literal>)</entry>
<entry>An array of zero or more <firstterm>header
fields</firstterm> where the byte is the field code, and the
- variant is the field value. The message type determines
+ variant is the field value. The message type determines
which fields are required.
</entry>
</row>
<row>
<entry><literal>METHOD_CALL</literal></entry>
<entry>1</entry>
- <entry>Method call.</entry>
+ <entry>Method call. This message type may prompt a
+ reply.</entry>
</row>
<row>
<entry><literal>METHOD_RETURN</literal></entry>
<row>
<entry><literal>NO_REPLY_EXPECTED</literal></entry>
<entry>0x1</entry>
- <entry>This message does not expect method return replies or
- error replies; the reply can be omitted as an
- optimization. However, it is compliant with this specification
- to return the reply despite this flag and the only harm
- from doing so is extra network traffic.
+ <entry>
+ <para>
+ This message does not expect method return replies or
+ error replies, even if it is of a type that can
+ have a reply; the reply should be omitted.
+ </para>
+ <para>
+ Note that METHOD_CALL is the only message type currently
+ defined in this specification that can expect a reply,
+ so the presence or absence of this flag in the other
+ three message types that are currently
+ documented is meaningless: replies to those message
+ types should not be sent, whether this flag is present
+ or not.
+ </para>
</entry>
</row>
<row>
for the destination name in response to this message.
</entry>
</row>
+ <row>
+ <entry><literal>ALLOW_INTERACTIVE_AUTHORIZATION</literal></entry>
+ <entry>0x4</entry>
+ <entry>
+ <para>
+ This flag may be set on a method call message to
+ inform the receiving side that the caller is prepared
+ to wait for interactive authorization, which might
+ take a considerable time to complete. For instance,
+ if this flag is set, it would be appropriate to
+ query the user for passwords or confirmation via
+ Polkit or a similar framework.
+ </para>
+ <para>
+ This flag is only useful when
+ unprivileged code calls a more privileged method call,
+ and an authorization framework is deployed that allows
+ possibly interactive authorization. If no such framework
+ is deployed it has no effect. This flag should not
+ be set by default by client implementations. If it is
+ set, the caller should also set a suitably long timeout
+ on the method call to make sure the user interaction
+ may complete. This flag is only valid for method call
+ messages, and shall be ignored otherwise.
+ </para>
+ <para>
+ Interaction that takes place as a part of the
+ effect of the method being called is outside the scope
+ of this flag, even if it could also be characterized
+ as authentication or authorization. For instance, in
+ a method call that directs a network management service
+ to attempt to connect to a virtual private network,
+ this flag should control how the network management
+ service makes the decision "is this user allowed to
+ change system network configuration?", but it should
+ not affect how or whether the network management
+ service interacts with the user to obtain the credentials
+ that are required for access to the VPN.
+ </para>
+ <para>
+ If a this flag is not set on a method call, and a
+ service determines that the requested operation is
+ not allowed without interactive authorization, but
+ could be allowed after successful interactive
+ authorization, it may return the
+ <literal>org.freedesktop.DBus.Error.InteractiveAuthorizationRequired</literal>
+ error.
+ </para>
+ <para>
+ The absence of this flag does not guarantee that
+ interactive authorization will not be applied, since
+ existing services that pre-date this flag might
+ already use interactive authorization. However,
+ existing D-Bus APIs that will use interactive
+ authorization should document that the call may take
+ longer than usual, and new D-Bus APIs should avoid
+ interactive authorization in the absence of this flag.
+ </para>
+ </entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
<para>
Again, if an implementation sees a header field code that it does not
expect, it must ignore that field, as it will be part of a new
- (but compatible) version of this specification. This also applies
- to known header fields appearing in unexpected messages, for
+ (but compatible) version of this specification. This also applies
+ to known header fields appearing in unexpected messages, for
example: if a signal has a reply serial it must be ignored
even though it has no meaning as of this version of the spec.
</para>
<entry><literal>STRING</literal></entry>
<entry><literal>SIGNAL</literal></entry>
<entry>
- The interface to invoke a method call on, or
- that a signal is emitted from. Optional for
+ The interface to invoke a method call on, or
+ that a signal is emitted from. Optional for
method calls, required for signals.
The special interface
<literal>org.freedesktop.DBus.Local</literal> is reserved;
<entry><literal>STRING</literal></entry>
<entry>optional</entry>
<entry>The name of the connection this message is intended for.
- Only used in combination with the message bus, see
+ Only used in combination with the message bus, see
<xref linkend="message-bus"/>.</entry>
</row>
<row>
<entry><literal>SIGNATURE</literal></entry>
<entry>optional</entry>
<entry>The signature of the message body.
- If omitted, it is assumed to be the
+ If omitted, it is assumed to be the
empty signature "" (i.e. the body must be 0-length).</entry>
</row>
<row>
The various names in D-Bus messages have some restrictions.
</para>
<para>
- There is a <firstterm>maximum name length</firstterm>
- of 255 which applies to bus names, interfaces, and members.
+ There is a <firstterm>maximum name length</firstterm>
+ of 255 which applies to bus names, interfaces, and members.
</para>
<sect3 id="message-protocol-names-interface">
<title>Interface names</title>
<para>
- Interfaces have names with type <literal>STRING</literal>, meaning that
- they must be valid UTF-8. However, there are also some
- additional restrictions that apply to interface names
+ Interfaces have names with type <literal>STRING</literal>, meaning that
+ they must be valid UTF-8. However, there are also some
+ additional restrictions that apply to interface names
specifically:
<itemizedlist>
<listitem><para>Interface names are composed of 1 or more elements separated by
- a period ('.') character. All elements must contain at least
+ a period ('.') character. All elements must contain at least
one character.
</para>
</listitem>
- <listitem><para>Each element must only contain the ASCII characters
+ <listitem><para>Each element must only contain the ASCII characters
"[A-Z][a-z][0-9]_" and must not begin with a digit.
</para>
</listitem>
- <listitem><para>Interface names must contain at least one '.' (period)
+
<listitem><para>Interface names must contain at least one '.' (period)
character (and thus at least two elements).
</para></listitem>
- <listitem><para>Interface names must not begin with a '.' (period) character.</para></listitem>
- <listitem><para>Interface names must not exceed the maximum name length.</para></listitem>
+
<listitem><para>Interface names must not begin with a '.' (period) character.</para></listitem>
+
<listitem><para>Interface names must not exceed the maximum name length.</para></listitem>
</itemizedlist>
</para>
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
+ some additional restrictions that apply to bus names
specifically:
<itemizedlist>
<listitem><para>Bus names that start with a colon (':')
</para>
</listitem>
<listitem><para>Bus names are composed of 1 or more elements separated by
- a period ('.') character. All elements must contain at least
+ a period ('.') character. All elements must contain at least
one character.
</para>
</listitem>
- <listitem><para>Each element must only contain the ASCII characters
+ <listitem><para>Each element must only contain the ASCII characters
"[A-Z][a-z][0-9]_-". Only elements that are part of a unique
connection name may begin with a digit, elements in
other bus names must not begin with a digit.
</para>
</listitem>
- <listitem><para>Bus names must contain at least one '.' (period)
+
<listitem><para>Bus names must contain at least one '.' (period)
character (and thus at least two elements).
</para></listitem>
- <listitem><para>Bus names must not begin with a '.' (period) character.</para></listitem>
- <listitem><para>Bus names must not exceed the maximum name length.</para></listitem>
+
<listitem><para>Bus names must not begin with a '.' (period) character.</para></listitem>
+
<listitem><para>Bus names must not exceed the maximum name length.</para></listitem>
</itemizedlist>
</para>
<para>
<para>
Member (i.e. method or signal) names:
<itemizedlist>
- <listitem><para>Must only contain the ASCII characters
+
<listitem><para>Must only contain the ASCII characters
"[A-Z][a-z][0-9]_" and may not begin with a
digit.</para></listitem>
- <listitem><para>Must not contain the '.' (period) character.</para></listitem>
- <listitem><para>Must not exceed the maximum name length.</para></listitem>
- <listitem><para>Must be at least 1 byte in length.</para></listitem>
+
<listitem><para>Must not contain the '.' (period) character.</para></listitem>
+
<listitem><para>Must not exceed the maximum name length.</para></listitem>
+
<listitem><para>Must be at least 1 byte in length.</para></listitem>
</itemizedlist>
</para>
<para>
A method call message is required to have a <literal>MEMBER</literal> header field
indicating the name of the method. Optionally, the message has an
- <literal>INTERFACE</literal> field giving the interface the method is a part of. In the
- absence of an <literal>INTERFACE</literal> field, if two interfaces on the same object have
- a method with the same name, it is undefined which of the two methods
- will be invoked. Implementations may also choose to return an error in
- this ambiguous case. However, if a method name is unique
- implementations must not require an interface field.
+ <literal>INTERFACE</literal> field giving the interface the method is a part of.
+ Including the <literal>INTERFACE</literal> in all method call
+ messages is strongly recommended.
+ </para>
+ <para>
+ In the absence of an <literal>INTERFACE</literal> field, if two
+ or more interfaces on the same object have a method with the same
+ name, it is undefined which of those methods will be invoked.
+ Implementations may choose to either return an error, or deliver the
+ message as though it had an arbitrary one of those interfaces.
+ </para>
+ <para>
+ In some situations (such as the well-known system bus), messages
+ are filtered through an access-control list external to the
+ remote object implementation. If that filter rejects certain
+ messages by matching their interface, or accepts only messages
+ to specific interfaces, it must also reject messages that have no
+ <literal>INTERFACE</literal>: otherwise, malicious
+ applications could use this to bypass the filter.
</para>
<para>
Method call messages also include a <literal>PATH</literal> field
reply can have one of two types; either <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>.
</para>
<para>
- If the reply has type <literal>METHOD_RETURN</literal>, the arguments to the reply message
- are the return value(s) or "out parameters" of the method call.
- If the reply has type <literal>ERROR</literal>, then an "exception" has been thrown,
- and the call fails; no return value will be provided. It makes
+ If the reply has type <literal>METHOD_RETURN</literal>, the arguments to the reply message
+ are the return value(s) or "out parameters" of the method call.
+ If the reply has type <literal>ERROR</literal>, then an "exception" has been thrown,
+ and the call fails; no return value will be provided. It makes
no sense to send multiple replies to the same method call.
</para>
<para>
- Even if a method call has no return values, a <literal>METHOD_RETURN</literal>
- reply is required, so the caller will know the method
+ Even if a method call has no return values, a <literal>METHOD_RETURN</literal>
+ reply is required, so the caller will know the method
was successfully processed.
</para>
<para>
- The <literal>METHOD_RETURN</literal> or <literal>ERROR</literal> reply message must have the <literal>REPLY_SERIAL</literal>
+ The <literal>METHOD_RETURN</literal> or <literal>ERROR</literal> reply message must have the <literal>REPLY_SERIAL</literal>
header field.
</para>
<para>
- If a <literal>METHOD_CALL</literal> message has the flag <literal>NO_REPLY_EXPECTED</literal>,
- then as an optimization the application receiving the method
- call may choose to omit the reply message (regardless of
- whether the reply would have been <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>).
- However, it is also acceptable to ignore the <literal>NO_REPLY_EXPECTED</literal>
- flag and reply anyway.
+ If a <literal>METHOD_CALL</literal> message has the flag <literal>NO_REPLY_EXPECTED</literal>,
+ then the application receiving the method should not send the reply message (regardless of
+ whether the reply would have been <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>).
</para>
<para>
Unless a message has the flag <literal>NO_AUTO_START</literal>, if the
in order. "out" arguments are not represented in the caller's message.
</para>
<para>
- The recipient constructs a reply by appending first the return value
- if any, then each "out" or "inout" argument, in order.
+ The recipient constructs a reply by appending first the return value
+ if any, then each "out" or "inout" argument, in order.
"in" arguments are not represented in the reply message.
</para>
<para>
exceptions.
</para>
<para>
- In converting from native APIs to D-Bus, it is perhaps nice to
- map D-Bus naming conventions ("FooBar") to native conventions
- such as "fooBar" or "foo_bar" automatically. This is OK
- as long as you can say that the native API is one that
+ In converting from native APIs to D-Bus, it is perhaps nice to
+ map D-Bus naming conventions ("FooBar") to native conventions
+ such as "fooBar" or "foo_bar" automatically. This is OK
+ as long as you can say that the native API is one that
was specifically written for D-Bus. It makes the most sense
- when writing object implementations that will be exported
- over the bus. Object proxies used to invoke remote D-Bus
+ when writing object implementations that will be exported
+ over the bus. Object proxies used to invoke remote D-Bus
objects probably need the ability to call any D-Bus method,
and thus a magic name mapping like this could be a problem.
</para>
<para>
This specification doesn't require anything of native API bindings;
- the preceding is only a suggested convention for consistency
+ the preceding is only a suggested convention for consistency
among bindings.
</para>
</sect4>
<sect3 id="message-protocol-types-signal">
<title>Signal Emission</title>
<para>
- Unlike method calls, signal emissions have no replies.
+ Unlike method calls, signal emissions have no replies.
A signal emission is simply a single message of type <literal>SIGNAL</literal>.
- It must have three header fields: <literal>PATH</literal> giving the object
+ It must have three header fields: <literal>PATH</literal> giving the object
the signal was emitted from, plus <literal>INTERFACE</literal> and <literal>MEMBER</literal> giving
the fully-qualified name of the signal. The <literal>INTERFACE</literal> header is required
for signals, though it is optional for method calls.
<sect3 id="message-protocol-types-errors">
<title>Errors</title>
<para>
- Messages of type <literal>ERROR</literal> are most commonly replies
- to a <literal>METHOD_CALL</literal>, but may be returned in reply
+ Messages of type <literal>ERROR</literal> are most commonly replies
+ to a <literal>METHOD_CALL</literal>, but may be returned in reply
to any kind of message. The message bus for example
- will return an <literal>ERROR</literal> in reply to a signal emission if
+ will return an <literal>ERROR</literal> in reply to a signal emission if
the bus does not have enough memory to send the signal.
</para>
<para>
- An <literal>ERROR</literal> may have any arguments, but if the first
+ An <literal>ERROR</literal> may have any arguments, but if the first
argument is a <literal>STRING</literal>, it must be an error message.
The error message may be logged or shown to the user
in some way.
<sect3 id="message-protocol-types-notation">
<title>Notation in this document</title>
<para>
- This document uses a simple pseudo-IDL to describe particular method
+ This document uses a simple pseudo-IDL to describe particular method
calls and signals. Here is an example of a method call:
<programlisting>
org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags,
out UINT32 resultcode)
</programlisting>
- This means <literal>INTERFACE</literal> = org.freedesktop.DBus, <literal>MEMBER</literal> = StartServiceByName,
+ This means <literal>INTERFACE</literal> = org.freedesktop.DBus, <literal>MEMBER</literal> = StartServiceByName,
<literal>METHOD_CALL</literal> arguments are <literal>STRING</literal> and <literal>UINT32</literal>, <literal>METHOD_RETURN</literal> argument
is <literal>UINT32</literal>. Remember that the <literal>MEMBER</literal> field can't contain any '.' (period)
characters so it's known that the last part of the name in
</programlisting>
or equally valid, the return value could be done as an argument:
<programlisting>
- void org::freedesktop::DBus::StartServiceByName (const char *name,
+ void org::freedesktop::DBus::StartServiceByName (const char *name,
unsigned int flags,
unsigned int *resultcode);
</programlisting>
- It's really up to the API designer how they want to make
- this look. You could design an API where the namespace wasn't used
+ It's really up to the API designer how they want to make
+ this look. You could design an API where the namespace wasn't used
in C++, using STL or Qt, using varargs, or whatever you wanted.
</para>
<para>
<programlisting>
org.freedesktop.DBus.NameLost (STRING name)
</programlisting>
- Signals don't specify "in" vs. "out" because only
+ Signals don't specify "in" vs. "out" because only
a single direction is possible.
</para>
<para>
<sect2 id="message-protocol-handling-invalid">
<title>Invalid Protocol and Spec Extensions</title>
-
+
<para>
For security reasons, the D-Bus protocol should be strictly parsed and
validated, with the exception of defined extension points. Any invalid
</para>
<para>
- Generally speaking violations of the "must" requirements in this spec
- should be considered possible attempts to exploit security, and violations
+ Generally speaking violations of the "must" requirements in this spec
+ should be considered possible attempts to exploit security, and violations
of the "should" suggestions should be considered legitimate (though perhaps
they should generate an error in some cases).
</para>
<itemizedlist>
<listitem>
<para>
- In the authentication protocol (see <xref linkend="auth-protocol"/>) unknown
- commands result in an ERROR rather than a disconnect. This enables
- future extensions to the protocol. Commands starting with EXTENSION_ are
+ In the authentication protocol (see <xref linkend="auth-protocol"/>) unknown
+ commands result in an ERROR rather than a disconnect. This enables
+ future extensions to the protocol. Commands starting with EXTENSION_ are
reserved for third parties.
</para>
</listitem>
<para>
Messages with an unknown type (something other than
<literal>METHOD_CALL</literal>, <literal>METHOD_RETURN</literal>,
- <literal>ERROR</literal>, <literal>SIGNAL</literal>) are ignored.
- Unknown-type messages must still be well-formed in the same way
- as the known messages, however. They still have the normal
+ <literal>ERROR</literal>, <literal>SIGNAL</literal>) are ignored.
+ Unknown-type messages must still be well-formed in the same way
+ as the known messages, however. They still have the normal
header and body.
</para>
</listitem>
<listitem>
<para>
- Header fields with an unknown or unexpected field code must be ignored,
+ Header fields with an unknown or unexpected field code must be ignored,
though again they must still be well-formed.
</para>
</listitem>
Commands from the client to the server are as follows:
<itemizedlist>
- <listitem><para>AUTH [mechanism] [initial-response]</para></listitem>
- <listitem><para>CANCEL</para></listitem>
- <listitem><para>BEGIN</para></listitem>
- <listitem><para>DATA <data in hex encoding></para></listitem>
- <listitem><para>ERROR [human-readable error explanation]</para></listitem>
- <listitem><para>NEGOTIATE_UNIX_FD</para></listitem>
- </itemizedlist>
+
<listitem><para>AUTH [mechanism] [initial-response]</para></listitem>
+
<listitem><para>CANCEL</para></listitem>
+
<listitem><para>BEGIN</para></listitem>
+
<listitem><para>DATA <data in hex encoding></para></listitem>
+
<listitem><para>ERROR [human-readable error explanation]</para></listitem>
+
<listitem><para>NEGOTIATE_UNIX_FD</para></listitem>
+ </itemizedlist>
From server to client are as follows:
<itemizedlist>
- <listitem><para>REJECTED <space-separated list of mechanism names></para></listitem>
- <listitem><para>OK <GUID in hex></para></listitem>
- <listitem><para>DATA <data in hex encoding></para></listitem>
- <listitem><para>ERROR</para></listitem>
- <listitem><para>AGREE_UNIX_FD</para></listitem>
- </itemizedlist>
+
<listitem><para>REJECTED <space-separated list of mechanism names></para></listitem>
+
<listitem><para>OK <GUID in hex></para></listitem>
+
<listitem><para>DATA <data in hex encoding></para></listitem>
+
<listitem><para>ERROR</para></listitem>
+
<listitem><para>AGREE_UNIX_FD</para></listitem>
+ </itemizedlist>
</para>
<para>
- Unofficial extensions to the command set must begin with the letters
+ Unofficial extensions to the command set must begin with the letters
"EXTENSION_", to avoid conflicts with future official commands.
For example, "EXTENSION_COM_MYDOMAIN_DO_STUFF".
</para>
socket, and even on operating systems that do not require a byte to be
sent in order to transmit credentials. The text protocol described in
this document begins after the single nul byte. If the first byte
- received from the client is not a nul byte, the server may disconnect
+ received from the client is not a nul byte, the server may disconnect
that client.
</para>
<para>
- A nul byte in any context other than the initial byte is an error;
+ A nul byte in any context other than the initial byte is an error;
the protocol is ASCII-only.
</para>
<para>
- The credentials sent along with the nul byte may be used with the
+ The credentials sent along with the nul byte may be used with the
SASL mechanism EXTERNAL.
</para>
</sect2>
REJECTED.
</para>
<para>
- If authentication succeeds after exchanging DATA commands,
+ If authentication succeeds after exchanging DATA commands,
an OK command must be sent to the client.
</para>
<para>
<sect2 id="auth-command-data">
<title>DATA Command</title>
<para>
- The DATA command may come from either client or server, and simply
- contains a hex-encoded block of data to be interpreted
+ The DATA command may come from either client or server, and simply
+ contains a hex-encoded block of data to be interpreted
according to the SASL mechanism in use.
</para>
<para>
- Some SASL mechanisms support sending an "empty string";
+ Some SASL mechanisms support sending an "empty string";
FIXME we need some way to do this.
</para>
</sect2>
<sect2 id="auth-command-begin">
<title>BEGIN Command</title>
<para>
- The BEGIN command acknowledges that the client has received an
+ The BEGIN command acknowledges that the client has received an
OK command from the server, and that the stream of messages
- is about to begin.
+ is about to begin.
</para>
<para>
The first octet received by the server after the \r\n of the BEGIN
</para><para>
Optionally, the REJECTED command has a space-separated list of
available auth mechanisms as arguments. If a server ever provides
- a list of supported mechanisms, it must provide the same list
- each time it sends a REJECTED message. Clients are free to
+ a list of supported mechanisms, it must provide the same list
+ each time it sends a REJECTED message. Clients are free to
ignore all lists received after the first.
</para>
</sect2>
<para>
If an ERROR is sent, the server or client that sent the
error must continue as if the command causing the ERROR had never been
- received. However, the the server or client receiving the error
- should try something other than whatever caused the error;
+ received. However, the the server or client receiving the error
+ should try something other than whatever caused the error;
if only canceling/rejecting the authentication.
</para>
<para>
</sect2>
<sect2 id="auth-examples">
<title>Authentication examples</title>
-
+
<para>
<figure>
- <title>Example of successful magic cookie authentication</title>
- <programlisting>
+ <title>Example of successful magic cookie authentication</title>
(MAGIC_COOKIE is a made up mechanism)
C: AUTH MAGIC_COOKIE 3138363935333137393635383634
S: OK 1234deadbeef
C: BEGIN
</programlisting>
- </figure>
+ </figure>
<figure>
- <title>Example of finding out mechanisms then picking one</title>
- <programlisting>
+ <title>Example of finding out mechanisms then picking one</title>
C: AUTH
S: REJECTED KERBEROS_V4 SKEY
C: AUTH SKEY 7ab83f32ee
S: OK 1234deadbeef
C: BEGIN
</programlisting>
- </figure>
+ </figure>
<figure>
- <title>Example of client sends unknown command then falls back to regular auth</title>
- <programlisting>
+ <title>Example of client sends unknown command then falls back to regular auth</title>
C: FOOBAR
S: ERROR
C: AUTH MAGIC_COOKIE 3736343435313230333039
S: OK 1234deadbeef
C: BEGIN
</programlisting>
- </figure>
+ </figure>
<figure>
- <title>Example of server doesn't support initial auth mechanism</title>
- <programlisting>
+ <title>Example of server doesn't support initial auth mechanism</title>
C: AUTH MAGIC_COOKIE 3736343435313230333039
S: REJECTED KERBEROS_V4 SKEY
C: AUTH SKEY 7ab83f32ee
S: OK 1234deadbeef
C: BEGIN
</programlisting>
- </figure>
+ </figure>
<figure>
- <title>Example of wrong password or the like followed by successful retry</title>
- <programlisting>
+ <title>Example of wrong password or the like followed by successful retry</title>
C: AUTH MAGIC_COOKIE 3736343435313230333039
S: REJECTED KERBEROS_V4 SKEY
C: AUTH SKEY 7ab83f32ee
S: OK 1234deadbeef
C: BEGIN
</programlisting>
- </figure>
+ </figure>
<figure>
- <title>Example of skey cancelled and restarted</title>
- <programlisting>
+ <title>Example of skey cancelled and restarted</title>
C: AUTH MAGIC_COOKIE 3736343435313230333039
S: REJECTED KERBEROS_V4 SKEY
C: AUTH SKEY 7ab83f32ee
S: OK 1234deadbeef
C: BEGIN
</programlisting>
- </figure>
+ </figure>
<figure>
- <title>Example of successful magic cookie authentication with successful negotiation of Unix FD passing</title>
- <programlisting>
+ <title>Example of successful magic cookie authentication with successful negotiation of Unix FD passing</title>
(MAGIC_COOKIE is a made up mechanism)
C: AUTH MAGIC_COOKIE 3138363935333137393635383634
S: AGREE_UNIX_FD
C: BEGIN
</programlisting>
- </figure>
+ </figure>
<figure>
- <title>Example of successful magic cookie authentication with unsuccessful negotiation of Unix FD passing</title>
- <programlisting>
+ <title>Example of successful magic cookie authentication with unsuccessful negotiation of Unix FD passing</title>
(MAGIC_COOKIE is a made up mechanism)
C: AUTH MAGIC_COOKIE 3138363935333137393635383634
S: ERROR
C: BEGIN
</programlisting>
- </figure>
+ </figure>
</para>
</sect2>
<sect2 id="auth-states">
<title>Authentication state diagrams</title>
-
+
<para>
- This section documents the auth protocol in terms of
- a state machine for the client and the server. This is
+ This section documents the auth protocol in terms of
+ a state machine for the client and the server. This is
probably the most robust way to implement the protocol.
</para>
<sect3 id="auth-states-client">
<title>Client states</title>
-
+
<para>
To more precisely describe the interaction between the
protocol state machine and the authentication mechanisms the
</para>
</listitem>
</itemizedlist>
-
+
Both RESP and CHALL may be empty.
</para>
-
+
<para>
The Client starts by getting an initial response from the
default mechanism and sends AUTH MECH RESP, or AUTH MECH if
returns OK the client starts in state
<emphasis>WaitingForOK</emphasis>.
</para>
-
+
<para>
The client should keep track of available mechanisms and
which it mechanisms it has already attempted. This list is
<sect3 id="auth-states-server">
<title>Server states</title>
-
+
<para>
For the server MECH(RESP) means that the client response
RESP was fed to the the mechanism MECH, which returns one of
</para>
</formalpara>
-
+
<formalpara>
<title><emphasis>WaitingForData</emphasis></title>
<para>
</formalpara>
</sect3>
-
+
</sect2>
<sect2 id="auth-mechanisms">
<title>Authentication mechanisms</title>
The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client
has the ability to read a private file owned by the user being
authenticated. If the client can prove that it has access to a secret
- cookie stored in this file, then the client is authenticated.
- Thus the security of DBUS_COOKIE_SHA1 depends on a secure home
+ cookie stored in this file, then the client is authenticated.
+ Thus the security of DBUS_COOKIE_SHA1 depends on a secure home
directory.
</para>
<para>
<itemizedlist>
<listitem>
<para>
- The client sends the username it would like to authenticate
+ The client sends the username it would like to authenticate
as, hex-encoded.
</para>
</listitem>
</para>
<para>
Cookies are stored in a user's home directory, in the directory
- <filename>~/.dbus-keyrings/</filename>. This directory must
- not be readable or writable by other users. If it is,
- clients and servers must ignore it. The directory
+ <filename>~/.dbus-keyrings/</filename>. This directory must
+ not be readable or writable by other users. If it is,
+ clients and servers must ignore it. The directory
contains cookie files named after the cookie context.
</para>
<para>
- A cookie file contains one cookie per line. Each line
+ A cookie file contains one cookie per line. Each line
has three space-separated fields:
<itemizedlist>
<listitem>
<listitem>
<para>
The cookie itself, a hex-encoded random block of bytes. The cookie
- may be of any length, though obviously security increases
+ may be of any length, though obviously security increases
as the length increases.
</para>
</listitem>
Once the lockfile has been created, the server loads the cookie
file. It should then delete any cookies that are old (the
timeout can be fairly short), or more than a reasonable
- time in the future (so that cookies never accidentally
- become permanent, if the clock was set far into the future
- at some point). If no recent keys remain, the
+ time in the future (so that cookies never accidentally
+ become permanent, if the clock was set far into the future
+ at some point). If no recent keys remain, the
server may generate a new key.
</para>
</listitem>
<listitem>
<para>
- The pruned and possibly added-to cookie file
- must be resaved atomically (using a temporary
+ The pruned and possibly added-to cookie file
+ must be resaved atomically (using a temporary
file which is rename()'d).
</para>
</listitem>
</itemizedlist>
</para>
<para>
- Clients need not lock the file in order to load it,
- because servers are required to save the file atomically.
+ Clients need not lock the file in order to load it,
+ because servers are required to save the file atomically.
</para>
</sect3>
</sect2>
Each value is escaped.
</para>
<para>
- For example:
+ For example:
<programlisting>unix:path=/tmp/dbus-test</programlisting>
Which is the address to a unix socket with the path /tmp/dbus-test.
</para>
</para>
</listitem>
</itemizedlist>
- The set of optionally-escaped bytes is intended to preserve address
+ The set of optionally-escaped bytes is intended to preserve address
readability and convenience.
</para>
those two connections are equivalent post-connection but should have
distinct UUIDs to distinguish the kinds of connection.
</para>
-
+
<para>
The intent of the address UUID feature is to allow a client to avoid
opening multiple identical connections to the same server, by allowing the
</para>
<para>
- Note that the address key is <literal>guid</literal> even though the
+ Note that the address key is <literal>guid</literal> even though the
rest of the API and documentation says "UUID," for historical reasons.
</para>
<para>
- [FIXME clarify if attempting to connect to each is a requirement
+ [FIXME clarify if attempting to connect to each is a requirement
or just a suggestion]
When connecting to a server, multiple server addresses can be
separated by a semi-colon. The library will then try to connect
<programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
</para>
+ <para>
+ Some addresses are <firstterm>connectable</firstterm>. A connectable
+ address is one containing enough information for a client to connect
+ to it. For instance, <literal>tcp:host=127.0.0.1,port=4242</literal>
+ is a connectable address. It is not necessarily possible to listen
+ on every connectable address: for instance, it is not possible to
+ listen on a <literal>unixexec:</literal> address.
+ </para>
+
+ <para>
+ Some addresses are <firstterm>listenable</firstterm>. A listenable
+ address is one containing enough information for a server to listen on
+ it, producing a connectable address (which may differ from the
+ original address). Many listenable addresses are not connectable:
+ for instance, <literal>tcp:host=127.0.0.1</literal>
+ is listenable, but not connectable (because it does not specify
+ a port number).
+ </para>
+
+ <para>
+ Listening on an address that is not connectable will result in a
+ connectable address that is not the same as the listenable address.
+ For instance, listening on <literal>tcp:host=127.0.0.1</literal>
+ might result in the connectable address
+ <literal>tcp:host=127.0.0.1,port=30958</literal>,
+ listening on <literal>unix:tmpdir=/tmp</literal>
+ might result in the connectable address
+ <literal>unix:abstract=/tmp/dbus-U8OSdmf7</literal>, or
+ listening on <literal>unix:runtime=yes</literal>
+ might result in the connectable address
+ <literal>unix:path=/run/user/1234/bus</literal>.
+ </para>
</sect1>
-
+
<sect1 id="transports">
<title>Transports</title>
<para>
[FIXME we need to specify in detail each transport and its possible arguments]
-
- Current transports include: unix domain sockets (including
+
+ Current transports include: unix domain sockets (including
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>
-
+
<sect2 id="transports-unix-domain-sockets">
<title>Unix Domain Sockets</title>
<para>
- Unix domain sockets can be either paths in the file system or on Linux
- kernels, they can be abstract which are similar to paths but
- do not show up in the file system.
+ Unix domain sockets can be either paths in the file system or on Linux
+ kernels, they can be abstract which are similar to paths but
+ do not show up in the file system.
</para>
<para>
- When a socket is opened by the D-Bus library it truncates the path
- name right before the first trailing Nul byte. This is true for both
- normal paths and abstract paths. Note that this is a departure from
- previous versions of D-Bus that would create sockets with a fixed
- length path name. Names which were shorter than the fixed length
- would be padded by Nul bytes.
+ When a socket is opened by the D-Bus library it truncates the path
+ name right before the first trailing Nul byte. This is true for both
+ normal paths and abstract paths. Note that this is a departure from
+ previous versions of D-Bus that would create sockets with a fixed
+ length path name. Names which were shorter than the fixed length
+ would be padded by Nul bytes.
</para>
<para>
Unix domain sockets are not available on Windows.
</para>
+ <para>
+ Unix addresses that specify <literal>path</literal> or
+ <literal>abstract</literal> are both listenable and connectable.
+ Unix addresses that specify <literal>tmpdir</literal> are only
+ listenable: the corresponding connectable address will specify
+ either <literal>path</literal> or <literal>abstract</literal>.
+ Similarly, Unix addresses that specify <literal>runtime</literal>
+ are only listenable, and the corresponding connectable address
+ will specify <literal>path</literal>.
+ </para>
<sect3 id="transports-unix-domain-sockets-addresses">
<title>Server Address Format</title>
- <para>
- Unix domain socket addresses are identified by the "unix:" prefix
+ <para>
+ Unix domain socket addresses are identified by the "unix:" prefix
and support the following key/value pairs:
</para>
<informaltable>
<row>
<entry>abstract</entry>
<entry>(string)</entry>
- <entry>unique string (path) in the abstract namespace. If set, the "path" or "tempdir" key must not be set.</entry>
+ <entry>unique string (path) in the abstract namespace. If set, the "path" or "tmpdir" key must not be set. This key is only supported on platforms with "abstract Unix sockets", of which Linux is the only known example.</entry>
+ </row>
+ <row>
+ <entry>runtime</entry>
+ <entry><literal>yes</literal></entry>
+ <entry>If given, This key can only be used in server addresses, not in client addresses. If set, its value must be <literal>yes</literal>. This is typically used in an address string like <literal>unix:runtime=yes;unix:tmpdir=/tmp</literal> so that there can be a fallback if <literal>XDG_RUNTIME_DIR</literal> is not set.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
+ <para>
+ Exactly one of the keys <literal>path</literal>,
+ <literal>abstract</literal>, <literal>runtime</literal> or
+ <literal>tmpdir</literal> must be provided.
+ </para>
</sect3>
</sect2>
<sect2 id="transports-launchd">
<para>
launchd is not available on Microsoft Windows.
</para>
+ <para>
+ launchd addresses are listenable and connectable.
+ </para>
<sect3 id="transports-launchd-addresses">
<title>Server Address Format</title>
<para>
</tbody>
</tgroup>
</informaltable>
+ <para>
+ The <literal>env</literal> key is required.
+ </para>
</sect3>
</sect2>
<sect2 id="transports-systemd">
<para>
The systemd transport defines no parameter keys.
</para>
+ <para>
+ systemd addresses are listenable, but not connectable. The
+ corresponding connectable address is the <literal>unix</literal>
+ or <literal>tcp</literal> address of the socket.
+ </para>
</sect2>
<sect2 id="transports-tcp-sockets">
<title>TCP Sockets</title>
<para>
The tcp transport provides TCP/IP based connections between clients
- located on the same or different hosts.
+ located on the same or different hosts.
</para>
<para>
- Using tcp transport without any additional secure authentification mechanismus
- over a network is unsecure.
+ Using tcp transport without any additional secure authentification mechanismus
+ over a network is unsecure.
</para>
- <para>
- 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>
+ On Windows and most Unix platforms, the TCP stack is unable to transfer
+ credentials over a TCP connection, so the EXTERNAL authentication
+ mechanism does not work for this transport.
+ </para>
+ <para>
+ All <literal>tcp</literal> addresses are listenable.
+ <literal>tcp</literal> addresses in which both
+ <literal>host</literal> and <literal>port</literal> are
+ specified, and <literal>port</literal> is non-zero,
+ are also connectable.
</para>
<sect3 id="transports-tcp-sockets-addresses">
<title>Server Address Format</title>
- <para>
- TCP/IP socket addresses are identified by the "tcp:" prefix
+ <para>
+ TCP/IP socket addresses are identified by the "tcp:" prefix
and support the following key/value pairs:
</para>
<informaltable>
<row>
<entry>host</entry>
<entry>(string)</entry>
- <entry>dns name or ip address</entry>
+ <entry>DNS name or IP address</entry>
+ </row>
+ <row>
+ <entry>bind</entry>
+ <entry>(string)</entry>
+ <entry>Used in a listenable address to configure the interface
+ on which the server will listen: either the IP address of one of
+ the local machine's interfaces (most commonly <literal>127.0.0.1
+ </literal>), or a DNS name that resolves to one of those IP
+ addresses, or '*' to listen on all interfaces simultaneously.
+ If not specified, the default is the same value as "host".
+ </entry>
</row>
<row>
<entry>port</entry>
<entry>(number)</entry>
- <entry>The tcp port the server will open. A zero value let the server
- choose a free port provided from the underlaying operating system.
- libdbus is able to retrieve the real used port from the server.
+ <entry>The tcp port the server will open. A zero value let the server
+ choose a free port provided from the underlaying operating system.
+ libdbus is able to retrieve the real used port from the server.
</entry>
</row>
<row>
key-value pair and send it over the socket. After that, the
transport behaves like an unsecured tcp transport.
</para>
+ <para>
+ All nonce-tcp addresses are listenable. nonce-tcp addresses in which
+ <literal>host</literal>, <literal>port</literal> and
+ <literal>noncefile</literal> are all specified,
+ and <literal>port</literal> is nonzero, are also connectable.
+ </para>
<sect3 id="transports-nonce-tcp-sockets-addresses">
<title>Server Address Format</title>
- <para>
- Nonce TCP/IP socket addresses uses the "nonce-tcp:" prefix
+ <para>
+ Nonce TCP/IP socket addresses uses the "nonce-tcp:" prefix
and support the following key/value pairs:
</para>
<informaltable>
<row>
<entry>host</entry>
<entry>(string)</entry>
- <entry>dns name or ip address</entry>
+ <entry>DNS name or IP address</entry>
+ </row>
+ <row>
+ <entry>bind</entry>
+ <entry>(string)</entry>
+ <entry>The same as for tcp: addresses
+ </entry>
</row>
<row>
<entry>port</entry>
<entry>(number)</entry>
- <entry>The tcp port the server will open. A zero value let the server
- choose a free port provided from the underlaying operating system.
- libdbus is able to retrieve the real used port from the server.
+ <entry>The tcp port the server will open. A zero value let the server
+ choose a free port provided from the underlaying operating system.
+ libdbus is able to retrieve the real used port from the server.
</entry>
</row>
<row>
<row>
<entry>noncefile</entry>
<entry>(path)</entry>
- <entry>file location containing the secret</entry>
+ <entry>File location containing the secret.
+ This is only meaningful in connectable addresses:
+ a listening D-Bus server that offers this transport
+ will always create a new nonce file.</entry>
</row>
</tbody>
</tgroup>
<para>
Executed subprocesses are not available on Windows.
</para>
+ <para>
+ <literal>unixexec</literal> addresses are connectable, but are not
+ listenable.
+ </para>
<sect3 id="transports-exec-addresses">
<title>Server Address Format</title>
<para>
<para>The autolaunch transport provides a way for dbus clients to autodetect
a running dbus session bus and to autolaunch a session bus if not present.
</para>
+ <para>
+ On Unix, <literal>autolaunch</literal> addresses are connectable,
+ but not listenable.
+ </para>
+ <para>
+ On Windows, <literal>autolaunch</literal> addresses are both
+ connectable and listenable.
+ </para>
+
<sect3 id="meta-transports-autolaunch-addresses">
<title>Server Address Format</title>
<para>
<title>UUIDs</title>
<para>
A working D-Bus implementation uses universally-unique IDs in two places.
- First, each server address has a UUID identifying the address,
+ First, each server address has a UUID identifying the address,
as described in <xref linkend="addresses"/>. Second, each operating
system kernel instance running a D-Bus client or server has a UUID
identifying that kernel, retrieved by invoking the method
of the UUID.
</para>
</sect1>
-
+
<sect1 id="standard-interfaces">
<title>Standard Interfaces</title>
<para>
- See <xref linkend="message-protocol-types-notation"/> for details on
+ See <xref linkend="message-protocol-types-notation"/> for details on
the notation used in this section. There are some standard interfaces
that may be useful across various D-Bus applications.
</para>
<sect2 id="standard-interfaces-peer">
<title><literal>org.freedesktop.DBus.Peer</literal></title>
<para>
- The <literal>org.freedesktop.DBus.Peer</literal> interface
+ The <literal>org.freedesktop.DBus.Peer</literal> interface
has two methods:
<programlisting>
org.freedesktop.DBus.Peer.Ping ()
</para>
<para>
On receipt of the <literal>METHOD_CALL</literal> message
- <literal>org.freedesktop.DBus.Peer.GetMachineId</literal>, an application should
- reply with a <literal>METHOD_RETURN</literal> containing a hex-encoded
+ <literal>org.freedesktop.DBus.Peer.GetMachineId</literal>, an application should
+ reply with a <literal>METHOD_RETURN</literal> containing a hex-encoded
UUID representing the identity of the machine the process is running on.
This UUID must be the same for all processes on a single system at least
- until that system next reboots. It should be the same across reboots
- if possible, but this is not always possible to implement and is not
+ until that system next reboots. It should be the same across reboots
+ if possible, but this is not always possible to implement and is not
guaranteed.
It does not matter which object path a GetMachineId is sent to. The
reference implementation handles this method automatically.
The UUID is intended to be per-instance-of-the-operating-system, so may represent
a virtual machine running on a hypervisor, rather than a physical machine.
Basically if two processes see the same UUID, they should also see the same
- shared memory, UNIX domain sockets, process IDs, and other features that require
+ shared memory, UNIX domain sockets, process IDs, and other features that require
a running OS kernel in common between the processes.
</para>
<para>
- The UUID is often used where other programs might use a hostname. Hostnames
+ The UUID is often used where other programs might use a hostname. Hostnames
can change without rebooting, however, or just be "localhost" - so the UUID
is more robust.
</para>
<sect2 id="standard-interfaces-properties">
<title><literal>org.freedesktop.DBus.Properties</literal></title>
<para>
- Many native APIs will have a concept of object <firstterm>properties</firstterm>
- or <firstterm>attributes</firstterm>. These can be exposed via the
+ Many native APIs will have a concept of object <firstterm>properties</firstterm>
+ or <firstterm>attributes</firstterm>. These can be exposed via the
<literal>org.freedesktop.DBus.Properties</literal> interface.
</para>
<para>
see <xref linkend="standard-interfaces-introspectable"/>.
</para>
<para>
- An empty string may be provided for the interface name; in this case,
- if there are multiple properties on an object with the same name,
- the results are undefined (picking one by according to an arbitrary
- deterministic rule, or returning an error, are the reasonable
+ An empty string may be provided for the interface name; in this case,
+ if there are multiple properties on an object with the same name,
+ the results are undefined (picking one by according to an arbitrary
+ deterministic rule, or returning an error, are the reasonable
possibilities).
</para>
<para>
<sect1 id="introspection-format">
<title>Introspection Data Format</title>
<para>
- As described in <xref linkend="standard-interfaces-introspectable"/>,
- objects may be introspected at runtime, returning an XML string
- that describes the object. The same XML format may be used in
- other contexts as well, for example as an "IDL" for generating
+ As described in <xref linkend="standard-interfaces-introspectable"/>,
+ objects may be introspected at runtime, returning an XML string
+ that describes the object. The same XML format may be used in
+ other contexts as well, for example as an "IDL" for generating
static language bindings.
</para>
<para>
</listitem>
<listitem>
<para>
- If a child <node> has any sub-elements, then they
+ If a child <node> has any sub-elements, then they
must represent a complete introspection of the child.
- If a child <node> is empty, then it may or may
+ If a child <node> is empty, then it may or may
not have sub-elements; the child must be introspected
- in order to find out. The intent is that if an object
+ in order to find out. The intent is that if an object
knows that its children are "fast" to introspect
- it can go ahead and return their information, but
+ it can go ahead and return their information, but
otherwise it can omit it.
</para>
</listitem>
<listitem>
<para>
- The direction element on <arg> may be omitted,
- in which case it defaults to "in" for method calls
- and "out" for signals. Signals only allow "out"
+ The direction element on <arg> may be omitted,
+ in which case it defaults to "in" for method calls
+ and "out" for signals. Signals only allow "out"
so while direction may be specified, it's pointless.
</para>
</listitem>
<listitem>
<para>
- The possible directions are "in" and "out",
+ The possible directions are "in" and "out",
unlike CORBA there is no "inout"
</para>
</listitem>
<listitem>
<para>
- The possible property access flags are
+ The possible property access flags are
"readwrite", "read", and "write"
</para>
</listitem>
<listitem>
<para>
- Multiple interfaces can of course be listed for
+ Multiple interfaces can of course be listed for
one <node>.
</para>
</listitem>
<para>
Method, interface, property, and signal elements may have
"annotations", which are generic key/value pairs of metadata.
- They are similar conceptually to Java's annotations and C# attributes.
+ They are similar conceptually to Java's annotations and C# attributes.
Well-known annotations:
</para>
<informaltable>
<tgroup cols="3">
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Values (separated by ,)</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>org.freedesktop.DBus.Deprecated</entry>
- <entry>true,false</entry>
- <entry>Whether or not the entity is deprecated; defaults to false</entry>
- </row>
- <row>
- <entry>org.freedesktop.DBus.GLib.CSymbol</entry>
- <entry>(string)</entry>
- <entry>The C symbol; may be used for methods and interfaces</entry>
- </row>
- <row>
- <entry>org.freedesktop.DBus.Method.NoReply</entry>
- <entry>true,false</entry>
- <entry>If set, don't expect a reply to the method call; defaults to false.</entry>
- </row>
- <row>
- <entry>org.freedesktop.DBus.Property.EmitsChangedSignal</entry>
- <entry>true,invalidates,false</entry>
- <entry>
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Values (separated by ,)</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>org.freedesktop.DBus.Deprecated</entry>
+ <entry>true,false</entry>
+ <entry>Whether or not the entity is deprecated; defaults to false</entry>
+ </row>
+ <row>
+ <entry>org.freedesktop.DBus.GLib.CSymbol</entry>
+ <entry>(string)</entry>
+ <entry>The C symbol; may be used for methods and interfaces</entry>
+ </row>
+ <row>
+ <entry>org.freedesktop.DBus.Method.NoReply</entry>
+ <entry>true,false</entry>
+ <entry>If set, don't expect a reply to the method call; defaults to false.</entry>
+ </row>
+ <row>
+ <entry>org.freedesktop.DBus.Property.EmitsChangedSignal</entry>
+ <entry>true,invalidates,const,false</entry>
+ <entry>
<para>
If set to <literal>false</literal>, the
<literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
guaranteed to be emitted if the property changes.
</para>
<para>
+ If set to <literal>const</literal> the property never
+ changes value during the lifetime of the object it
+ belongs to, and hence the signal is never emitted for
+ it.
+ </para>
+ <para>
If set to <literal>invalidates</literal> the signal
is emitted but the value is not included in the
signal.
defaults to the value specified in the enclosing
interface element.
</para>
+ <para>
+ This annotation is intended to be used by code
+ generators to implement client-side caching of
+ property values. For all properties for which the
+ annotation is set to <literal>const</literal>,
+ <literal>invalidates</literal> or
+ <literal>true</literal> the client may
+ unconditionally cache the values as the properties
+ don't change or notifications are generated for them
+ if they do.
+ </para>
</entry>
- </row>
- </tbody>
+ </row>
+ </tbody>
</tgroup>
</informaltable>
</sect1>
<sect2 id="message-bus-overview">
<title>Message Bus Overview</title>
<para>
- The message bus accepts connections from one or more applications.
- Once connected, applications can exchange messages with other
+ The message bus accepts connections from one or more applications.
+ Once connected, applications can exchange messages with other
applications that are also connected to the bus.
</para>
<para>
<para>
Each name may have <firstterm>queued owners</firstterm>. When an
application requests a name for a connection and the name is already in
- use, the bus will optionally add the connection to a queue waiting for
+ use, the bus will optionally add the connection to a queue waiting for
the name. If the current owner of the name disconnects or releases
the name, the next connection in the queue will become the new owner.
</para>
<para>
This feature causes the right thing to happen if you start two text
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
+ and the second will be queued as a possible owner of that name. When
the first exits, the second will take over.
</para>
connections to the same bus.
</para>
<para>
- Ownership of a unique name is a prerequisite for interaction with
- the message bus. It logically follows that the unique name is always
- the first name that an application comes to own, and the last
+ Ownership of a unique name is a prerequisite for interaction with
+ the message bus. It logically follows that the unique name is always
+ the first name that an application comes to own, and the last
one that it loses ownership of.
</para>
<para>
<entry>STRING</entry>
<entry>Name to request</entry>
</row>
- <row>
- <entry>1</entry>
- <entry>UINT32</entry>
- <entry>Flags</entry>
- </row>
+ <row>
+ <entry>1</entry>
+ <entry>UINT32</entry>
+ <entry>Flags</entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
<para>
If the method caller is currently the primary owner of the name,
the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and DBUS_NAME_FLAG_DO_NOT_QUEUE
- values are updated with the values from the new RequestName call,
+ values are updated with the values from the new RequestName call,
and nothing further happens.
</para>
</listitem>
invocation has the DBUS_NAME_FLAG_REPLACE_EXISTING flag, then
the caller of RequestName replaces the current primary owner at
the head of the queue and the current primary owner moves to the
- second position in the queue. If the caller of RequestName was
- in the queue previously its flags are updated with the values from
+ second position in the queue. If the caller of RequestName was
+ in the queue previously its flags are updated with the values from
the new RequestName in addition to moving it to the head of the queue.
</para>
</listitem>
automatically replace the new primary owner. In other words,
DBUS_NAME_FLAG_REPLACE_EXISTING is not saved, it is only used at the
time RequestName is called. This is deliberate to avoid an infinite loop
- anytime two applications are both DBUS_NAME_FLAG_ALLOW_REPLACEMENT
+ anytime two applications are both DBUS_NAME_FLAG_ALLOW_REPLACEMENT
and DBUS_NAME_FLAG_REPLACE_EXISTING.
</para>
<para>
</row>
</thead>
<tbody>
- <row>
- <entry>DBUS_NAME_FLAG_ALLOW_REPLACEMENT</entry>
- <entry>0x1</entry>
- <entry>
+ <row>
+ <entry>DBUS_NAME_FLAG_ALLOW_REPLACEMENT</entry>
+ <entry>0x1</entry>
+ <entry>
If an application A specifies this flag and succeeds in
becoming the owner of the name, and another application B
application A as the owner.
</entry>
- </row>
- <row>
- <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
- <entry>0x2</entry>
- <entry>
+ </row>
+ <row>
+ <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
+ <entry>0x2</entry>
+ <entry>
Try to replace the current owner if there is one. If this
flag is not set the application will only become the owner of
the current owner specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT.
</entry>
- </row>
- <row>
- <entry>DBUS_NAME_FLAG_DO_NOT_QUEUE</entry>
- <entry>0x4</entry>
- <entry>
+ </row>
+ <row>
+ <entry>DBUS_NAME_FLAG_DO_NOT_QUEUE</entry>
+ <entry>0x4</entry>
+ <entry>
Without this flag, if an application requests a name that is
already owned, the application will be placed in a queue to
became the name owner.
</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
The return code can be one of the following values:
</row>
</thead>
<tbody>
- <row>
+ <row>
<entry>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</entry>
- <entry>1</entry> <entry>The caller is now the primary owner of
- the name, replacing any previous owner. Either the name had no
- owner before, or the caller specified
- DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner specified
+ <entry>1</entry> <entry>The caller is now the primary owner of
+ the name, replacing any previous owner. Either the name had no
+ owner before, or the caller specified
+ DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner specified
DBUS_NAME_FLAG_ALLOW_REPLACEMENT.</entry>
- </row>
- <row>
- <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
- <entry>2</entry>
+ </row>
+ <row>
+ <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
+ <entry>2</entry>
- <entry>The name already had an owner,
+ <entry>The name already had an owner,
DBUS_NAME_FLAG_DO_NOT_QUEUE was not specified, and either
the current owner did not specify
DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the requesting
application did not specify DBUS_NAME_FLAG_REPLACE_EXISTING.
</entry>
- </row>
- <row>
- <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry> <entry>3</entry>
- <entry>The name already has an owner,
- DBUS_NAME_FLAG_DO_NOT_QUEUE was specified, and either
- DBUS_NAME_FLAG_ALLOW_REPLACEMENT was not specified by the
- current owner, or DBUS_NAME_FLAG_REPLACE_EXISTING was not
- specified by the requesting application.</entry>
- </row>
- <row>
- <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
- <entry>4</entry>
- <entry>The application trying to request ownership of a name is already the owner of it.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
+ </row>
+ <row>
+ <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry> <entry>3</entry>
+ <entry>The name already has an owner,
+ DBUS_NAME_FLAG_DO_NOT_QUEUE was specified, and either
+ DBUS_NAME_FLAG_ALLOW_REPLACEMENT was not specified by the
+ current owner, or DBUS_NAME_FLAG_REPLACE_EXISTING was not
+ specified by the requesting application.</entry>
+ </row>
+ <row>
+ <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
+ <entry>4</entry>
+ <entry>The application trying to request ownership of a name is already the owner of it.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
</para>
</sect3>
</row>
</thead>
<tbody>
- <row>
+ <row>
<entry>DBUS_RELEASE_NAME_REPLY_RELEASED</entry>
<entry>1</entry> <entry>The caller has released his claim on
the given name. Either the caller was the primary owner of
waiting in the queue for the name, or the caller was waiting
in the queue for the name and has now been removed from the
queue.</entry>
- </row>
- <row>
- <entry>DBUS_RELEASE_NAME_REPLY_NON_EXISTENT</entry>
- <entry>2</entry>
- <entry>The given name does not exist on this bus.</entry>
- </row>
- <row>
- <entry>DBUS_RELEASE_NAME_REPLY_NOT_OWNER</entry>
- <entry>3</entry>
- <entry>The caller was not the primary owner of this name,
+ </row>
+ <row>
+ <entry>DBUS_RELEASE_NAME_REPLY_NON_EXISTENT</entry>
+ <entry>2</entry>
+ <entry>The given name does not exist on this bus.</entry>
+ </row>
+ <row>
+ <entry>DBUS_RELEASE_NAME_REPLY_NOT_OWNER</entry>
+ <entry>3</entry>
+ <entry>The caller was not the primary owner of this name,
and was also not waiting in the queue to own this name.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
</para>
</sect3>
<literal>DESTINATION</literal> field is absent, it is considered to
be a <firstterm>broadcast signal</firstterm>, and is sent to all
applications with <firstterm>message matching rules</firstterm> that
- match the message. Most signal messages are broadcasts.
+ match the message. Most signal messages are broadcasts, and
+ no other message types currently defined in this specification
+ may be broadcast.
</para>
<para>
<para>
Message bus implementations may impose a security policy which
prevents certain messages from being sent or received.
- When a message cannot be sent or received due to a security
+ When a method call message cannot be sent or received due to a security
policy, the message bus should send an error reply, unless the
original message had the <literal>NO_REPLY</literal> flag.
</para>
adding the same rule with the <literal>eavesdrop</literal> match
omitted.
</para>
+
+ <para>
+ Eavesdropping interacts poorly with buses with non-trivial
+ access control restrictions. The
+ <xref linkend="bus-messages-become-monitor"/> method provides
+ an alternative way to monitor buses.
+ </para>
</sect3>
<sect3 id="message-bus-routing-match-rules">
<title>Match Rules</title>
<para>
- An important part of the message bus routing protocol is match
+ An important part of the message bus routing protocol is match
rules. Match rules describe the messages that should be sent to a
client, based on the contents of the message. Broadcast signals
are only sent to clients which have a suitable match rule: this
if the security policy of the message bus allows it.
</para>
<para>
- Match rules are added using the AddMatch bus method
+ Match rules are added using the AddMatch bus method
(see <xref linkend="bus-messages-add-match"/>). Rules are
- specified as a string of comma separated key/value pairs.
- Excluding a key from the rule indicates a wildcard match.
- For instance excluding the the member from a match rule but
+ specified as a string of comma separated key/value pairs.
+ Excluding a key from the rule indicates a wildcard match.
+ For instance excluding the the member from a match rule but
adding a sender would let all messages from that sender through.
- An example of a complete rule would be
+ An example of a complete rule would be
"type='signal',sender='org.freedesktop.DBus',interface='org.freedesktop.DBus',member='Foo',path='/bar/foo',destination=':452345.34',arg2='bar'"
</para>
<para>
- The following table describes the keys that can be used to create
+ Within single quotes (ASCII apostrophe, U+0027), a backslash
+ (U+005C) represents itself, and an apostrophe ends the quoted
+ section. Outside single quotes, \' (backslash, apostrophe)
+ represents an apostrophe, and any backslash not followed by
+ an apostrophe represents itself. For instance, the match rules
+ <literal>arg0=''\''',arg1='\',arg2=',',arg3='\\'</literal> and
+ <literal>arg0=\',arg1=\,arg2=',',arg3=\\</literal>
+ both match messages where the arguments are a 1-character string
+ containing an apostrophe, a 1-character string containing a
+ backslash, a 1-character string containing a comma, and a
+ 2-character string containing two backslashes<footnote>
+ <para>
+ This idiosyncratic quoting style is based on the rules for
+ escaping items to appear inside single-quoted strings
+ in POSIX <literal>/bin/sh</literal>, but please
+ note that backslashes that are not inside single quotes have
+ different behaviour. This syntax does not offer any way to
+ represent an apostrophe inside single quotes (it is necessary
+ to leave the single-quoted section, backslash-escape the
+ apostrophe and re-enter single quotes), or to represent a
+ comma outside single quotes (it is necessary to wrap it in
+ a single-quoted section).
+ </para>
+ </footnote>.
+ </para>
+ <para>
+ The following table describes the keys that can be used to create
a match rule.
<informaltable>
<tgroup cols="3">
<entry>An interface name (see <xref linkend="message-protocol-names-interface"/>)</entry>
<entry>Match messages sent over or to a particular interface. An example of an
interface match is interface='org.freedesktop.Hal.Manager'.
- If a message omits the interface header, it must not match any rule
+ If a message omits the interface header, it must not match any rule
that specifies this key.</entry>
</row>
<row>
<row>
<entry><literal>arg[0, 1, 2, 3, ...]</literal></entry>
<entry>Any string</entry>
- <entry>Arg matches are special and are used for further restricting the
+ <entry>Arg matches are special and are used for further restricting the
match based on the arguments in the body of a message. Only arguments of type
- STRING can be matched in this way. An example of an argument match
- would be arg3='Foo'. Only argument indexes from 0 to 63 should be
+ STRING can be matched in this way. An example of an argument match
+ would be arg3='Foo'. Only argument indexes from 0 to 63 should be
accepted.</entry>
</row>
<row>
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
+ the owner of that name will provide, and what interfaces those
objects will have.
</para>
<para>
and <literal>Exec</literal> (the command to be executed).
<figure>
- <title>Example service description file</title>
- <programlisting>
+ <title>Example service description file</title>
# Sample service description file
[D-BUS Service]
Name=com.example.ConfigurationDatabase
Exec=/usr/bin/sample-configd
</programlisting>
- </figure>
+ </figure>
</para>
<para>
only by name.
</para>
<para>
- Contrast this with a per-display scope. To achieve that, we would
+ Contrast this with a per-display scope. To achieve that, we would
want a single bus spanning all sessions using a given display.
- So we might set a <literal>_DBUS_DISPLAY_BUS_ADDRESS</literal>
+ So we might set a <literal>_DBUS_DISPLAY_BUS_ADDRESS</literal>
property on screen 0 of the display, pointing to this bus.
</para>
</sect3>
<sect2 id="message-bus-types">
<title>Well-known Message Bus Instances</title>
<para>
- Two standard message bus instances are defined here, along with how
+ Two standard message bus instances are defined here, along with how
to locate them and where their service files live.
</para>
<sect3 id="message-bus-types-login">
session may interact with one another using this message bus.
</para>
<para>
- The address of the login session message bus is given
- in the <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment
- variable. If that variable is not set, applications may
- also try to read the address from the X Window System root
+ The address of the login session message bus is given
+ in the <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment
+ variable. If that variable is not set, applications may
+ also try to read the address from the X Window System root
window property <literal>_DBUS_SESSION_BUS_ADDRESS</literal>.
The root window property must have type <literal>STRING</literal>.
- The environment variable should have precedence over the
+ The environment variable should have precedence over the
root window property.
</para>
<para>The address of the login session message bus is given in the
<para>
A computer may have a <firstterm>system message bus</firstterm>,
accessible to all applications on the system. This message bus may be
- used to broadcast system events, such as adding new hardware devices,
+ used to broadcast system events, such as adding new hardware devices,
changes in the printer queue, and so forth.
</para>
<para>
- The address of the system message bus is given
- in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment
- variable. If that variable is not set, applications should try
+ The address of the system message bus is given
+ in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment
+ variable. If that variable is not set, applications should try
to connect to the well-known address
<literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
<footnote>
<para>
- The D-Bus reference implementation actually honors the
- <literal>$(localstatedir)</literal> configure option
+ The D-Bus reference implementation actually honors the
+ <literal>$(localstatedir)</literal> configure option
for this address, on both client and server side.
</para>
</footnote>
</para>
<para>
There is no corresponding "disconnect" request; if a client wishes to
- disconnect from the bus, it simply closes the socket (or other
+ disconnect from the bus, it simply closes the socket (or other
communication channel).
</para>
</sect3>
<entry>STRING</entry>
<entry>Name with a new owner</entry>
</row>
- <row>
- <entry>1</entry>
- <entry>STRING</entry>
- <entry>Old owner or empty string if none</entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>STRING</entry>
- <entry>New owner or empty string if none</entry>
- </row>
+ <row>
+ <entry>1</entry>
+ <entry>STRING</entry>
+ <entry>Old owner or empty string if none</entry>
+ </row>
+ <row>
+ <entry>2</entry>
+ <entry>STRING</entry>
+ <entry>New owner or empty string if none</entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
This signal indicates that the owner of a name has changed.
- It's also the signal to use to detect the appearance of
+ It's also the signal to use to detect the appearance of
new names on the bus.
</para>
</sect3>
<entry>STRING</entry>
<entry>Name of the service to start</entry>
</row>
- <row>
- <entry>1</entry>
- <entry>UINT32</entry>
- <entry>Flags (currently not used)</entry>
- </row>
+ <row>
+ <entry>1</entry>
+ <entry>UINT32</entry>
+ <entry>Flags (currently not used)</entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
</row>
</thead>
<tbody>
- <row>
+ <row>
<entry>DBUS_START_REPLY_SUCCESS</entry>
<entry>1</entry>
<entry>The service was successfully started.</entry>
this concept. On Unix, this is the process ID defined by
POSIX.</entry>
</row>
+ <row>
+ <entry>WindowsSID</entry>
+ <entry>STRING</entry>
+ <entry>The Windows security identifier in its string form,
+ e.g. "S-1-5-21-3623811015-3361044348-30300820-1013" for
+ a domain or local computer user or "S-1-5-18" for the
+ LOCAL_SYSTEM user</entry>
+ </row>
+
+ <row>
+ <entry>LinuxSecurityLabel</entry>
+ <entry>ARRAY of BYTE</entry>
+ <entry>
+ <para>On Linux systems, the security label that would result
+ from the SO_PEERSEC getsockopt call. The array contains
+ the non-zero bytes of the security label in an unspecified
+ ASCII-compatible encoding<footnote>
+ <para>It could be ASCII or UTF-8, but could also be
+ ISO Latin-1 or any other encoding.</para>
+ </footnote>, followed by a single zero byte.</para>
+ <para>
+ For example, the SELinux context
+ <literal>system_u:system_r:init_t:s0</literal>
+ (a string of length 27) would be encoded as 28 bytes
+ ending with ':', 's', '0', '\x00'.<footnote>
+ <para>Note that this is not the same as the older
+ GetConnectionSELinuxContext method, which does
+ not append the zero byte. Always appending the
+ zero byte allows callers to read the string
+ from the message payload without copying.</para>
+ </footnote>
+ </para>
+ <para>
+ On SELinux systems this is the SELinux context, as output
+ by <literal>ps -Z</literal> or <literal>ls -Z</literal>.
+ Typical values might include
+ <literal>system_u:system_r:init_t:s0</literal>,
+ <literal>unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023</literal>,
+ or
+ <literal>unconfined_u:unconfined_r:chrome_sandbox_t:s0-s0:c0.c1023</literal>.
+ </para>
+ <para>
+ On Smack systems, this is the Smack label.
+ Typical values might include
+ <literal>_</literal>, <literal>*</literal>,
+ <literal>User</literal>, <literal>System</literal>
+ or <literal>System::Shared</literal>.
+ </para>
+ <para>
+ On AppArmor systems, this is the AppArmor context,
+ a composite string encoding the AppArmor label (one or more
+ profiles) and the enforcement mode.
+ Typical values might include <literal>unconfined</literal>,
+ <literal>/usr/bin/firefox (enforce)</literal> or
+ <literal>user1 (complain)</literal>.
+ </para>
+ </entry>
+ </row>
+
</tbody>
</tgroup>
</informaltable>
</tbody>
</tgroup>
</informaltable>
- Adds a match rule to match messages going through the message bus (see <xref linkend='message-bus-routing-match-rules'/>).
- If the bus does not have enough resources the <literal>org.freedesktop.DBus.Error.OOM</literal>
- error is returned.
+ Adds a match rule to match messages going through the message bus (see <xref linkend='message-bus-routing-match-rules'/>).
+ If the bus does not have enough resources the <literal>org.freedesktop.DBus.Error.OOM</literal>
+ error is returned.
</para>
</sect3>
<sect3 id="bus-messages-remove-match">
</tbody>
</tgroup>
</informaltable>
- Removes the first rule that matches (see <xref linkend='message-bus-routing-match-rules'/>).
- If the rule is not found the <literal>org.freedesktop.DBus.Error.MatchRuleNotFound</literal>
- error is returned.
+ Removes the first rule that matches (see <xref linkend='message-bus-routing-match-rules'/>).
+ If the rule is not found the <literal>org.freedesktop.DBus.Error.MatchRuleNotFound</literal>
+ error is returned.
</para>
</sect3>
</tbody>
</tgroup>
</informaltable>
- Gets the unique ID of the bus. The unique ID here is shared among all addresses the
- bus daemon is listening on (TCP, UNIX domain socket, etc.) and its format is described in
- <xref linkend="uuids"/>. Each address the bus is listening on also has its own unique
+ Gets the unique ID of the bus. The unique ID here is shared among all addresses the
+ bus daemon is listening on (TCP, UNIX domain socket, etc.) and its format is described in
+ <xref linkend="uuids"/>. Each address the bus is listening on also has its own unique
ID, as described in <xref linkend="addresses"/>. The per-bus and per-address IDs are not related.
There is also a per-machine ID, described in <xref linkend="standard-interfaces-peer"/> and returned
by org.freedesktop.DBus.Peer.GetMachineId().
</para>
</sect3>
+ <sect3 id="bus-messages-become-monitor">
+ <title><literal>org.freedesktop.DBus.Monitoring.BecomeMonitor</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ BecomeMonitor (in ARRAY of STRING rule, in UINT32 flags)
+ </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>ARRAY of STRING</entry>
+ <entry>Match rules to add to the connection</entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>UINT32</entry>
+ <entry>Not used, must be 0</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ <para>
+ Converts the connection into a <emphasis>monitor
+ connection</emphasis> which can be used as a debugging/monitoring
+ tool. Only a user who is privileged on this
+ bus (by some implementation-specific definition) may create
+ monitor connections<footnote>
+ <para>
+ In the reference implementation,
+ the default configuration is that each user (identified by
+ numeric user ID) may monitor their own session bus,
+ and the root user (user ID zero) may monitor the
+ system bus.
+ </para>
+ </footnote>.
+ </para>
+
+ <para>
+ Monitor connections lose all their bus names, including the unique
+ connection name, and all their match rules. Sending messages on a
+ monitor connection is not allowed: applications should use a private
+ connection for monitoring.
+ </para>
+
+ <para>
+ Monitor connections may receive all messages, even messages that
+ should only have gone to some other connection ("eavesdropping").
+ The first argument is a list of match rules, which replace any
+ match rules that were previously active for this connection.
+ These match rules are always treated as if they contained the
+ special <literal>eavesdrop='true'</literal> member.
+ </para>
+
+ <para>
+ As a special case, an empty list of match rules (which would
+ otherwise match nothing, making the monitor useless) is treated
+ as a shorthand for matching all messages.
+ </para>
+
+ <para>
+ The second argument might be used for flags to influence the
+ behaviour of the monitor connection in future D-Bus versions.
+ </para>
+
+ <para>
+ Message bus implementations should attempt to minimize the
+ side-effects of monitoring — in particular, unlike ordinary
+ eavesdropping, monitoring the system bus does not require the
+ access control rules to be relaxed, which would change the set
+ of messages that can be delivered to their (non-monitor)
+ destinations. However, it is unavoidable that monitoring
+ will increase the message bus's resource consumption. In
+ edge cases where there was barely enough time or memory without
+ monitoring, this might result in message deliveries failing
+ when they would otherwise have succeeded.
+ </para>
+ </sect3>
+
</sect2>
</sect1>
name if the message bus has associated the application's connection
with the name. Names may also have <firstterm>queued
owners</firstterm> (see <xref linkend="term-queued-owner"/>).
- The bus assigns a unique name to each connection,
- see <xref linkend="term-unique-name"/>. Other names
- can be thought of as "well-known names" and are
+ The bus assigns a unique name to each connection,
+ see <xref linkend="term-unique-name"/>. Other names
+ can be thought of as "well-known names" and are
used to find applications that offer specific functionality.
</para>
</para>
</glossdef>
</glossentry>
-
+
<glossentry id="term-message"><glossterm>Message</glossterm>
<glossdef>
<para>
<glossentry id="term-message-bus"><glossterm>Message Bus</glossterm>
<glossdef>
<para>
- The message bus is a special application that forwards
+ The message bus is a special application that forwards
or routes messages between a group of applications
- connected to the message bus. It also manages
+ connected to the message bus. It also manages
<firstterm>names</firstterm> used for routing
messages.
</para>
<glossentry id="term-name"><glossterm>Name</glossterm>
<glossdef>
<para>
- See <xref linkend="term-bus-name"/>. "Name" may
+ See <xref linkend="term-bus-name"/>. "Name" may
also be used to refer to some of the other names
in D-Bus, such as interface names.
</para>
<glossentry id="one-to-one"><glossterm>One-to-One</glossterm>
<glossdef>
- <para>
An application talking directly to another application, without going
through a message bus. One-to-one connections may be "peer to peer" or
"client to server." The D-Bus protocol has no concept of client
Services normally guarantee some particular features, for example they
may guarantee that they will request a specific name such as
"com.example.Screensaver", have a singleton object
- "/com/example/Application", and that object will implement the
+ "/com/example/Application", and that object will implement the
interface "com.example.Screensaver.Control".
</para>
</glossdef>
projects / platform / upstream / dbus.git / blobdiff