Re: [PATCH 1/3] docs: document all of the org.freedesktop.DBus methods together
Tom Gundersen <[email protected]>
| Newsgroups | gmane.comp.freedesktop.dbus |
|---|---|
| Message-ID | <CAG-2HqXkgekqU27gS3qxoxYC-mES6-ABbGZGPYsrGE=XtL72MQ@mail.gmail.com> |
On Tue, Apr 25, 2017 at 2:53 PM, Tom Gundersen <[email protected]> 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 <[email protected]> > --- > 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 > _______________________________________________ dbus mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dbus