X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fdbus-specification.xml;h=86e2b9b7f570cab193a4cdedcb0a1ab4df8a80bc;hb=f0f67e4329bfc219cf9f37a4e9f0dce9513b9ae0;hp=c4fee669d3d5de021cb928566e7cff3099c05afd;hpb=9a28fa6a4efec3e664d4d33a4dd471e021ab85dc;p=platform%2Fupstream%2Fdbus.git diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index c4fee66..86e2b9b 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -478,7 +478,10 @@ STRUCT 114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')') - Struct + Struct; type code 114 'r' is reserved for use in + bindings and implementations to represent the general + concept of a struct, and must not appear in signatures + used on D-Bus. VARIANT 118 (ASCII 'v') @@ -486,12 +489,48 @@ DICT_ENTRY 101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') - Entry in a dict or map (array of key-value pairs) + Entry in a dict or map (array of key-value pairs). + Type code 101 'e' is reserved for use in bindings and + implementations to represent the general concept of a + dict or dict-entry, and must not appear in signatures + used on D-Bus. UNIX_FD 104 (ASCII 'h') Unix file descriptor + + (reserved) + 109 (ASCII 'm') + Reserved for a + 'maybe' type compatible with the one in GVariant, + and must not appear in signatures used on D-Bus until + specified here + + + (reserved) + 42 (ASCII '*') + Reserved for use in bindings/implementations to + represent any single complete type, + and must not appear in signatures used on D-Bus. + + + (reserved) + 63 (ASCII '?') + Reserved for use in bindings/implementations to + represent any basic type, and must + not appear in signatures used on D-Bus. + + + (reserved) + 64 (ASCII '@'), 38 (ASCII '&'), + 94 (ASCII '^') + Reserved for internal use by bindings/implementations, + and must not appear in signatures used on D-Bus. + GVariant uses these type-codes to encode calling + conventions. + @@ -723,9 +762,29 @@ + + 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 @@ -1144,21 +1203,48 @@ Interface names must not exceed the maximum name length. + + + Interface names should start with the reversed DNS domain name of + the author of the interface (in lower-case), like interface names + in Java. It is conventional for the rest of the interface name + to consist of words run together, with initial capital letters + on all words ("CamelCase"). Several levels of hierarchy can be used. + It is also a good idea to include the major version of the interface + in the name, and increment it if incompatible changes are made; + this way, a single object can implement several versions of an + interface in parallel, if necessary. + + + + For instance, if the owner of example.com is + developing a D-Bus API for a music player, they might define + interfaces called com.example.MusicPlayer1, + com.example.MusicPlayer1.Track and + com.example.MusicPlayer1.Seekable. + + + + D-Bus does not distinguish between the concepts that would be + called classes and interfaces in Java: either can be identified on + D-Bus by an interface name. + Bus names Connections have one or more bus names associated with them. - A connection has exactly one bus name that is a unique connection - name. The unique connection name remains with the connection for - its entire lifetime. + A connection has exactly one bus name that is a unique + connection name. The unique connection name remains + with the connection for its entire lifetime. A bus name is of type STRING, meaning that it must be valid UTF-8. However, there are also some additional restrictions that apply to bus names specifically: Bus names that start with a colon (':') - character are unique connection names. + character are unique connection names. Other bus names + are called well-known bus names. Bus names are composed of 1 or more elements separated by @@ -1185,6 +1271,31 @@ Note that the hyphen ('-') character is allowed in bus names but not in interface names. + + + Like interface + names, well-known bus names should start with the + reversed DNS domain name of the author of the interface (in + lower-case), and it is conventional for the rest of the well-known + bus name to consist of words run together, with initial + capital letters. As with interface names, including a version + number in well-known bus names is a good idea; it's possible to + have the well-known bus name for more than one version + simultaneously if backwards compatibility is required. + + + + If a well-known bus name implies the presence of a "main" interface, + that "main" interface is often given the same name as + the well-known bus name, and situated at the corresponding object + path. For instance, if the owner of example.com + is developing a D-Bus API for a music player, they might define + that any application that takes the well-known name + com.example.MusicPlayer1 should have an object + at the object path /com/example/MusicPlayer1 + which implements the interface + com.example.MusicPlayer1. + Member names @@ -1199,12 +1310,31 @@ Must be at least 1 byte in length. + + + It is conventional for member names on D-Bus to consist of + capitalized words with no punctuation ("camel-case"). + Method names should usually be verbs, such as + GetItems, and signal names should usually be + a description of an event, such as ItemsChanged. + Error names Error names have the same restrictions as interface names. + + + Error names have the same naming conventions as interface + names, and often contain .Error.; for instance, + the owner of example.com might define the + errors com.example.MusicPlayer.Error.FileNotFound + and com.example.MusicPlayer.Error.OutOfMemory. + The errors defined by D-Bus itself, such as + org.freedesktop.DBus.Error.Failed, follow a + similar pattern. + @@ -2808,22 +2938,6 @@ - - Naming Conventions - - - D-Bus namespaces are all lowercase and correspond to reversed domain - names, as with Java. e.g. "org.freedesktop" - - - Interface, signal, method, and property names are "WindowsStyleCaps", note - that the first letter is capitalized, unlike Java. - - - Object paths are normally all lowercase with underscores used rather than - hyphens. - - UUIDs