Update to spec 0.17.22

1 files changed, 58 insertions, 27 deletions

diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml
index 204ecf11d..b0e905fd6 100644
--- a/spec/Channel_Type_Contact_Search.xml
+++ b/spec/Channel_Type_Contact_Search.xml
@@ -43,6 +43,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         running search can be cancelled by calling
         <tp:member-ref>Stop</tp:member-ref>.</p>
 
+      <p>If the protocol supports limiting the number of results returned by a
+        search and subsequently requesting more results, after
+        <tp:member-ref>Limit</tp:member-ref> results have been received the
+        search state will be set to <code>More_Available</code>. Clients may
+        call <tp:member-ref>More</tp:member-ref> to request another
+        <tp:member-ref>Limit</tp:member-ref> results. If allowed by the
+        connection manager, clients may specify the "page size" by specifying
+        <tp:member-ref>Limit</tp:member-ref> when calling
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>.
+        </p>
+
       <p>The client should call the channel's <tp:dbus-ref
         namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
         method when it is finished with the channel, so that any handles held
@@ -73,10 +84,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <tp:enumvalue suffix="In_Progress" value="1">
         <tp:docstring>The search is in progress</tp:docstring>
       </tp:enumvalue>
-      <tp:enumvalue suffix="Completed" value="2">
+      <tp:enumvalue suffix="More_Available" value="2">
+        <tp:docstring>The search has paused, but more results can be retrieved
+          by calling <tp:member-ref>More</tp:member-ref>.</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Completed" value="3">
         <tp:docstring>The search has been completed</tp:docstring>
       </tp:enumvalue>
-      <tp:enumvalue suffix="Failed" value="3">
+      <tp:enumvalue suffix="Failed" value="4">
         <tp:docstring>The search has failed</tp:docstring>
       </tp:enumvalue>
     </tp:enum>
@@ -127,6 +142,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
         <ul>
           <li><code>Not_Started</code> → <code>In_Progress</code></li>
+          <li><code>In_Progress</code> → <code>More_Available</code></li>
+          <li><code>More_Available</code> → <code>In_Progress</code></li>
           <li><code>In_Progress</code> → <code>Completed</code></li>
           <li><code>In_Progress</code> → <code>Failed</code></li>
         </ul>
@@ -215,35 +232,33 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
               Gadu-Gadu and TOC appear to support this.
             </tp:rationale>
           </dd>
-
-          <dt><code>x-search-offset</code></dt>
-          <dd>
-            <p>For protocols that support paging results, the offset from the
-              start of the results that should be returned, i.e. the number of
-              contacts from the beginning that should be omitted.</p>
-
-            <p>For example, if the search terms match 50 contacts, this key
-              is set to <code>"20"</code> and <code>x-search-limit</code>
-              is set to <code>"10"</code>, then the ten contacts from the 21st
-              to the 30th should be returned.</p>
-
-            <p>Connection managers for protocols which do not natively support
-              restricting the number of results returned MUST NOT support
-              either this term or <code>x-search-limit</code>: all results
-              should be signalled, and the client can provide its own paging as
-              desired.</p>
-          </dd>
-
-          <dt><code>x-search-limit</code></dt>
-          <dd>For protocols that support limiting results, the maximum number
-            of results that should be returned.  For example, if the search
-            terms match <i>Antonius</i>, <i>Bridget</i> and <i>Charles</i> and
-            this key is set to <code>"2"</code>, the search service SHOULD only
-            return <i>Antonius</i> and <i>Bridget</i>.</dd>
         </dl>
       </tp:docstring>
     </tp:simple-type>
 
+    <property name="Limit" type="u" access="read"
+      tp:name-for-bindings="Limit">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>If supported by the protocol, the maximum number of results that
+          should be returned, where <code>0</code> represents no limit. If the
+          protocol does not support limiting results, this should be
+          <code>0</code>.</p>
+
+        <p>For example, if the terms passed to
+          <tp:member-ref>Search</tp:member-ref> match <i>Antonius</i>,
+          <i>Bridget</i> and <i>Charles</i> and this property is
+          <code>2</code>, the search service SHOULD only return <i>Antonius</i>
+          and <i>Bridget</i>.</p>
+
+        <p>This property cannot change during the lifetime of the channel.
+          This property SHOULD be in the Allowed_Properties of a
+          <tp:type>Requestable_Channel_Class</tp:type> if and only if the
+          protocol supports specifying a limit; implementations SHOULD use
+          <code>0</code> as the default if possible, or a protocol-specific
+          sensible default otherwise.</p>
+      </tp:docstring>
+    </property>
+
     <property name="AvailableSearchKeys" type="as" access="read"
       tp:name-for-bindings="Available_Search_Keys">
       <tp:docstring>
@@ -310,6 +325,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </tp:possible-errors>
     </method>
 
+    <method name="More" tp:name-for-bindings="More">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        Request that a search in <tp:member-ref>SearchState</tp:member-ref>
+        <code>More_Available</code> move back to state <code>In_Progress</code>
+        and continue listing up to <tp:member-ref>Limit</tp:member-ref> more results.
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+          <tp:docstring>
+            The <tp:member-ref>SearchState</tp:member-ref> is not
+            <code>More_Available</code>.
+          </tp:docstring>
+        </tp:error>
+      </tp:possible-errors>
+    </method>
+
     <method name="Stop" tp:name-for-bindings="Stop">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Stop the current search. This may not be called while the