<row>
<entry>sndr</entry>
<entry>STRING</entry>
- <entry>The name of the service that sent this message.
+ <entry>The name of the base service that sent this message.
The message bus fills in this field; the field is
only meaningful in combination with the message bus.</entry>
</row>
<sect2 id="auth-protocol-overview">
<title>Protocol Overview</title>
<para>
-The protocol is a line-based protocol, where each line ends with
-\r\n. Each line begins with an all-caps ASCII command name containing
-only the character range [A-Z], a space, then any arguments for the
-command, then the \r\n ending the line. The protocol is
-case-sensitive. All bytes must be in the ASCII character set.
+ The protocol is a line-based protocol, where each line ends with
+ \r\n. Each line begins with an all-caps ASCII command name containing
+ only the character range [A-Z], a space, then any arguments for the
+ command, then the \r\n ending the line. The protocol is
+ case-sensitive. All bytes must be in the ASCII character set.
-Commands from the client to the server are as follows:
+ Commands from the client to the server are as follows:
- <itemizedlist>
+ <itemizedlist>
<listitem><para>AUTH [mechanism] [initial-response]</para></listitem>
<listitem><para>CANCEL</para></listitem
- <listitem><para>BEGIN</para></listitem>
- <listitem><para>DATA <data in base 64 encoding></para></listitem>
- <listitem><para>ERROR [human-readable error explanation]</para></listitem>
+
<listitem><para>BEGIN</para></listitem>
+
<listitem><para>DATA <data in base 64 encoding></para></listitem>
+
<listitem><para>ERROR [human-readable error explanation]</para></listitem>
</itemizedlist>
-From server to client are as follows:
+ From server to client are as follows:
<itemizedlist>
<listitem><para>REJECTED <space-separated list of mechanism names></para></listitem>
<sect2 id="auth-nul-byte">
<title>Special credentials-passing nul byte</title>
<para>
-Immediately after connecting to the server, the client must send a
-single nul byte. This byte may be accompanied by credentials
-information on some operating systems that use sendmsg() with
-SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain
-sockets. However, the nul byte MUST be sent even on other kinds of
-socket, and even on operating systems that do not require a byte to be
-sent in order to transmit credentials. The text protocol described in
-this document begins after the single nul byte. If the first byte
-received from the client is not a nul byte, the server may disconnect
-that client.
-</para>
-<para>
-A nul byte in any context other than the initial byte is an error;
-the protocol is ASCII-only.
-</para>
-<para>
-The credentials sent along with the nul byte may be used with the
-SASL mechanism EXTERNAL.
+ Immediately after connecting to the server, the client must send a
+ single nul byte. This byte may be accompanied by credentials
+ information on some operating systems that use sendmsg() with
+ SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain
+ sockets. However, the nul byte MUST be sent even on other kinds of
+ socket, and even on operating systems that do not require a byte to be
+ sent in order to transmit credentials. The text protocol described in
+ this document begins after the single nul byte. If the first byte
+ received from the client is not a nul byte, the server may disconnect
+ that client.
+ </para>
+ A nul byte in any context other than the initial byte is an error;
+ the protocol is ASCII-only.
+ </para>
+ The credentials sent along with the nul byte may be used with the
+ SASL mechanism EXTERNAL.
</para>
</sect2>
<sect2 id="auth-command-auth">
<title>AUTH command</title>
-<para>
- If an AUTH command has no arguments, it is a request to list
- available mechanisms. The server SHOULD respond with a REJECTED
- command listing the mechanisms it understands.
-</para>
-<para>
- If an AUTH command specifies a mechanism, and the server supports
- said mechanism, the server SHOULD begin exchanging SASL
- challenge-response data with the client using DATA commands.
-</para>
-<para>
- If the server does not support the mechanism given in the AUTH
- command, it SHOULD send a REJECTED command listing the mechanisms
- it does support.
-</para>
-<para>
- If the [initial-response] argument is provided, it is intended for
- use with mechanisms that have no initial challenge (or an empty
- initial challenge), as if it were the argument to an initial DATA
- command. If the selected mechanism has an initial challenge, the
- server should reject authentication by sending REJECTED.
-</para>
-<para>
- If authentication succeeds after exchanging DATA commands,
- an OK command should be sent to the client.
-</para>
-<para>
- The first octet received by the client after the \r\n of the OK
- command MUST be the first octet of the authenticated/encrypted
- stream of D-BUS messages.
-</para>
-<para>
- The first octet received by the server after the \r\n of the BEGIN
- command from the client MUST be the first octet of the
- authenticated/encrypted stream of D-BUS messages.
-</para>
+ If an AUTH command has no arguments, it is a request to list
+ available mechanisms. The server SHOULD respond with a REJECTED
+ command listing the mechanisms it understands.
+ </para>
+ If an AUTH command specifies a mechanism, and the server supports
+ said mechanism, the server SHOULD begin exchanging SASL
+ challenge-response data with the client using DATA commands.
+ </para>
+ If the server does not support the mechanism given in the AUTH
+ command, it SHOULD send a REJECTED command listing the mechanisms
+ it does support.
+ </para>
+ If the [initial-response] argument is provided, it is intended for
+ use with mechanisms that have no initial challenge (or an empty
+ initial challenge), as if it were the argument to an initial DATA
+ command. If the selected mechanism has an initial challenge, the
+ server should reject authentication by sending REJECTED.
+ </para>
+ If authentication succeeds after exchanging DATA commands,
+ an OK command should be sent to the client.
+ </para>
+ The first octet received by the client after the \r\n of the OK
+ command MUST be the first octet of the authenticated/encrypted
+ stream of D-BUS messages.
+ </para>
+ The first octet received by the server after the \r\n of the BEGIN
+ command from the client MUST be the first octet of the
+ authenticated/encrypted stream of D-BUS messages.
+ </para>
</sect2>
- <sect2 id="auth-command-cancel">
- <title>CANCEL Command</title>
- <para>
- At any time up to sending the BEGIN command, the client may send a
- CANCEL command. On receiving the CANCEL command, the server MUST
- send a REJECTED command and abort the current authentication
- exchange.
- </para>
- </sect2>
- <sect2 id="auth-command-data">
- <title>DATA Command</title>
- <para>
- The DATA command may come from either client or server, and simply
- contains a base64-encoded block of data to be interpreted
- according to the SASL mechanism in use.
- </para>
- <para>
- Some SASL mechanisms support sending an "empty string";
- FIXME we need some way to do this.
- </para>
- </sect2>
- <sect2 id="auth-command-begin">
- <title>BEGIN Command</title>
- <para>
- The BEGIN command acknowledges that the client has received an
- OK command from the server, and that the stream of messages
- is about to begin.
- </para>
- <para>
- The first octet received by the server after the \r\n of the BEGIN
- command from the client MUST be the first octet of the
- authenticated/encrypted stream of D-BUS messages.
- </para>
- </sect2>
- <sect2 id="auth-command-rejected">
- <title>REJECTED Command</title>
- <para>
- The REJECTED command indicates that the current authentication
- exchange has failed, and further exchange of DATA is inappropriate.
- The client would normally try another mechanism, or try providing
- different responses to challenges.
- </para><para>
- Optionally, the REJECTED command has a space-separated list of
- available auth mechanisms as arguments. If a server ever provides
- a list of supported mechanisms, it MUST provide the same list
- each time it sends a REJECTED message. Clients are free to
- ignore all lists received after the first.
- </para>
- </sect2>
- <sect2 id="auth-command-ok">
- <title>OK Command</title>
- <para>
- The OK command indicates that the client has been authenticated,
- and that further communication will be a stream of D-BUS messages
- (optionally encrypted, as negotiated) rather than this protocol.
- </para>
- <para>
- The first octet received by the client after the \r\n of the OK
- command MUST be the first octet of the authenticated/encrypted
- stream of D-BUS messages.
- </para>
- <para>
- The client MUST respond to the OK command by sending a BEGIN
- command, followed by its stream of messages, or by disconnecting.
- The server MUST NOT accept additional commands using this protocol
- after the OK command has been sent.
- </para>
- </sect2>
- <sect2 id="auth-command-error">
- <title>ERROR Command</title>
- <para>
- The ERROR command indicates that either server or client did not
- know a command, does not accept the given command in the current
- context, or did not understand the arguments to the command. This
- allows the protocol to be extended; a client or server can send a
- command present or permitted only in new protocol versions, and if
- an ERROR is received instead of an appropriate response, fall back
- to using some other technique.
- </para><para>
- If an ERROR is sent, the server or client MUST continue as if the
- command causing the ERROR had never been received.
- </para>
- </sect2>
- <sect2 id="auth-examples">
+ <sect2 id="auth-command-cancel">
+ <title>CANCEL Command</title>
+ At any time up to sending the BEGIN command, the client may send a
+ CANCEL command. On receiving the CANCEL command, the server MUST
+ send a REJECTED command and abort the current authentication
+ exchange.
+ </para>
+ </sect2>
+ <sect2 id="auth-command-data">
+ <title>DATA Command</title>
+ The DATA command may come from either client or server, and simply
+ contains a base64-encoded block of data to be interpreted
+ according to the SASL mechanism in use.
+ </para>
+ Some SASL mechanisms support sending an "empty string";
+ FIXME we need some way to do this.
+ </para>
+ </sect2>
+ <sect2 id="auth-command-begin">
+ <title>BEGIN Command</title>
+ The BEGIN command acknowledges that the client has received an
+ OK command from the server, and that the stream of messages
+ is about to begin.
+ </para>
+ The first octet received by the server after the \r\n of the BEGIN
+ command from the client MUST be the first octet of the
+ authenticated/encrypted stream of D-BUS messages.
+ </para>
+ </sect2>
+ <sect2 id="auth-command-rejected">
+ <title>REJECTED Command</title>
+ The REJECTED command indicates that the current authentication
+ exchange has failed, and further exchange of DATA is inappropriate.
+ The client would normally try another mechanism, or try providing
+ different responses to challenges.
+ Optionally, the REJECTED command has a space-separated list of
+ available auth mechanisms as arguments. If a server ever provides
+ a list of supported mechanisms, it MUST provide the same list
+ each time it sends a REJECTED message. Clients are free to
+ ignore all lists received after the first.
+ </para>
+ </sect2>
+ <sect2 id="auth-command-ok">
+ <title>OK Command</title>
+ The OK command indicates that the client has been authenticated,
+ and that further communication will be a stream of D-BUS messages
+ (optionally encrypted, as negotiated) rather than this protocol.
+ </para>
+ The first octet received by the client after the \r\n of the OK
+ command MUST be the first octet of the authenticated/encrypted
+ stream of D-BUS messages.
+ </para>
+ The client MUST respond to the OK command by sending a BEGIN
+ command, followed by its stream of messages, or by disconnecting.
+ The server MUST NOT accept additional commands using this protocol
+ after the OK command has been sent.
+ </para>
+ </sect2>
+ <sect2 id="auth-command-error">
+ <title>ERROR Command</title>
+ The ERROR command indicates that either server or client did not
+ know a command, does not accept the given command in the current
+ context, or did not understand the arguments to the command. This
+ allows the protocol to be extended; a client or server can send a
+ command present or permitted only in new protocol versions, and if
+ an ERROR is received instead of an appropriate response, fall back
+ to using some other technique.
+ If an ERROR is sent, the server or client MUST continue as if the
+ command causing the ERROR had never been received.
+ </para>
+ </sect2>
+ <sect2 id="auth-examples">
<title>Authentication examples</title>
<para>
- <figure>
+ <figure>
<title>Example of successful magic cookie authentication</title>
<programlisting>
-(MAGIC_COOKIE is a made up mechanism)
+ (MAGIC_COOKIE is a made up mechanism)
- C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
- S: OK
- C: BEGIN
+ C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
+ S: OK
+ C: BEGIN
</programlisting>
</figure>
- <figure>
+ <figure>
<title>Example of finding out mechanisms then picking one</title>
<programlisting>
- C: AUTH
- S: REJECTED KERBEROS_V4 SKEY
- C: AUTH SKEY bW9yZ2Fu
- S: DATA OTUgUWE1ODMwOA==
- C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
- S: OK
- C: BEGIN
+ C: AUTH
+ S: REJECTED KERBEROS_V4 SKEY
+ C: AUTH SKEY bW9yZ2Fu
+ S: DATA OTUgUWE1ODMwOA==
+ C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
+ S: OK
+ C: BEGIN
</programlisting>
</figure>
- <figure>
+ <figure>
<title>Example of client sends unknown command then falls back to regular auth</title>
<programlisting>
- C: FOOBAR
- S: ERROR
- C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
- S: OK
- C: BEGIN
+ C: FOOBAR
+ S: ERROR
+ C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
+ S: OK
+ C: BEGIN
</programlisting>
</figure>
- <figure>
+ <figure>
<title>Example of server doesn't support initial auth mechanism</title>
<programlisting>
- C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
- S: REJECTED KERBEROS_V4 SKEY
- C: AUTH SKEY bW9yZ2Fu
- S: DATA OTUgUWE1ODMwOA==
- C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
- S: OK
- C: BEGIN
+ C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
+ S: REJECTED KERBEROS_V4 SKEY
+ C: AUTH SKEY bW9yZ2Fu
+ S: DATA OTUgUWE1ODMwOA==
+ C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
+ S: OK
+ C: BEGIN
</programlisting>
</figure>
- <figure>
+ <figure>
<title>Example of wrong password or the like followed by successful retry</title>
<programlisting>
- C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
- S: REJECTED KERBEROS_V4 SKEY
- C: AUTH SKEY bW9yZ2Fu
- S: DATA OTUgUWE1ODMwOA==
- C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
- S: REJECTED
- C: AUTH SKEY bW9yZ2Fu
- S: DATA OTUgUWE1ODMwOA==
- C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
- S: OK
- C: BEGIN
+ C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
+ S: REJECTED KERBEROS_V4 SKEY
+ C: AUTH SKEY bW9yZ2Fu
+ S: DATA OTUgUWE1ODMwOA==
+ C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
+ S: REJECTED
+ C: AUTH SKEY bW9yZ2Fu
+ S: DATA OTUgUWE1ODMwOA==
+ C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
+ S: OK
+ C: BEGIN
</programlisting>
</figure>
- <figure>
+ <figure>
<title>Example of skey cancelled and restarted</title>
<programlisting>
- C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
- S: REJECTED KERBEROS_V4 SKEY
- C: AUTH SKEY bW9yZ2Fu
- S: DATA OTUgUWE1ODMwOA==
- C: CANCEL
- S: REJECTED
- C: AUTH SKEY bW9yZ2Fu
- S: DATA OTUgUWE1ODMwOA==
- C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
- S: OK
- C: BEGIN
+ C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
+ S: REJECTED KERBEROS_V4 SKEY
+ C: AUTH SKEY bW9yZ2Fu
+ S: DATA OTUgUWE1ODMwOA==
+ C: CANCEL
+ S: REJECTED
+ C: AUTH SKEY bW9yZ2Fu
+ S: DATA OTUgUWE1ODMwOA==
+ C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
+ S: OK
+ C: BEGIN
</programlisting>
</figure>
</para>
<para>
Server addresses consist of a transport name followed by a colon, and
then an optional, comma-separated list of keys and values in the form key=value.
+ [FIXME how do you escape colon, comma, and semicolon in the values of the key=value pairs?]
</para>
<para>
For example:
Which is the address to a unix socket with the path /tmp/dbus-test.
</para>
<para>
+ [FIXME clarify if attempting to connect to each is a requirement
+ or just a suggestion]
When connecting to a server, multiple server addresses can be
separated by a semi-colon. The library will then try to connect
to the first address and if that fails, it'll try to connect to
<programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
</para>
<para>
+ [FIXME we need to specify in detail each transport and its possible arguments]
Currently, a transport over local UNIX sockets exists, a debug
transport that only works in-process and therefore can be used
for for unit testing also exists. It is possible that other
<para>
A reply to a message conventionally has the same name as the message
being replied to. When following method call conventions (see <xref
- linkend="message-conventions-method">), this convention is mandatory,
+ linkend="message-conventions-method">), this convention is mandatory,
because a message with multiple possible replies can't be mapped
to method call semantics without special-case code.
</para>
an application should reply with
<literal>org.freedesktop.Peer.Ping</literal>. Neither the
message nor its reply have any arguments.
- [FIXME the messages here are just made up to illustrate the
- format for defining them]
+ [FIXME the messages here are just made up to illustrate the
+ format for defining them]
</para>
</sect2>
<sect2 id="standard-messages-get-props">
</para>
<para>
- [FIXME the messages here are just made up to illustrate the
- format for defining them]
+ [FIXME the messages here are just made up to illustrate the
+ format for defining them]
</para>
</sect2>
</sect1>
</para>
<para>
Messages may have a <literal>srvc</literal> field (see <xref
- linkend="message-protocol-header-fields">). When the message bus
- receives a message, if the <literal>srvc</literal> field is absent, the
- message is taken to be a standard peer-to-peer message and interpreted
- by the message bus itself. For example, sending
+ linkend="message-protocol-header-fields">). When the message bus
+ receives a message, if the <literal>srvc</literal> field is absent, the
+ message is taken to be a standard peer-to-peer message and interpreted
+ by the message bus itself. For example, sending
an <literal>org.freedesktop.Peer.Ping</literal> message with no
<literal>srvc</literal> will cause the message bus itself to reply
to the ping immediately; the message bus would never make
messages are routed to the owner of the named service.
Messages may also be <firstterm>broadcast</firstterm>
by sending them to the special service
- <literal>org.freedesktop.Broadcast</literal>. Broadcast messages
- are sent to all applications with <firstterm>message matching rules</firstterm>
- that match the message.
+ <literal>org.freedesktop.Broadcast</literal>. Broadcast messages are
+ sent to all applications with <firstterm>message matching
+ rules</firstterm> that match the message.
</para>
<para>
Continuing the <literal>org.freedesktop.Peer.Ping</literal> example, if
might receive the ping, and all would normally reply to it.
</para>
</sect2>
- <sect2 id="message-bus-messages">
- <title>Message Bus Messages</title>
- <para>
- The special message bus service <literal>org.freedesktop.DBus</literal>
- responds to a number of messages, allowing applications to
- interact with the message bus.
- </para>
- </sect2>
- <sect2 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>Name of the service assigned to the client</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- Before a client is able to send messages to other clients it
- must send the <literal>org.freedesktop.DBus.Hello</literal>
- message to the message bus service. If a client tries to send
- a message to another client, or a message to the message bus
- service that isn't the
- <literal>org.freedesktop.DBus.Hello</literal> message, it will
- be disconnected from the bus.
- </para>
- <para>
- The reply message contains the name of the base service. Any
- messages sent to the base service will be rereouted by the
- message bus, delivering it to the client.
- </para>
- </sect2>
- <sect2 id="bus-messages-list-services">
- <title><literal>org.freedesktop.DBus.ListServices</literal></title>
- <para>
- As a method:
- <programlisting>
- STRING_ARRAY ListServices ()
- </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_ARRAY</entry>
- <entry>Array of strings where each string is the name of a service</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- Returns a list of all existing services registered with the message bus.
- </para>
- </sect2>
- <sect2 id="bus-messages-service-exists">
- <title><literal>org.freedesktop.DBus.ServiceExists</literal></title>
- <para>
- As a method:
- <programlisting>
- UINT32 ServiceExists (in STRING service_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 of the service</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, 1 if the service exists and 0 otherwise</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- Checks if a service with a specified name exists.
- </para>
- </sect2>
-
- <sect2 id="bus-messages-acquire-service">
- <title><literal>org.freedesktop.DBus.AcquireService</literal></title>
- <para>
- As a method:
- <programlisting>
- UINT32 AcquireService (in STRING service_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 of the service</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>
- Tries to become owner of a specific service. The flags
- specified can be the following values logically ORed together:
-
- <informaltable>
- <tgroup cols=3>
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Value</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT</entry>
- <entry>0x1</entry>
- <entry>
- If the client succeeds in being the owner of the specified service,
- then ownership of the service can't be transferred until the service
- disconnects. If this flag is not set, then any client trying to become
- the owner of the service will succeed and the previous owner will be
- sent a <literal>org.freedesktop.DBus.ServiceLost</literal> message.
-</entry>
- </row>
- <row>
- <entry>DBUS_SERVICE_FLAGS_REPLACE_EXISTING</entry>
- <entry>0x2</entry>
- <entry>Only become the owner of the service if there is no current owner.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- The return value can be one of the following values:
-
- <informaltable>
- <tgroup cols=3>
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Value</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>DBUS_SERVICE_REPLY_PRIMARY_OWNER</entry>
- <entry>0x1</entry>
- <entry>The client is now the primary owner of the service.</entry>
- </row>
- <row>
- <entry>DBUS_SERVICE_REPLY_IN_QUEUE</entry>
- <entry>0x2</entry>
- <entry>The service already has an owner which do not want to give up ownership and therefore the client has been put in a queue.</entry>
- </row>
- <row>
- <entry>DBUS_SERVICE_REPLY_SERVICE_EXISTS</entry>
- <entry>0x4</entry>
- <entry>The service does already have a primary owner, and DBUS_SERVICE_FLAG_REPLACE_EXISTING was not specified when trying to acquire the service.</entry>
- </row>
- <row>
- <entry>DBUS_SERVICE_REPLY_ALREADY_OWNER</entry>
- <entry>0x8</entry>
- <entry>The client trying to request ownership of the service is already the owner of it.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </sect2>
- <sect2 id="bus-messages-service-acquired">
- <title><literal>org.freedesktop.DBus.ServiceAcquired</literal></title>
- <para>
- As a method:
- <programlisting>
- ServiceAcquired (in STRING service_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 of the service</entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>UINT32</entry>
- <entry>Flags</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- This message is sent to a specific client when it becomes the primary owner of a service.
- </para>
- </sect2>
- <sect2 id="bus-messages-service-lost">
- <title><literal>org.freedesktop.DBus.ServiceLost</literal></title>
- <para>
- As a method:
- <programlisting>
- ServiceLost (in STRING service_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 of the service</entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>UINT32</entry>
- <entry>Flags</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- This message is sent to a specific client when it loses primary ownership of a service.
- </para>
- </sect2>
-
- <sect2 id="bus-messages-service-created">
- <title><literal>org.freedesktop.DBus.ServiceCreated</literal></title>
- <para>
- As a method:
- <programlisting>
- ServiceCreated (in STRING service_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 of the service</entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>UINT32</entry>
- <entry>Flags</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- This message is broadcast to all clients when a service has been successfully registered on the message bus.
- </para>
- </sect2>
- <sect2 id="bus-messages-service-deleted">
- <title><literal>org.freedesktop.DBus.ServiceDeleted</literal></title>
- <para>
- As a method:
- <programlisting>
- ServiceDeleted (in STRING service_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 of the service</entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>UINT32</entry>
- <entry>Flags</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- This message is broadcast to all clients when a service has been deleted from the message bus.
- </para>
- </sect2>
-
- <sect2 id="bus-messages-activate-service">
- <title><literal>org.freedesktop.DBus.ActivateService</literal></title>
+ <sect2 id="message-bus-services">
+ <title>Message Bus Services</title>
<para>
- As a method:
- <programlisting>
- void ActivateService (in STRING service_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 of the service to activate</entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>UINT32</entry>
- <entry>Flags (currently not used)</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
+ A service is a name that identifies a certain application. Each
+ application connected to the message bus has at least one service name
+ assigned at connection time and returned in response to the
+ <literal>org.freedesktop.DBus.Hello</literal> message.
+ This automatically-assigned service name is called
+ the application's <firstterm>base service</firstterm>.
+ Base service names are unique and MUST never be reused for two different
+ applications.
</para>
<para>
- Tries to launch the executable associated with a service. For more information, see the part on <xref linkend="message-bus-activation">
+ [FIXME I think we should define the format of the base service name,
+ and specify that a regular service name can never be in that
+ format; this allows us to categorically prevent "spoofing" - for
+ example perhaps the base service name starts with a certain
+ character that no real service name can start with]
</para>
- </sect2>
-
- <sect2 id="services">
- <title>Message Bus Services</title>
<para>
- A service is a name that identifies a certain client. Each
- client connected to the message bus has at least one service
- name acquired through the
- <literal>org.freedesktop.DBus.Hello</literal> message. In
- addition, a client can request additional service names to be
- associated with it using the
+ An application can request additional service names to be associated
+ with it using the
<literal>org.freedesktop.DBus.AcquireService</literal>
- message.
+ message. [FIXME what service names are allowed; ASCII or unicode;
+ length limit; etc.]
</para>
<para>
+ [FIXME this needs more detail, and should move the service-related message
+ descriptions up into this section perhaps]
Service ownership handling can be specified in the flags part
of the <literal>org.freedesktop.DBus.AcquireService</literal>
- message. If a client specifies the
- DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT flag, then all clients
+ message. If an application specifies the
+ DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT flag, then all applications
trying to acquire the service will be put in a queue. When the
primary owner disconnects from the bus or removes ownership
- from the service, the next client in the queue will be the
+ from the service, the next application in the queue will be the
primary owner. If the DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT
flag is not specified, then the primary owner will lose
- ownership whenever another client requests ownership of the
+ ownership whenever another application requests ownership of the
service.
</para>
</sect2>
+ <sect2 id="message-bus-routing">
+ <title>Message Bus Message Routing</title>
+ <para>
+ When a message is received by the message bus, the message's
+ <literal>sndr</literal> header field MUST be set to the base service of
+ the application which sent the message. If the service already has
+ a <literal>sndr</literal> field, the pre-existing field is replaced.
+ This rule means that a replies are always sent to the base service name,
+ i.e. to the same application that sent the message being replied to.
+ </para>
+ <para>
+ [FIXME go into detail about broadcast, multicast, unicast, etc.]
+ </para>
+ </sect2>
<sect2 id="message-bus-activation">
<title>Message Bus Service Activation</title>
<para>
- Activation is a way to launch executables that handle certain
- services. The bus daemon looks in certain directories
- (possibly different depending on if it's a system bus or a
- message bus) for service description files.
+ <firstterm>Activation</firstterm> means to locate a service
+ owner for a service that is currently unowned. For now, it
+ means to launch an executable that will take ownership of
+ a particular service.
</para>
<para>
+ To find an executable corresponding to a particular service, the bus
+ daemon looks for <firstterm>service description files</firstterm>.
+ Service description files define a mapping from service names to
+ executables. Different kinds of message bus will look for these files
+ in different places, see <xref linkend="message-bus-types">.
+ </para>
+ <para>
+ [FIXME the file format should be much better specified than
+ "similar to .desktop entries" esp. since desktop entries
+ are already badly-specified. ;-)]
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://www.freedesktop.org/standards/desktop-entry-spec/desktop-entry-spec.html">desktop
- entries</ulink>. All service description files must be in
+ url="http://www.freedesktop.org/standards/desktop-entry-spec/desktop-entry-spec.html">desktop
+ entries</ulink>. All service description files must be in
UTF-8 encoding.
<figure>
</figure>
</para>
<para>
- When a client requests a service to be activated, the bus
+ When an application requests a service to be activated, the bus
daemon tries to find it in the list of activation entries. It
then tries to spawn the executable associated with it. If this
- fails, it will report an error.
+ fails, it will report an error. [FIXME what happens if two
+ .service files offer the same service; what kind of error is reported]
</para>
<para>
The executable launched will have the environment variable
- <literal>DBUS_ADDRESS</literal> set to the address of the
- server so it can connect and register the appropriate services.
+ <literal>DBUS_BUS_ADDRESS</literal> set to the address of the
+ message bus so it can connect and register the appropriate services.
</para>
</sect2>
- <sect2 id="message-bus-location">
- <title>Finding The Message Bus</title>
+
+ <sect2 id="message-bus-types">
+ <title>Standard Message Bus Instances</title>
<para>
Two standard message bus instances are defined here, along with how
- to locate them.
- </para>
- <para>
- Each time a user logs in, a <firstterm>login session message
- bus</firstterm> may be started. All applications in the user's login
- session may interact with one another using this message bus. [specify
- how to find the address of the login session message bus via
- environment variable and/or X property]
+ to locate them and where their service files live.
</para>
+ <sect3 id="message-bus-types-login">
+ <title>Login session message bus</title>
+ <para>
+ Each time a user logs in, a <firstterm>login session message
+ bus</firstterm> may be started. All applications in the user's login
+ session may interact with one another using this message bus. [specify
+ how to find the address of the login session message bus via
+ environment variable and/or X property]
+ </para>
+ <para>
+ [FIXME specify location of .service files, probably using
+ DESKTOP_DIRS etc. from basedir specification, though login session
+ bus is not really desktop-specific]
+ </para>
+ </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.
+ [specify how to find the address of the system message bus]
+ </para>
+ <para>
+ [FIXME specify location of system bus .service files]
+ </para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="message-bus-messages">
+ <title>Message Bus Messages</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.
- [specify how to find the address of the system message bus]
+ The special message bus service <literal>org.freedesktop.DBus</literal>
+ responds to a number of messages, allowing applications to
+ interact with the message bus.
</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>Name of the service assigned to the application</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 service. If an application tries to send
+ a message to another application, or a message to the message bus
+ service that isn't the
+ <literal>org.freedesktop.DBus.Hello</literal> message, it will
+ be disconnected from the bus.
+ </para>
+ <para>
+ The reply message contains the name of the application's base service.
+ </para>
+ </sect3>
+ <sect3 id="bus-messages-list-services">
+ <title><literal>org.freedesktop.DBus.ListServices</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ STRING_ARRAY ListServices ()
+ </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_ARRAY</entry>
+ <entry>Array of strings where each string is the name of a service</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ Returns a list of all existing services registered with the message bus.
+ </para>
+ </sect3>
+ <sect3 id="bus-messages-service-exists">
+ <title><literal>org.freedesktop.DBus.ServiceExists</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ UINT32 ServiceExists (in STRING service_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 of the service</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, 1 if the service exists and 0 otherwise</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ Checks if a service with a specified name exists.
+ </para>
+ </sect3>
+
+ <sect3 id="bus-messages-acquire-service">
+ <title><literal>org.freedesktop.DBus.AcquireService</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ UINT32 AcquireService (in STRING service_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 of the service</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>
+ Tries to become owner of a specific service. The flags
+ specified can be the following values logically ORed together:
+
+ <informaltable>
+ <tgroup cols=3>
+ <thead>
+ <row>
+ <entry>Identifier</entry>
+ <entry>Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT</entry>
+ <entry>0x1</entry>
+ <entry>
+ If the application succeeds in being the owner of the specified service,
+ then ownership of the service can't be transferred until the service
+ disconnects. If this flag is not set, then any application trying to become
+ the owner of the service will succeed and the previous owner will be
+ sent a <literal>org.freedesktop.DBus.ServiceLost</literal> message.
+ </entry>
+ </row>
+ <row>
+ <entry>DBUS_SERVICE_FLAGS_REPLACE_EXISTING</entry>
+ <entry>0x2</entry>
+ <entry>Only become the owner of the service if there is no current owner.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ [FIXME if it's one of the following values, why are the values
+ done as flags instead of just 0, 1, 2, 3, 4]
+ The return value can be one of the following values:
+
+ <informaltable>
+ <tgroup cols=3>
+ <thead>
+ <row>
+ <entry>Identifier</entry>
+ <entry>Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>DBUS_SERVICE_REPLY_PRIMARY_OWNER</entry>
+ <entry>0x1</entry>
+ <entry>The application is now the primary owner of the service.</entry>
+ </row>
+ <row>
+ <entry>DBUS_SERVICE_REPLY_IN_QUEUE</entry>
+ <entry>0x2</entry>
+ <entry>The service already has an owner which do not want to give up ownership and therefore the application has been put in a queue.</entry>
+ </row>
+ <row>
+ <entry>DBUS_SERVICE_REPLY_SERVICE_EXISTS</entry>
+ <entry>0x4</entry>
+ <entry>The service does already have a primary owner, and DBUS_SERVICE_FLAG_REPLACE_EXISTING was not specified when trying to acquire the service.</entry>
+ </row>
+ <row>
+ <entry>DBUS_SERVICE_REPLY_ALREADY_OWNER</entry>
+ <entry>0x8</entry>
+ <entry>The application trying to request ownership of the service is already the owner of it.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </sect3>
+ <sect3 id="bus-messages-service-acquired">
+ <title><literal>org.freedesktop.DBus.ServiceAcquired</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ ServiceAcquired (in STRING service_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 of the service</entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>UINT32</entry>
+ <entry>Flags</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ This message is sent to a specific application when it becomes the
+ primary owner of a service.
+ </para>
+ </sect3>
+ <sect3 id="bus-messages-service-lost">
+ <title><literal>org.freedesktop.DBus.ServiceLost</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ ServiceLost (in STRING service_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 of the service</entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>UINT32</entry>
+ <entry>Flags</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ This message is sent to a specific application when it loses primary
+ ownership of a service.
+
+ [FIXME instead of ServiceLost/ServiceCreated going only to
+ a specific app, why not just OwnerChanged that covers both
+ lost and created and changed owner and deleted]
+ </para>
+ </sect3>
+
+ <sect3 id="bus-messages-service-created">
+ <title><literal>org.freedesktop.DBus.ServiceCreated</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ ServiceCreated (in STRING service_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 of the service</entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>UINT32</entry>
+ <entry>Flags</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ This message is broadcast to all applications when a service has been
+ successfully registered on the message bus.
+ </para>
+ </sect3>
+
+ <sect3 id="bus-messages-service-deleted">
+ <title><literal>org.freedesktop.DBus.ServiceDeleted</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ ServiceDeleted (in STRING service_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 of the service</entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>UINT32</entry>
+ <entry>Flags</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ This message is broadcast to all applications when a service has been
+ deleted from the message bus.
+ </para>
+ </sect3>
+
+ <sect3 id="bus-messages-activate-service">
+ <title><literal>org.freedesktop.DBus.ActivateService</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ void ActivateService (in STRING service_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 of the service to activate</entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>UINT32</entry>
+ <entry>Flags (currently not used)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ Tries to launch the executable associated with a service. For more information, see <xref linkend="message-bus-activation">.
+
+ [FIXME need semantics in much more detail here; for example,
+ if I activate a service then send it a message, is the message
+ queued for the new service or is there a race]
+ </para>
+ </sect3>
</sect2>
+
</sect1>
<!--
<appendix id="implementation-notes">
This glossary defines some of the terms used in this specification.
</para>
+ <glossentry id="term-activation"><glossterm>Activation</glossterm>
+ <glossdef>
+ <para>
+ The process of creating an owner for a particular service,
+ typically by launching an executable.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="term-base-service"><glossterm>Base Service</glossterm>
+ <glossdef>
+ <para>
+ The special service automatically assigned to an application by the
+ message bus. This service may never change owner, and the service
+ name will be unique (never reused during the lifetime of the
+ message bus).
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="term-broadcast"><glossterm>Broadcast</glossterm>
<glossdef>
<para>
A message sent to the special <literal>org.freedesktop.Broadcast</literal>
service; the message bus will forward the broadcast message
- to all clients that have expressed interest in it.
+ to all applications that have expressed interest in it.
</para>
</glossdef>
</glossentry>
</glossdef>
</glossentry>
+ <glossentry id="term-service-description-files"><glossterm>Service Description Files</glossterm>
+ <glossdef>
+ <para>
+ ".service files" tell the bus how to activate a particular service.
+ See <xref linkend="term-activation">
+ </para>
+ </glossdef>
+ </glossentry>
+
</glossary>
</article>
projects / platform / upstream / dbus.git / commitdiff