X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fdbus-specification.xml;h=959c4e7f218ffed388de14dcf2b36b8efc4331db;hb=349260f245d95a6c8bcc0f000be1f3232c616052;hp=7280cf1768611b037b8168796e3e2031fddfb5a6;hpb=c99a3df254dbfcd945de919054c391c5565460af;p=platform%2Fupstream%2Fdbus.git
diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 7280cf1..959c4e7 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -782,9 +782,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
@@ -1228,21 +1248,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
@@ -1269,6 +1316,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
@@ -1283,12 +1355,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.
+
@@ -2892,22 +2983,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
@@ -3037,6 +3112,22 @@
+ It is conventional to give D-Bus properties names consisting of
+ capitalized words without punctuation ("CamelCase"), like
+ member names.
+ For instance, the GObject property
+ connection-status or the Qt property
+ connectionStatus could be represented on D-Bus
+ as ConnectionStatus.
+
+
+ Strictly speaking, D-Bus property names are not required to follow
+ the same naming restrictions as member names, but D-Bus property
+ names that would not be valid member names (in particular,
+ GObject-style dash-separated property names) can cause interoperability
+ problems and should be avoided.
+
+
The available properties and whether they are writable can be determined
by calling org.freedesktop.DBus.Introspectable.Introspect,
see .
@@ -4500,9 +4591,25 @@
- [FIXME specify location of .service files, probably using
- DESKTOP_DIRS etc. from basedir specification, though login session
- bus is not really desktop-specific]
+ On Unix systems, the session bus should search for .service files
+ in $XDG_DATA_DIRS/dbus-1/services as defined
+ by the
+ XDG Base Directory Specification.
+ Implementations may also search additional locations, which
+ should be searched with lower priority than anything in
+ XDG_DATA_HOME, XDG_DATA_DIRS or their respective defaults;
+ for example, the reference implementation also
+ looks in ${datadir}/dbus-1/services as
+ set at compile time.
+
+
+ As described in the XDG Base Directory Specification, software
+ packages should install their session .service files to their
+ configured ${datadir}/dbus-1/services,
+ where ${datadir} is as defined by the GNU
+ coding standards. System administrators or users can arrange
+ for these service files to be read by setting XDG_DATA_DIRS or by
+ symlinking them into the default locations.
@@ -5216,6 +5323,11 @@
can be thought of as "well-known names" and are
used to find applications that offer specific functionality.
+
+
+ See for details of
+ the syntax and naming conventions for bus names.
+
@@ -5254,10 +5366,14 @@
Namespace
-
- Used to prevent collisions when defining new interfaces or bus
- names. The convention used is the same one Java uses for defining
- classes: a reversed domain name.
+
+ Used to prevent collisions when defining new interfaces, bus names
+ etc. The convention used is the same one Java uses for defining
+ classes: a reversed domain name.
+ See ,
+ ,
+ ,
+ .