X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fdbus-specification.xml;h=b31307083afada09d94be5c530f93e084cb2ddc2;hb=1dd0ff6d5bc95516d26bd1dff6dd97599ac60e2e;hp=d806b8eaf59bfdee0469eb24ab44be0c6dfa0ddf;hpb=a183a33fb5bceefe53d60d584f352ca0b61667e1;p=platform%2Fupstream%2Fdbus.git diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index d806b8e..b313070 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -6,8 +6,8 @@
D-Bus Specification - Version 0.19 - 2012-02-21 + Version 0.20 + unreleased Havoc @@ -74,8 +74,9 @@ current commit log - - + smcv, walters + reorganise for clarity, remove false claims about + basic types, mention /o/fd/DBus 0.19 @@ -292,17 +293,68 @@ it back from the wire format is unmarshaling. - - 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 zero or more + single complete + types, each made up of one or more + 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. + + + + A single complete type is a sequence of type codes that fully describes + one type: either a basic type, or a single fully-described container type. + 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 (all of which + are defined below). 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, by containing a struct or dict + entry. + + + + Basic types - 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. + The simplest type codes are the basic + types, which are the types whose structure is entirely + defined by their 1-character type code. Basic types consist of + fixed types and string-like types. + + + + The fixed types + are basic types whose values have a fixed length, namely BYTE, + BOOLEAN, DOUBLE, UNIX_FD, and signed or unsigned integers of length + 16, 32 or 64 bits. @@ -319,10 +371,260 @@ - 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. + The characteristics of the fixed types are listed in this table. + + + + + + Conventional name + ASCII type-code + Encoding + + + + + BYTE + y (121) + Unsigned 8-bit integer + + + BOOLEAN + b (98) + Boolean value: 0 is false, 1 is true, any other value + allowed by the marshalling format is invalid + + + INT16 + n (110) + Signed (two's complement) 16-bit integer + + + UINT16 + q (113) + Unsigned 16-bit integer + + + INT32 + i (105) + Signed (two's complement) 32-bit integer + + + UINT32 + u (117) + Unsigned 32-bit integer + + + INT64 + x (120) + Signed (two's complement) 64-bit integer + (mnemonic: x and t are the first characters in "sixty" not + already used for something more common) + + + UINT64 + t (116) + Unsigned 64-bit integer + + + DOUBLE + d (100) + IEEE 754 double-precision floating point + + + UNIX_FD + h (104) + Unsigned 32-bit integer representing an index into an + out-of-band array of file descriptors, transferred via some + platform-specific mechanism (mnemonic: h for handle) + + + + + + + + The string-like types + are basic types with a variable length. The value of any string-like + type is conceptually 0 or more Unicode codepoints encoded in UTF-8, + none of which may be U+0000. The UTF-8 text must be validated + strictly: in particular, it must not contain overlong sequences, + noncharacters such as U+FFFE, or codepoints above U+10FFFF. + + + + The marshalling formats for the string-like types all end with a + single zero (NUL) byte, but that byte is not considered to be part of + the text. + + + + The characteristics of the string-like types are listed in this table. + + + + + + Conventional name + ASCII type-code + Validity constraints + + + + + STRING + s (115) + No extra constraints + + + OBJECT_PATH + o (111) + Must be + a + syntactically valid object path + + + SIGNATURE + g (103) + Zero or more + single + complete types + + + + + + + + Valid Object Paths + + + An object path is a name used to refer to an object instance. + Conceptually, each participant in a D-Bus message exchange may have + any number of object instances (think of C++ or Java objects) and each + such instance will have a path. Like a filesystem, the object + instances in an application form a hierarchical tree. + + + + Object paths are often namespaced by starting with a reversed + domain name and containing an interface version number, in the + same way as + interface + names and + well-known + bus names. + This makes it possible to implement more than one service, or + more than one version of a service, in the same process, + even if the services share a connection but cannot otherwise + co-operate (for instance, if they are implemented by different + plugins). + + + + For instance, if the owner of example.com is + developing a D-Bus API for a music player, they might use the + hierarchy of object paths that start with + /com/example/MusicPlayer1 for its objects. + + + + The following rules define a valid object path. Implementations must + not send or accept messages with invalid object paths. + + + + The path may be of any length. + + + + + The path must begin with an ASCII '/' (integer 47) character, + and must consist of elements separated by slash characters. + + + + + Each element must only contain the ASCII characters + "[A-Z][a-z][0-9]_" + + + + + No element may be the empty string. + + + + + Multiple '/' characters cannot occur in sequence. + + + + + A trailing '/' character is not allowed unless the + path is the root path (a single '/' character). + + + + + + + + + Valid Signatures + + An implementation must not send or accept invalid signatures. + Valid signatures will conform to the following rules: + + + + The signature is a list of single complete types. + Arrays must have element types, and structs must + have both open and close parentheses. + + + + + Only type codes, open and close parentheses, and open and + close curly brackets are allowed in the signature. The + STRUCT type code + is not allowed in signatures, because parentheses + are used instead. Similarly, the + DICT_ENTRY type code is not allowed in + signatures, because curly brackets are used instead. + + + + + The maximum depth of container type nesting is 32 array type + codes and 32 open parentheses. This implies that the maximum + total depth of recursion is 64, for an "array of array of array + of ... struct of struct of struct of ..." where there are 32 + array and 32 struct. + + + + + The maximum length of a signature is 255. + + + + + + + When signatures appear in messages, the marshalling format + guarantees that they will be followed by a nul byte (which can + be interpreted as either C-style string termination or the INVALID + type-code), but this is not conceptually part of the signature. + + + + + + + Container types + + In addition to basic types, there are four container types: STRUCT, ARRAY, VARIANT, and DICT_ENTRY. @@ -378,34 +680,6 @@ - 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 @@ -413,6 +687,14 @@ + Unlike a message signature, the variant signature can + contain only a single complete type. So "i", "ai" + or "(ii)" is OK, but "ii" is not. Use of variants may not + cause a total message depth to be larger than 64, including + other container types such as structures. + + + A DICT_ENTRY works exactly like a struct, but rather than parentheses it uses curly braces, and it has more restrictions. The restrictions are: it occurs only as an array element type; it has @@ -435,6 +717,10 @@ In most languages, an array of dict entry would be represented as a map, hash table, or dict object. + + + + Summary of types The following table summarizes the D-Bus types. @@ -566,9 +852,21 @@ + - - Marshaling (Wire Format) + + Marshaling (Wire Format) + + + D-Bus defines a marshalling format for its type system, which is + used in D-Bus messages. This is not the only possible marshalling + format for the type system: for instance, GVariant (part of GLib) + re-uses the D-Bus type system but implements an alternative marshalling + format. + + + + Byte order and alignment Given a type signature, a block of bytes can be converted into typed @@ -577,11 +875,11 @@ - 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 + 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. @@ -597,6 +895,95 @@ + As an exception to natural alignment, STRUCT and + DICT_ENTRY values are always aligned to an 8-byte + boundary, regardless of the alignments of their contents. + + + + + Marshalling basic types + + + To marshal and unmarshal fixed types, you simply read one value + from the data block corresponding to each type code in the signature. + All signed integer values are encoded in two's complement, DOUBLE + values are IEEE 754 double-precision floating-point, and BOOLEAN + values are encoded in 32 bits (of which only the least significant + bit is used). + + + + The string-like types are all marshalled as a + fixed-length unsigned integer n giving the + length of the variable part, followed by n + nonzero bytes of UTF-8 text, followed by a single zero (nul) byte + which is not considered to be part of the text. The alignment + of the string-like type is the same as the alignment of + n. + + + + For the STRING and OBJECT_PATH types, n is + encoded in 4 bytes, leading to 4-byte alignment. + For the SIGNATURE type, n is encoded as a single + byte. As a result, alignment padding is never required before a + SIGNATURE. + + + + + Marshalling containers + + + Arrays are marshalled as a UINT32 + n giving the length of the array data in bytes, + followed by alignment padding to the alignment boundary of the array + element type, followed by the n bytes of the + array elements marshalled in sequence. n does not + include the padding after the length, or any padding after the + last element. + + + + For instance, if the current position in the message is a multiple + of 8 bytes and the byte-order is big-endian, an array containing only + the 64-bit integer 5 would be marshalled as: + + +00 00 00 08 8 bytes of data +00 00 00 00 padding to 8-byte boundary +00 00 00 00 00 00 00 05 first element = 5 + + + + + Arrays have a maximum length defined to be 2 to the 26th power or + 67108864. Implementations must not send or accept arrays exceeding this + length. + + + + Structs and dict entries are marshalled in the same way as their + contents, but their alignment is always to an 8-byte boundary, + even if their contents would normally be less strictly aligned. + + + + Variants are marshalled as the SIGNATURE of + the contents (which must be a single complete type), followed by a + marshalled value with the type given by that signature. The + variant has the same 1-byte alignment as the signature, which means + that alignment padding before a variant is never needed. + Use of variants may not cause a total message depth to be larger + than 64, including other container types such as structures. + + + + + Summary of D-Bus marshalling + + Given all this, the types are marshaled on the wire as follows: @@ -661,7 +1048,7 @@ OBJECT_PATH Exactly the same as STRING except the - content must be a valid object path (see below). + content must be a valid object path (see above). 4 (for the length) @@ -670,7 +1057,7 @@ SIGNATURE The same as STRING except the length is a single byte (thus signatures have a maximum length of 255) - and the content must be a valid signature (see below). + and the content must be a valid signature (see above). 1 @@ -679,14 +1066,8 @@ 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. - Arrays have a maximum length defined to be 2 to the 26th power or - 67108864. Implementations must not send or accept arrays exceeding this - length. + alignment padding to the alignment boundary of the array element type, + followed by each array element. 4 (for the length) @@ -705,14 +1086,9 @@ 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", "ai" - or "(ii)" is OK, but "ii" is not. Use of variants may not - cause a total message depth to be larger than 64, including - other container types such as structures. + The marshaled SIGNATURE of a single + complete type, followed by a marshaled value with the type + given in the signature. 1 (alignment of the signature) @@ -739,130 +1115,7 @@ - - - Valid Object Paths - - - An object path is a name used to refer to an object instance. - Conceptually, each participant in a D-Bus message exchange may have - any number of object instances (think of C++ or Java objects) and each - such instance will have a path. Like a filesystem, the object - instances in an application form a hierarchical tree. - - - - The following rules define a valid object path. Implementations must - not send or accept messages with invalid object paths. - - - - The path may be of any length. - - - - - The path must begin with an ASCII '/' (integer 47) character, - and must consist of elements separated by slash characters. - - - - - Each element must only contain the ASCII characters - "[A-Z][a-z][0-9]_" - - - - - No element may be the empty string. - - - - - Multiple '/' characters cannot occur in sequence. - - - - - A trailing '/' character is not allowed unless the - path is the root path (a single '/' character). - - - - - - - Object paths are often namespaced by starting with a reversed - domain name and containing an interface version number, in the - same way as - interface - names and - well-known - bus names. - This makes it possible to implement more than one service, or - more than one version of a service, in the same process, - even if the services share a connection but cannot otherwise - co-operate (for instance, if they are implemented by different - plugins). - - - - For instance, if the owner of example.com is - developing a D-Bus API for a music player, they might use the - hierarchy of object paths that start with - /com/example/MusicPlayer1 for its objects. - - - - Valid Signatures - - An implementation must not send or accept invalid signatures. - Valid signatures will conform to the following rules: - - - - The signature ends with a nul byte. - - - - - The signature is a list of single complete types. - Arrays must have element types, and structs must - have both open and close parentheses. - - - - - Only type codes and open and close parentheses are - allowed in the signature. The STRUCT type code - is not allowed in signatures, because parentheses - are used instead. - - - - - The maximum depth of container type nesting is 32 array type - codes and 32 open parentheses. This implies that the maximum - total depth of recursion is 64, for an "array of array of array - of ... struct of struct of struct of ..." where there are 32 - array and 32 struct. - - - - - The maximum length of a signature is 255. - - - - - Signatures must be nul-terminated. - - - - - - @@ -3553,10 +3806,13 @@ that connection is said to own the name. - The bus itself owns a special name, org.freedesktop.DBus. - This name routes messages to the bus, allowing applications to make - administrative requests. For example, applications can ask the bus - to assign a name to a connection. + The bus itself owns a special name, + org.freedesktop.DBus, with an object + located at /org/freedesktop/DBus that + implements the org.freedesktop.DBus + interface. This service allows applications to make + administrative requests of the bus itself. For example, + applications can ask the bus to assign a name to a connection. Each name may have queued owners. When an