From: Simon McVittie Date: Fri, 15 Jun 2012 12:58:24 +0000 (+0100) Subject: Promote the definition of valid object paths and signatures into the type system X-Git-Tag: dbus-1.7.0~67 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=7b81cecae005b189f1d8616e0c23c0c0c86ba9dd;p=platform%2Fupstream%2Fdbus.git 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. 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 eea9ef3..52c9e6c 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -494,6 +494,130 @@ + + Valid Object Paths + + + 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. + + + + Object paths are often namespaced by starting with a reversed + domain name and containing an interface version number, in the + same way as + interface + names and + well-known + bus names. + This makes it possible to implement more than one service, or + more than one version of a service, in the same process, + even if the services share a connection but cannot otherwise + co-operate (for instance, if they are implemented by different + plugins). + + + + For instance, if the owner of example.com is + developing a D-Bus API for a music player, they might use the + hierarchy of object paths that start with + /com/example/MusicPlayer1 for its objects. + + + + The following rules define a valid object path. Implementations must + not send or accept messages with invalid object paths. + + + + The path may be of any length. + + + + + The path must begin with an ASCII '/' (integer 47) character, + and must consist of elements separated by slash characters. + + + + + Each element must only contain the ASCII characters + "[A-Z][a-z][0-9]_" + + + + + No element may be the empty string. + + + + + Multiple '/' characters cannot occur in sequence. + + + + + A trailing '/' character is not allowed unless the + path is the root path (a single '/' character). + + + + + + + + + Valid Signatures + + An implementation must not send or accept invalid signatures. + Valid signatures will conform to the following rules: + + + + The signature is a list of single complete types. + Arrays must have element types, and structs must + have both open and close parentheses. + + + + + Only type codes, open and close parentheses, and open and + close curly brackets are allowed in the signature. The + STRUCT type code + is not allowed in signatures, because parentheses + are used instead. Similarly, the + DICT_ENTRY type code is not allowed in + signatures, because curly brackets are used instead. + + + + + 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. + + + + + The maximum length of a signature is 255. + + + + + + + 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. + + + @@ -841,7 +965,7 @@ OBJECT_PATH Exactly the same as STRING except the - content must be a valid object path (see below). + content must be a valid object path (see above). 4 (for the length) @@ -850,7 +974,7 @@ SIGNATURE The same as STRING 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). 1 @@ -919,130 +1043,7 @@ - - - Valid Object Paths - - - 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. - - - - The following rules define a valid object path. Implementations must - not send or accept messages with invalid object paths. - - - - The path may be of any length. - - - - - The path must begin with an ASCII '/' (integer 47) character, - and must consist of elements separated by slash characters. - - - - - Each element must only contain the ASCII characters - "[A-Z][a-z][0-9]_" - - - - - No element may be the empty string. - - - - - Multiple '/' characters cannot occur in sequence. - - - - - A trailing '/' character is not allowed unless the - path is the root path (a single '/' character). - - - - - - - Object paths are often namespaced by starting with a reversed - domain name and containing an interface version number, in the - same way as - interface - names and - well-known - bus names. - This makes it possible to implement more than one service, or - more than one version of a service, in the same process, - even if the services share a connection but cannot otherwise - co-operate (for instance, if they are implemented by different - plugins). - - - - For instance, if the owner of example.com is - developing a D-Bus API for a music player, they might use the - hierarchy of object paths that start with - /com/example/MusicPlayer1 for its objects. - - - - Valid Signatures - - An implementation must not send or accept invalid signatures. - Valid signatures will conform to the following rules: - - - - The signature ends with a nul byte. - - - - - The signature is a list of single complete types. - Arrays must have element types, and structs must - have both open and close parentheses. - - - - - Only type codes and open and close parentheses are - allowed in the signature. The STRUCT type code - is not allowed in signatures, because parentheses - are used instead. - - - - - 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. - - - - - The maximum length of a signature is 255. - - - - - Signatures must be nul-terminated. - - - - - -