<date>(not yet released)</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>
<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><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><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><literal>INT16</literal></entry>
<entry>110 (ASCII 'n')</entry>
<entry>16-bit signed integer</entry>
<entry><literal>UINT16</literal></entry>
<entry>113 (ASCII 'q')</entry>
<entry>16-bit unsigned integer</entry>
- </row><row>
+ </row><row>
<entry><literal>INT32</literal></entry>
<entry>105 (ASCII 'i')</entry>
<entry>32-bit signed integer</entry>
<entry><literal>UINT32</literal></entry>
<entry>117 (ASCII 'u')</entry>
<entry>32-bit unsigned integer</entry>
- </row><row>
+ </row><row>
<entry><literal>INT64</literal></entry>
<entry>120 (ASCII 'x')</entry>
<entry>64-bit signed integer</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>
</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>
</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>
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
<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>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.
+ 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.
+ 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>
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,false</entry>
+ <entry>
<para>
If set to <literal>false</literal>, the
<literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
interface element.
</para>
</entry>
- </row>
- </tbody>
+ </row>
+ </tbody>
</tgroup>
</informaltable>
</sect1>
<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>
</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>
<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
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>
<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>
<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>
</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.
+ 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">
</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.
+ If the rule is not found the <literal>org.freedesktop.DBus.Error.MatchRuleNotFound</literal>
+ error is returned.
</para>
</sect3>
<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 / thirdparty / dbus.git / commitdiff
