From cc63ef88a5f1f4f65d9003a6a0995001b883e891 Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Tue, 18 Jan 2005 00:20:39 +0000 Subject: 2005-01-17 Havoc Pennington * doc/dbus-specification.xml: partially update spec --- doc/dbus-specification.xml | 679 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 516 insertions(+), 163 deletions(-) (limited to 'doc/dbus-specification.xml') diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 4793278f..b07f062f 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -7,8 +7,8 @@
D-BUS Specification - Version 0.8 - 06 September 2003 + Version 0.9 + 17 January 2005 Havoc @@ -77,25 +77,30 @@ + - 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. + The base D-BUS protocol is a one-to-one (peer-to-peer or client-server) + 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 + has been installed), or desktop interoperability, for example a file monitoring service or a configuration service. + Message Protocol + A message consists of a header and a body. If you @@ -107,79 +112,434 @@ 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. + arguments, which are typed values, such as an + integer or a byte array. + + + + Both header and body use the same type system and format for + serializing data. Each type of value has a wire format. + Converting a value from some other representation into the wire + format is called marshaling and converting + it back from the wire format is unmarshaling. - - Header Encoding + + Type Signatures + + + The D-BUS protocol does not include type tags in the marshaled data; a + block of marshaled values must have a known type + signature. The type signature is made up of type + codes. A type code is an ASCII character representing the + type of a value. Because ASCII characters are used, the type signature + will always form a valid ASCII string. A simple string compare + determines whether two type signatures are equivalent. + + + + As a simple example, the type code for 32-bit integer (INT32) is + the ASCII character 'i'. So the signature for a block of values + containing a single INT32 would be: + + "i" + + A block of values containing two INT32 would have this signature: + + "ii" + + + + + All basic types work like + INT32 in this example. To marshal and unmarshal + basic types, you simply read one value from the data + block corresponding to each type code in the signature. + In addition to basic types, there are three container + types: STRUCT, ARRAY, and VARIANT. + + + + STRUCT has a type code, ASCII character 'r', but this type + code does not appear in signatures. Instead, ASCII characters + '(' and ')' are used to mark the beginning and end of the struct. + So for example, a struct containing two integers would have this + signature: + + "(ii)" + + Structs can be nested, so for example a struct containing + an integer and another struct: + + "(i(ii))" + + The value block storing that struct would contain three integers; the + type signature allows you to distinguish "(i(ii))" from "((ii)i)" or + "(iii)" or "iii". + + + + ARRAY has ASCII character 'a' as type code. The array type code must be + followed by a single complete type. The single + complete type following the array is the type of each array element. So + the simple example is: + + "ai" + + which is an array of 32-bit integers. But an array can be of any type, + such as this array-of-struct-with-two-int32-fields: + + "a(ii)" + + Or this array of array of integer: + + "aai" + + + + + The phrase single complete type deserves some + definition. A single complete type is a basic type code, a variant type code, + an array with its element type, or a struct with its fields. + So the following signatures are not single complete types: + + "aa" + + + "(ii" + + + "ii)" + + And the following signatures contain multiple complete types: + + "ii" + + + "aiai" + + + "(ii)(ii)" + + Note however that a single complete type may contain + multiple other single complete types. + + + + VARIANT has ASCII character 'v' as its type code. A marshaled value of + type VARIANT will have the signature of a single complete type as part + of the value. This signature will be followed by a + marshaled value of that type. + + + + The following table summarizes the D-BUS types. + + + + + Type name + Code + Description + + + + + INVALID + 0 (ASCII NUL) + Not a valid type code, used to terminate signatures + + BYTE + 121 (ASCII 'y') + 8-bit unsigned integer + + BOOLEAN + 98 (ASCII 'b') + Boolean value, 0 is FALSE and 1 is TRUE. Everything else is invalid. + + INT32 + 105 (ASCII 'i') + 32-bit signed integer + + UINT32 + 117 (ASCII 'u') + 32-bit unsigned integer + + INT64 + 120 (ASCII 'x') + 64-bit signed integer + + UINT64 + 116 (ASCII 't') + 64-bit unsigned integer + + DOUBLE + 100 (ASCII 'd') + IEEE 754 double + + STRING + 115 (ASCII 's') + UTF-8 string (must be valid UTF-8). Must be nul terminated. + + OBJECT_PATH + 111 (ASCII 'o') + Name of an object instance + + SIGNATURE + 103 (ASCII 'g') + A type signature + + ARRAY + 97 (ASCII 'a') + Array + + STRUCT + 114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')') + Struct + + VARIANT + 118 (ASCII 'v') + Variant type (the type of the value is part of the value itself) + + + + + + + + + + Marshaling (Wire Format) + - 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. + Given a type signature, a block of bytes can be converted into typed + values. This section describes the format of the block of bytes. Byte + order and alignment issues are handled uniformly for all D-BUS types. + + + A block of bytes has an associated byte order. The byte order + has to be discovered in some way; for D-BUS messages, the + byte order is part of the message header as described in + . For now, assume + that the byte order is known to be either little endian or big + endian. + + - The header MUST begin with the following mandatory fields in the following - order: + Each value in a block of bytes is aligned "naturally," for example + 4-byte values are aligned to a 4-byte boundary, and 8-byte values to an + 8-byte boundary. To properly align a value, alignment + padding may be necessary. The alignment padding must always + be the minimum required padding to properly align the following value; + and it must always be made up of nul bytes. The alignment padding must + not be left uninitialized (it can't contain garbage), and more padding + than required must not be used. + + + + Given all this, the types are marshaled on the wire as follows: + + + + + Type name + Encoding + Alignment + + + + + INVALID + Not applicable; cannot be marshaled. + N/A + + BYTE + A single 8-bit byte. + 1 + + BOOLEAN + As for UINT32, but only 0 and 1 are valid values. + 4 + + INT32 + 32-bit signed integer in the message's byte order. + 4 + + UINT32 + 32-bit unsigned integer in the message's byte order. + 4 + + INT64 + 64-bit signed integer in the message's byte order. + 8 + + UINT64 + 64-bit unsigned integer in the message's byte order. + 8 + + DOUBLE + 64-bit IEEE 754 double in the message's byte order. + 8 + + STRING + A UINT32 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. + + + 4 (for the length) + + + OBJECT_PATH + Exactly the same as STRING. + + + 4 (for the length) + + + SIGNATURE + The same as STRING except the length is a single + byte (thus signatures have a maximum length of 255). + + + 1 + + + ARRAY + + A UINT32 giving the length of the array data in bytes, followed by + alignment padding to the alignment boundary of the array element type, + followed by each array element. The array length is from the + end of the alignment padding to the end of the last element, + i.e. it does not include the padding after the length, + or any padding after the last element. + + + 4 (for the length) + + + STRUCT + + A struct must start on an 8-byte boundary regardless of the + type of the struct fields. The struct value consists of each + field marshaled in sequence starting from that 8-byte + alignment boundary. + + + 8 + + + VARIANT + + A variant type has a marshaled SIGNATURE + followed by a marshaled value with the type + given in the signature. + Unlike a message signature, the variant signature + can contain only a single complete type. + So "i" is OK, "ii" is not. + + + 1 (alignment of the signature) + + + + + + + + + + Message Format + + + A message consists of a header and a body. The header is a block of + values with a fixed signature and meaning. The body is a separate block + of values, with a signature specified in the header. + + + + The length of the header must be a multiple of 8, allowing the body to + begin on an 8-byte boundary when storing the entire message in a single + buffer. If the header does not naturally end on an 8-byte boundary + up to 7 bytes of nul-initialized alignment padding must be added. + + + + The message body need not end on an 8-byte boundary. + + + + The signature of the header is: + + "yyyyuua(yv)" + + Written out more readably, this is: + + BYTE, BYTE, BYTE, BYTE, UINT32, UINT32, ARRAY of STRUCT of (BYTE,VARIANT) + + + + + These values have the following meanings: - Size + Value Description - 1 byte + 1st BYTE Endianness flag; ASCII 'l' for little-endian or ASCII 'B' for big-endian. - 1 byte - Type of message. Unknown types MUST be ignored. + 2nd BYTE + Message type. Unknown types MUST be ignored. Currently-defined types are described below. - 1 byte + 3rd BYTE Bitwise OR of flags. Unknown flags MUST be ignored. Currently-defined flags are described below. - 1 byte + 4th 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. + FIXME this field is stupid and pointless to put in + every message. - 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. + 1st UINT32 + Length in bytes of the message body, starting + from the end of the header. The header ends after + its alignment padding to an 8-boundary. - 4 bytes - An unsigned 32-bit integer in the - message's byte order, indicating the total length in bytes of - the message body. + 2nd UINT32 + The serial of this message, used as a cookie + by the sender to identify the reply corresponding + to this request. - 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. + ARRAY of STRUCT of (BYTE,VARIANT) + An array of zero or more header + fields where the byte is the field code, and the + variant is the field value. The message type determines + which fields are required. @@ -187,7 +547,8 @@ - Types that can appear in the second byte of the header: + Message types that can appear in the second byte + of the header are: @@ -259,130 +620,122 @@ - - - Header Fields - - In addition to the required header information mentioned - in , - the header must contain the required named header - fields and zero or more of the optional 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 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. - + + A header must contain the required named header fields for the given + message type, and zero or more of any optional 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. + - - Here are the currently-defined named header fields: - - - - - Conventional Name - Decimal Value - Type - Required - Description - - - - - INVALID - 0 - INVALID - no - Not a valid field name (error if it appears in a message) - - - PATH - 1 - OBJECT_PATH - yes - The object to send the message to; objects are identified by - a path, "/foo/bar" - - - INTERFACE - 2 - STRING - yes - The interface to invoke a method call on, or - that a signal is emitted from. e.g. "org.freedesktop.Introspectable" - - - MEMBER - 3 - STRING - yes - The member, either the method name or signal name. - e.g. "Frobate" - - - ERROR_NAME - 4 - STRING - no - The name of the error that occurred, for errors - - - REPLY_SERIAL - 5 - UINT32 - no - The serial number of the message this message is a reply - to. (The serial number is one of the mandatory header fields, - see .) - - - DESTINATION - 6 - STRING - no - The name of the service this message should be routed to. - Only used in combination with the message bus, see - . - - - SENDER - 7 - STRING - no - 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. - - + + Again, if an implementation sees a header field name that it does not + understand, it MUST ignore that field, as it will be part of a new + (but compatible) version of this specification. + + + Here are the currently-defined named header fields: + + + + + Conventional Name + Decimal Value + Type + Required In + Description + + + + + INVALID + 0 + INVALID + not allowed + Not a valid field name (error if it appears in a message) + + + PATH + 1 + OBJECT_PATH + METHOD_CALL, SIGNAL + The object to send a call to, + or the object a signal is emitted from. + + + + INTERFACE + 2 + STRING + SIGNAL + + The interface to invoke a method call on, or + that a signal is emitted from. Optional for + method calls, required for signals. + + + + MEMBER + 3 + STRING + METHOD_CALL, SIGNAL + The member, either the method name or signal name. + + + ERROR_NAME + 4 + STRING + ERROR + The name of the error that occurred, for errors + + + REPLY_SERIAL + 5 + UINT32 + ERROR, METHOD_RETURN + The serial number of the message this message is a reply + to. (The serial number is the second UINT32 in the header.) + + + DESTINATION + 6 + STRING + optional + The name of the service this message should be routed to. + Only used in combination with the message bus, see + . + + + SENDER + 7 + STRING + optional + 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. + + + SIGNATURE + 8 + SIGNATURE + optional + The signature of the message body. + If omitted, it is assumed to be the + empty signature "" (i.e. the body is 0-length). + + + + + + + + Message Arguments -- cgit