X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fdbus-specification.xml;h=673383a99bbd1ab5d4cb4c9988aceac3c880aa44;hb=7d9239c9c78cb6d0b9c282376fcf3cda1de23209;hp=d806b8eaf59bfdee0469eb24ab44be0c6dfa0ddf;hpb=e48de6be84f89636f11159b9e7ea56b6dc49d577;p=platform%2Fupstream%2Fdbus.git diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index d806b8e..673383a 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -1,13 +1,13 @@ -
D-Bus Specification - Version 0.19 - 2012-02-21 + Version 0.22 + (not yet released) Havoc @@ -72,12 +72,26 @@ - current - commit log + 0.22 + not yet released (commit log) + 0.21 + 2013-04-25 + smcv + allow Unicode noncharacters in UTF-8 (Unicode + Corrigendum #9) + + + 0.20 + 22 February 2013 + smcv, walters + reorganise for clarity, remove false claims about + basic types, mention /o/fd/DBus + + 0.19 20 February 2012 smcv/lp @@ -292,17 +306,68 @@ it back from the wire format is unmarshaling. - - Type Signatures + + The D-Bus protocol does not include type tags in the marshaled data; a + block of marshaled values must have a known type + signature. The type signature is made up of zero or more + single complete + types, each made up of one or more + type codes. + + + + A type code is an ASCII character representing the + type of a value. Because ASCII characters are used, the type signature + will always form a valid ASCII string. A simple string compare + determines whether two type signatures are equivalent. + + + + A single complete type is a sequence of type codes that fully describes + one type: either a basic type, or a single fully-described container type. + A single complete type is a basic type code, a variant type code, + an array with its element type, or a struct with its fields (all of which + are defined below). So the following signatures are not single complete + types: + + "aa" + + + "(ii" + + + "ii)" + + And the following signatures contain multiple complete types: + + "ii" + + + "aiai" + + + "(ii)(ii)" + + Note however that a single complete type may contain + multiple other single complete types, by containing a struct or dict + entry. + + + + Basic types - The D-Bus protocol does not include type tags in the marshaled data; a - block of marshaled values must have a known type - signature. The type signature is made up of type - codes. A type code is an ASCII character representing the - type of a value. Because ASCII characters are used, the type signature - will always form a valid ASCII string. A simple string compare - determines whether two type signatures are equivalent. + The simplest type codes are the basic + types, which are the types whose structure is entirely + defined by their 1-character type code. Basic types consist of + fixed types and string-like types. + + + + The fixed types + are basic types whose values have a fixed length, namely BYTE, + BOOLEAN, DOUBLE, UNIX_FD, and signed or unsigned integers of length + 16, 32 or 64 bits. @@ -319,10 +384,267 @@ - All basic types work like - INT32 in this example. To marshal and unmarshal - basic types, you simply read one value from the data - block corresponding to each type code in the signature. + The characteristics of the fixed types are listed in this table. + + + + + + Conventional name + ASCII type-code + Encoding + + + + + BYTE + y (121) + Unsigned 8-bit integer + + + BOOLEAN + b (98) + Boolean value: 0 is false, 1 is true, any other value + allowed by the marshalling format is invalid + + + INT16 + n (110) + Signed (two's complement) 16-bit integer + + + UINT16 + q (113) + Unsigned 16-bit integer + + + INT32 + i (105) + Signed (two's complement) 32-bit integer + + + UINT32 + u (117) + Unsigned 32-bit integer + + + INT64 + x (120) + Signed (two's complement) 64-bit integer + (mnemonic: x and t are the first characters in "sixty" not + already used for something more common) + + + UINT64 + t (116) + Unsigned 64-bit integer + + + DOUBLE + d (100) + IEEE 754 double-precision floating point + + + UNIX_FD + h (104) + Unsigned 32-bit integer representing an index into an + out-of-band array of file descriptors, transferred via some + platform-specific mechanism (mnemonic: h for handle) + + + + + + + + The string-like types + are basic types with a variable length. The value of any string-like + type is conceptually 0 or more Unicode codepoints encoded in UTF-8, + none of which may be U+0000. The UTF-8 text must be validated + strictly: in particular, it must not contain overlong sequences + or codepoints above U+10FFFF. + + + + Since D-Bus Specification version 0.21, in accordance with Unicode + Corrigendum #9, the "noncharacters" U+FDD0..U+FDEF, U+nFFFE and + U+nFFFF are allowed in UTF-8 strings (but note that older versions of + D-Bus rejected these noncharacters). + + + + The marshalling formats for the string-like types all end with a + single zero (NUL) byte, but that byte is not considered to be part of + the text. + + + + The characteristics of the string-like types are listed in this table. + + + + + + Conventional name + ASCII type-code + Validity constraints + + + + + STRING + s (115) + No extra constraints + + + OBJECT_PATH + o (111) + Must be + a + syntactically valid object path + + + SIGNATURE + g (103) + Zero or more + single + complete types + + + + + + + + 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. + + + + + + + Container types + + In addition to basic types, there are four container types: STRUCT, ARRAY, VARIANT, and DICT_ENTRY. @@ -378,34 +700,6 @@ - The phrase single complete type deserves some - definition. A single complete type is a basic type code, a variant type code, - an array with its element type, or a struct with its fields. - So the following signatures are not single complete types: - - "aa" - - - "(ii" - - - "ii)" - - And the following signatures contain multiple complete types: - - "ii" - - - "aiai" - - - "(ii)(ii)" - - Note however that a single complete type may contain - multiple other single complete types. - - - VARIANT has ASCII character 'v' as its type code. A marshaled value of type VARIANT will have the signature of a single complete type as part of the value. This signature will be followed by a @@ -413,6 +707,14 @@ + 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. The restrictions are: it occurs only as an array element type; it has @@ -435,6 +737,10 @@ In most languages, an array of dict entry would be represented as a map, hash table, or dict object. + + + + Summary of types The following table summarizes the D-Bus types. @@ -566,9 +872,21 @@ + + + + Marshaling (Wire Format) + + + D-Bus defines a marshalling format for its type system, which is + used in D-Bus messages. This is not the only possible marshalling + format for the type system: for instance, GVariant (part of GLib) + re-uses the D-Bus type system but implements an alternative marshalling + format. + - - Marshaling (Wire Format) + + Byte order and alignment Given a type signature, a block of bytes can be converted into typed @@ -577,11 +895,11 @@ - A block of bytes has an associated byte order. The byte order - has to be discovered in some way; for D-Bus messages, the - byte order is part of the message header as described in - . For now, assume - that the byte order is known to be either little endian or big + A block of bytes has an associated byte order. The byte order + has to be discovered in some way; for D-Bus messages, the + byte order is part of the message header as described in + . For now, assume + that the byte order is known to be either little endian or big endian. @@ -597,6 +915,95 @@ + 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. + + + + + Marshalling basic types + + + To marshal and unmarshal fixed types, you simply read one value + from the data block corresponding to each type code in the signature. + All signed integer values are encoded in two's complement, DOUBLE + values are IEEE 754 double-precision floating-point, and BOOLEAN + values are encoded in 32 bits (of which only the least significant + bit is used). + + + + The string-like types are all marshalled as a + fixed-length unsigned integer n giving the + length of the variable part, followed by n + 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 + n. + + + + For the STRING and OBJECT_PATH types, n is + encoded in 4 bytes, leading to 4-byte alignment. + For the SIGNATURE type, n is encoded as a single + byte. As a result, alignment padding is never required before a + SIGNATURE. + + + + + Marshalling containers + + + 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. + + + + + Summary of D-Bus marshalling + + Given all this, the types are marshaled on the wire as follows: @@ -661,7 +1068,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) @@ -670,199 +1077,65 @@ 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). - - - 1 - - - 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. - - - 4 (for the length) - - - STRUCT - - A struct must start on an 8-byte boundary regardless of the - type of the struct fields. The struct value consists of each - field marshaled in sequence starting from that 8-byte - alignment boundary. - - - 8 - - - 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. - - - 1 (alignment of the signature) - - - DICT_ENTRY - - Identical to STRUCT. - - - 8 - - - UNIX_FD - 32-bit unsigned integer in the message's byte - order. The actual file descriptors need to be - transferred out-of-band via some platform specific - mechanism. On the wire, values of this type store the index to the - file descriptor in the array of file descriptors that - accompany the message. - 4 - - - - - - - - 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. - - + and the content must be a valid signature (see above). + + + 1 + + + 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. + + + 4 (for the length) + + + STRUCT + + A struct must start on an 8-byte boundary regardless of the + type of the struct fields. The struct value consists of each + field marshaled in sequence starting from that 8-byte + alignment boundary. + + + 8 + + + VARIANT + + 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) + + + DICT_ENTRY + + Identical to STRUCT. + + + 8 + + + UNIX_FD + 32-bit unsigned integer in the message's byte + order. The actual file descriptors need to be + transferred out-of-band via some platform specific + mechanism. On the wire, values of this type store the index to the + file descriptor in the array of file descriptors that + accompany the message. + 4 + + + + + - - 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. - - - - - - @@ -2174,7 +2447,7 @@ - Receive REJECT [mechs] → send AUTH [next mech], + Receive REJECTED [mechs] → send AUTH [next mech], goto WaitingForData or WaitingForOK @@ -2210,7 +2483,7 @@ - Receive REJECT [mechs] → send AUTH [next mech], + Receive REJECTED [mechs] → send AUTH [next mech], goto WaitingForData or WaitingForOK @@ -2252,7 +2525,7 @@ - REJECT means that the client failed to authenticate or + REJECTED means that the client failed to authenticate or there was an error in RESP. @@ -2299,7 +2572,7 @@ - MECH(RESP) returns REJECT → send REJECTED + MECH(RESP) returns REJECTED → send REJECTED [mechs], goto WaitingForAuth @@ -2353,7 +2626,7 @@ - MECH(RESP) returns REJECT → send REJECTED + MECH(RESP) returns REJECTED → send REJECTED [mechs], goto WaitingForAuth @@ -3388,8 +3661,8 @@ <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> - <node name="/org/freedesktop/sample_object"> - <interface name="org.freedesktop.SampleInterface"> + <node name="/com/example/sample_object"> + <interface name="com.example.SampleInterface"> <method name="Frobate"> <arg name="foo" type="i" direction="in"/> <arg name="bar" type="s" direction="out"/> @@ -3549,14 +3822,17 @@ unique-for-the-lifetime-of-the-bus name automatically assigned. Applications may request additional names for a connection. Additional names are usually "well-known names" such as - "org.freedesktop.TextEditor". When a name is bound to a connection, + "com.example.TextEditor". When a name is bound to a connection, that connection is said to own the name. - The bus itself owns a special name, org.freedesktop.DBus. - This name routes messages to the bus, allowing applications to make - administrative requests. For example, applications can ask the bus - to assign a name to a connection. + The bus itself owns a special name, + org.freedesktop.DBus, with an object + located at /org/freedesktop/DBus that + implements the org.freedesktop.DBus + interface. This service allows applications to make + administrative requests of the bus itself. For example, + applications can ask the bus to assign a name to a connection. Each name may have queued owners. When an @@ -3568,7 +3844,7 @@ This feature causes the right thing to happen if you start two text - editors for example; the first one may request "org.freedesktop.TextEditor", + editors for example; the first one may request "com.example.TextEditor", and the second will be queued as a possible owner of that name. When the first exits, the second will take over. @@ -4140,8 +4416,7 @@ The following table describes the keys that can be used to create - a match rule: - The following table summarizes the D-Bus types. + a match rule. @@ -4343,9 +4618,9 @@ With D-Bus, starting a service is normally done by name. That is, applications ask the message bus to start some program that will own a - well-known name, such as org.freedesktop.TextEditor. - This implies a contract documented along with the name - org.freedesktop.TextEditor for which objects + well-known name, such as com.example.TextEditor. + This implies a contract documented along with the name + com.example.TextEditor for which object the owner of that name will provide, and what interfaces those objects will have. @@ -4384,8 +4659,8 @@ # Sample service description file [D-BUS Service] - Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf; - Exec=/usr/libexec/gconfd-2 + Name=com.example.ConfigurationDatabase + Exec=/usr/bin/sample-configd @@ -5304,6 +5579,225 @@ + + <literal>org.freedesktop.DBus.GetConnectionCredentials</literal> + + As a method: + + DICT<STRING,VARIANT> GetConnectionCredentials (in STRING bus_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Unique or well-known bus name of the connection to + query, such as :12.34 or + com.example.tea + + + + + Reply arguments: + + + + + Argument + Type + Description + + + + + 0 + DICT<STRING,VARIANT> + Credentials + + + + + + + + Returns as many credentials as possible for the process connected to + the server. If unable to determine certain credentials (for instance, + because the process is not on the same machine as the bus daemon, + or because this version of the bus daemon does not support a + particular security framework), or if the values of those credentials + cannot be represented as documented here, then those credentials + are omitted. + + + + Keys in the returned dictionary not containing "." are defined + by this specification. Bus daemon implementors supporting + credentials frameworks not mentioned in this document should either + contribute patches to this specification, or use keys containing + "." and starting with a reversed domain name. + + + + + Key + Value type + Value + + + + + UnixUserID + UINT32 + The numeric Unix user ID, as defined by POSIX + + + ProcessID + UINT32 + The numeric process ID, on platforms that have + this concept. On Unix, this is the process ID defined by + POSIX. + + + + + + + + This method was added in D-Bus 1.7 to reduce the round-trips + required to list a process's credentials. In older versions, calling + this method will fail: applications should recover by using the + separate methods such as + + instead. + + + + + <literal>org.freedesktop.DBus.GetAdtAuditSessionData</literal> + + As a method: + + ARRAY of BYTE GetAdtAuditSessionData (in STRING bus_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Unique or well-known bus name of the connection to + query, such as :12.34 or + com.example.tea + + + + + Reply arguments: + + + + + Argument + Type + Description + + + + + 0 + ARRAY of BYTE + auditing data as returned by + adt_export_session_data() + + + + + Returns auditing data used by Solaris ADT, in an unspecified + binary format. If you know what this means, please contribute + documentation via the D-Bus bug tracking system. + This method is on the core DBus interface for historical reasons; + the same information should be made available via + + in future. + + + + + <literal>org.freedesktop.DBus.GetConnectionSELinuxSecurityContext</literal> + + As a method: + + ARRAY of BYTE GetConnectionSELinuxSecurityContext (in STRING bus_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Unique or well-known bus name of the connection to + query, such as :12.34 or + com.example.tea + + + + + Reply arguments: + + + + + Argument + Type + Description + + + + + 0 + ARRAY of BYTE + some sort of string of bytes, not necessarily UTF-8, + not including '\0' + + + + + Returns the security context used by SELinux, in an unspecified + format. If you know what this means, please contribute + documentation via the D-Bus bug tracking system. + This method is on the core DBus interface for historical reasons; + the same information should be made available via + + in future. + + + + <literal>org.freedesktop.DBus.AddMatch</literal> @@ -5546,9 +6040,9 @@ A service is an executable that can be launched by the bus daemon. Services normally guarantee some particular features, for example they may guarantee that they will request a specific name such as - "org.freedesktop.Screensaver", have a singleton object - "/org/freedesktop/Application", and that object will implement the - interface "org.freedesktop.ScreensaverControl". + "com.example.Screensaver", have a singleton object + "/com/example/Application", and that object will implement the + interface "com.example.Screensaver.Control".