[Telepathy-commits] [telepathy-spec/master] Nail down what the intended errors from RequestHandles are, and give examples

[Simon McVittie]

Historically, basically all implementors of RequestHandles have had
different interpretations of the error conditions, which was a mess.
---
 spec/Connection.xml |   26 ++++++++++++++++----------
 1 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/spec/Connection.xml b/spec/Connection.xml
index 9516196..a8a5d4e 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -582,21 +582,27 @@ USA.</p>
 
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
-        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
-          <tp:docstring>
-            The handle type is invalid
-          </tp:docstring>
-        </tp:error>
-        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
           <tp:docstring>
-            The given name is not a valid entity of the given type
+            The given name does not identify a valid entity of the given type.
+
+            <tp:rationale>
+              For instance, an XMPP connection would raise this error for
+              identifiers with type Handle_Type_Room that do not contain
+              exactly one '@' character, that contain spaces, and so on.
+            </tp:rationale>
           </tp:docstring>
         </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
           <tp:docstring>
-            The given handle type is valid, but not implemented on this
-            connection.  For instance, a CM for a protocol that doesn't have
-            chat rooms would not implement room handles.
+            The given handle type is not valid, or is not implemented on this
+            connection.
+            
+            <tp:rationale>
+              For instance, a connection to a protocol that doesn't have
+              chat rooms would raise this error for room handles, and all CMs
+              would raise this error for Handle_Type_None.
+            </tp:rationale>
           </tp:docstring>
         </tp:error>
       </tp:possible-errors>
-- 
1.5.6.5