From 78b69c683ea27514c0787b2d1e2244d7182bc72d Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Tue, 30 Sep 2003 03:34:00 +0000 Subject: 2003-09-29 Havoc Pennington * configure.in: split checks for Doxygen from XML docs, check for xmlto * doc/Makefile.am: XML-ify all the docs, and add a blank dbus-tutorial.xml --- doc/dbus-specification.xml | 2201 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2201 insertions(+) create mode 100644 doc/dbus-specification.xml (limited to 'doc/dbus-specification.xml') diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml new file mode 100644 index 00000000..698e35a2 --- /dev/null +++ b/doc/dbus-specification.xml @@ -0,0 +1,2201 @@ + + + +
+ + D-BUS Specification + Version 0.8 + 06 September 2003 + + + Havoc + Pennington + + Red Hat, Inc. +
+ hp@pobox.com +
+ + + + Anders + Carlsson + + CodeFactory AB +
+ andersca@codefactory.se +
+ + + + Alexander + Larsson + + Red Hat, Inc. +
+ alexl@redhat.com +
+ + + + + + + Introduction + + D-BUS is a system for low-latency, low-overhead, easy to use + interprocess communication (IPC). In more detail: + + + + D-BUS is low-latency because it is designed + to avoid round trips and allow asynchronous operation, much like + the X protocol. + + + + + D-BUS is low-overhead because it uses a + binary protocol, and does not have to convert to and from a text + format such as XML. Because D-BUS is intended for potentially + high-resolution same-machine IPC, not primarily for Internet IPC, + this is an interesting optimization. + + + + + D-BUS is easy to use because it works in terms + of messages rather than byte streams, and + automatically handles a lot of the hard IPC issues. Also, the D-BUS + library is designed to be wrapped in a way that lets developers use + their framework's existing object/type system, rather than learning + a new one specifically for IPC. + + + + + + The base D-BUS protocol is a peer-to-peer protocol, specified in . That is, it is a system for one application + to talk to a single other application. However, the primary intended + application of D-BUS is the D-BUS message bus, + specified in . The message bus is a special + application that accepts connections from multiple other applications, and + forwards messages among them. + + + Uses of D-BUS include notification of system changes (notification of when + a camera is plugged in to a computer, or a new version of some software + has been installed), or desktop interoperablity, for example a file + monitoring service or a configuration service. + + + + + Message Protocol + + A message consists of a + header and a body. If you + think of a message as a package, the header is the address, and the body + contains the package contents. The message delivery system uses the header + information to figure out where to send the message and how to interpret + it; the recipient inteprets the body of the message. + + + + The body of the message is made up of zero or more + arguments, which are typed + values, such as an integer or a byte array. + + + + Header Encoding + + Following the mandatory fields, there are zero or more named fields (see + ), and then nul bytes + padding the header such that its total length in bytes is a multiple of + 8. + + + The header MUST begin with the following mandatory fields in the following + order: + + + + + Size + Description + + + + + 1 byte + Endianness flag; ASCII 'l' for little-endian + or ASCII 'B' for big-endian. + + + 1 byte + Type of message. Unknown types MUST be ignored. + Currently-defined types are described below. + + + + 1 byte + Bitwise OR of flags. Unknown flags + MUST be ignored. Currently-defined flags are described below. + + + + 1 byte + Major protocol version of the sending application. If + the major protocol version of the receiving application does not + match, the applications will not be able to communicate and the + D-BUS connection MUST be disconnected. The major protocol + version for this version of the specification is 0. + + + + 4 bytes + An unsigned 32-bit integer in the + message's byte order, indicating the total length in bytes of + the header including named fields and any alignment padding. + MUST be a multiple of 8. + + + + 4 bytes + An unsigned 32-bit integer in the + message's byte order, indicating the total length in bytes of + the message body. + + + + 4 bytes + The message's serial number, an unsigned 32-bit integer in + the message's byte order. The serial number is a cookie used to + identify message replies; thus all outstanding unreplied-to messages + from the same connection MUST have a different serial number. + Zero is not a valid serial number, but all other numbers are + allowed. + + + + + + + + Types that can appear in the second byte of the header: + + + + + Conventional name + Decimal value + Description + + + + + INVALID + 0 + This is an invalid type, if seen in a message + the connection should be dropped immediately. + + + METHOD_CALL + 1 + Method call. + + + METHOD_RETURN + 2 + Method reply with returned data. + + + ERROR + 3 + Error reply. If the first argument exists and is a + string, it is an error message. + + + SIGNAL + 4 + Signal emission. + + + + + + + Flags that can appear in the third byte of the header: + + + + + Conventional name + Hex value + Description + + + + + NO_REPLY_EXPECTED + 0x1 + This message does not expect method return replies or + error replies; the reply can be omitted as an + optimization. However, it is compliant with this specification + to return the reply despite this flag. + + + + + + + + + Header Fields + + In addition to the required header information mentioned + in , + the header may contain zero or more named + header fields. Future versions of this protocol + specification may add new fields. Implementations must + ignore fields they do not understand. Implementations + must not invent their own header fields; only changes to + this specification may introduce new header fields. + + + + Header field names MUST consist of a single byte, possible values + of which are defined below. Following the name, the field MUST have + a type code represented as a single unsigned byte, and then a + properly-aligned value of that type. See for a description of how each + type is encoded. If an implementation sees a header field name that + it does not understand, it MUST ignore that field. + + + + Here are the currently-defined named header fields: + + + + + Conventional Name + Decimal Value + Type + Description + + + + + INVALID + 0 + INVALID + Not a valid field name (error if it appears in a message) + + + PATH + 1 + STRING + The object to send the message to; objects are identified by + a path, "/foo/bar" + + + INTERFACE + 2 + STRING + The interface to invoke a method call on, or + that a signal is emitted from. e.g. "org.freedesktop.Introspectable" + + + MEMBER + 3 + STRING + The member, either the method name or signal name. + e.g. "Frobate" + + + ERROR_NAME + 4 + STRING + The name of the error that occurred, for errors + + + REPLY_SERIAL + 5 + UINT32 + The serial number of the message this message is a reply + to. (The serial number is one of the mandatory header fields, + see .) + + + SERVICE + 6 + STRING + The name of the service this message should be routed to. + Only used in combination with the message bus, see + . + + + SENDER_SERVICE + 7 + STRING + Sender service. 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. + + + + + + + + + Header Alignment Padding + + To allow implementations to keep the header and the body in a single + buffer while keeping data types aligned, the total length of the header + must be a multiple of 8 bytes. To achieve this, the header MUST be padded + with nul bytes to align its total length on an 8-byte boundary. + The minimum number of padding bytes MUST be used. Because zero is an + invalid field name, implementations can distinguish padding (which must be + zero initialized) from additional named fields. + + + + + Message Arguments + + The message body is made up of arguments. Each argument is a type code, + represented by a single unsigned byte, followed by the aligned value of + the argument in a type-dependent format. Alignment padding between the + typecode and the value is initialized to zero. + + + + + + + Type name + Code + Description + + + + + INVALID + 0 + Not a valid type code (error if it appears in a message) + + NIL + 1 + Marks an "unset" or "nonexistent" argument + + BYTE + 2 + 8-bit unsigned integer + + BOOLEAN + 3 + Boolean value, 0 is FALSE and 1 is TRUE. Everything else is invalid. + + INT32 + 4 + 32-bit signed integer + + UINT32 + 5 + 32-bit unsigned integer + + INT64 + 6 + 64-bit signed integer + + UINT64 + 7 + 64-bit unsigned integer + + DOUBLE + 8 + IEEE 754 double + + STRING + 9 + UTF-8 string (must be valid UTF-8). Must be zero terminated. + + NAMED + 10 + A named byte array, used for custom types + + ARRAY + 11 + Array + + DICT + 12 + A dictionary of key/value pairs + + + + + + + The types are encoded as follows: + + + + + Type name + Encoding + + + + + INVALID + Not applicable; cannot be encoded. + + NIL + No data is encoded; the type code is followed immediately + by the type code of the next argument. + + BYTE + A byte. + + BOOLEAN + A byte, with valid values 0 and 1. + + INT32 + 32-bit signed integer in the message's byte order, aligned to 4-byte boundary. + + UINT32 + 32-bit unsigned integer in the message's byte order, aligned to 4-byte boundary. + + INT64 + 64-bit signed integer in the message's byte order, aligned to 8-byte boundary. + + UINT64 + 64-bit unsigned integer in the message's byte order, aligned to 8-byte boundary. + + DOUBLE + 64-bit IEEE 754 double in the message's byte order, aligned to 8-byte boundary. + + STRING + UINT32 aligned to 4-byte boundary indicating the string's + length in bytes excluding its terminating nul, followed by + string data of the given length, followed by a terminating nul + byte. + + + NAMED + A string (encoded as the STRING type above) giving the + name of the type followed by an UINT32 aligned to 4-byte boundary + indicating the data length in bytes, followed by the data. + + + ARRAY + A sequence of bytes giving the element type of the array, terminated + by a type different from ARRAY (just one byte for one-dimensional arrays, but + larger for multi-dimensional arrays), followed by an UINT32 (aligned to 4 bytes) + giving the length of the array data in bytes. This is followed by each array entry + encoded the way it would normally be encoded, except arrays, which are encoded + without the type information, since that is already declared above. Arrays containing + NIL are not allowed. + + + DICT + UINT32 giving the length of the dictionary data in bytes. + This is followed by a number of keyname/value pairs, where the + keyname is encoded as a STRING above, and the value is encoded + as a byte with typecode and how that type normally would be encoded + alone. + + + + + + + + + + Valid names + + The various header fields of type STRING have some restrictions + on the string's format. + + + Service names + + Services have names with type STRING, meaning that + they must be valid UTF-8. However, there are also some + additional restrictions that apply to service names + specifically: + + They must contain at least one '.' (period) character + They must not begin with a '.' (period) character + They must not exceed 256 bytes in length + They must be at least 1 byte in length + + + As a special exception, base service names (those beginning with a colon + (':') character) need not contain a period. + + + FIXME really, shouldn't we ban basically everything non-alphanumeric + so the name will work in all programming languages? + + + + Interface names + + Interface names have the same restrictions as service names, + but do not have the special exception for names beginning with + a colon. + + + FIXME really, shouldn't we ban basically everything non-alphanumeric + so the name will work in all programming languages? + + + + Method names + + Method names: + + May not contain the '.' (period) character + Must not exceed 256 bytes in length + Must be at least 1 byte in length + + + + FIXME really, shouldn't we ban basically everything non-alphanumeric + so the name will work in all programming languages? + + + + Path names + + A path must begin with an ASCII '/' (slash) character. Paths may not + end with a slash character unless the path is the one-byte string + "/". Two slash characters may not appear adjacent to one another (the + empty string is not a valid "subdirectory"). Paths may not exceed + 256 bytes in length. + + + + Error names + + Error names have the same restrictions as interface names. + + + FIXME really, shouldn't we ban basically everything non-alphanumeric + so the name will work in all programming languages? + + + + + + Message types + + Each of the message types (METHOD_CALL, METHOD_RETURN, ERROR, and + SIGNAL) has its own expected usage conventions and header fields. + + + Method Calls, Returns, and Errors + + Some messages invoke an operation on a remote object. These are + called method call messages and have the type tag METHOD_CALL. Such + messages map naturally to methods on objects in a typical program. + + + A method call message is expected to have a MEMBER header field + indicating the name of the method. Optionally, the message has an + INTERFACE field giving the interface the method is a part of. In the + absence of an INTERFACE field, if two interfaces on the same object have + a method with the same name, it is undefined which of the two methods + will be invoked. Implementations may also choose to return an error in + this ambiguous case. However, if a method name is unique + implementations should not require an interface field. + + + Method call messages also include a PATH field indicating the + object to invoke the method on. If the call is passing through + a message bus, the message will also have a SERVICE field giving + the service to receive the message. + + + When an application handles a method call message, it is expected to + return a reply. The reply is identified by a REPLY_SERIAL header field + indicating the serial number of the METHOD_CALL being replied to. The + reply can have one of two types; either METHOD_RETURN or ERROR. + + + If the reply has type METHOD_RETURN, the arguments to the reply message + are the return value(s) or "out parameters" of the method call. + If the reply has type ERROR, then an "exception" has been thrown, + and the call fails; no return value will be provided. It makes + no sense to send multiple replies to the same method call. + + + Even if a method call has no return values, a METHOD_RETURN + reply is expected, so the caller will know the method + was successfully processed. + + + If a METHOD_CALL message has the flag NO_REPLY_EXPECTED, + then as an optimization the application receiving the method + call may choose to omit the reply message (regardless of + whether the reply would have been METHOD_RETURN or ERROR). + However, it is also acceptable to ignore the NO_REPLY_EXPECTED + flag and reply anyway. + + + Mapping method calls to native APIs + + APIs for D-BUS may map method calls to a method call in a specific + programming language, such as C++, or may map a method call written + in an IDL to a D-BUS message. + + + In APIs of this nature, arguments to a method are often termed "in" + (which implies sent in the METHOD_CALL), or "out" (which implies + returned in the METHOD_RETURN). Some APIs such as CORBA also have + "inout" arguments, which are both sent and received, i.e. the caller + passes in a value which is modified. Mapped to D-BUS, an "inout" + argument is equivalent to an "in" argument, followed by an "out" + argument. You can't pass things "by reference" over the wire, so + "inout" is purely an illusion of the in-process API. + + + Given a method with zero or one return values, followed by zero or more + arguments, where each argument may be "in", "out", or "inout", the + caller constructs a message by appending each "in" or "inout" argument, + in order. "out" arguments are not represented in the caller's message. + + + The recipient constructs a reply by appending first the return value + if any, then each "out" or "inout" argument, in order. + "in" arguments are not represented in the reply message. + + + + + + + Signal Emission + + Unlike method calls, signal emissions have no replies. + A signal emission is simply a single message of type SIGNAL. + It must have three header fields: PATH giving the object + the signal was emitted from, plus INTERFACE and MEMBER giving + the fully-qualified name of the signal. + + + + + Notation in this document + + This document uses a simple pseudo-IDL to describe particular method + calls and signals. Here is an example of a method call: + + org.freedesktop.DBus.ActivateService (in STRING service_name, in UINT32 flags, + out UINT32 resultcode) + + This means INTERFACE = org.freedesktop.DBus, MEMBER = ActivateService, + METHOD_CALL arguments are STRING and UINT32, METHOD_RETURN argument + is UINT32. Remember that the MEMBER field can't contain any '.' (period) + characters so it's known that the last part of the name in + the "IDL" is the member name. + + + In C++ that might end up looking like this: + + unsigned int org::freedesktop::DBus::ActivateService (const char *service_name, + unsigned int flags); + + or equally valid, the return value could be done as an argument: + + void org::freedesktop::DBus::ActivateService (const char *service_name, + unsigned int flags, + unsigned int *resultcode); + + It's really up to the API designer how they want to make + this look. You could design an API where the namespace wasn't used + in C++, using STL or Qt, using varargs, or whatever you wanted. + + + Signals are written as follows: + + org.freedesktop.DBus.ServiceLost (STRING service_name) + + Signals don't specify "in" vs. "out" because only + a single direction is possible. + + + In this ad hoc notation, the special type name ANY means any type + other than NIL, and the special type name ANY_OR_NIL means any valid + type. + + + It isn't especially encouraged to use this lame pseudo-IDL in actual + API implementations; you might use the native notation for the + language you're using, or you might use COM or CORBA IDL, for example. + + + + + + + + Authentication Protocol + + Before the flow of messages begins, two applications must + authenticate. A simple plain-text protocol is used for + authentication; this protocol is a SASL profile, and maps fairly + directly from the SASL specification. The message encoding is + NOT used here, only plain text messages. + + + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. + + + 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. + + Commands from the client to the server are as follows: + + + AUTH [mechanism] [initial-response] + CANCEL + BEGIN + DATA <data in base 64 encoding> + ERROR [human-readable error explanation] + + + From server to client are as follows: + + + REJECTED <space-separated list of mechanism names> + OK + DATA <data in base 64 encoding> + ERROR + + + + + 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. + + + + 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. + + + + 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 that sent the + error MUST continue as if the command causing the ERROR had never been + received. However, the the server or client receiving the error + should try something other than whatever caused the error; + if only canceling/rejecting the authentication. + + + + Authentication examples + + +
+ Example of successful magic cookie authentication + + (MAGIC_COOKIE is a made up mechanism) + + 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 + +
+
+ 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 + +
+
+ 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 + +
+
+ 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 + +
+
+ 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 + +
+ + + + Authentication state diagrams + + + WRITEME + + + + Authentication mechanisms + + This section describes some new authentication mechanisms. + D-BUS also allows any standard SASL mechanism of course. + + + DBUS_COOKIE_SHA1 + + The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client + has the ability to read a private file owned by the user being + authenticated. If the client can prove that it has access to a secret + cookie stored in this file, then the client is authenticated. + Thus the security of DBUS_COOKIE_SHA1 depends on a secure home + directory. + + + Authentication proceeds as follows: + + + + The client sends the username it would like to authenticate + as. + + + + + The server sends the name of its "cookie context" (see below); a + space character; the integer ID of the secret cookie the client + must demonstrate knowledge of; a space character; then a + hex-encoded randomly-generated challenge string. + + + + + The client locates the cookie, and generates its own hex-encoded + randomly-generated challenge string. The client then + concatentates the server's hex-encoded challenge, a ":" + character, its own hex-encoded challenge, another ":" character, + and the hex-encoded cookie. It computes the SHA-1 hash of this + composite string. It sends back to the server the client's + hex-encoded challenge string, a space character, and the SHA-1 + hash. + + + + + The server generates the same concatenated string used by the + client and computes its SHA-1 hash. It compares the hash with + the hash received from the client; if the two hashes match, the + client is authenticated. + + + + + + Each server has a "cookie context," which is a name that identifies a + set of cookies that apply to that server. A sample context might be + "org_freedesktop_session_bus". Context names must be valid ASCII, + nonzero length, and may not contain the characters slash ("/"), + backslash ("\"), space (" "), newline ("\n"), carriage return ("\r"), + tab ("\t"), or period ("."). There is a default context, + "org_freedesktop_global" that's used by servers that do not specify + otherwise. + + + Cookies are stored in a user's home directory, in the directory + ~/.dbus-keyrings/. This directory must + not be readable or writable by other users. If it is, + clients and servers must ignore it. The directory + contains cookie files named after the cookie context. + + + A cookie file contains one cookie per line. Each line + has three space-separated fields: + + + + The cookie ID number, which must be a non-negative integer and + may not be used twice in the same file. + + + + + The cookie's creation time, in UNIX seconds-since-the-epoch + format. + + + + + The cookie itself, a hex-encoded random block of bytes. + + + + + + Only server processes modify the cookie file. + They must do so with this procedure: + + + + Create a lockfile name by appending ".lock" to the name of the + cookie file. The server should attempt to create this file + using O_CREAT | O_EXCL. If file creation + fails, the lock fails. Servers should retry for a reasonable + period of time, then they may choose to delete an existing lock + to keep users from having to manually delete a stale + lock. Lockfiles are used instead of real file + locking fcntl() because real locking + implementations are still flaky on network + filesystems. + + + + + Once the lockfile has been created, the server loads the cookie + file. It should then delete any cookies that are old (the + timeout can be fairly short), or more than a reasonable + time in the future (so that cookies never accidentally + become permanent, if the clock was set far into the future + at some point). If no recent keys remain, the + server may generate a new key. + + + + + The pruned and possibly added-to cookie file + must be resaved atomically (using a temporary + file which is rename()'d). + + + + + The lock must be dropped by deleting the lockfile. + + + + + + Clients need not lock the file in order to load it, + because servers are required to save the file atomically. + + + + + + Server Addresses + + 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: + unix:path=/tmp/dbus-test + 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 + the next one specified, and so forth. For example + unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2 + + + [FIXME we need to specify in detail each transport and its possible arguments] + Current transports include: unix domain sockets (including + abstract namespace on linux), TCP/IP, and a debug/testing transport using + in-process pipes. Future possible transports include one that + tunnels over X11 protocol. + + + + + Standard Peer-to-Peer Messages + + See for details on + the notation used in this section. + + + <literal>org.freedesktop.Peer.Ping</literal> + + + org.freedesktop.Peer.Ping () + + + + On receipt of the METHOD_CALL + message org.freedesktop.Peer.Ping, an application + should do nothing other than reply with a METHOD_RETURN as usual. + + + + + <literal>org.freedesktop.Props.Get</literal> + + [FIXME this is just a bogus made-up method that isn't implemented + or thought through, to save an example of table formatting for the + argument descriptions] + + org.freedesktop.Props.Get (in STRING property_name, + out ANY_OR_NIL property_value) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + in STRING + Name of the property to get + + + 1 + out ANY_OR_NIL + The value of the property. The type depends on the property. + + + + + + + + + + Message Bus Specification + + Message Bus Overview + + The message bus accepts connections from one or more applications. + Once connected, applications can send and receive messages from + the message bus, as in the peer-to-peer case. + + + The message bus keeps track of a set of + services. A service is simply a name, such as + com.yoyodyne.Screensaver, which can be + owned by one or more of the connected + applications. The message bus itself always owns the special service + org.freedesktop.DBus. + + + Services may have secondary owners. Secondary owners + of a service are kept in a queue; if the primary owner of a service + disconnects, or releases the service, the next secondary owner becomes + the new owner of the service. + + + Messages may have a SERVICE field (see ). When the message bus + receives a message, if the SERVICE 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 + SERVICE will cause the message bus itself to reply + to the ping immediately; the message bus would never make + this message visible to other applications. + + + If the SERVICE field is present, then it indicates a + request for the message bus to route the message. In the usual case, + messages are routed to the owner of the named service. + Messages may also be broadcast + by sending them to the special service + org.freedesktop.DBus.Broadcast. Broadcast messages are + sent to all applications with message matching + rules that match the message. + + + Continuing the org.freedesktop.Peer.Ping example, if + the ping message were sent with a SERVICE name of + com.yoyodyne.Screensaver, then the ping would be + forwarded, and the Yoyodyne Corporation screensaver application would be + expected to reply to the ping. If + org.freedesktop.Peer.Ping were sent to + org.freedesktop.DBus.Broadcast, then multiple applications + might receive the ping, and all would normally reply to it. + + + + + Message Bus Services + + 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. + + + Ownership of the base service is a prerequisite for interaction with + the message bus. It logically follows that the base service is always + the first service that an application comes to own, and the last + service that it loses ownership of. + + + Base service names must begin with the character ':' (ASCII colon + character); service names that are not base service names must not begin + with this character. (The bus must reject any attempt by an application + to manually create a service name beginning with ':'.) This restriction + categorically prevents "spoofing"; messages sent to a base service name + will always go to a single application instance and that instance only. + + + An application can request additional service names to be associated + with it using the + org.freedesktop.DBus.AcquireService + 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 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 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 application requests ownership of the + service. + + + When a client disconnects from the bus, all the services that + the clients own are deleted, or in the case of a service that + prohibits replacement, ownership is transferred to the next + client in the queue, if any. + + + + 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 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 + 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. + +
+ Example service description file + + # Sample service description file + [D-BUS Service] + Name=org.gnome.ConfigurationDatabase + Exec=/usr/libexec/gconfd-2 + +
+ + + 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. [FIXME what + happens if two .service files offer the same service; what + kind of error is reported, should we have a way for the client + to choose one?] + + + The executable launched will have the environment variable + DBUS_ACTIVATION_ADDRESS set to the address of the + message bus so it can connect and register the appropriate services. + + + The executable being launched may want to know whether the message bus + activating it is one of the well-known message buses (see ). To facilitate this, the bus MUST also set + the DBUS_ACTIVATION_BUS_TYPE environment variable if it is one + of the well-known buses. The currently-defined values for this variable + are system for the systemwide message bus, + and session for the per-login-session message + bus. The activated executable must still connect to the address given + in DBUS_ACTIVATION_ADDRESS, but may assume that the + resulting connection is to the well-known bus. + + + [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.] + + + + + Well-known Message Bus Instances + + Two standard message bus instances are defined here, along with how + 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. + + + The address of the login session message bus is given + in the DBUS_SESSION_BUS_ADDRESS environment + variable. If that variable is not set, applications may + also try to read the address from the X Window System root + window property _DBUS_SESSION_BUS_ADDRESS. + The root window property must have type STRING. + The environment variable should have precedence over the + root window 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, + changes in the printer queue, and so forth. + + + The address of the login session message bus is given + in the DBUS_SYSTEM_BUS_ADDRESS environment + variable. If that variable is not set, applications should try + to connect to the well-known address + unix:path=/var/run/dbus/system_bus_socket. + + + The D-BUS reference implementation actually honors the + $(localstatedir) configure option + for this address, on both client and server side. + + + + + [FIXME specify location of system bus .service files] + + + + + + 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 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. If a client wishes to + disconnect from the bus, it just has to disconnect from the + transport used. No de-registration message is necessary. + + + 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: + + BOOLEAN ServiceExists (in STRING service_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Name of the service + + + + + Reply arguments: + + + + + Argument + Type + Description + + + + + 0 + BOOLEAN + Return value, true if the service exists + + + + + + + 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 + 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 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: + + UINT32 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) + + + + + Reply arguments: + + + + + Argument + Type + Description + + + + + 0 + UINT32 + Return value + + + + + 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] + + + The return value can be one of the following values: + + + + + Identifier + Value + Description + + + + + DBUS_ACTIVATION_REPLY_ACTIVATED + 0x0 + The service was activated successfully. + + + DBUS_ACTIVATION_REPLY_ALREADY_ACTIVE + 0x1 + The service is already active. + + + + + + + + + + <literal>org.freedesktop.DBus.Error.NoMemory</literal> + + As a method: + + void NoMemory () + + + + Sent by the message bus when it can't process a message due to an out of memory failure. + + + + + <literal>org.freedesktop.DBus.Error.ServiceDoesNotExist</literal> + + As a method: + + void ServiceDoesNotExist (in STRING error) + + + + Sent by the message bus as a reply to a client that tried to send a message to a service that doesn't exist. + + + + + + + + Glossary + + This glossary defines some of the terms used in this specification. + + + Activation + + + The process of creating an owner for a particular service, + typically by launching an executable. + + + + + Base Service + + + 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). + + + + + Broadcast + + + A message sent to the special org.freedesktop.DBus.Broadcast + service; the message bus will forward the broadcast message + to all applications that have expressed interest in it. + + + + + Message + + + A message is the atomic unit of communication via the D-BUS + protocol. It consists of a header and a + body; the body is made up of + arguments. + + + + + Message Bus + + + The message bus is a special application that forwards + or broadcasts messages between a group of applications + connected to the message bus. It also manages + services. + + + + + Namespace + + + Used to prevent collisions when defining message and service + names. The convention used is the same as Java uses for + defining classes: a reversed domain name. + + + + + Object + + + Each application contains objects, + which have interfaces and + methods. Objects are referred to + by a name, called a path or + object reference. + + + + + Path + + + Object references (object names) in D-BUS are + organized into a filesystem-style hierarchy, so + each object is named by a path. As in LDAP, + there's no difference between "files" and "directories"; + a path can refer to an object, while still having + child objects below it. + + + + + Peer-to-peer + + + An application talking directly to another application, without going through a message bus. + + + + Secondary service owner + + + Each service has a primary owner; messages sent to the service name + go to the primary owner. However, certain services also maintain + a queue of secondary owners "waiting in the wings." If + the primary owner releases the service, then the first secondary + owner in the queue automatically becomes the primary owner. + + + + Service + + + A service is simply a named list of applications. For example, the + hypothetical com.yoyodyne.Screensaver service might + accept messages that affect a screensaver from Yoyodyne Corporation. + An application is said to own a service if the + message bus has associated the application with the service name. + Services may also have secondary owners (see + ). + + + + Service name + + + The name used when referring to a service. If the service is + a base service it has a unique service name, for example + ":1-20", and otherwise it should be namespaced. + + + + Service Description Files + + + ".service files" tell the bus how to activate a particular service. + See + + + + + +
+ -- cgit