[telepathy-spec/master] Connection: split Name_In_Use into three D-Bus errors

[Simon McVittie]

Not_Yours is too special to use for this (clients should handle it a bit
specially) and I think it's useful to divide up the three cases.
---
 spec/Connection.xml |   18 ++++++++----------
 spec/errors.xml     |   48 +++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 53 insertions(+), 13 deletions(-)

diff --git a/spec/Connection.xml b/spec/Connection.xml
index 2b03f96..7b9bb63 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -737,12 +737,17 @@ USA.</p>
             <li>If the status change is from Connecting to Disconnected
               and the 'register' parameter to RequestConnection was present
               and true, the requested account could not be created on the
-              server because it already exists.</li>
+              server because it already exists.
+              The equivalent D-Bus error is
+              <code>org.freedesktop.Telepathy.Error.RegistrationExists</code>.
+            </li>
 
             <li>If the status change is from Connecting to Disconnected
               but the 'register' parameter is absent or false, the connection
               manager could not connect to the specified account because
               a connection to that account already exists.
+              The equivalent D-Bus error is
+              <code>org.freedesktop.Telepathy.Error.AlreadyConnected</code>.
 
               <tp:rationale>
                 In some protocols, like XMPP (when connecting with the same
@@ -755,6 +760,8 @@ USA.</p>
               the existing connection was automatically disconnected because
               a new connection to the same account (perhaps from a different
               client or location) was established.
+              The equivalent D-Bus error is
+              <code>org.freedesktop.Telepathy.Error.ConnectionReplaced</code>.
 
               <tp:rationale>
                 In some protocols, like MSNP (when connecting twice with the
@@ -763,15 +770,6 @@ USA.</p>
               </tp:rationale>
             </li>
           </ul>
-
-          <p>When disconnected for this reason, the equivalent D-Bus error is
-            <code>org.freedesktop.Telepathy.Error.NotYours</code>.
-          </p>
-
-          <tp:rationale>
-            These three errors are distinct but very similar, and can be
-            distinguished by other factors.
-          </tp:rationale>
         </tp:docstring>
       </tp:enumvalue>
 
diff --git a/spec/errors.xml b/spec/errors.xml
index 7b1798d..e8f2031 100644
--- a/spec/errors.xml
+++ b/spec/errors.xml
@@ -71,9 +71,13 @@
   </tp:error>
 
   <tp:error name="Not Yours">
-    <tp:docstring>
-      The requested channel or other resource already exists, and another
-      client is responsible for it
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>The requested channel or other resource already exists, and another
+        user interface in this session is responsible for it.</p>
+
+      <p>User interfaces SHOULD handle this error unobtrusively, since it
+        indicates that some other user interface is already processing the
+        channel.</p>
     </tp:docstring>
   </tp:error>
 
@@ -325,6 +329,44 @@
     </tp:docstring>
   </tp:error>
 
+  <tp:error name="Already Connected">
+    <tp:docstring>
+      Raised when the user attempts to connect to an account but they are
+      already connected (perhaps from another client or computer), and the
+      protocol or account settings do not allow this.
+
+      <tp:rationale>
+        XMPP can have this behaviour if the user chooses the same resource
+        in both clients (it is server-dependent whether the result is
+        AlreadyConnected on the new connection, ConnectionReplaced on the
+        old connection, or two successful connections).
+      </tp:rationale>
+    </tp:docstring>
+  </tp:error>
+
+  <tp:error name="Connection Replaced">
+    <tp:docstring>
+      Raised by an existing connection to an account if it is replaced by
+      a new connection (perhaps from another client or computer).
+
+      <tp:rationale>
+        In MSNP, when connecting twice with the same Passport, the new
+        connection "wins" and the old one is automatically disconnected.
+        XMPP can also have this behaviour if the user chooses the same
+        resource in two clients (it is server-dependent whether the result is
+        AlreadyConnected on the new connection, ConnectionReplaced on the
+        old connection, or two successful connections).
+      </tp:rationale>
+    </tp:docstring>
+  </tp:error>
+
+  <tp:error name="Registration Exists">
+    <tp:docstring>
+      Raised during in-band registration if the server indicates that the
+      requested account already exists.
+    </tp:docstring>
+  </tp:error>
+
   <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
   <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
   <tp:license xmlns="http://www.w3.org/1999/xhtml">
-- 
1.5.6.5