[Telepathy-commits] [telepathy-spec/master] Restrict Connection bus names and object paths to have exactly 7 components

[Simon McVittie]

Equivalently, restrict the account part to have exactly 1
component. Current versions of telepathy-glib and telepathy-python
already enforce this constraint in practice, and telepathy-snom also
already complies - so this change has no effect on any known connection
manager, except possibly telepathy-wilde, which is no longer spec-compliant
in any case.

Also move the definition of the Connection's bus name and object path
to Connection.xml where it belongs, and improve hyperlinking between
Connection and Connection_Manager.
---
 spec/Connection.xml         |   48 +++++++++++++++++++++++++++++++++++++++---
 spec/Connection_Manager.xml |   43 +++++++++-----------------------------
 2 files changed, 54 insertions(+), 37 deletions(-)

diff --git a/spec/Connection.xml b/spec/Connection.xml
index a5bc084..5ce9fe5 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -668,10 +668,43 @@ USA.</p>
     </signal>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-    <p>This models a connection to a single user account on a communication
-    service. Its basic capability is to provide the facility to request and
-    receive channels of differing types (such as text channels or streaming
-    media channels) which are used to carry out further communication.</p>
+      <p>This models a connection to a single user account on a communication
+        service. Its basic capability is to provide the facility to request and
+        receive channels of differing types (such as text channels or streaming
+        media channels) which are used to carry out further communication.</p>
+
+      <p>In order to allow Connection objects to be discovered by new clients,
+        the object path and well-known bus name MUST be of the form
+        <code>/org/freedesktop/Telepathy/Connection/cmname/proto/account</code>
+        and
+        <code>org.freedesktop.Telepathy.Connection.cmname.proto.account</code>
+        where:</p>
+
+      <ul>
+        <li><em>cmname</em> is the same
+          <tp:type>Connection_Manager_Name</tp:type> that appears
+          in the connection manager's object path and well-known bus name</li>
+        <li><em>proto</em> is the <tp:type>Protocol</tp:type> name as seen in
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager">ListProtocols</tp:dbus-ref>,
+          but with "-" replaced with "_" to get a valid
+          object path/bus name</li>
+        <li><em>account</em> is some non-empty sequence of ASCII letters,
+          digits and underscores not starting with a digit</li>
+      </ul>
+
+      <p><em>account</em> SHOULD be formed such that any valid distinct
+        connection instance on this protocol has a distinct name. This
+        might be formed by including the server name followed by the user
+        name (escaped via some suitable mechanism like telepathy-glib's
+        tp_escape_as_identifier() function to preserve uniqueness); on
+        protocols where connecting multiple times is permissable, a
+        per-connection identifier might be necessary to ensure
+        uniqueness.</p>
+
+      <p>Clients MAY parse the object path to determine the connection
+        manager name and the protocol, but MUST NOT attempt to parse the
+        <em>account</em> part. Connection managers MAY use any unique string
+        for this part.</p>
 
     <p>As well as the methods and signatures below, arbitrary interfaces may be
     provided by the Connection object to represent extra connection-wide
@@ -702,6 +735,13 @@ USA.</p>
     keep handles from being released with HoldHandles, and notify that they are
     no longer storing handles with ReleaseHandles.</p>
     </tp:docstring>
+
+    <tp:changed version="0.17.UNRELEASED">Previously, the account part of
+      Connection bus names/object paths was allowed to have more than one
+      component (i.e. contain dots or slashes), resulting in Connection
+      bus names and object paths with more than 7 components. We now restrict
+      Connection bus names/object paths to have exactly 7
+      components.</tp:changed>
   </interface>
 </node>
 <!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml
index 33f1ede..89c0efc 100644
--- a/spec/Connection_Manager.xml
+++ b/spec/Connection_Manager.xml
@@ -220,39 +220,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         </tp:docstring>
       </arg>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>Request a Connection object representing a given account on a given
-        protocol with the given parameters. The method returns the bus name
-        and the object path where the new Connection object can be found, which
-        should have the status of Connection_Status_Disconnected, to allow
-        signal handlers to be attached before connecting is started with the
-        Connect method.</p>
-
-        <p>In order to allow Connection objects to be discovered by new clients,
-        the object path and well-known bus name must be of the form
-        <code>/org/freedesktop/Telepathy/Connection/cmname/proto/account</code>
-        and
-        <code>org.freedesktop.Telepathy.Connection.cmname.proto.account</code>
-        where:</p>
-
-        <ul>
-          <li><em>cmname</em> is the same connection manager name that appears
-            in the connection manager's object path and well-known bus name</li>
-          <li><em>proto</em> is the protocol name as seen in
-            ListProtocols, but with "-" replaced with "_" to get a valid
-            object path/bus name</li>
-          <li><em>account</em> SHOULD be a series of elements formed such that
-            any valid distinct connection instance on this protocol has a
-            distinct name; this might be formed by including the server name
-            followed by the user name (escaped via some suitable mechanism like
-            telepathy-glib's tp_escape_as_identifier() function to preserve
-            uniqueness), or on protocols where connecting multiple times
-            is permissable, a per-connection identifier might be necessary to
-            ensure uniqueness</li>
-        </ul>
-
-        <p>Clients MUST NOT attempt to parse the <em>account</em> part of the
-          bus name. Connection managers MAY use any unique string for this
-          part.</p>
+        <p>Request a
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
+          object representing a given account on a given
+          protocol with the given parameters. The method returns the bus name
+          and the object path where the new Connection object can be found,
+          which should have the status of Connection_Status_Disconnected, to
+          allow signal handlers to be attached before connecting is started
+          with the
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">Connect</tp:dbus-ref>
+          method.</p>
 
         <p>The parameters which must and may be provided in the parameters
         dictionary can be discovered with the GetParameters method. These
-- 
1.5.6.3