From: Simon McVittie Date: Mon, 13 Jun 2011 12:24:40 +0000 (+0100) Subject: Define the fixed and string-like types a bit more formally X-Git-Tag: dbus-1.7.0~68 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c8e7a5690b19a2ba37fd2e22fd800a842f1c8af8;p=thirdparty%2Fdbus.git Define the fixed and string-like types a bit more formally Reviewed-by: Will Thompson Bug: https://bugs.freedesktop.org/show_bug.cgi?id=38252 --- diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 9907fa3b9..eea9ef34b 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -342,6 +342,20 @@ Basic types + + 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. + + 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 @@ -356,11 +370,130 @@ - All fixed types work like - INT32 in this example: to marshal and unmarshal - fixed 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 + + + + + @@ -616,6 +749,33 @@ than required must not be used. + + 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. + + Given all this, the types are marshaled on the wire as follows: