Attachment 120520 Details for Bug 93382 – spec: Clarify the marshaling format in a few minor ways

[patch] spec: Clarify the marshaling format in a few minor ways

spec-Clarify-the-marshaling-format-in-a-few-minor-.patch (text/plain), 4.45 KB, created by Philip Withnall on 2015-12-15 09:26:56 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Philip Withnall

Created: 2015-12-15 09:26:56 UTC

Size: 4.45 KB

patch

obsolete

>From d62f7ce538aa6c9b771fe07010dbd27f9f75c4a8 Mon Sep 17 00:00:00 2001
>From: Philip Withnall <philip.withnall@collabora.co.uk>
>Date: Tue, 15 Dec 2015 09:25:36 +0000
>Subject: [PATCH] spec: Clarify the marshaling format in a few minor ways
>MIME-Version: 1.0
>Content-Type: text/plain; charset=UTF-8
>Content-Transfer-Encoding: 8bit
>
>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).
>
>https://bugs.freedesktop.org/show_bug.cgi?id=93382
>---
> doc/dbus-specification.xml | 30 +++++++++++++++++++-----------
> 1 file changed, 19 insertions(+), 11 deletions(-)
>
>diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
>index 0500220..3b55915 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,24 @@
>       </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 alignment padding is placed after the
>+        trailing nul byte, rather than between <varname>n</varname> and the
>+        string text.
>       </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>
>     </sect2>
> 
>@@ -1024,7 +1029,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 +1039,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 +1063,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>
> 
>-- 
>2.5.0

Actions: View | Splinter Review

Attachments on bug 93382: 120520 | 120606

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.