From c58cb1b49562f45387475e2e58cd4f4c9ba0fb2c Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Mon, 13 Jun 2011 14:59:20 +0100 Subject: Describe how to marshal arrays, structs, dict-entries, variants in prose --- doc/dbus-specification.xml | 79 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 62 insertions(+), 17 deletions(-) diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 715a4f69..f0090167 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -647,6 +647,14 @@ marshaled value of that type. + + 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. @@ -846,6 +854,12 @@ not be left uninitialized (it can't contain garbage), and more padding than required must not be used. + + + 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. + @@ -882,7 +896,49 @@ Marshalling containers - ... to be written ... + + 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. + @@ -971,14 +1027,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) @@ -997,14 +1047,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) -- cgit v1.2.3