<?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>
</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