Update to spec 0.21.6

- HasImmortalHandles property

5 files changed, 70 insertions, 23 deletions

diff --git a/spec/Connection.xml b/spec/Connection.xml
index a694e2429..51ec1ab23 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -222,6 +222,9 @@ USA.</p>
     </method>
 
     <method name="HoldHandles" tp:name-for-bindings="Hold_Handles">
+      <tp:changed version="0.21.6">If
+        <tp:member-ref>HasImmortalHandles</tp:member-ref> is true,
+        this method no longer does anything.</tp:changed>
       <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type">
         <tp:docstring>
           The type of handle to be held
@@ -235,7 +238,13 @@ USA.</p>
       </arg>
 
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>Notify the connection manger that your client is holding a copy
+        <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true,
+          which SHOULD always be the case in this version of telepathy-spec,
+          this method does nothing and returns successfully, unless
+          the given handle type or any of the given handles is invalid.</p>
+
+        <p>In older connection managers, this method
+        notifies the connection manger that your client is holding a copy
         of handles which may not be in use in any existing channel or
         list, and were not obtained by using the
         <tp:member-ref>RequestHandles</tp:member-ref> method. For
@@ -390,6 +399,9 @@ USA.</p>
     </signal>
 
     <method name="ReleaseHandles" tp:name-for-bindings="Release_Handles">
+      <tp:changed version="0.21.6">If
+        <tp:member-ref>HasImmortalHandles</tp:member-ref> is true,
+        this method no longer does anything.</tp:changed>
       <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type">
         <tp:docstring>
           An integer handle type (as defined in RequestHandle)
@@ -403,10 +415,17 @@ USA.</p>
       </arg>
 
       <tp:docstring>
-        Explicitly notify the connection manager that your client is no
+        <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true,
+          which SHOULD always be the case in this version of telepathy-spec,
+          this method does nothing and returns successfully, unless
+          the given handle type or any of the given handles is invalid.</p>
+
+        <p>In older connection managers, this method
+        explicitly notifies the connection manager that your client is no
         longer holding any references to the given handles, and that they
         may be deallocated if they are not held by any other clients or
-        referenced by any existing channels. See HoldHandles for notes.
+        referenced by any existing channels. See
+        <tp:member-ref>HoldHandles</tp:member-ref> for notes.</p>
       </tp:docstring>
 
       <tp:possible-errors>
@@ -421,11 +440,6 @@ USA.</p>
             One of the given handles is not valid
           </tp:docstring>
         </tp:error>
-        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
-          <tp:docstring>
-            One of the given handles is not held by this client
-          </tp:docstring>
-        </tp:error>
       </tp:possible-errors>
     </method>
 
@@ -622,6 +636,9 @@ USA.</p>
     </tp:simple-type>
 
     <method name="RequestHandles" tp:name-for-bindings="Request_Handles">
+      <tp:changed version="0.21.6">If
+        <tp:member-ref>HasImmortalHandles</tp:member-ref> is true,
+        this method no longer has its reference-counting effect.</tp:changed>
       <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type">
         <tp:docstring>
           The type of handle required
@@ -641,17 +658,23 @@ USA.</p>
         </tp:docstring>
       </arg>
 
-      <tp:docstring>
-        Request several handles from the connection manager which represent a
-        number of contacts, rooms or server-stored lists on the service. The
-        connection manager should record that these handles are in use by the
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Request several handles from the connection manager which represent a
+          number of contacts, rooms or server-stored lists on the service.</p>
+
+        <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true,
+          which SHOULD always be the case in this version of telepathy-spec,
+          the handles remain valid until the connection disconnects.</p>
+
+        <p>The implementation of this method in older connection managers
+        must record that these handles are in use by the
         client who invokes this method, and must not deallocate the handles
         until the client disconnects from the bus or calls the
         <tp:member-ref>ReleaseHandles</tp:member-ref>
         method. Where the identifier refers to an entity that already has a
         handle in this connection manager, this handle should be returned
         instead. The handle number 0 must not be returned by the connection
