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 @@
STRUCT114 (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.VARIANT118 (ASCII 'v')
@@ -486,12 +489,48 @@
DICT_ENTRY101 (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_FD104 (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