Merge pull request #101 from SamWhited/ev_search_endpoint

Entity Versioning Search Endpoint

inbox/entityversioning.xml

@@ -349,7 +349,7 @@
 </iq>
 
 <!-- Server -->
-<iq from='romeo@montague.lit' id='56' to='romeo@montague.lit/home' type='result>
+<iq from='romeo@montague.lit' id='56' to='romeo@montague.lit/home' type='result'>
   <query xmlns='jabber:iq:roster' full_list='false'>
     <item subscription='both' jid='bill@shakespeare.lit'>
       <version xmlns='urn:xmpp:entityver:0'>9ZFZXVP9</version>
@@ -368,6 +368,47 @@
       any) is left up to the server implementation.
     </p>
   </section2>
+  <section2 topic='List search'>
+    <p>
+      When a client has an incomplete versioned list, it may be beneficial to
+      download more of the list without requesting the full list. To do this,
+      servers which support entity versioning MUST supply a "search" IQ which
+      can be used to discover list items matching a certain criteria. What data
+      to match on (JID, metadata, associated vcards, etc.), and what type of
+      search are left up to the server implementation and MAY be different
+      between profiles.
+    </p>
+    <p>
+      Search queries are qualified by the 'urn:xmpp:entityver:0:search'
+      namespace and MUST have a 'profile' attribute set to the namespace for
+      which the search is being performed. For instance, searching the roster
+      looks like the following:
+      <example caption="Roster search"><![CDATA[
+<!-- Client -->
+<iq from='romeo@montague.lit/home'
+     id='564'
+     to='romeo@montague.lit'
+     type='get'>
+  <query xmlns="urn:xmpp:entityver:0:search" profile='urn:xmpp:entityver:profile:roster:0'>
+    Search term
+  </query>
+</iq>
+
+<!-- Server -->
+<iq from='romeo@montague.lit' id='564' to='romeo@montague.lit/home' type='result'>
+  <query xmlns="urn:xmpp:entityver:0:search" profile='urn:xmpp:entityver:profile:roster:0' type='result'>
+    <item subscription='both' jid='matching_search@term.lit'>
+      <version xmlns='urn:xmpp:entityver:0'>4YAZ7Y38</version>
+    </item>
+  </query>
+</iq>
+    ]]></example>
+    </p>
+    <p>
+      Search results SHOULD be added to the given list's cache. In this way,
+      the full list does not need to be known.
+    </p>
+  </section2>
   <section2 topic='Aggregate Tokens' anchor='agg_tokens'>
     <p>
       While the version token approach to caching does not require a great deal
@@ -498,6 +539,7 @@ anne@shakespeare.lit:VIZSVF0D,bill@shakespeare.lit:25P2A7H8
     <p>This specification defines the following XML namespace:</p>
     <ul>
       <li>urn:xmpp:entityver:0</li>
+      <li>urn:xmpp:entityver:0:search</li>
     </ul>
     <p>
       Upon advancement of this specification from a status of Experimental to a