[PATCH 1/3] docs: document all of the org.freedesktop.DBus methods together
Tom Gundersen
teg at jklm.no
Tue Apr 25 12:56:23 UTC 2017
On Tue, Apr 25, 2017 at 2:53 PM, Tom Gundersen <teg at jklm.no> wrote:
> 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.
It appears git got the better of me with this patch. Please view it
with "git show --minimal" or something like that to get the actual
changed lines (mostly just moved a few paragraphs around).
Cheers,
Tom
> 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