[PATCH 1/3] docs: document all of the org.freedesktop.DBus methods together
Tom Gundersen
teg at jklm.no
Tue Apr 25 12:53:43 UTC 2017
This patch simply moves RequestName, ReleaseName and ListNameOwners
to the "Message Bus Messages" section. This keeps the documentation
of the org.freedesktop.DBus interface in one place for easier reading.
Only very minor rewording was done, but no substantive changes.
Signed-off-by: Tom Gundersen <teg at jklm.no>
---
doc/dbus-specification.xml | 2257 ++++++++++++++++++++++----------------------
1 file changed, 1125 insertions(+), 1132 deletions(-)
diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 0f0ca5ae..7759de36 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -4253,1036 +4253,645 @@
name. These names can be released again using the
<literal>org.freedesktop.DBus.ReleaseName</literal> message.
</para>
+ </sect2>
- <sect3 id="bus-messages-request-name">
- <title><literal>org.freedesktop.DBus.RequestName</literal></title>
+ <sect2 id="message-bus-routing">
+ <title>Message Bus Message Routing</title>
+
+ <para>
+ Messages may have a <literal>DESTINATION</literal> field (see <xref
+ linkend="message-protocol-header-fields"/>), resulting in a
+ <firstterm>unicast message</firstterm>. If the
+ <literal>DESTINATION</literal> field is present, it specifies a message
+ recipient by name. Method calls and replies normally specify this field.
+ The message bus must send messages (of any type) with the
+ <literal>DESTINATION</literal> field set to the specified recipient,
+ regardless of whether the recipient has set up a match rule matching
+ the message.
+ </para>
+
+ <para>
+ When the message bus receives a signal, if the
+ <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, and
+ no other message types currently defined in this specification
+ may be broadcast.
+ </para>
+
+ <para>
+ Unicast signal messages (those with a <literal>DESTINATION</literal>
+ field) are not commonly used, but they are treated like any unicast
+ message: they are delivered to the specified receipient,
+ regardless of its match rules. One use for unicast signals is to
+ avoid a race condition in which a signal is emitted before the intended
+ recipient can call <xref linkend="bus-messages-add-match"/> to
+ receive that signal: if the signal is sent directly to that recipient
+ using a unicast message, it does not need to add a match rule at all,
+ and there is no race condition. Another use for unicast signals,
+ on message buses whose security policy prevents eavesdropping, is to
+ send sensitive information which should only be visible to one
+ recipient.
+ </para>
+
+ <para>
+ When the message bus receives a method call, if the
+ <literal>DESTINATION</literal> field is absent, the call is taken to be
+ a standard one-to-one message and interpreted by the message bus
+ itself. For example, sending an
+ <literal>org.freedesktop.DBus.Peer.Ping</literal> message with no
+ <literal>DESTINATION</literal> will cause the message bus itself to
+ reply to the ping immediately; the message bus will not make this
+ message visible to other applications.
+ </para>
+
+ <para>
+ Continuing the <literal>org.freedesktop.DBus.Peer.Ping</literal> example, if
+ the ping message were sent with a <literal>DESTINATION</literal> name of
+ <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
+ forwarded, and the Yoyodyne Corporation screensaver application would be
+ expected to reply to the ping.
+ </para>
+
+ <para>
+ Message bus implementations may impose a security policy which
+ prevents certain messages from being sent or received.
+ 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>
+
+ <sect3 id="message-bus-routing-eavesdropping">
+ <title>Eavesdropping</title>
<para>
- As a method:
- <programlisting>
- UINT32 RequestName (in STRING name, in UINT32 flags)
- </programlisting>
- Message arguments:
+ Receiving a unicast message whose <literal>DESTINATION</literal>
+ indicates a different recipient is called
+ <firstterm>eavesdropping</firstterm>. On a message bus which acts as
+ a security boundary (like the standard system bus), the security
+ policy should usually prevent eavesdropping, since unicast messages
+ are normally kept private and may contain security-sensitive
+ information.
+ </para>
+
+ <para>
+ Eavesdropping is mainly useful for debugging tools, such as
+ the <literal>dbus-monitor</literal> tool in the reference
+ implementation of D-Bus. Tools which eavesdrop on the message bus
+ should be careful to avoid sending a reply or error in response to
+ messages intended for a different client.
+ </para>
+
+ <para>
+ Clients may attempt to eavesdrop by adding match rules
+ (see <xref linkend="message-bus-routing-match-rules"/>) containing
+ the <literal>eavesdrop='true'</literal> match. If the message bus'
+ security policy does not allow eavesdropping, the match rule can
+ still be added, but will not have any practical effect. For
+ compatibility with older message bus implementations, if adding such
+ a match rule results in an error reply, the client may fall back to
+ 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
+ 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
+ avoids waking up client processes to deal with signals that are
+ not relevant to that client.
+ </para>
+ <para>
+ Messages that list a client as their <literal>DESTINATION</literal>
+ do not need to match the client's match rules, and are sent to that
+ client regardless. As a result, match rules are mainly used to
+ receive a subset of broadcast signals.
+ </para>
+ <para>
+ Match rules can also be used for eavesdropping
+ (see <xref linkend="message-bus-routing-eavesdropping"/>),
+ if the security policy of the message bus allows it.
+ </para>
+ <para>
+ 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
+ adding a sender would let all messages from that sender through.
+ 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>
+ 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">
<thead>
<row>
- <entry>Argument</entry>
- <entry>Type</entry>
+ <entry>Key</entry>
+ <entry>Possible Values</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
- <entry>0</entry>
- <entry>STRING</entry>
- <entry>Name to request</entry>
+ <entry><literal>type</literal></entry>
+ <entry>'signal', 'method_call', 'method_return', 'error'</entry>
+ <entry>Match on the message type. An example of a type match is type='signal'</entry>
</row>
<row>
- <entry>1</entry>
- <entry>UINT32</entry>
- <entry>Flags</entry>
+ <entry><literal>sender</literal></entry>
+ <entry>A bus or unique name (see <xref linkend="term-bus-name"/>
+ and <xref linkend="term-unique-name"/> respectively)
+ </entry>
+ <entry>Match messages sent by a particular sender. An example of a sender match
+ is sender='org.freedesktop.Hal'</entry>
</row>
- </tbody>
- </tgroup>
- </informaltable>
- Reply arguments:
- <informaltable>
- <tgroup cols="3">
- <thead>
<row>
- <entry>Argument</entry>
- <entry>Type</entry>
- <entry>Description</entry>
+ <entry><literal>interface</literal></entry>
+ <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
+ that specifies this key.</entry>
</row>
- </thead>
- <tbody>
<row>
- <entry>0</entry>
- <entry>UINT32</entry>
- <entry>Return value</entry>
+ <entry><literal>member</literal></entry>
+ <entry>Any valid method or signal name</entry>
+ <entry>Matches messages which have the give method or signal name. An example of
+ a member match is member='NameOwnerChanged'</entry>
</row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- This method call should be sent to
- <literal>org.freedesktop.DBus</literal> and asks the message bus to
- assign the given name to the method caller. Each name maintains a
- queue of possible owners, where the head of the queue is the primary
- or current owner of the name. Each potential owner in the queue
- maintains the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and
- DBUS_NAME_FLAG_DO_NOT_QUEUE settings from its latest RequestName
- call. When RequestName is invoked the following occurs:
- <itemizedlist>
- <listitem>
- <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,
- and nothing further happens.
- </para>
- </listitem>
+ <row>
+ <entry><literal>path</literal></entry>
+ <entry>An object path (see <xref linkend="message-protocol-marshaling-object-path"/>)</entry>
+ <entry>Matches messages which are sent from or to the given object. An example of a
+ path match is path='/org/freedesktop/Hal/Manager'</entry>
+ </row>
+ <row>
+ <entry><literal>path_namespace</literal></entry>
+ <entry>An object path</entry>
+ <entry>
+ <para>
+ Matches messages which are sent from or to an
+ object for which the object path is either the
+ given value, or that value followed by one or
+ more path components.
+ </para>
- <listitem>
- <para>
- If the current primary owner (head of the queue) has
- DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, and the RequestName
- 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
- the new RequestName in addition to moving it to the head of the queue.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If replacement is not possible, and the method caller is
- currently in the queue but not the primary owner, its flags are
- updated with the values from the new RequestName call.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If replacement is not possible, and the method caller is
- currently not in the queue, the method caller is appended to the
- queue.
- </para>
- </listitem>
+ <para>
+ For example,
+ <literal>path_namespace='/com/example/foo'</literal>
+ would match signals sent by
+ <literal>/com/example/foo</literal>
+ or by
+ <literal>/com/example/foo/bar</literal>,
+ but not by
+ <literal>/com/example/foobar</literal>.
+ </para>
- <listitem>
- <para>
- If any connection in the queue has DBUS_NAME_FLAG_DO_NOT_QUEUE
- set and is not the primary owner, it is removed from the
- queue. This can apply to the previous primary owner (if it
- was replaced) or the method caller (if it updated the
- DBUS_NAME_FLAG_DO_NOT_QUEUE flag while still stuck in the
- queue, or if it was just added to the queue with that flag set).
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Note that DBUS_NAME_FLAG_REPLACE_EXISTING results in "jumping the
- queue," even if another application already in the queue had specified
- DBUS_NAME_FLAG_REPLACE_EXISTING. This comes up if a primary owner
- that does not allow replacement goes away, and the next primary owner
- does allow replacement. In this case, queued items that specified
- DBUS_NAME_FLAG_REPLACE_EXISTING <emphasis>do not</emphasis>
- 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
- and DBUS_NAME_FLAG_REPLACE_EXISTING.
- </para>
- <para>
- The flags argument contains any of the following values logically ORed
- together:
+ <para>
+ Using both <literal>path</literal> and
+ <literal>path_namespace</literal> in the same match
+ rule is not allowed.
+ </para>
- <informaltable>
- <tgroup cols="3">
- <thead>
+ <para>
+ <emphasis>
+ This match key was added in version 0.16 of the
+ D-Bus specification and implemented by the bus
+ daemon in dbus 1.5.0 and later.
+ </emphasis>
+ </para>
+ </entry>
+ </row>
<row>
- <entry>Conventional Name</entry>
- <entry>Value</entry>
- <entry>Description</entry>
+ <entry><literal>destination</literal></entry>
+ <entry>A unique name (see <xref linkend="term-unique-name"/>)</entry>
+ <entry>Matches messages which are being sent to the given unique name. An
+ example of a destination match is destination=':1.0'</entry>
</row>
- </thead>
- <tbody>
<row>
- <entry>DBUS_NAME_FLAG_ALLOW_REPLACEMENT</entry>
- <entry>0x1</entry>
+ <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
+ 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
+ accepted.</entry>
+ </row>
+ <row>
+ <entry><literal>arg[0, 1, 2, 3, ...]path</literal></entry>
+ <entry>Any string</entry>
<entry>
+ <para>Argument path matches provide a specialised form of wildcard matching for
+ path-like namespaces. They can match arguments whose type is either STRING or
+ OBJECT_PATH. As with normal argument matches,
+ if the argument is exactly equal to the string given in the match
+ rule then the rule is satisfied. Additionally, there is also a
+ match when either the string given in the match rule or the
+ appropriate message argument ends with '/' and is a prefix of the
+ other. An example argument path match is arg0path='/aa/bb/'. This
+ would match messages with first arguments of '/', '/aa/',
+ '/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match
+ messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'.</para>
- If an application A specifies this flag and succeeds in
- becoming the owner of the name, and another application B
- later calls RequestName with the
- DBUS_NAME_FLAG_REPLACE_EXISTING flag, then application A
- will lose ownership and receive a
- <literal>org.freedesktop.DBus.NameLost</literal> signal, and
- application B will become the new owner. If DBUS_NAME_FLAG_ALLOW_REPLACEMENT
- is not specified by application A, or DBUS_NAME_FLAG_REPLACE_EXISTING
- is not specified by application B, then application B will not replace
- application A as the owner.
-
+ <para>This is intended for monitoring “directories” in file system-like
+ hierarchies, as used in the <citetitle>dconf</citetitle> configuration
+ system. An application interested in all nodes in a particular hierarchy would
+ monitor <literal>arg0path='/ca/example/foo/'</literal>. Then the service could
+ emit a signal with zeroth argument <literal>"/ca/example/foo/bar"</literal> to
+ represent a modification to the “bar” property, or a signal with zeroth
+ argument <literal>"/ca/example/"</literal> to represent atomic modification of
+ many properties within that directory, and the interested application would be
+ notified in both cases.</para>
+ <para>
+ <emphasis>
+ This match key was added in version 0.12 of the
+ D-Bus specification, implemented for STRING
+ arguments by the bus daemon in dbus 1.2.0 and later,
+ and implemented for OBJECT_PATH arguments in dbus 1.5.0
+ and later.
+ </emphasis>
+ </para>
</entry>
</row>
<row>
- <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
- <entry>0x2</entry>
+ <entry><literal>arg0namespace</literal></entry>
+ <entry>Like a bus name, except that the string is not
+ required to contain a '.' (period)</entry>
<entry>
+ <para>Match messages whose first argument is of type STRING, and is a bus name
+ or interface name within the specified namespace. This is primarily intended
+ for watching name owner changes for a group of related bus names, rather than
+ for a single name or all name changes.</para>
- 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 name if there is no current owner. If this flag is set,
- the application will replace the current owner if
- the current owner specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT.
+ <para>Because every valid interface name is also a valid
+ bus name, this can also be used for messages whose
+ first argument is an interface name.</para>
+
+ <para>For example, the match rule
+ <literal>member='NameOwnerChanged',arg0namespace='com.example.backend1'</literal>
+ matches name owner changes for bus names such as
+ <literal>com.example.backend1.foo</literal>,
+ <literal>com.example.backend1.foo.bar</literal>, and
+ <literal>com.example.backend1</literal> itself.</para>
+ <para>See also <xref linkend='bus-messages-name-owner-changed'/>.</para>
+ <para>
+ <emphasis>
+ This match key was added in version 0.16 of the
+ D-Bus specification and implemented by the bus
+ daemon in dbus 1.5.0 and later.
+ </emphasis>
+ </para>
</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
- own the name when the current owner gives it up. If this
- flag is given, the application will not be placed in the
- queue, the request for the name will simply fail. This flag
- also affects behavior when an application is replaced as
- name owner; by default the application moves back into the
- waiting queue, unless this flag was provided when the application
- became the name owner.
-
+ <entry><literal>eavesdrop</literal></entry>
+ <entry><literal>'true'</literal>, <literal>'false'</literal></entry>
+ <entry>Since D-Bus 1.5.6, match rules do not
+ match messages which have a <literal>DESTINATION</literal>
+ field unless the match rule specifically
+ requests this
+ (see <xref linkend="message-bus-routing-eavesdropping"/>)
+ by specifying <literal>eavesdrop='true'</literal>
+ in the match rule. <literal>eavesdrop='false'</literal>
+ restores the default behaviour. Messages are
+ delivered to their <literal>DESTINATION</literal>
+ regardless of match rules, so this match does not
+ affect normal delivery of unicast messages.
+ If the message bus has a security policy which forbids
+ eavesdropping, this match may still be used without error,
+ but will not have any practical effect.
+ In older versions of D-Bus, this match was not allowed
+ in match rules, and all match rules behaved as if
+ <literal>eavesdrop='true'</literal> had been used.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
+ </para>
+ </sect3>
+ </sect2>
+ <sect2 id="message-bus-starting-services">
+ <title>Message Bus Starting Services (Activation)</title>
+ <para>
+ The message bus can start applications on behalf of other applications.
+ This is referred to as <firstterm>service activation</firstterm> or
+ <firstterm>activation</firstterm>.
+ An application that can be started in this way is called a
+ <firstterm>service</firstterm> or an
+ <firstterm>activatable service</firstterm>.
+ </para>
- The return code can be one of the following values:
+ <para>
+ <firstterm>Starting a service</firstterm> should be read as synonymous
+ with service activation.
+ </para>
- <informaltable>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Conventional Name</entry>
- <entry>Value</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <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
- DBUS_NAME_FLAG_ALLOW_REPLACEMENT.</entry>
- </row>
- <row>
- <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
- <entry>2</entry>
-
- <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>
- </para>
- </sect3>
-
- <sect3 id="bus-messages-release-name">
- <title><literal>org.freedesktop.DBus.ReleaseName</literal></title>
- <para>
- As a method:
- <programlisting>
- UINT32 ReleaseName (in STRING 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>Name to release</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>UINT32</entry>
- <entry>Return value</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- This method call should be sent to
- <literal>org.freedesktop.DBus</literal> and asks the message bus to
- release the method caller's claim to the given name. If the caller is
- the primary owner, a new primary owner will be selected from the
- queue if any other owners are waiting. If the caller is waiting in
- the queue for the name, the caller will removed from the queue and
- will not be made an owner of the name if it later becomes available.
- If there are no other owners in the queue for the name, it will be
- removed from the bus entirely.
-
- The return code can be one of the following values:
-
- <informaltable>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Conventional Name</entry>
- <entry>Value</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <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
- the name, and the name is now unused or taken by somebody
- 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,
- and was also not waiting in the queue to own this name.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </sect3>
-
- <sect3 id="bus-messages-list-queued-owners">
- <title><literal>org.freedesktop.DBus.ListQueuedOwners</literal></title>
- <para>
- As a method:
- <programlisting>
- ARRAY of STRING ListQueuedOwners (in STRING 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>The well-known bus name to query, such as
- <literal>com.example.cappuccino</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 STRING</entry>
- <entry>The unique bus names of connections currently queued
- for the name</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- This method call should be sent to
- <literal>org.freedesktop.DBus</literal> and lists the connections
- currently queued for a bus name (see
- <xref linkend="term-queued-owner"/>).
- </para>
- </sect3>
- </sect2>
-
- <sect2 id="message-bus-routing">
- <title>Message Bus Message Routing</title>
+ <para>
+ In D-Bus, service activation is normally done by
+ <firstterm>auto-starting</firstterm>.
+ In auto-starting, applications send a
+ message to a particular well-known name, such as
+ <literal>com.example.TextEditor1</literal>, without specifying the
+ <literal>NO_AUTO_START</literal> flag in the message header.
+ If no application on the bus owns the requested name, but the bus
+ daemon does know how to start an activatable service for that name,
+ then the bus daemon will start that service, wait for it to request
+ that name, and deliver the message to it.
+ </para>
<para>
- Messages may have a <literal>DESTINATION</literal> field (see <xref
- linkend="message-protocol-header-fields"/>), resulting in a
- <firstterm>unicast message</firstterm>. If the
- <literal>DESTINATION</literal> field is present, it specifies a message
- recipient by name. Method calls and replies normally specify this field.
- The message bus must send messages (of any type) with the
- <literal>DESTINATION</literal> field set to the specified recipient,
- regardless of whether the recipient has set up a match rule matching
- the message.
+ It is also possible for applications to send an explicit request to
+ start a service: this is another form of activation, distinct from
+ auto-starting. See
+ <xref linkend="bus-messages-start-service-by-name"/> for details.
</para>
<para>
- When the message bus receives a signal, if the
- <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, and
- no other message types currently defined in this specification
- may be broadcast.
+ In either case, this implies a contract documented along with the name
+ <literal>com.example.TextEditor1</literal> for which object
+ the owner of that name will provide, and what interfaces those
+ objects will have.
</para>
<para>
- Unicast signal messages (those with a <literal>DESTINATION</literal>
- field) are not commonly used, but they are treated like any unicast
- message: they are delivered to the specified receipient,
- regardless of its match rules. One use for unicast signals is to
- avoid a race condition in which a signal is emitted before the intended
- recipient can call <xref linkend="bus-messages-add-match"/> to
- receive that signal: if the signal is sent directly to that recipient
- using a unicast message, it does not need to add a match rule at all,
- and there is no race condition. Another use for unicast signals,
- on message buses whose security policy prevents eavesdropping, is to
- send sensitive information which should only be visible to one
- recipient.
+ To find an executable corresponding to a particular name, the bus daemon
+ looks for <firstterm>service description files</firstterm>. Service
+ description files define a mapping from names to executables. Different
+ kinds of message bus will look for these files in different places, see
+ <xref linkend="message-bus-types"/>.
</para>
-
<para>
- When the message bus receives a method call, if the
- <literal>DESTINATION</literal> field is absent, the call is taken to be
- a standard one-to-one message and interpreted by the message bus
- itself. For example, sending an
- <literal>org.freedesktop.DBus.Peer.Ping</literal> message with no
- <literal>DESTINATION</literal> will cause the message bus itself to
- reply to the ping immediately; the message bus will not make this
- message visible to other applications.
+ Service description files have the ".service" file
+ extension. The message bus will only load service description files
+ ending with .service; all other files will be ignored. The file format
+ is similar to that of <ulink
+ url="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">desktop
+ entries</ulink>. All service description files must be in UTF-8
+ encoding. To ensure that there will be no name collisions, service files
+ must be namespaced using the same mechanism as messages and service
+ names.
</para>
<para>
- Continuing the <literal>org.freedesktop.DBus.Peer.Ping</literal> example, if
- the ping message were sent with a <literal>DESTINATION</literal> name of
- <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
- forwarded, and the Yoyodyne Corporation screensaver application would be
- expected to reply to the ping.
+ On the well-known system bus, the name of a service description file
+ must be its well-known name plus <literal>.service</literal>,
+ for instance
+ <literal>com.example.ConfigurationDatabase1.service</literal>.
</para>
<para>
- Message bus implementations may impose a security policy which
- prevents certain messages from being sent or received.
- 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.
+ On the well-known session bus, services should follow the same
+ service description file naming convention as on the system bus,
+ but for backwards compatibility they are not required to do so.
</para>
- <sect3 id="message-bus-routing-eavesdropping">
- <title>Eavesdropping</title>
- <para>
- Receiving a unicast message whose <literal>DESTINATION</literal>
- indicates a different recipient is called
- <firstterm>eavesdropping</firstterm>. On a message bus which acts as
- a security boundary (like the standard system bus), the security
- policy should usually prevent eavesdropping, since unicast messages
- are normally kept private and may contain security-sensitive
- information.
- </para>
-
- <para>
- Eavesdropping is mainly useful for debugging tools, such as
- the <literal>dbus-monitor</literal> tool in the reference
- implementation of D-Bus. Tools which eavesdrop on the message bus
- should be careful to avoid sending a reply or error in response to
- messages intended for a different client.
+ <para>
+ [FIXME the file format should be much better specified than "similar to
+ .desktop entries" esp. since desktop entries are already
+ badly-specified. ;-)]
+ These sections from the specification apply to service files as well:
+
+ <itemizedlist>
+ <listitem><para>General syntax</para></listitem>
+ <listitem><para>Comment format</para></listitem>
+ </itemizedlist>
+
+ Service description files must contain a
+ <literal>D-BUS Service</literal> group with at least the keys
+ <literal>Name</literal> (the well-known name of the service)
+ and <literal>Exec</literal> (the command to be executed).
+
+ <figure>
+ <title>Example service description file</title>
+ <programlisting>
+ # Sample service description file
+ [D-BUS Service]
+ Name=com.example.ConfigurationDatabase1
+ Exec=/usr/bin/sample-configd
+ </programlisting>
+ </figure>
+ </para>
+
+ <para>
+ Additionally, service description files for the well-known system
+ bus on Unix must contain a <literal>User</literal> key, whose value
+ is the name of a user account (e.g. <literal>root</literal>).
+ The system service will be run as that user.
+ </para>
+
+ <para>
+ When an application asks to start a service by name, the bus daemon tries to
+ find a service that will own that name. It then tries to spawn the
+ executable associated with it. If this fails, it will report an
+ error.
+ </para>
+
+ <para>
+ On the well-known system bus, it is not possible for two .service files
+ in the same directory to offer the same service, because they are
+ constrained to have names that match the service name.
+ </para>
+
+ <para>
+ On the well-known session bus, if two .service files in the same
+ directory offer the same service name, the result is undefined.
+ Distributors should avoid this situation, for instance by naming
+ session services' .service files according to their service name.
+ </para>
+
+ <para>
+ If two .service files in different directories offer the same
+ service name, the one in the higher-priority directory is used:
+ for instance, on the system bus, .service files in
+ /usr/local/share/dbus-1/system-services take precedence over those
+ in /usr/share/dbus-1/system-services.
+ </para>
+ <para>
+ The executable launched will have the environment variable
+ <literal>DBUS_STARTER_ADDRESS</literal> set to the address of the
+ message bus so it can connect and request the appropriate names.
+ </para>
+ <para>
+ The executable being launched may want to know whether the message bus
+ starting it is one of the well-known message buses (see <xref
+ linkend="message-bus-types"/>). To facilitate this, the bus must also set
+ the <literal>DBUS_STARTER_BUS_TYPE</literal> environment variable if it is one
+ of the well-known buses. The currently-defined values for this variable
+ are <literal>system</literal> for the systemwide message bus,
+ and <literal>session</literal> for the per-login-session message
+ bus. The new executable must still connect to the address given
+ in <literal>DBUS_STARTER_ADDRESS</literal>, but may assume that the
+ resulting connection is to the well-known bus.
+ </para>
+ <para>
+ [FIXME there should be a timeout somewhere, either specified
+ in the .service file, by the client, or just a global value
+ and if the client being activated fails to connect within that
+ timeout, an error should be sent back.]
+ </para>
+
+ <sect3 id="message-bus-starting-services-scope">
+ <title>Message Bus Service Scope</title>
+ <para>
+ The "scope" of a service is its "per-", such as per-session,
+ per-machine, per-home-directory, or per-display. The reference
+ implementation doesn't yet support starting services in a different
+ scope from the message bus itself. So e.g. if you start a service
+ on the session bus its scope is per-session.
+ </para>
+ <para>
+ We could add an optional scope to a bus name. For example, for
+ per-(display,session pair), we could have a unique ID for each display
+ generated automatically at login and set on screen 0 by executing a
+ special "set display ID" binary. The ID would be stored in a
+ <literal>_DBUS_DISPLAY_ID</literal> property and would be a string of
+ random bytes. This ID would then be used to scope names.
+ Starting/locating a service could be done by ID-name pair rather than
+ only by name.
+ </para>
+ <para>
+ 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>
+ property on screen 0 of the display, pointing to this bus.
</para>
+ </sect3>
+
+ <sect3 id="message-bus-starting-services-systemd">
+ <title>systemd Activation</title>
<para>
- Clients may attempt to eavesdrop by adding match rules
- (see <xref linkend="message-bus-routing-match-rules"/>) containing
- the <literal>eavesdrop='true'</literal> match. If the message bus'
- security policy does not allow eavesdropping, the match rule can
- still be added, but will not have any practical effect. For
- compatibility with older message bus implementations, if adding such
- a match rule results in an error reply, the client may fall back to
- adding the same rule with the <literal>eavesdrop</literal> match
- omitted.
+ Service description files may contain a
+ <literal>SystemdService</literal> key. Its value is the name of a
+ <ulink
+ url="https://www.freedesktop.org/wiki/Software/systemd/">systemd</ulink>
+ service, for example
+ <literal>dbus-com.example.MyDaemon.service</literal>.
</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.
+ If this key is present, the bus daemon may carry out activation for
+ this D-Bus service by sending a request to systemd asking it to
+ start the systemd service whose name is the value of
+ <literal>SystemdService</literal>. For example, the reference
+ <literal>dbus-daemon</literal> has a
+ <literal>--systemd-activation</literal> option that enables this
+ feature, and that option is given when it is started by systemd.
+ </para>
+
+ <para>
+ On the well-known system bus, it is a common practice to set
+ <literal>SystemdService</literal> to <literal>dbus-</literal>,
+ followed by the well-known bus name, followed by
+ <literal>.service</literal>, then register that name as an alias
+ for the real systemd service. This allows D-Bus activation of a
+ service to be enabled or disabled independently of whether the
+ service is started by systemd during boot.
</para>
</sect3>
- <sect3 id="message-bus-routing-match-rules">
- <title>Match Rules</title>
+ <sect3 id="message-bus-starting-services-apparmor">
+ <title>Mediating Activation with AppArmor</title>
+
<para>
- 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
- avoids waking up client processes to deal with signals that are
- not relevant to that client.
+ Please refer to
+ <ulink url="http://wiki.apparmor.net/index.php/Documentation">AppArmor documentation</ulink>
+ for general information on AppArmor, and how it mediates D-Bus
+ messages when used in conjunction with a kernel and
+ <literal>dbus-daemon</literal> that support this.
</para>
+
<para>
- Messages that list a client as their <literal>DESTINATION</literal>
- do not need to match the client's match rules, and are sent to that
- client regardless. As a result, match rules are mainly used to
- receive a subset of broadcast signals.
+ In recent versions of the reference <literal>dbus-daemon</literal>,
+ AppArmor policy rules of type <literal>dbus send</literal>
+ are also used to control auto-starting: if a message is sent to
+ the well-known name of an activatable service, the
+ <literal>dbus-daemon</literal> will attempt to determine whether
+ it would deliver the message to that service
+ <emphasis>before</emphasis>auto-starting it, by making some
+ assumptions about the resulting process's credentials.
</para>
+
<para>
- Match rules can also be used for eavesdropping
- (see <xref linkend="message-bus-routing-eavesdropping"/>),
- if the security policy of the message bus allows it.
+ If it does proceed with auto-starting, when the service appears, the
+ <literal>dbus-daemon</literal> repeats the policy check (with
+ the service's true credentials, which might not be identical)
+ before delivering the message. In practice, this second check will
+ usually be more strict than the first; the first check would only
+ be more strict if there are "blacklist"-style rules like
+ <literal>deny dbus send peer=(label=/usr/bin/protected)</literal>
+ that match on the peer's specific credentials, but AppArmor is
+ normally used in a "whitelist" style where this does not apply.
</para>
+
<para>
- 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
- adding a sender would let all messages from that sender through.
- 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'"
+ To support this process, service description files may contain a
+ <literal>AssumedAppArmorLabel</literal> key. Its value is the name
+ of an AppArmor label, for example
+ <literal>/usr/sbin/mydaemon</literal>.
+ If present, AppArmor mediation of messages that auto-start a
+ service will decide whether to allow auto-starting to occur based
+ on the assumption that the activated service will be confined
+ under the specified label; in particular, rules of the form
+ <literal>dbus send peer=(label=/usr/sbin/mydaemon)</literal> or
+ <literal>deny dbus send peer=(label=/usr/sbin/mydaemon)</literal>
+ will match it, allowing or denying as appropriate
+ (even if there is in fact no profile of that name loaded).
</para>
+
<para>
- 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>.
+ Otherwise, AppArmor mediation of messages that auto-start a
+ service will decide whether to allow auto-starting to occur
+ without specifying any particular label. In particular, any rule of
+ the form <literal>dbus send peer=(label=X)</literal> or
+ <literal>deny dbus send peer=(label=X)</literal>
+ (for any value of X, including the special label
+ <literal>unconfined</literal>) will not influence whether the
+ auto-start is allowed.
</para>
- <para>
- The following table describes the keys that can be used to create
- a match rule.
- <informaltable>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Key</entry>
- <entry>Possible Values</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>type</literal></entry>
- <entry>'signal', 'method_call', 'method_return', 'error'</entry>
- <entry>Match on the message type. An example of a type match is type='signal'</entry>
- </row>
- <row>
- <entry><literal>sender</literal></entry>
- <entry>A bus or unique name (see <xref linkend="term-bus-name"/>
- and <xref linkend="term-unique-name"/> respectively)
- </entry>
- <entry>Match messages sent by a particular sender. An example of a sender match
- is sender='org.freedesktop.Hal'</entry>
- </row>
- <row>
- <entry><literal>interface</literal></entry>
- <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
- that specifies this key.</entry>
- </row>
- <row>
- <entry><literal>member</literal></entry>
- <entry>Any valid method or signal name</entry>
- <entry>Matches messages which have the give method or signal name. An example of
- a member match is member='NameOwnerChanged'</entry>
- </row>
- <row>
- <entry><literal>path</literal></entry>
- <entry>An object path (see <xref linkend="message-protocol-marshaling-object-path"/>)</entry>
- <entry>Matches messages which are sent from or to the given object. An example of a
- path match is path='/org/freedesktop/Hal/Manager'</entry>
- </row>
- <row>
- <entry><literal>path_namespace</literal></entry>
- <entry>An object path</entry>
- <entry>
- <para>
- Matches messages which are sent from or to an
- object for which the object path is either the
- given value, or that value followed by one or
- more path components.
- </para>
-
- <para>
- For example,
- <literal>path_namespace='/com/example/foo'</literal>
- would match signals sent by
- <literal>/com/example/foo</literal>
- or by
- <literal>/com/example/foo/bar</literal>,
- but not by
- <literal>/com/example/foobar</literal>.
- </para>
-
- <para>
- Using both <literal>path</literal> and
- <literal>path_namespace</literal> in the same match
- rule is not allowed.
- </para>
-
- <para>
- <emphasis>
- This match key was added in version 0.16 of the
- D-Bus specification and implemented by the bus
- daemon in dbus 1.5.0 and later.
- </emphasis>
- </para>
- </entry>
- </row>
- <row>
- <entry><literal>destination</literal></entry>
- <entry>A unique name (see <xref linkend="term-unique-name"/>)</entry>
- <entry>Matches messages which are being sent to the given unique name. An
- example of a destination match is destination=':1.0'</entry>
- </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
- 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
- accepted.</entry>
- </row>
- <row>
- <entry><literal>arg[0, 1, 2, 3, ...]path</literal></entry>
- <entry>Any string</entry>
- <entry>
- <para>Argument path matches provide a specialised form of wildcard matching for
- path-like namespaces. They can match arguments whose type is either STRING or
- OBJECT_PATH. As with normal argument matches,
- if the argument is exactly equal to the string given in the match
- rule then the rule is satisfied. Additionally, there is also a
- match when either the string given in the match rule or the
- appropriate message argument ends with '/' and is a prefix of the
- other. An example argument path match is arg0path='/aa/bb/'. This
- would match messages with first arguments of '/', '/aa/',
- '/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match
- messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'.</para>
-
- <para>This is intended for monitoring “directories” in file system-like
- hierarchies, as used in the <citetitle>dconf</citetitle> configuration
- system. An application interested in all nodes in a particular hierarchy would
- monitor <literal>arg0path='/ca/example/foo/'</literal>. Then the service could
- emit a signal with zeroth argument <literal>"/ca/example/foo/bar"</literal> to
- represent a modification to the “bar” property, or a signal with zeroth
- argument <literal>"/ca/example/"</literal> to represent atomic modification of
- many properties within that directory, and the interested application would be
- notified in both cases.</para>
- <para>
- <emphasis>
- This match key was added in version 0.12 of the
- D-Bus specification, implemented for STRING
- arguments by the bus daemon in dbus 1.2.0 and later,
- and implemented for OBJECT_PATH arguments in dbus 1.5.0
- and later.
- </emphasis>
- </para>
- </entry>
- </row>
- <row>
- <entry><literal>arg0namespace</literal></entry>
- <entry>Like a bus name, except that the string is not
- required to contain a '.' (period)</entry>
- <entry>
- <para>Match messages whose first argument is of type STRING, and is a bus name
- or interface name within the specified namespace. This is primarily intended
- for watching name owner changes for a group of related bus names, rather than
- for a single name or all name changes.</para>
-
- <para>Because every valid interface name is also a valid
- bus name, this can also be used for messages whose
- first argument is an interface name.</para>
-
- <para>For example, the match rule
- <literal>member='NameOwnerChanged',arg0namespace='com.example.backend1'</literal>
- matches name owner changes for bus names such as
- <literal>com.example.backend1.foo</literal>,
- <literal>com.example.backend1.foo.bar</literal>, and
- <literal>com.example.backend1</literal> itself.</para>
-
- <para>See also <xref linkend='bus-messages-name-owner-changed'/>.</para>
- <para>
- <emphasis>
- This match key was added in version 0.16 of the
- D-Bus specification and implemented by the bus
- daemon in dbus 1.5.0 and later.
- </emphasis>
- </para>
- </entry>
- </row>
- <row>
- <entry><literal>eavesdrop</literal></entry>
- <entry><literal>'true'</literal>, <literal>'false'</literal></entry>
- <entry>Since D-Bus 1.5.6, match rules do not
- match messages which have a <literal>DESTINATION</literal>
- field unless the match rule specifically
- requests this
- (see <xref linkend="message-bus-routing-eavesdropping"/>)
- by specifying <literal>eavesdrop='true'</literal>
- in the match rule. <literal>eavesdrop='false'</literal>
- restores the default behaviour. Messages are
- delivered to their <literal>DESTINATION</literal>
- regardless of match rules, so this match does not
- affect normal delivery of unicast messages.
- If the message bus has a security policy which forbids
- eavesdropping, this match may still be used without error,
- but will not have any practical effect.
- In older versions of D-Bus, this match was not allowed
- in match rules, and all match rules behaved as if
- <literal>eavesdrop='true'</literal> had been used.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </sect3>
- </sect2>
- <sect2 id="message-bus-starting-services">
- <title>Message Bus Starting Services (Activation)</title>
- <para>
- The message bus can start applications on behalf of other applications.
- This is referred to as <firstterm>service activation</firstterm> or
- <firstterm>activation</firstterm>.
- An application that can be started in this way is called a
- <firstterm>service</firstterm> or an
- <firstterm>activatable service</firstterm>.
- </para>
-
- <para>
- <firstterm>Starting a service</firstterm> should be read as synonymous
- with service activation.
- </para>
-
- <para>
- In D-Bus, service activation is normally done by
- <firstterm>auto-starting</firstterm>.
- In auto-starting, applications send a
- message to a particular well-known name, such as
- <literal>com.example.TextEditor1</literal>, without specifying the
- <literal>NO_AUTO_START</literal> flag in the message header.
- If no application on the bus owns the requested name, but the bus
- daemon does know how to start an activatable service for that name,
- then the bus daemon will start that service, wait for it to request
- that name, and deliver the message to it.
- </para>
-
- <para>
- It is also possible for applications to send an explicit request to
- start a service: this is another form of activation, distinct from
- auto-starting. See
- <xref linkend="bus-messages-start-service-by-name"/> for details.
- </para>
-
- <para>
- In either case, this implies a contract documented along with the name
- <literal>com.example.TextEditor1</literal> for which object
- the owner of that name will provide, and what interfaces those
- objects will have.
- </para>
-
- <para>
- To find an executable corresponding to a particular name, the bus daemon
- looks for <firstterm>service description files</firstterm>. Service
- description files define a mapping from names to executables. Different
- kinds of message bus will look for these files in different places, see
- <xref linkend="message-bus-types"/>.
- </para>
- <para>
- Service description files have the ".service" file
- extension. The message bus will only load service description files
- ending with .service; all other files will be ignored. The file format
- is similar to that of <ulink
- url="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">desktop
- entries</ulink>. All service description files must be in UTF-8
- encoding. To ensure that there will be no name collisions, service files
- must be namespaced using the same mechanism as messages and service
- names.
- </para>
-
- <para>
- On the well-known system bus, the name of a service description file
- must be its well-known name plus <literal>.service</literal>,
- for instance
- <literal>com.example.ConfigurationDatabase1.service</literal>.
- </para>
-
- <para>
- On the well-known session bus, services should follow the same
- service description file naming convention as on the system bus,
- but for backwards compatibility they are not required to do so.
- </para>
-
- <para>
- [FIXME the file format should be much better specified than "similar to
- .desktop entries" esp. since desktop entries are already
- badly-specified. ;-)]
- These sections from the specification apply to service files as well:
-
- <itemizedlist>
- <listitem><para>General syntax</para></listitem>
- <listitem><para>Comment format</para></listitem>
- </itemizedlist>
-
- Service description files must contain a
- <literal>D-BUS Service</literal> group with at least the keys
- <literal>Name</literal> (the well-known name of the service)
- and <literal>Exec</literal> (the command to be executed).
-
- <figure>
- <title>Example service description file</title>
- <programlisting>
- # Sample service description file
- [D-BUS Service]
- Name=com.example.ConfigurationDatabase1
- Exec=/usr/bin/sample-configd
- </programlisting>
- </figure>
- </para>
-
- <para>
- Additionally, service description files for the well-known system
- bus on Unix must contain a <literal>User</literal> key, whose value
- is the name of a user account (e.g. <literal>root</literal>).
- The system service will be run as that user.
- </para>
-
- <para>
- When an application asks to start a service by name, the bus daemon tries to
- find a service that will own that name. It then tries to spawn the
- executable associated with it. If this fails, it will report an
- error.
- </para>
-
- <para>
- On the well-known system bus, it is not possible for two .service files
- in the same directory to offer the same service, because they are
- constrained to have names that match the service name.
- </para>
-
- <para>
- On the well-known session bus, if two .service files in the same
- directory offer the same service name, the result is undefined.
- Distributors should avoid this situation, for instance by naming
- session services' .service files according to their service name.
- </para>
-
- <para>
- If two .service files in different directories offer the same
- service name, the one in the higher-priority directory is used:
- for instance, on the system bus, .service files in
- /usr/local/share/dbus-1/system-services take precedence over those
- in /usr/share/dbus-1/system-services.
- </para>
- <para>
- The executable launched will have the environment variable
- <literal>DBUS_STARTER_ADDRESS</literal> set to the address of the
- message bus so it can connect and request the appropriate names.
- </para>
- <para>
- The executable being launched may want to know whether the message bus
- starting it is one of the well-known message buses (see <xref
- linkend="message-bus-types"/>). To facilitate this, the bus must also set
- the <literal>DBUS_STARTER_BUS_TYPE</literal> environment variable if it is one
- of the well-known buses. The currently-defined values for this variable
- are <literal>system</literal> for the systemwide message bus,
- and <literal>session</literal> for the per-login-session message
- bus. The new executable must still connect to the address given
- in <literal>DBUS_STARTER_ADDRESS</literal>, but may assume that the
- resulting connection is to the well-known bus.
- </para>
- <para>
- [FIXME there should be a timeout somewhere, either specified
- in the .service file, by the client, or just a global value
- and if the client being activated fails to connect within that
- timeout, an error should be sent back.]
- </para>
-
- <sect3 id="message-bus-starting-services-scope">
- <title>Message Bus Service Scope</title>
- <para>
- The "scope" of a service is its "per-", such as per-session,
- per-machine, per-home-directory, or per-display. The reference
- implementation doesn't yet support starting services in a different
- scope from the message bus itself. So e.g. if you start a service
- on the session bus its scope is per-session.
- </para>
- <para>
- We could add an optional scope to a bus name. For example, for
- per-(display,session pair), we could have a unique ID for each display
- generated automatically at login and set on screen 0 by executing a
- special "set display ID" binary. The ID would be stored in a
- <literal>_DBUS_DISPLAY_ID</literal> property and would be a string of
- random bytes. This ID would then be used to scope names.
- Starting/locating a service could be done by ID-name pair rather than
- only by name.
- </para>
- <para>
- 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>
- property on screen 0 of the display, pointing to this bus.
- </para>
- </sect3>
-
- <sect3 id="message-bus-starting-services-systemd">
- <title>systemd Activation</title>
-
- <para>
- Service description files may contain a
- <literal>SystemdService</literal> key. Its value is the name of a
- <ulink
- url="https://www.freedesktop.org/wiki/Software/systemd/">systemd</ulink>
- service, for example
- <literal>dbus-com.example.MyDaemon.service</literal>.
- </para>
-
- <para>
- If this key is present, the bus daemon may carry out activation for
- this D-Bus service by sending a request to systemd asking it to
- start the systemd service whose name is the value of
- <literal>SystemdService</literal>. For example, the reference
- <literal>dbus-daemon</literal> has a
- <literal>--systemd-activation</literal> option that enables this
- feature, and that option is given when it is started by systemd.
- </para>
-
- <para>
- On the well-known system bus, it is a common practice to set
- <literal>SystemdService</literal> to <literal>dbus-</literal>,
- followed by the well-known bus name, followed by
- <literal>.service</literal>, then register that name as an alias
- for the real systemd service. This allows D-Bus activation of a
- service to be enabled or disabled independently of whether the
- service is started by systemd during boot.
- </para>
- </sect3>
-
- <sect3 id="message-bus-starting-services-apparmor">
- <title>Mediating Activation with AppArmor</title>
-
- <para>
- Please refer to
- <ulink url="http://wiki.apparmor.net/index.php/Documentation">AppArmor documentation</ulink>
- for general information on AppArmor, and how it mediates D-Bus
- messages when used in conjunction with a kernel and
- <literal>dbus-daemon</literal> that support this.
- </para>
-
- <para>
- In recent versions of the reference <literal>dbus-daemon</literal>,
- AppArmor policy rules of type <literal>dbus send</literal>
- are also used to control auto-starting: if a message is sent to
- the well-known name of an activatable service, the
- <literal>dbus-daemon</literal> will attempt to determine whether
- it would deliver the message to that service
- <emphasis>before</emphasis>auto-starting it, by making some
- assumptions about the resulting process's credentials.
- </para>
-
- <para>
- If it does proceed with auto-starting, when the service appears, the
- <literal>dbus-daemon</literal> repeats the policy check (with
- the service's true credentials, which might not be identical)
- before delivering the message. In practice, this second check will
- usually be more strict than the first; the first check would only
- be more strict if there are "blacklist"-style rules like
- <literal>deny dbus send peer=(label=/usr/bin/protected)</literal>
- that match on the peer's specific credentials, but AppArmor is
- normally used in a "whitelist" style where this does not apply.
- </para>
-
- <para>
- To support this process, service description files may contain a
- <literal>AssumedAppArmorLabel</literal> key. Its value is the name
- of an AppArmor label, for example
- <literal>/usr/sbin/mydaemon</literal>.
- If present, AppArmor mediation of messages that auto-start a
- service will decide whether to allow auto-starting to occur based
- on the assumption that the activated service will be confined
- under the specified label; in particular, rules of the form
- <literal>dbus send peer=(label=/usr/sbin/mydaemon)</literal> or
- <literal>deny dbus send peer=(label=/usr/sbin/mydaemon)</literal>
- will match it, allowing or denying as appropriate
- (even if there is in fact no profile of that name loaded).
- </para>
-
- <para>
- Otherwise, AppArmor mediation of messages that auto-start a
- service will decide whether to allow auto-starting to occur
- without specifying any particular label. In particular, any rule of
- the form <literal>dbus send peer=(label=X)</literal> or
- <literal>deny dbus send peer=(label=X)</literal>
- (for any value of X, including the special label
- <literal>unconfined</literal>) will not influence whether the
- auto-start is allowed.
- </para>
-
+
<para>
Rules of type <literal>dbus receive</literal> are not checked
when deciding whether to allow auto-starting; they are only checked
@@ -5429,197 +5038,570 @@
<para>the machine's ID</para>
</listitem>
- <listitem>
- <para>the literal character '-' (dash)</para>
- </listitem>
+ <listitem>
+ <para>the literal character '-' (dash)</para>
+ </listitem>
+
+ <listitem>
+ <para>the X display without the screen number, with the
+ following prefixes removed, if present: ":", "localhost:"
+ ."localhost.localdomain:". That is, a display of
+ "localhost:10.0" produces just the number "10"</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The contents of this file NAME=value assignment pairs and
+ lines starting with # are comments (no comments are allowed
+ otherwise). The following variable names are defined:
+ <informaltable
+ frame="all">
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ <para>Variable</para>
+ </entry>
+
+ <entry>
+ <para>meaning</para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>DBUS_SESSION_BUS_ADDRESS</para>
+ </entry>
+
+ <entry>
+ <para>the actual address of the server socket</para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>DBUS_SESSION_BUS_PID</para>
+ </entry>
+
+ <entry>
+ <para>the PID of the server process</para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>DBUS_SESSION_BUS_WINDOWID</para>
+ </entry>
+
+ <entry>
+ <para>the window ID</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ <para>
+ At least the DBUS_SESSION_BUS_ADDRESS variable MUST be present
+ in this file.
+ </para>
+
+ <para>
+ Failure to open this file MUST be interpreted as absence of a
+ running server. Therefore, the implementation MUST proceed to
+ attempting to launch a new bus server if the file cannot be
+ opened.
+ </para>
+
+ <para>
+ However, success in opening this file MUST NOT lead to the
+ conclusion that the server is running. Thus, a failure to connect to
+ the bus address obtained by the alternative method MUST NOT be
+ considered a fatal error. If the connection cannot be established,
+ the implementation MUST proceed to check the X selection settings or
+ to start the server on its own.
+ </para>
+
+ <para>
+ If the implementation concludes that the D-Bus server is not
+ running it MUST attempt to start a new server and it MUST also
+ ensure that the daemon started as an effect of the "autolaunch"
+ mechanism provides the lookup mechanisms described above, so
+ subsequent calls can locate the newly started server. The
+ implementation MUST also ensure that if two or more concurrent
+ initiations happen, only one server remains running and all other
+ initiations are able to obtain the address of this server and
+ connect to it. In other words, the implementation MUST ensure that
+ the X selection is not present when it attempts to set it, without
+ allowing another process to set the selection between the
+ verification and the setting (e.g., by using XGrabServer /
+ XungrabServer).
+ </para>
+ </sect4>
+ <sect4>
+ <title>Finding session services</title>
+ <para>
+ On Unix systems, the session bus should search for .service files
+ in <literal>$XDG_DATA_DIRS/dbus-1/services</literal> as defined
+ by the
+ <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG Base Directory Specification</ulink>.
+ Implementations may also search additional locations,
+ with a higher or lower priority than the XDG directories.
+ </para>
+ <para>
+ As described in the XDG Base Directory Specification, software
+ packages should install their session .service files to their
+ configured <literal>${datadir}/dbus-1/services</literal>,
+ where <literal>${datadir}</literal> is as defined by the GNU
+ coding standards. System administrators or users can arrange
+ for these service files to be read by setting XDG_DATA_DIRS or by
+ symlinking them into the default locations.
+ </para>
+ </sect4>
+ </sect3>
+ <sect3 id="message-bus-types-system">
+ <title>System message bus</title>
+ <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,
+ 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
+ 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
+ for this address, on both client and server side.
+ </para>
+ </footnote>
+ </para>
+ <para>
+ On Unix systems, the system bus should default to searching
+ for .service files in
+ <literal>/usr/local/share/dbus-1/system-services</literal>,
+ <literal>/usr/share/dbus-1/system-services</literal> and
+ <literal>/lib/dbus-1/system-services</literal>, with that order
+ of precedence. It may also search other implementation-specific
+ locations, but should not vary these locations based on environment
+ variables.
+ <footnote>
+ <para>
+ The system bus is security-sensitive and is typically executed
+ by an init system with a clean environment. Its launch helper
+ process is particularly security-sensitive, and specifically
+ clears its own environment.
+ </para>
+ </footnote>
+ </para>
+ <para>
+ Software packages should install their system .service
+ files to their configured
+ <literal>${datadir}/dbus-1/system-services</literal>,
+ where <literal>${datadir}</literal> is as defined by the GNU
+ coding standards. System administrators can arrange
+ for these service files to be read by editing the system bus'
+ configuration file or by symlinking them into the default
+ locations.
+ </para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="message-bus-messages">
+ <title>Message Bus Messages</title>
+ <para>
+ The special message bus name <literal>org.freedesktop.DBus</literal>
+ responds to a number of additional messages.
+ </para>
+
+ <sect3 id="bus-messages-hello">
+ <title><literal>org.freedesktop.DBus.Hello</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ STRING Hello ()
+ </programlisting>
+ 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>STRING</entry>
+ <entry>Unique name assigned to the connection</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ Before an application is able to send messages to other applications
+ it must send the <literal>org.freedesktop.DBus.Hello</literal> message
+ to the message bus to obtain a unique name. If an application without
+ a unique name tries to send a message to another application, or a
+ message to the message bus itself that isn't the
+ <literal>org.freedesktop.DBus.Hello</literal> message, it will be
+ disconnected from the bus.
+ </para>
+ <para>
+ There is no corresponding "disconnect" request; if a client wishes to
+ disconnect from the bus, it simply closes the socket (or other
+ communication channel).
+ </para>
+ </sect3>
+ <sect3 id="bus-messages-request-name">
+ <title><literal>org.freedesktop.DBus.RequestName</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ UINT32 RequestName (in STRING name, 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>STRING</entry>
+ <entry>Name to request</entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>UINT32</entry>
+ <entry>Flags</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>UINT32</entry>
+ <entry>Return value</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ Ask the message bus to assign the given name to the method caller. Each
+ name maintains a queue of possible owners, where the head of the queue is
+ the primary or current owner of the name. Each potential owner in the
+ queue maintains the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and
+ DBUS_NAME_FLAG_DO_NOT_QUEUE settings from its latest RequestName call.
+ When RequestName is invoked the following occurs:
+ <itemizedlist>
+ <listitem>
+ <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,
+ and nothing further happens.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If the current primary owner (head of the queue) has
+ DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, and the RequestName
+ 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
+ the new RequestName in addition to moving it to the head of the queue.
+ </para>
+ </listitem>
- <listitem>
- <para>the X display without the screen number, with the
- following prefixes removed, if present: ":", "localhost:"
- ."localhost.localdomain:". That is, a display of
- "localhost:10.0" produces just the number "10"</para>
- </listitem>
- </itemizedlist>
- </para>
+ <listitem>
+ <para>
+ If replacement is not possible, and the method caller is
+ currently in the queue but not the primary owner, its flags are
+ updated with the values from the new RequestName call.
+ </para>
+ </listitem>
- <para>
- The contents of this file NAME=value assignment pairs and
- lines starting with # are comments (no comments are allowed
- otherwise). The following variable names are defined:
- <informaltable
- frame="all">
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>
- <para>Variable</para>
- </entry>
+ <listitem>
+ <para>
+ If replacement is not possible, and the method caller is
+ currently not in the queue, the method caller is appended to the
+ queue.
+ </para>
+ </listitem>
- <entry>
- <para>meaning</para>
- </entry>
- </row>
+ <listitem>
+ <para>
+ If any connection in the queue has DBUS_NAME_FLAG_DO_NOT_QUEUE
+ set and is not the primary owner, it is removed from the
+ queue. This can apply to the previous primary owner (if it
+ was replaced) or the method caller (if it updated the
+ DBUS_NAME_FLAG_DO_NOT_QUEUE flag while still stuck in the
+ queue, or if it was just added to the queue with that flag set).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Note that DBUS_NAME_FLAG_REPLACE_EXISTING results in "jumping the
+ queue," even if another application already in the queue had specified
+ DBUS_NAME_FLAG_REPLACE_EXISTING. This comes up if a primary owner
+ that does not allow replacement goes away, and the next primary owner
+ does allow replacement. In this case, queued items that specified
+ DBUS_NAME_FLAG_REPLACE_EXISTING <emphasis>do not</emphasis>
+ 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
+ and DBUS_NAME_FLAG_REPLACE_EXISTING.
+ </para>
+ <para>
+ The flags argument contains any of the following values logically ORed
+ together:
- <row>
- <entry>
- <para>DBUS_SESSION_BUS_ADDRESS</para>
- </entry>
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Conventional Name</entry>
+ <entry>Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>DBUS_NAME_FLAG_ALLOW_REPLACEMENT</entry>
+ <entry>0x1</entry>
+ <entry>
- <entry>
- <para>the actual address of the server socket</para>
- </entry>
- </row>
+ If an application A specifies this flag and succeeds in
+ becoming the owner of the name, and another application B
+ later calls RequestName with the
+ DBUS_NAME_FLAG_REPLACE_EXISTING flag, then application A
+ will lose ownership and receive a
+ <literal>org.freedesktop.DBus.NameLost</literal> signal, and
+ application B will become the new owner. If DBUS_NAME_FLAG_ALLOW_REPLACEMENT
+ is not specified by application A, or DBUS_NAME_FLAG_REPLACE_EXISTING
+ is not specified by application B, then application B will not replace
+ application A as the owner.
- <row>
- <entry>
- <para>DBUS_SESSION_BUS_PID</para>
- </entry>
+ </entry>
+ </row>
+ <row>
+ <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
+ <entry>0x2</entry>
+ <entry>
- <entry>
- <para>the PID of the server process</para>
- </entry>
- </row>
+ 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 name if there is no current owner. If this flag is set,
+ the application will replace the current owner if
+ the current owner specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT.
- <row>
- <entry>
- <para>DBUS_SESSION_BUS_WINDOWID</para>
- </entry>
+ </entry>
+ </row>
+ <row>
+ <entry>DBUS_NAME_FLAG_DO_NOT_QUEUE</entry>
+ <entry>0x4</entry>
+ <entry>
- <entry>
- <para>the window ID</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
+ Without this flag, if an application requests a name that is
+ already owned, the application will be placed in a queue to
+ own the name when the current owner gives it up. If this
+ flag is given, the application will not be placed in the
+ queue, the request for the name will simply fail. This flag
+ also affects behavior when an application is replaced as
+ name owner; by default the application moves back into the
+ waiting queue, unless this flag was provided when the application
+ became the name owner.
- <para>
- At least the DBUS_SESSION_BUS_ADDRESS variable MUST be present
- in this file.
- </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
- <para>
- Failure to open this file MUST be interpreted as absence of a
- running server. Therefore, the implementation MUST proceed to
- attempting to launch a new bus server if the file cannot be
- opened.
- </para>
+ The return code can be one of the following values:
- <para>
- However, success in opening this file MUST NOT lead to the
- conclusion that the server is running. Thus, a failure to connect to
- the bus address obtained by the alternative method MUST NOT be
- considered a fatal error. If the connection cannot be established,
- the implementation MUST proceed to check the X selection settings or
- to start the server on its own.
- </para>
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Conventional Name</entry>
+ <entry>Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <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
+ DBUS_NAME_FLAG_ALLOW_REPLACEMENT.</entry>
+ </row>
+ <row>
+ <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
+ <entry>2</entry>
- <para>
- If the implementation concludes that the D-Bus server is not
- running it MUST attempt to start a new server and it MUST also
- ensure that the daemon started as an effect of the "autolaunch"
- mechanism provides the lookup mechanisms described above, so
- subsequent calls can locate the newly started server. The
- implementation MUST also ensure that if two or more concurrent
- initiations happen, only one server remains running and all other
- initiations are able to obtain the address of this server and
- connect to it. In other words, the implementation MUST ensure that
- the X selection is not present when it attempts to set it, without
- allowing another process to set the selection between the
- verification and the setting (e.g., by using XGrabServer /
- XungrabServer).
- </para>
- </sect4>
- <sect4>
- <title>Finding session services</title>
- <para>
- On Unix systems, the session bus should search for .service files
- in <literal>$XDG_DATA_DIRS/dbus-1/services</literal> as defined
- by the
- <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG Base Directory Specification</ulink>.
- Implementations may also search additional locations,
- with a higher or lower priority than the XDG directories.
- </para>
- <para>
- As described in the XDG Base Directory Specification, software
- packages should install their session .service files to their
- configured <literal>${datadir}/dbus-1/services</literal>,
- where <literal>${datadir}</literal> is as defined by the GNU
- coding standards. System administrators or users can arrange
- for these service files to be read by setting XDG_DATA_DIRS or by
- symlinking them into the default locations.
- </para>
- </sect4>
- </sect3>
- <sect3 id="message-bus-types-system">
- <title>System message bus</title>
- <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,
- 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
- 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
- for this address, on both client and server side.
- </para>
- </footnote>
+ <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>
</para>
+ </sect3>
+
+ <sect3 id="bus-messages-release-name">
+ <title><literal>org.freedesktop.DBus.ReleaseName</literal></title>
<para>
- On Unix systems, the system bus should default to searching
- for .service files in
- <literal>/usr/local/share/dbus-1/system-services</literal>,
- <literal>/usr/share/dbus-1/system-services</literal> and
- <literal>/lib/dbus-1/system-services</literal>, with that order
- of precedence. It may also search other implementation-specific
- locations, but should not vary these locations based on environment
- variables.
- <footnote>
- <para>
- The system bus is security-sensitive and is typically executed
- by an init system with a clean environment. Its launch helper
- process is particularly security-sensitive, and specifically
- clears its own environment.
- </para>
- </footnote>
+ As a method:
+ <programlisting>
+ UINT32 ReleaseName (in STRING 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>Name to release</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>UINT32</entry>
+ <entry>Return value</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
</para>
<para>
- Software packages should install their system .service
- files to their configured
- <literal>${datadir}/dbus-1/system-services</literal>,
- where <literal>${datadir}</literal> is as defined by the GNU
- coding standards. System administrators can arrange
- for these service files to be read by editing the system bus'
- configuration file or by symlinking them into the default
- locations.
- </para>
- </sect3>
- </sect2>
+ Ask the message bus to release the method caller's claim to the given
+ name. If the caller is the primary owner, a new primary owner will be
+ selected from the queue if any other owners are waiting. If the
+ caller is waiting in the queue for the name, the caller will removed
+ from the queue and will not be made an owner of the name if it later
+ becomes available. If there are no other owners in the queue for the
+ name, it will be removed from the bus entirely.
- <sect2 id="message-bus-messages">
- <title>Message Bus Messages</title>
- <para>
- The special message bus name <literal>org.freedesktop.DBus</literal>
- responds to a number of additional messages.
- </para>
+ The return code can be one of the following values:
- <sect3 id="bus-messages-hello">
- <title><literal>org.freedesktop.DBus.Hello</literal></title>
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Conventional Name</entry>
+ <entry>Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <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
+ the name, and the name is now unused or taken by somebody
+ 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,
+ and was also not waiting in the queue to own this name.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </sect3>
+
+ <sect3 id="bus-messages-list-queued-owners">
+ <title><literal>org.freedesktop.DBus.ListQueuedOwners</literal></title>
<para>
As a method:
<programlisting>
- STRING Hello ()
+ ARRAY of STRING ListQueuedOwners (in STRING name)
</programlisting>
- Reply arguments:
+ Message arguments:
<informaltable>
<tgroup cols="3">
<thead>
@@ -5633,25 +5615,36 @@
<row>
<entry>0</entry>
<entry>STRING</entry>
- <entry>Unique name assigned to the connection</entry>
+ <entry>The well-known bus name to query, such as
+ <literal>com.example.cappuccino</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 STRING</entry>
+ <entry>The unique bus names of connections currently queued
+ for the name</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
- Before an application is able to send messages to other applications
- it must send the <literal>org.freedesktop.DBus.Hello</literal> message
- to the message bus to obtain a unique name. If an application without
- a unique name tries to send a message to another application, or a
- message to the message bus itself that isn't the
- <literal>org.freedesktop.DBus.Hello</literal> message, it will be
- disconnected from the bus.
- </para>
- <para>
- There is no corresponding "disconnect" request; if a client wishes to
- disconnect from the bus, it simply closes the socket (or other
- communication channel).
+ List the connections currently queued for a bus name (see
+ <xref linkend="term-queued-owner"/>).
</para>
</sect3>
<sect3 id="bus-messages-list-names">
--
2.12.2
More information about the dbus
mailing list