<?xml version="1.0" standalone="no" ?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
[
]>
<article id="index">
<articleinfo>
<title>D-Bus Specification</title>
- <releaseinfo>Version 0.19</releaseinfo>
- <date>2012-02-21</date>
+ <releaseinfo>Version 0.22</releaseinfo>
+ <date>(not yet released)</date>
<authorgroup>
<author>
<firstname>Havoc</firstname>
</authorgroup>
<revhistory>
<revision>
- <revnumber>current</revnumber>
- <date><ulink url='http://cgit.freedesktop.org/dbus/dbus/log/doc/dbus-specification.xml'>commit log</ulink></date>
+ <revnumber>0.22</revnumber>
+ <date>not yet released (<ulink url='http://cgit.freedesktop.org/dbus/dbus/log/doc/dbus-specification.xml'>commit log</ulink>)</date>
<authorinitials></authorinitials>
<revremark></revremark>
</revision>
<revision>
+ <revnumber>0.21</revnumber>
+ <date>2013-04-25</date>
+ <authorinitials>smcv</authorinitials>
+ <revremark>allow Unicode noncharacters in UTF-8 (Unicode
+ Corrigendum #9)</revremark>
+ </revision>
+ <revision>
+ <revnumber>0.20</revnumber>
+ <date>22 February 2013</date>
+ <authorinitials>smcv, walters</authorinitials>
+ <revremark>reorganise for clarity, remove false claims about
+ basic types, mention /o/fd/DBus</revremark>
+ </revision>
+ <revision>
<revnumber>0.19</revnumber>
<date>20 February 2012</date>
<authorinitials>smcv/lp</authorinitials>
are basic types with a variable length. The value of any string-like
type is conceptually 0 or more Unicode codepoints encoded in UTF-8,
none of which may be U+0000. The UTF-8 text must be validated
- strictly: in particular, it must not contain overlong sequences,
- noncharacters such as U+FFFE, or codepoints above U+10FFFF.
+ strictly: in particular, it must not contain overlong sequences
+ or codepoints above U+10FFFF.
+ </para>
+
+ <para>
+ Since D-Bus Specification version 0.21, in accordance with Unicode
+ Corrigendum #9, the "noncharacters" U+FDD0..U+FDEF, U+nFFFE and
+ U+nFFFF are allowed in UTF-8 strings (but note that older versions of
+ D-Bus rejected these noncharacters).
</para>
<para>
</para>
<para>
+ Unlike a message signature, the variant signature can
+ contain only a single complete type. So "i", "ai"
+ or "(ii)" is OK, but "ii" is not. Use of variants may not
+ cause a total message depth to be larger than 64, including
+ other container types such as structures.
+ </para>
+
+ <para>
A <literal>DICT_ENTRY</literal> works exactly like a struct, but rather
than parentheses it uses curly braces, and it has more restrictions.
The restrictions are: it occurs only as an array element type; it has
not be left uninitialized (it can't contain garbage), and more padding
than required must not be used.
</para>
+
+ <para>
+ As an exception to natural alignment, <literal>STRUCT</literal> and
+ <literal>DICT_ENTRY</literal> values are always aligned to an 8-byte
+ boundary, regardless of the alignments of their contents.
+ </para>
</sect2>
<sect2>
<sect2>
<title>Marshalling containers</title>
- <para>... to be written ...</para>
+ <para>
+ Arrays are marshalled as a <literal>UINT32</literal>
+ <varname>n</varname> giving the length of the array data in bytes,
+ followed by alignment padding to the alignment boundary of the array
+ element type, followed by the <varname>n</varname> bytes of the
+ array elements marshalled in sequence. <varname>n</varname> does not
+ include the padding after the length, or any padding after the
+ last element.
+ </para>
+
+ <para>
+ For instance, if the current position in the message is a multiple
+ of 8 bytes and the byte-order is big-endian, an array containing only
+ the 64-bit integer 5 would be marshalled as:
+
+ <screen>
+00 00 00 08 <lineannotation>8 bytes of data</lineannotation>
+00 00 00 00 <lineannotation>padding to 8-byte boundary</lineannotation>
+00 00 00 00 00 00 00 05 <lineannotation>first element = 5</lineannotation>
+ </screen>
+ </para>
+
+ <para>
+ Arrays have a maximum length defined to be 2 to the 26th power or
+ 67108864. Implementations must not send or accept arrays exceeding this
+ length.
+ </para>
+
+ <para>
+ Structs and dict entries are marshalled in the same way as their
+ contents, but their alignment is always to an 8-byte boundary,
+ even if their contents would normally be less strictly aligned.
+ </para>
+
+ <para>
+ Variants are marshalled as the <literal>SIGNATURE</literal> of
+ the contents (which must be a single complete type), followed by a
+ marshalled value with the type given by that signature. The
+ variant has the same 1-byte alignment as the signature, which means
+ that alignment padding before a variant is never needed.
+ Use of variants may not cause a total message depth to be larger
+ than 64, including other container types such as structures.
+ </para>
</sect2>
<sect2>
<entry><literal>ARRAY</literal></entry>
<entry>
A <literal>UINT32</literal> giving the length of the array data in bytes, followed by
- alignment padding to the alignment boundary of the array element type,
- followed by each array element. The array length is from the
- end of the alignment padding to the end of the last element,
- i.e. it does not include the padding after the length,
- or any padding after the last element.
- Arrays have a maximum length defined to be 2 to the 26th power or
- 67108864. Implementations must not send or accept arrays exceeding this
- length.
+ alignment padding to the alignment boundary of the array element type,
+ followed by each array element.
</entry>
<entry>
4 (for the length)
</row><row>
<entry><literal>VARIANT</literal></entry>
<entry>
- A variant type has a marshaled
- <literal>SIGNATURE</literal> followed by a marshaled
- value with the type given in the signature. Unlike
- a message signature, the variant signature can
- contain only a single complete type. So "i", "ai"
- or "(ii)" is OK, but "ii" is not. Use of variants may not
- cause a total message depth to be larger than 64, including
- other container types such as structures.
+ The marshaled <literal>SIGNATURE</literal> of a single
+ complete type, followed by a marshaled value with the type
+ given in the signature.
</entry>
<entry>
1 (alignment of the signature)
</listitem>
<listitem>
<para>
- Receive REJECT [mechs] → send AUTH [next mech],
+ Receive REJECTED [mechs] → send AUTH [next mech],
goto <emphasis>WaitingForData</emphasis> or
<emphasis>WaitingForOK</emphasis>
</para>
<itemizedlist>
<listitem>
<para>
- Receive REJECT [mechs] → send AUTH [next mech],
+ Receive REJECTED [mechs] → send AUTH [next mech],
goto <emphasis>WaitingForData</emphasis> or
<emphasis>WaitingForOK</emphasis>
</para>
<listitem>
<para>
- REJECT means that the client failed to authenticate or
+ REJECTED means that the client failed to authenticate or
there was an error in RESP.
</para>
</listitem>
</member>
<member>
- MECH(RESP) returns REJECT → send REJECTED
+ MECH(RESP) returns REJECTED → send REJECTED
[mechs], goto
<emphasis>WaitingForAuth</emphasis>
</member>
</member>
<member>
- MECH(RESP) returns REJECT → send REJECTED
+ MECH(RESP) returns REJECTED → send REJECTED
[mechs], goto
<emphasis>WaitingForAuth</emphasis>
</member>
<programlisting>
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
- <node name="/org/freedesktop/sample_object">
- <interface name="org.freedesktop.SampleInterface">
+ <node name="/com/example/sample_object">
+ <interface name="com.example.SampleInterface">
<method name="Frobate">
<arg name="foo" type="i" direction="in"/>
<arg name="bar" type="s" direction="out"/>
unique-for-the-lifetime-of-the-bus name automatically assigned.
Applications may request additional names for a connection. Additional
names are usually "well-known names" such as
- "org.freedesktop.TextEditor". When a name is bound to a connection,
+ "com.example.TextEditor". When a name is bound to a connection,
that connection is said to <firstterm>own</firstterm> the name.
</para>
<para>
- The bus itself owns a special name, <literal>org.freedesktop.DBus</literal>.
- This name routes messages to the bus, allowing applications to make
- administrative requests. For example, applications can ask the bus
- to assign a name to a connection.
+ The bus itself owns a special name,
+ <literal>org.freedesktop.DBus</literal>, with an object
+ located at <literal>/org/freedesktop/DBus</literal> that
+ implements the <literal>org.freedesktop.DBus</literal>
+ interface. This service allows applications to make
+ administrative requests of the bus itself. For example,
+ applications can ask the bus to assign a name to a connection.
</para>
<para>
Each name may have <firstterm>queued owners</firstterm>. When an
<para>
This feature causes the right thing to happen if you start two text
- editors for example; the first one may request "org.freedesktop.TextEditor",
+ editors for example; the first one may request "com.example.TextEditor",
and the second will be queued as a possible owner of that name. When
the first exits, the second will take over.
</para>
</para>
<para>
The following table describes the keys that can be used to create
- a match rule:
- The following table summarizes the D-Bus types.
+ a match rule.
<informaltable>
<tgroup cols="3">
<thead>
<para>
With D-Bus, starting a service is normally done by name. That is,
applications ask the message bus to start some program that will own a
- well-known name, such as <literal>org.freedesktop.TextEditor</literal>.
- This implies a contract documented along with the name
- <literal>org.freedesktop.TextEditor</literal> for which objects
+ well-known name, such as <literal>com.example.TextEditor</literal>.
+ This implies a contract documented along with the name
+ <literal>com.example.TextEditor</literal> for which object
the owner of that name will provide, and what interfaces those
objects will have.
</para>
<programlisting>
# Sample service description file
[D-BUS Service]
- Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf;
- Exec=/usr/libexec/gconfd-2
+ Name=com.example.ConfigurationDatabase
+ Exec=/usr/bin/sample-configd
</programlisting>
</figure>
</para>
</para>
</sect3>
+ <sect3 id="bus-messages-get-connection-credentials">
+ <title><literal>org.freedesktop.DBus.GetConnectionCredentials</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ DICT<STRING,VARIANT> GetConnectionCredentials (in STRING bus_name)
+ </programlisting>
+ Message arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>STRING</entry>
+ <entry>Unique or well-known bus name of the connection to
+ query, such as <literal>:12.34</literal> or
+ <literal>com.example.tea</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ Reply arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>DICT<STRING,VARIANT></entry>
+ <entry>Credentials</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ <para>
+ Returns as many credentials as possible for the process connected to
+ the server. If unable to determine certain credentials (for instance,
+ because the process is not on the same machine as the bus daemon,
+ or because this version of the bus daemon does not support a
+ particular security framework), or if the values of those credentials
+ cannot be represented as documented here, then those credentials
+ are omitted.
+ </para>
+
+ <para>
+ Keys in the returned dictionary not containing "." are defined
+ by this specification. Bus daemon implementors supporting
+ credentials frameworks not mentioned in this document should either
+ contribute patches to this specification, or use keys containing
+ "." and starting with a reversed domain name.
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Key</entry>
+ <entry>Value type</entry>
+ <entry>Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>UnixUserID</entry>
+ <entry>UINT32</entry>
+ <entry>The numeric Unix user ID, as defined by POSIX</entry>
+ </row>
+ <row>
+ <entry>ProcessID</entry>
+ <entry>UINT32</entry>
+ <entry>The numeric process ID, on platforms that have
+ this concept. On Unix, this is the process ID defined by
+ POSIX.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ <para>
+ This method was added in D-Bus 1.7 to reduce the round-trips
+ required to list a process's credentials. In older versions, calling
+ this method will fail: applications should recover by using the
+ separate methods such as
+ <xref linkend="bus-messages-get-connection-unix-user"/>
+ instead.
+ </para>
+ </sect3>
+
+ <sect3 id="bus-messages-get-adt-audit-session-data">
+ <title><literal>org.freedesktop.DBus.GetAdtAuditSessionData</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ ARRAY of BYTE GetAdtAuditSessionData (in STRING bus_name)
+ </programlisting>
+ Message arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>STRING</entry>
+ <entry>Unique or well-known bus name of the connection to
+ query, such as <literal>:12.34</literal> or
+ <literal>com.example.tea</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ Reply arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>ARRAY of BYTE</entry>
+ <entry>auditing data as returned by
+ adt_export_session_data()</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ Returns auditing data used by Solaris ADT, in an unspecified
+ binary format. If you know what this means, please contribute
+ documentation via the D-Bus bug tracking system.
+ This method is on the core DBus interface for historical reasons;
+ the same information should be made available via
+ <xref linkend="bus-messages-get-connection-credentials"/>
+ in future.
+ </para>
+ </sect3>
+
+ <sect3 id="bus-messages-get-connection-selinux-security-context">
+ <title><literal>org.freedesktop.DBus.GetConnectionSELinuxSecurityContext</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ ARRAY of BYTE GetConnectionSELinuxSecurityContext (in STRING bus_name)
+ </programlisting>
+ Message arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>STRING</entry>
+ <entry>Unique or well-known bus name of the connection to
+ query, such as <literal>:12.34</literal> or
+ <literal>com.example.tea</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ Reply arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>ARRAY of BYTE</entry>
+ <entry>some sort of string of bytes, not necessarily UTF-8,
+ not including '\0'</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ Returns the security context used by SELinux, in an unspecified
+ format. If you know what this means, please contribute
+ documentation via the D-Bus bug tracking system.
+ This method is on the core DBus interface for historical reasons;
+ the same information should be made available via
+ <xref linkend="bus-messages-get-connection-credentials"/>
+ in future.
+ </para>
+ </sect3>
+
+
<sect3 id="bus-messages-add-match">
<title><literal>org.freedesktop.DBus.AddMatch</literal></title>
<para>
A service is an executable that can be launched by the bus daemon.
Services normally guarantee some particular features, for example they
may guarantee that they will request a specific name such as
- "org.freedesktop.Screensaver", have a singleton object
- "/org/freedesktop/Application", and that object will implement the
- interface "org.freedesktop.ScreensaverControl".
+ "com.example.Screensaver", have a singleton object
+ "/com/example/Application", and that object will implement the
+ interface "com.example.Screensaver.Control".
</para>
</glossdef>
</glossentry>
projects / platform / upstream / dbus.git / blobdiff