Attachment 47901 Details for Bug 38252 – [PATCH 6/8] Promote the definition of valid object paths and signatures into the type system

[patch] [PATCH 6/8] Promote the definition of valid object paths and signatures into the type system

0006-Promote-the-definition-of-valid-object-paths-and-sig.patch (text/plain), 9.40 KB, created by Simon McVittie on 2011-06-13 07:43:10 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Simon McVittie

Created: 2011-06-13 07:43:10 UTC

Size: 9.40 KB

patch

obsolete

>From ab5c02d079f6935132bd613bb6c12bd22bd5fb4e Mon Sep 17 00:00:00 2001
>From: Simon McVittie <simon.mcvittie@collabora.co.uk>
>Date: Mon, 13 Jun 2011 13:30:49 +0100
>Subject: [PATCH 6/8] Promote the definition of valid object paths and
> signatures into the type system
>
>Also remove the (double!) requirement that signatures be nul-terminated,
>and turn it into a note about the marshalling format.
>---
> doc/dbus-specification.xml |  209 ++++++++++++++++++++++----------------------
> 1 files changed, 104 insertions(+), 105 deletions(-)
>
>diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
>index a72e475..75d7d78 100644
>--- a/doc/dbus-specification.xml
>+++ b/doc/dbus-specification.xml
>@@ -478,6 +478,108 @@
>         </informaltable>
>       </para>
> 
>+      <sect3 id="message-protocol-marshaling-object-path">
>+        <title>Valid Object Paths</title>
>+
>+        <para>
>+          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.
>+        </para>
>+
>+        <para>
>+          The following rules define a valid object path. Implementations must
>+          not send or accept messages with invalid object paths.
>+          <itemizedlist>
>+            <listitem>
>+              <para>
>+                The path may be of any length.
>+              </para>
>+            </listitem>
>+            <listitem>
>+              <para>
>+                The path must begin with an ASCII '/' (integer 47) character,
>+                and must consist of elements separated by slash characters.
>+              </para>
>+            </listitem>
>+            <listitem>
>+              <para>
>+                Each element must only contain the ASCII characters
>+                "[A-Z][a-z][0-9]_"
>+              </para>
>+            </listitem>
>+            <listitem>
>+              <para>
>+                No element may be the empty string.
>+              </para>
>+            </listitem>
>+            <listitem>
>+              <para>
>+                Multiple '/' characters cannot occur in sequence.
>+              </para>
>+            </listitem>
>+            <listitem>
>+              <para>
>+                A trailing '/' character is not allowed unless the
>+                path is the root path (a single '/' character).
>+              </para>
>+            </listitem>
>+          </itemizedlist>
>+        </para>
>+
>+      </sect3>
>+
>+      <sect3 id="message-protocol-marshaling-signature">
>+        <title>Valid Signatures</title>
>+        <para>
>+          An implementation must not send or accept invalid signatures.
>+          Valid signatures will conform to the following rules:
>+          <itemizedlist>
>+            <listitem>
>+              <para>
>+                The signature is a list of single complete types.
>+                Arrays must have element types, and structs must
>+                have both open and close parentheses.
>+              </para>
>+            </listitem>
>+            <listitem>
>+              <para>
>+                Only type codes, open and close parentheses, and open and
>+                close curly brackets are allowed in the signature. The
>+                <literal>STRUCT</literal> type code
>+                is not allowed in signatures, because parentheses
>+                are used instead. Similarly, the
>+                <literal>DICT_ENTRY</literal> type code is not allowed in
>+                signatures, because curly brackets are used instead.
>+              </para>
>+            </listitem>
>+            <listitem>
>+              <para>
>+                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.
>+              </para>
>+            </listitem>
>+            <listitem>
>+              <para>
>+                The maximum length of a signature is 255.
>+              </para>
>+            </listitem>
>+          </itemizedlist>
>+        </para>
>+
>+        <para>
>+          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.
>+        </para>
>+      </sect3>
>+
>     </sect2>
> 
>     <sect2 id="container-types">
>@@ -825,7 +927,7 @@
>               </row><row>
>                 <entry><literal>OBJECT_PATH</literal></entry>
>                 <entry>Exactly the same as <literal>STRING</literal> except the 
>-                  content must be a valid object path (see below).
>+                  content must be a valid object path (see above).
>                 </entry>
>                 <entry>
>                   4 (for the length)
>@@ -834,7 +936,7 @@
>                 <entry><literal>SIGNATURE</literal></entry>
>                 <entry>The same as <literal>STRING</literal> 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).
>                 </entry>
>                 <entry>
>                   1
>@@ -903,110 +1005,7 @@
>           </tgroup>
>         </informaltable>
>       </para>
>-      
>-      <sect3 id="message-protocol-marshaling-object-path">
>-        <title>Valid Object Paths</title>
>-        
>-        <para>
>-          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.
>-        </para>
>-        
>-        <para>
>-          The following rules define a valid object path. Implementations must 
>-          not send or accept messages with invalid object paths.
>-          <itemizedlist>
>-            <listitem>
>-              <para>
>-                The path may be of any length.
>-              </para>
>-            </listitem>
>-            <listitem>
>-              <para>
>-                The path must begin with an ASCII '/' (integer 47) character, 
>-                and must consist of elements separated by slash characters.
>-              </para>
>-            </listitem>
>-            <listitem>
>-              <para>
>-                Each element must only contain the ASCII characters 
>-                "[A-Z][a-z][0-9]_"
>-              </para>
>-            </listitem>
>-            <listitem>
>-              <para>
>-                No element may be the empty string.
>-              </para>
>-            </listitem>
>-            <listitem>
>-              <para>
>-                Multiple '/' characters cannot occur in sequence.
>-              </para>
>-            </listitem>
>-            <listitem>
>-              <para>
>-                A trailing '/' character is not allowed unless the 
>-                path is the root path (a single '/' character).
>-              </para>
>-            </listitem>
>-          </itemizedlist>
>-        </para>
> 
>-      </sect3>
>-
>-      
>-      <sect3 id="message-protocol-marshaling-signature">
>-        <title>Valid Signatures</title>
>-        <para>
>-          An implementation must not send or accept invalid signatures.
>-          Valid signatures will conform to the following rules:
>-          <itemizedlist>
>-            <listitem>
>-              <para>
>-                The signature ends with a nul byte.
>-              </para>
>-            </listitem>
>-            <listitem>
>-              <para>
>-                The signature is a list of single complete types. 
>-                Arrays must have element types, and structs must 
>-                have both open and close parentheses.
>-              </para>
>-            </listitem>
>-            <listitem>
>-              <para>
>-                Only type codes and open and close parentheses are 
>-                allowed in the signature. The <literal>STRUCT</literal> type code
>-                is not allowed in signatures, because parentheses
>-                are used instead.
>-              </para>
>-            </listitem>
>-            <listitem>
>-              <para>
>-                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.
>-              </para>
>-            </listitem>
>-            <listitem>
>-              <para>
>-                The maximum length of a signature is 255.
>-              </para>
>-            </listitem>
>-            <listitem>
>-              <para>
>-                Signatures must be nul-terminated.
>-              </para>
>-            </listitem>
>-          </itemizedlist>
>-        </para>
>-      </sect3>
>-      
>     </sect2>
> 
>   </sect1>
>-- 
>1.7.5.4
>

Actions: View | Splinter Review

Attachments on bug 38252: 47896 | 47897 | 47898 | 47899 | 47900 | 47901 | 47902 | 47903

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.