-        manager.
+        manager.</p>
       </tp:docstring>
 
       <tp:possible-errors>
@@ -1169,6 +1192,18 @@ USA.</p>
       </arg>
     </method>
 
+    <property name="HasImmortalHandles"
+      tp:name-for-bindings="Has_Immortal_Handles"
+      access="read" type="b">
+      <tp:added version="0.21.6"/>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>True if handles last for the whole lifetime of the Connection.
+          This SHOULD be the case in all connection managers, but clients
+          MUST interoperate with older connection managers
+          (which reference-count handles).</p>
+      </tp:docstring>
+    </property>
+
     <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
diff --git a/spec/Connection_Interface_Contact_List.xml b/spec/Connection_Interface_Contact_List.xml
index 2342379c8..e0cccd541 100644
--- a/spec/Connection_Interface_Contact_List.xml
+++ b/spec/Connection_Interface_Contact_List.xml
@@ -173,10 +173,12 @@
 
       <arg direction="in" name="Hold" type="b">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>Whether to hold the handles on behalf of the calling process.
-            Equivalent to the corresponding argument to <tp:dbus-ref
-              namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts"
-              >GetContactAttributes</tp:dbus-ref>.</p>
+          <p>If true, all handles that appear as keys in the result have been
+            held on behalf of the calling process, as if by a call to
+            <tp:dbus-ref namespace="ofdT">Connection.HoldHandles</tp:dbus-ref>.
+            (If <tp:dbus-ref namespace="ofdT.Connection"
+              >HasImmortalHandles</tp:dbus-ref> is true, which SHOULD be the
+            case in all new connection managers, this has no effect.)</p>
         </tp:docstring>
       </arg>
 
diff --git a/spec/Connection_Interface_Contacts.xml b/spec/Connection_Interface_Contacts.xml
index cd769cebc..1020190d4 100644
--- a/spec/Connection_Interface_Contacts.xml
+++ b/spec/Connection_Interface_Contacts.xml
@@ -152,13 +152,16 @@
       </arg>
 
       <arg direction="in" name="Hold" type="b">
-        <tp:docstring>
-          If true, all handles in the result have been held on behalf of the
-          calling process, as if by a call to
-          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.HoldHandles</tp:dbus-ref>.
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>If true, all handles that appear as keys in the result have been
+            held on behalf of the calling process, as if by a call to
+            <tp:dbus-ref namespace="ofdT">Connection.HoldHandles</tp:dbus-ref>.
+            (If <tp:dbus-ref namespace="ofdT.Connection"
+              >HasImmortalHandles</tp:dbus-ref> is true, which SHOULD be the
+            case in all new connection managers, this has no effect.)</p>
 
           <tp:rationale>
-            For further round-trip avoidance.
+            <p>For further round-trip avoidance.</p>
           </tp:rationale>
         </tp:docstring>
       </arg>
diff --git a/spec/Connection_Interface_Mail_Notification.xml b/spec/Connection_Interface_Mail_Notification.xml
index 1ac6d1a67..395e1019d 100644
--- a/spec/Connection_Interface_Mail_Notification.xml
+++ b/spec/Connection_Interface_Mail_Notification.xml
@@ -23,6 +23,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
     <tp:added version="0.21.3">(as stable API)</tp:added>
 
+    <tp:client-interest>
+      <tp:docstring>
+        A client MUST notify interest in this feature before it will be
+        enabled.
+      </tp:docstring>
+    </tp:client-interest>
+
     <tp:flags name="Mail_Notification_Flags" value-prefix="Mail_Notification_Flag" type="u" >
       <tp:flag suffix="Supports_Unread_Mail_Count" value="1">
         <tp:docstring>
diff --git a/spec/all.xml b/spec/all.xml
index 8585057a6..94f0a34ff 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,7 +3,7 @@
   xmlns:xi="http://www.w3.org/2001/XInclude">
 
 <tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.21.5</tp:version>
+<tp:version>0.21.6</tp:version>
 
 <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
 <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>