From: Simon McVittie <simon.mcvittie@collabora.co.uk>
Date: Tue, 17 May 2011 16:06:46 +0000 (+0100)
Subject: Briefly mention why to namespace object-paths
X-Git-Tag: dbus-1.5.10~55^2~3
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=dd2b63e6e1fa4d773645a94f31709bd0a6eb0152;p=thirdparty%2Fdbus.git

Briefly mention why to namespace object-paths
---

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 20b0d48a1..ea72752f9 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -762,9 +762,29 @@
           </itemizedlist>
         </para>
 
+        <para>
+          Object paths are often namespaced by starting with a reversed
+          domain name and containing an interface version number, in the
+          same way as
+          <link linkend="message-protocol-names-interface">interface
+            names</link> and
+          <link linkend="message-protocol-names-bus">well-known
+            bus names</link>.
+          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).
+        </para>
+
+        <para>
+          For instance, if the owner of <literal>example.com</literal> is
+          developing a D-Bus API for a music player, they might use the
+          hierarchy of object paths that start with
+          <literal>/com/example/MusicPlayer1</literal> for its objects.
+        </para>
       </sect3>
 
-      
       <sect3 id="message-protocol-marshaling-signature">
         <title>Valid Signatures</title>
         <para>