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.sgml | 2197 ------------------------------------------- 1 file changed, 2197 deletions(-) delete mode 100644 doc/dbus-specification.sgml (limited to 'doc/dbus-specification.sgml') diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml deleted file mode 100644 index 696c3f45..00000000 --- a/doc/dbus-specification.sgml +++ /dev/null @@ -1,2197 +0,0 @@ - -
- - 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] - CANCELBEGIN - 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