Update to tp-spec head

20080717154511-93b9a-116972b240dc055f91ef95b430c427cb4e1e22a1.gz

1 files changed, 45 insertions, 8 deletions

diff --git a/spec/Connection.xml b/spec/Connection.xml
index 792499671..b350f140e 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -73,12 +73,39 @@ USA.</p>
         </tp:docstring>
       </arg>
 
-      <tp:docstring>
-        Get the optional interfaces supported by this connection.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Get the optional interfaces supported by this connection.
+          Before the connection status changes to CONNECTED, the return
+          from this method may change at any time, but it is guaranteed that
+          interfaces will only be added, not removed. After the connection
+          status changes to CONNECTED, the return from this method cannot
+          change further.</p>
+
+        <p>There is no explicit change notification; reasonable behaviour
+          for a client would be to retrieve the interfaces list once
+          initially, and once more when it becomes CONNECTED.</p>
+
+        <tp:rationale>
+          <p>In some connection managers, certain capabilities of a connection
+            are known to be implemented for all connections (e.g. support
+            for SimplePresence), and some interfaces (like SimplePresence) can
+            even be used before connecting. Other capabilities may
+            or may not exist, depending on server functionality; by the time
+            the connection goes CONNECTED, the connection manager is expected
+            to have evaluated the server's functionality and enabled any extra
+            interfaces for the remainder of the Connection's lifetime.</p>
+        </tp:rationale>
       </tp:docstring>
 
       <tp:possible-errors>
-        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected">
+          <tp:docstring>
+             Before version 0.17.UNRELEASED calling GetInterfaces while
+             on a connection that is not yet CONNECTED wasn't allowed. If a
+             CM returns this error, its list of interfaces should be regarded
+             as empty until it becomes CONNECTED.
+          </tp:docstring>
+        </tp:error>
       </tp:possible-errors>
     </method>
 
@@ -294,13 +321,19 @@ USA.</p>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
-          The handle type is invalid
+          <tp:docstring>
+            The handle type is invalid
+          </tp:docstring>
         </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
-          One of the given handles is not valid
+          <tp:docstring>
+            One of the given handles is not valid
+          </tp:docstring>
         </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
-          One of the given handles is not held by this client
+          <tp:docstring>
+            One of the given handles is not held by this client
+          </tp:docstring>
         </tp:error>
       </tp:possible-errors>
     </method>
@@ -483,10 +516,14 @@ USA.</p>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
-          The handle type is invalid
+          <tp:docstring>
+            The handle type is invalid
+          </tp:docstring>
         </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
-          The given name is not a valid entity of the given type
+          <tp:docstring>
+            The given name is not a valid entity of the given type
+          </tp:docstring>
         </tp:error>
       </tp:possible-errors>
     </method>