diff options
author | Philip Withnall <philip.withnall@collabora.co.uk> | 2015-12-15 09:25:36 +0000 |
---|---|---|
committer | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2016-06-30 14:07:10 +0100 |
commit | 771593c21d04391828184291e39b4aa166d767e4 (patch) | |
tree | 234da291f72405f619815500db28089963922bf1 | |
parent | e536ea93ec1e865920781f22e04bc39192dc2160 (diff) |
spec: Clarify the marshaling format in a few minor ways
This is an attempt to make that section a little clearer. I don’t think
any factual inaccuracies have been fixed (because I couldn’t find any).
Including some wording and an example by Simon McVittie.
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=93382
Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
-rw-r--r-- | doc/dbus-specification.xml | 56 |
1 files changed, 45 insertions, 11 deletions
diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 05002208..ba1e7390 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -968,8 +968,10 @@ <para> 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, <firstterm>alignment - padding</firstterm> may be necessary. The alignment padding must always + 8-byte boundary. Boundaries are calculated globally, with respect to + the first byte in the message. To properly align a value, + <firstterm>alignment padding</firstterm> may be necessary before the + value. 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 @@ -996,21 +998,50 @@ </para> <para> - The string-like types are all marshalled as a + The string-like types (STRING, OBJECT_PATH and SIGNATURE) are all + marshalled as a fixed-length unsigned integer <varname>n</varname> giving the length of the variable part, followed by <varname>n</varname> 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 - <varname>n</varname>. + <varname>n</varname>: any padding required for <varname>n</varname> + appears immediately before <varname>n</varname> itself. There is never + any alignment padding between <varname>n</varname> and the string text, + or between the string text and the trailing nul. The alignment padding + for the next value in the message (if there is one) starts after the + trailing nul. </para> <para> For the STRING and OBJECT_PATH types, <varname>n</varname> is - encoded in 4 bytes, leading to 4-byte alignment. - For the SIGNATURE type, <varname>n</varname> is encoded as a single - byte. As a result, alignment padding is never required before a - SIGNATURE. + encoded in 4 bytes (a <literal>UINT32</literal>), leading to 4-byte + alignment. For the SIGNATURE type, <varname>n</varname> is encoded as a + single byte (a <literal>UINT8</literal>). As a result, alignment + padding is never required before a SIGNATURE. + </para> + + <para> + For example, if the current position is a multiple of 8 bytes from the + beginning of a little-endian message, strings ‘foo’, ‘+’ and ‘bar’ + would be serialized in sequence as follows: + + <screen> + <lineannotation>no padding required, we are already at a multiple of 4</lineannotation> +0x03 0x00 0x00 0x00 <lineannotation>length of ‘foo’ = 3</lineannotation> + 0x66 0x6f 0x6f <lineannotation>‘foo’</lineannotation> + 0x00 <lineannotation>trailing nul</lineannotation> + + <lineannotation>no padding required, we are already at a multiple of 4</lineannotation> +0x01 0x00 0x00 0x00 <lineannotation>length of ‘+’ = 1</lineannotation> + 0x2b <lineannotation>‘+’</lineannotation> + 0x00 <lineannotation>trailing nul</lineannotation> + + 0x00 0x00 <lineannotation>2 bytes of padding to reach next multiple of 4</lineannotation> +0x03 0x00 0x00 0x00 <lineannotation>length of ‘bar’ = 1</lineannotation> + 0x62 0x61 0x72 <lineannotation>‘bar’</lineannotation> + 0x00 <lineannotation>trailing nul</lineannotation> + </screen> </para> </sect2> @@ -1024,7 +1055,8 @@ element type, followed by the <varname>n</varname> bytes of the array elements marshalled in sequence. <varname>n</varname> does not include the padding after the length, or any padding after the - last element. + last element. i.e. <varname>n</varname> should be divisible by the + number of elements in the array. </para> <para> @@ -1033,7 +1065,7 @@ the 64-bit integer 5 would be marshalled as: <screen> -00 00 00 08 <lineannotation>8 bytes of data</lineannotation> +00 00 00 08 <lineannotation><varname>n</varname> = 8 bytes of data</lineannotation> 00 00 00 00 <lineannotation>padding to 8-byte boundary</lineannotation> 00 00 00 00 00 00 00 05 <lineannotation>first element = 5</lineannotation> </screen> @@ -1057,8 +1089,10 @@ 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 + Use of variants must not cause a total message depth to be larger than 64, including other container types such as structures. + (See <link linkend="message-protocol-marshaling-signature">Valid + Signatures</link>.) </para> </sect2> |