From c62323786c49a7082307b1cf6320c5ee6c1afdaa Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Tue, 18 Feb 2003 03:08:04 +0000 Subject: 2003-02-17 Havoc Pennington * doc/dbus-specification.sgml: lots of cosmetic cleanups/rearrangement, add assorted FIXME, change DBUS_ADDRESS env variable to DBUS_BUS_ADDRESS, s/client/application/, s/server/bus/ (except in authentication section). Add a section "Message Bus Message Routing" --- doc/dbus-specification.sgml | 1472 +++++++++++++++++++++++-------------------- 1 file changed, 788 insertions(+), 684 deletions(-) (limited to 'doc/dbus-specification.sgml') diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml index e94980f2..fc48d337 100644 --- a/doc/dbus-specification.sgml +++ b/doc/dbus-specification.sgml @@ -244,7 +244,7 @@ sndr STRING - The name of the service that sent this message. + 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. @@ -419,23 +419,23 @@ Protocol Overview -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: - + AUTH [mechanism] [initial-response] CANCELBEGIN - DATA <data in base 64 encoding> - ERROR [human-readable error explanation] + BEGIN + DATA <data in base 64 encoding> + ERROR [human-readable error explanation] -From server to client are as follows: + From server to client are as follows: REJECTED <space-separated list of mechanism names> @@ -448,227 +448,227 @@ From server to client are as follows: Special credentials-passing nul byte -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. - - -A nul byte in any context other than the initial byte is an error; -the protocol is ASCII-only. - - -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. + + + A nul byte in any context other than the initial byte is an error; + the protocol is ASCII-only. + + + The credentials sent along with the nul byte may be used with the + SASL mechanism EXTERNAL. AUTH command - - 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. - - - 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. - - - 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. - - - 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. - - - If authentication succeeds after exchanging DATA commands, - an OK command should be sent to the client. - - - 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. - - - 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. - + + 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. + + + 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. + + + 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. + + + 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. + + + If authentication succeeds after exchanging DATA commands, + an OK command should be sent to the client. + + + 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. + + + 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. + - - CANCEL Command - - 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. - - - - DATA Command - - 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. - - - Some SASL mechanisms support sending an "empty string"; - FIXME we need some way to do this. - - - - BEGIN Command - - 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. - - - 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. - - - - REJECTED Command - - 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. - - - - OK Command - - 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. - - - 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. - - - 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. - - - - ERROR Command - - 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. - - - + + CANCEL Command + + 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. + + + + DATA Command + + 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. + + + Some SASL mechanisms support sending an "empty string"; + FIXME we need some way to do this. + + + + BEGIN Command + + 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. + + + 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. + + + + REJECTED Command + + 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. + + + + OK Command + + 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. + + + 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. + + + 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. + + + + ERROR Command + + 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. + + + Authentication examples -
+
Example of successful magic cookie authentication -(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
-
+
Example of finding out mechanisms then picking one - 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
-
+
Example of client sends unknown command then falls back to regular auth - 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
-
+
Example of server doesn't support initial auth mechanism - 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
-
+
Example of wrong password or the like followed by successful retry - 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
-
+
Example of skey cancelled and restarted - 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
@@ -679,6 +679,7 @@ SASL mechanism EXTERNAL. 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?] For example: @@ -686,6 +687,8 @@ SASL mechanism EXTERNAL. Which is the address to a unix socket with the path /tmp/dbus-test. + [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 @@ -693,6 +696,7 @@ SASL mechanism EXTERNAL. unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2 + [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 @@ -752,7 +756,7 @@ SASL mechanism EXTERNAL. A reply to a message conventionally has the same name as the message being replied to. When following method call conventions (see ), 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. @@ -841,8 +845,8 @@ SASL mechanism EXTERNAL. an application should reply with org.freedesktop.Peer.Ping. 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] @@ -893,8 +897,8 @@ SASL mechanism EXTERNAL. - [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] @@ -918,10 +922,10 @@ SASL mechanism EXTERNAL. Messages may have a srvc field (see ). When the message bus - receives a message, if the srvc 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 srvc 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 org.freedesktop.Peer.Ping message with no srvc will cause the message bus itself to reply to the ping immediately; the message bus would never make @@ -933,9 +937,9 @@ SASL mechanism EXTERNAL. messages are routed to the owner of the named service. Messages may also be broadcast by sending them to the special service - org.freedesktop.Broadcast. Broadcast messages - are sent to all applications with message matching rules - that match the message. + org.freedesktop.Broadcast. Broadcast messages are + sent to all applications with message matching + rules that match the message. Continuing the org.freedesktop.Peer.Ping example, if @@ -948,485 +952,88 @@ SASL mechanism EXTERNAL. might receive the ping, and all would normally reply to it. - - Message Bus Messages - - The special message bus service org.freedesktop.DBus - responds to a number of messages, allowing applications to - interact with the message bus. - - - - <literal>org.freedesktop.DBus.Hello</literal> - - As a method: - - STRING Hello () - - Reply arguments: - - - - - Argument - Type - Description - - - - - 0 - STRING - Name of the service assigned to the client - - - - - - - Before a client is able to send messages to other clients it - must send the org.freedesktop.DBus.Hello - 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 - org.freedesktop.DBus.Hello message, it will - be disconnected from the bus. - - - 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. - - - - <literal>org.freedesktop.DBus.ListServices</literal> - - As a method: - - STRING_ARRAY ListServices () - - Reply arguments: - - - - - Argument - Type - Description - - - - - 0 - STRING_ARRAY - Array of strings where each string is the name of a service - - - - - - - Returns a list of all existing services registered with the message bus. - - - - <literal>org.freedesktop.DBus.ServiceExists</literal> - - As a method: - - UINT32 ServiceExists (in STRING service_name) - - Message arguments: - - - - - Argument - Type - Description - - - - - 0 - STRING - Name of the service - - - - - Reply arguments: - - - - - Argument - Type - Description - - - - - 0 - UINT32 - Return value, 1 if the service exists and 0 otherwise - - - - - - - Checks if a service with a specified name exists. - - - - - <literal>org.freedesktop.DBus.AcquireService</literal> - - As a method: - - UINT32 AcquireService (in STRING service_name) - - Message arguments: - - - - - Argument - Type - Description - - - - - 0 - STRING - Name of the service - - - 1 - UINT32 - Flags - - - - - Reply arguments: - - - - - Argument - Type - Description - - - - - 0 - UINT32 - Return value - - - - - - - Tries to become owner of a specific service. The flags - specified can be the following values logically ORed together: - - - - - - Identifier - Value - Description - - - - - DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT - 0x1 - - 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 org.freedesktop.DBus.ServiceLost message. - - - - DBUS_SERVICE_FLAGS_REPLACE_EXISTING - 0x2 - Only become the owner of the service if there is no current owner. - - - - - - The return value can be one of the following values: - - - - - - Identifier - Value - Description - - - - - DBUS_SERVICE_REPLY_PRIMARY_OWNER - 0x1 - The client is now the primary owner of the service. - - - DBUS_SERVICE_REPLY_IN_QUEUE - 0x2 - The service already has an owner which do not want to give up ownership and therefore the client has been put in a queue. - - - DBUS_SERVICE_REPLY_SERVICE_EXISTS - 0x4 - The service does already have a primary owner, and DBUS_SERVICE_FLAG_REPLACE_EXISTING was not specified when trying to acquire the service. - - - DBUS_SERVICE_REPLY_ALREADY_OWNER - 0x8 - The client trying to request ownership of the service is already the owner of it. - - - - - - - - <literal>org.freedesktop.DBus.ServiceAcquired</literal> - - As a method: - - ServiceAcquired (in STRING service_name) - - Message arguments: - - - - - Argument - Type - Description - - - - - 0 - STRING - Name of the service - - - 1 - UINT32 - Flags - - - - - - - This message is sent to a specific client when it becomes the primary owner of a service. - - - - <literal>org.freedesktop.DBus.ServiceLost</literal> - - As a method: - - ServiceLost (in STRING service_name) - - Message arguments: - - - - - Argument - Type - Description - - - - - 0 - STRING - Name of the service - - - 1 - UINT32 - Flags - - - - - - - This message is sent to a specific client when it loses primary ownership of a service. - - - - - <literal>org.freedesktop.DBus.ServiceCreated</literal> - - As a method: - - ServiceCreated (in STRING service_name) - - Message arguments: - - - - - Argument - Type - Description - - - - - 0 - STRING - Name of the service - - - 1 - UINT32 - Flags - - - - - - - This message is broadcast to all clients when a service has been successfully registered on the message bus. - - - - <literal>org.freedesktop.DBus.ServiceDeleted</literal> - - As a method: - - ServiceDeleted (in STRING service_name) - - Message arguments: - - - - - Argument - Type - Description - - - - - 0 - STRING - Name of the service - - - 1 - UINT32 - Flags - - - - - - - This message is broadcast to all clients when a service has been deleted from the message bus. - - - - - <literal>org.freedesktop.DBus.ActivateService</literal> + + Message Bus Services - As a method: - - void ActivateService (in STRING service_name, in UINT32 flags) - - Message arguments: - - - - - Argument - Type - Description - - - - - 0 - STRING - Name of the service to activate - - - 1 - UINT32 - Flags (currently not used) - - - - + 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 + org.freedesktop.DBus.Hello message. + This automatically-assigned service name is called + the application's base service. + Base service names are unique and MUST never be reused for two different + applications. - Tries to launch the executable associated with a service. For more information, see the part on + [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] - - - - Message Bus Services - 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 - org.freedesktop.DBus.Hello 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 org.freedesktop.DBus.AcquireService - message. + message. [FIXME what service names are allowed; ASCII or unicode; + length limit; etc.] + [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 org.freedesktop.DBus.AcquireService - 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. + + Message Bus Message Routing + + When a message is received by the message bus, the message's + sndr header field MUST be set to the base service of + the application which sent the message. If the service already has + a sndr 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. + + + [FIXME go into detail about broadcast, multicast, unicast, etc.] + + Message Bus Service Activation - 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. + Activation 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. + To find an executable corresponding to a particular service, the bus + daemon looks for service description files. + 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 . + + + [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 desktop - entries. All service description files must be in + url="http://www.freedesktop.org/standards/desktop-entry-spec/desktop-entry-spec.html">desktop + entries. All service description files must be in UTF-8 encoding.
@@ -1440,37 +1047,505 @@ SASL mechanism EXTERNAL.
- 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] The executable launched will have the environment variable - DBUS_ADDRESS set to the address of the - server so it can connect and register the appropriate services. + DBUS_BUS_ADDRESS set to the address of the + message bus so it can connect and register the appropriate services. - - Finding The Message Bus + + + Standard Message Bus Instances Two standard message bus instances are defined here, along with how - to locate them. - - - Each time a user logs in, a login session message - bus 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. + + Login session message bus + + Each time a user logs in, a login session message + bus 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] + + + [FIXME specify location of .service files, probably using + DESKTOP_DIRS etc. from basedir specification, though login session + bus is not really desktop-specific] + + + + System message bus + + A computer may have a system message bus, + 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] + + + [FIXME specify location of system bus .service files] + + + + + + Message Bus Messages - A computer may have a system message bus, - 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 org.freedesktop.DBus + responds to a number of messages, allowing applications to + interact with the message bus. + + + <literal>org.freedesktop.DBus.Hello</literal> + + As a method: + + STRING Hello () + + Reply arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Name of the service assigned to the application + + + + + + + Before an application is able to send messages to other applications it + must send the org.freedesktop.DBus.Hello + 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 + org.freedesktop.DBus.Hello message, it will + be disconnected from the bus. + + + The reply message contains the name of the application's base service. + + + + <literal>org.freedesktop.DBus.ListServices</literal> + + As a method: + + STRING_ARRAY ListServices () + + Reply arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING_ARRAY + Array of strings where each string is the name of a service + + + + + + + Returns a list of all existing services registered with the message bus. + + + + <literal>org.freedesktop.DBus.ServiceExists</literal> + + As a method: + + UINT32 ServiceExists (in STRING service_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Name of the service + + + + + Reply arguments: + + + + + Argument + Type + Description + + + + + 0 + UINT32 + Return value, 1 if the service exists and 0 otherwise + + + + + + + Checks if a service with a specified name exists. + + + + + <literal>org.freedesktop.DBus.AcquireService</literal> + + As a method: + + UINT32 AcquireService (in STRING service_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Name of the service + + + 1 + UINT32 + Flags + + + + + Reply arguments: + + + + + Argument + Type + Description + + + + + 0 + UINT32 + Return value + + + + + + + Tries to become owner of a specific service. The flags + specified can be the following values logically ORed together: + + + + + + Identifier + Value + Description + + + + + DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT + 0x1 + + 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 org.freedesktop.DBus.ServiceLost message. + + + + DBUS_SERVICE_FLAGS_REPLACE_EXISTING + 0x2 + Only become the owner of the service if there is no current owner. + + + + + + [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: + + + + + + Identifier + Value + Description + + + + + DBUS_SERVICE_REPLY_PRIMARY_OWNER + 0x1 + The application is now the primary owner of the service. + + + DBUS_SERVICE_REPLY_IN_QUEUE + 0x2 + The service already has an owner which do not want to give up ownership and therefore the application has been put in a queue. + + + DBUS_SERVICE_REPLY_SERVICE_EXISTS + 0x4 + The service does already have a primary owner, and DBUS_SERVICE_FLAG_REPLACE_EXISTING was not specified when trying to acquire the service. + + + DBUS_SERVICE_REPLY_ALREADY_OWNER + 0x8 + The application trying to request ownership of the service is already the owner of it. + + + + + + + + <literal>org.freedesktop.DBus.ServiceAcquired</literal> + + As a method: + + ServiceAcquired (in STRING service_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Name of the service + + + 1 + UINT32 + Flags + + + + + + + This message is sent to a specific application when it becomes the + primary owner of a service. + + + + <literal>org.freedesktop.DBus.ServiceLost</literal> + + As a method: + + ServiceLost (in STRING service_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Name of the service + + + 1 + UINT32 + Flags + + + + + + + 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] + + + + + <literal>org.freedesktop.DBus.ServiceCreated</literal> + + As a method: + + ServiceCreated (in STRING service_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Name of the service + + + 1 + UINT32 + Flags + + + + + + + This message is broadcast to all applications when a service has been + successfully registered on the message bus. + + + + + <literal>org.freedesktop.DBus.ServiceDeleted</literal> + + As a method: + + ServiceDeleted (in STRING service_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Name of the service + + + 1 + UINT32 + Flags + + + + + + + This message is broadcast to all applications when a service has been + deleted from the message bus. + + + + + <literal>org.freedesktop.DBus.ActivateService</literal> + + As a method: + + void ActivateService (in STRING service_name, in UINT32 flags) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Name of the service to activate + + + 1 + UINT32 + Flags (currently not used) + + + + + + + Tries to launch the executable associated with a service. For more information, see . + + [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] + + +