Update telepathy-spec to 0.17.21

1 files changed, 355 insertions, 96 deletions

diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml
index 0b166bb16..204ecf11d 100644
--- a/spec/Channel_Type_Contact_Search.xml
+++ b/spec/Channel_Type_Contact_Search.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Type_Contact_Search" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
-  <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
-  <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+  <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright>
+  <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright>
+  <tp:copyright> Copyright © 2006 INdT </tp:copyright>
   <tp:license xmlns="http://www.w3.org/1999/xhtml">
     <p>This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
@@ -18,135 +18,394 @@ Lesser General Public License for more details.</p>
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
   </tp:license>
-  <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch"
-    tp:causes-havoc='not well-tested'>
+  <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch.DRAFT"
+    tp:causes-havoc='experimental'>
     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
 
-    <tp:struct name="Search_Key_Info">
-      <tp:docstring>A struct representing details on search strings.</tp:docstring>
-      <tp:member type="b" name="Is_Mandatory">
-        <tp:docstring>Booleans indicating if the search key is mandatory.
-          </tp:docstring>
-      </tp:member>
-      <tp:member type="g" name="Type_Signature">
-        <tp:docstring>The type signature of the value for this search key.
-          </tp:docstring>
-      </tp:member>
-    </tp:struct>
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>A channel type for searching server-stored user directories. A new
+        channel should be requested by a client for each search attempt, and
+        closed when the search is completed or the required result has been
+        found in order to free unused handles.</p>
 
-    <tp:mapping name="Search_Key_Info_Map">
-      <tp:docstring>A dictionary mapping string search key names to its search details.
-        </tp:docstring>
-      <tp:member type="s" name="Term"/>
-      <tp:member type="(bg)" tp:type="Search_Key_Info" name="Details"/>
-    </tp:mapping>
+      <p>Before searching, the
+        <tp:member-ref>AvailableSearchKeys</tp:member-ref> property should be
+        inspected to determine the valid search keys which can be provided to
+        the <tp:member-ref>Search</tp:member-ref> method. A search request is
+        then started by providing some of these terms to the Search method, and
+        the <tp:member-ref>SearchState</tp:member-ref> will change from
+        <code>Not_Started</code> to <code>In_Progress</code>.  As results are
+        returned by the server, the
+        <tp:member-ref>SearchResultReceived</tp:member-ref> signal is emitted
+        for each contact found; when the search is complete, the search state
+        will be set to <code>Completed</code>. If the search fails after Search
+        has been called, the state will change to <code>Failed</code>.  A
+        running search can be cancelled by calling
+        <tp:member-ref>Stop</tp:member-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
+        only by the channel can be released.</p>
+
+      <p>Each channel can only be used for a single search; a new channel
+        should be requested for each subsequent search. Connection managers
+        MUST support multiple ContactSearch channels being open at once (even
+        to the same server, if applicable).</p>
+
+      <p>It does not make sense to request this channel type using <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>;
+        clients SHOULD request channels of this type using
+        <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>
+        instead.</p>
+
+      <tp:rationale>
+        <p>A contact search channel that is already in use for a different
+          search isn't useful.</p>
+      </tp:rationale>
+    </tp:docstring>
 
-    <method name="GetSearchKeys" tp:name-for-bindings="Get_Search_Keys">
-      <arg direction="out" type="s">
-        <tp:docstring>
-          A string with any instructions from the server
-        </tp:docstring>
-      </arg>
-      <arg direction="out" type="a{s(bg)}" tp:type="Search_Key_Info_Map">
-        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          A dictionary mapping string search key names to its search details.
-        </tp:docstring>
-      </arg>
-      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>Returns any instructions from the server along with a dictionary of
-        search key names to their types, and a boolean indicating if the key is
-        mandatory. The following well-known search key names should be used
-        where appropriate:</p>
-        <dl>
-          <dt>s:first</dt><dd>The desired contact's given name</dd>
-          <dt>s:last</dt><dd>The desired contact's family name</dd>
-          <dt>s:nick</dt><dd>The desired contact's nickname</dd>
-          <dt>s:email</dt><dd>The e-mail address of the desired contact</dd>
-        </dl>
-      </tp:docstring>
-      <tp:possible-errors>
-        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
-        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
-        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
-      </tp:possible-errors>
-    </method>
     <tp:enum name="Channel_Contact_Search_State" type="u">
-      <tp:enumvalue suffix="Before" value="0">
+      <tp:enumvalue suffix="Not_Started" value="0">
         <tp:docstring>The search has not started</tp:docstring>
       </tp:enumvalue>
-      <tp:enumvalue suffix="During" value="1">
+      <tp:enumvalue suffix="In_Progress" value="1">
         <tp:docstring>The search is in progress</tp:docstring>
       </tp:enumvalue>
-      <tp:enumvalue suffix="After" value="2">
+      <tp:enumvalue suffix="Completed" value="2">
         <tp:docstring>The search has been completed</tp:docstring>
       </tp:enumvalue>
+      <tp:enumvalue suffix="Failed" value="3">
+        <tp:docstring>The search has failed</tp:docstring>
+      </tp:enumvalue>
     </tp:enum>
-    <method name="GetSearchState" tp:name-for-bindings="Get_Search_State">
-      <arg direction="out" type="u" tp:type="Channel_Contact_Search_State">
-        <tp:docstring>The search state represented as one of the values of
-          ChannelContactSearchState</tp:docstring>
+
+    <property name="SearchState" tp:name-for-bindings="Search_State"
+      access="read" type="u" tp:type="Channel_Contact_Search_State">
+      <tp:docstring>
+        The current state of this search channel object. Change notification
+        is via <tp:member-ref>SearchStateChanged</tp:member-ref>.
+      </tp:docstring>
+    </property>
+
+    <signal name="SearchStateChanged"
+      tp:name-for-bindings="Search_State_Changed">
+      <arg name="State" type="u" tp:type="Channel_Contact_Search_State">
+        <tp:docstring>The new search state</tp:docstring>
+      </arg>
+      <arg name="Error" type="s" tp:type="DBus_Error_Name">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          If the new state is <code>Failed</code>, the name of a D-Bus error
+          describing what went wrong. Otherwise, the empty string.
+        </tp:docstring>
+      </arg>
+      <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Additional information about the state transition, which may
+            include the following well-known keys:</p>
+
+          <dl>
+            <dt>debug-message (s)</dt>
+            <dd>Debugging information on the change, corresponding to the
+              message part of a D-Bus error message, which SHOULD NOT be
+              displayed to users under normal circumstances</dd>
+          </dl>
+
+          <tp:rationale>
+            <p>This argument allows for future extensions. For instance,
+              if moving to state <code>Failed</code> because the server
+              rejected one of our search terms, we could define a key
+              that indicates which terms were invalid.</p>
+          </tp:rationale>
+        </tp:docstring>
       </arg>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Emitted when the <tp:member-ref>SearchState</tp:member-ref> property
+          changes. The implementation MUST NOT make transitions other than the
+          following:</p>
+
+        <ul>
+          <li><code>Not_Started</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>
+      </tp:docstring>
+    </signal>
+
+    <tp:simple-type name="Contact_Search_Key" type="s">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Any of the following search keys, with the indicated result for
+          the search:</p>
+
+        <dl>
+          <dt>The empty string</dt>
+          <dd>Search for the search term in some implementation-dependent
+            set of fields, using an implementation-dependent algorithm
+            (e.g. searching for each word mentioned)
+            <tp:rationale>
+              The "one big search box" approach to searching, as is familiar
+              from Google. The Sametime plugin to Pidgin appears to search in
+              this way.
+            </tp:rationale>
+          </dd>
+
+          <dt>A <tp:type>VCard_Field</tp:type></dt>
+          <dd>Search for the search term in fields matching that name (for
+            instance, <code>nickname</code> would search nicknames, and
+            <code>tel</code> would search any available phone number,
+            regardless of its work/home/mobile/... status).</dd>
+
+          <dt>A <tp:type>VCard_Field</tp:type> followed by
+            "<code>;</code>" and a
+            <tp:type>VCard_Type_Parameter</tp:type> of the form
+            "<code>type=...</code>"</dt>
+          <dd>Search for the search term in fields of that name and type
+            only (for instance, <code>tel;type=mobile</code>).</dd>
+
+          <dt><code>x-telepathy-identifier</code></dt>
+          <dd>Search for contacts whose identifier in the IM protocol
+            matches the search term (e.g. contains it as a substring)
+            <tp:rationale>
+              Otherwise, starting a search by identifier would require the UI
+              to know the vCard field name corresponding to identifiers in
+              this protocol, which might be non-standard (like
+              <code>x-jabber</code>) or not exist at all.
+            </tp:rationale>
+          </dd>
+
+          <dt><code>x-gender</code></dt>
+          <dd>For the search term "male" or "female", search only for contacts
+            listed as male or female, respectively. The results for other
+            search terms are undefined; it is likely that contacts with
+            unspecified gender will only be matched if this search key
+            is omitted from the request.
+            <tp:rationale>
+              Examples in XEP-0055 suggest this usage, and at least Gadu-Gadu
+              also supports limiting search results by gender.
+            </tp:rationale>
+          </dd>
+
+          <dt><code>x-n-family</code></dt>
+          <dd>Search for the search term in contacts' family names
+            (the first component of the vCard field <code>n</code>).
+            <tp:rationale>
+              Gadu-Gadu and TOC seem to support this mode of searching.
+            </tp:rationale>
+          </dd>
+
+          <dt><code>x-n-given</code></dt>
+          <dd>Search for the search term in contacts' given names
+            (the second component of the vCard field <code>n</code>).
+            <tp:rationale>
+              As for <code>x-n-family</code>.
+            </tp:rationale>
+          </dd>
+
+          <dt><code>x-online</code></dt>
+          <dd>For the search term "yes", search only for contacts who are
+            currently online. The results for other search terms are undefined.
+            <tp:rationale>Gadu-Gadu appears to support this.</tp:rationale>
+          </dd>
+
+          <dt><code>x-adr-locality</code></dt>
+          <dd>Search for the search term as a locality or city (the fourth
+            component of the vCard field <code>adr</code>).
+            <tp:rationale>
+              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="AvailableSearchKeys" type="as" access="read"
+      tp:name-for-bindings="Available_Search_Keys">
       <tp:docstring>
-        Returns the current state of this search channel object.
+        The set of search keys supported by this channel. Example values
+        include [""] (for protocols where several address fields are
+        implicitly searched) or ["x-n-given", "x-n-family", "nickname",
+        "email"] (for XMPP XEP-0055, without extensibility via Data Forms).
+        This property cannot change during the lifetime of a channel.
+
+        <tp:rationale>
+          It can be in the <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
+          signal for round-trip reduction.
+        </tp:rationale>
       </tp:docstring>
-    </method>
-    <method name="Search">
-      <arg direction="in" name="Terms" type="a{sv}" tp:type="String_Variant_Map">
+    </property>
+
+    <tp:mapping name="Contact_Search_Map">
+      <tp:docstring>A map from search keys to search terms.</tp:docstring>
+      <tp:member name="Key" type="s" tp:type="Contact_Search_Key">
+        <tp:docstring>
+          The search key to match against
+        </tp:docstring>
+      </tp:member>
+
+      <tp:member name="Term" type="s">
+        <tp:docstring>
+          The term or terms to be searched for in the search key; depending on
+          the protocol and the server implementation, this may be matched by
+          exact or approximate equality, substring matching, word matching
+          or any other matching algorithm
+        </tp:docstring>
+      </tp:member>
+    </tp:mapping>
+
+    <method name="Search" tp:name-for-bindings="Search">
+      <arg direction="in" name="Terms"
+        type="a{ss}" tp:type="Contact_Search_Map">
         <tp:docstring>
           A dictionary mapping search key names to the desired values
         </tp:docstring>
       </arg>
       <tp:docstring>
-        Send a request to start a search for contacts on this connection. A
-        valid search request will cause the SearchStateChanged signal to be
-        emitted with the status CHANNEL_CONTACT_SEARCH_STATE_DURING.
+        Send a request to start a search for contacts on this connection. This
+        may only be called while the <tp:member-ref>SearchState</tp:member-ref>
+        is Not_Started; a valid search request will cause the
+        <tp:member-ref>SearchStateChanged</tp:member-ref> signal to be emitted
+        with the state In_Progress.
       </tp:docstring>
       <tp:possible-errors>
-        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+          <tp:docstring>
+            The <tp:member-ref>SearchState</tp:member-ref> is no longer
+            Not_Started, so this method is no longer available.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+          <tp:docstring>
+            The search terms included something this connection manager cannot
+            search for.
+          </tp:docstring>
+        </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
-        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
       </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
+          <tp:member-ref>SearchState</tp:member-ref> is Not_Started. If called
+          while the SearchState is In_Progress,
+          <tp:member-ref>SearchStateChanged</tp:member-ref> will be emitted,
+          with the state Failed and the error
+          <code>org.freedesktop.Telepathy.Errors.Cancelled</code>.</p>
+
+        <p>Calling this method on a search in state Completed or Failed
+          succeeds, but has no effect.</p>
+
+        <tp:rationale>
+          <p>Specifying Stop to succeed when the search has finished means that
+            clients who call Stop just before receiving
+            <tp:member-ref>SearchStateChanged</tp:member-ref> don't have to
+            handle a useless error.</p>
+        </tp:rationale>
+
+        <p>Depending on the protocol, the connection manager may not be
+          able to prevent the server from sending further results after this
+          method returns; if this is the case, it MUST ignore any further
+          results.</p>
+      </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_Started, so
+            this method is not yet available.
+          </tp:docstring>
+        </tp:error>
+      </tp:possible-errors>
+    </method>
+
     <signal name="SearchResultReceived"
       tp:name-for-bindings="Search_Result_Received">
       <arg name="Contact" type="u" tp:type="Contact_Handle">
-        <tp:docstring>An integer handle for the contact</tp:docstring>
+        <tp:docstring>An integer handle for the contact, which will remain
+          valid at least until this Channel closes</tp:docstring>
       </arg>
-      <arg name="Values" type="a{sv}" tp:type="String_Variant_Map">
-        <tp:docstring>A dictionary mapping search key names to values for this contact</tp:docstring>
+      <arg name="Info" type="a(sasas)" tp:type="Contact_Info_Field[]">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>An array of fields representing information about this
+            contact, in the same format used in the <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.Connection.Interface">ContactInfo.DRAFT</tp:dbus-ref>
+            interface. It is possible that a separate call to <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT">RequestContactInfo</tp:dbus-ref>
+            would return more information than this signal provides.</p>
+
+          <p>This array SHOULD include the <code>x-telepathy-identifier</code>
+            field, whose values matches the result of calling <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>
+            on the Contact handle.</p>
+
+          <tp:rationale>
+            <p>UIs will most likely want to show the identifier to the user;
+              while they could do this by inspecting the signalled handle,
+              including it in this signal is cheap and removes a roundtrip to
+              look it up.</p>
+          </tp:rationale>
+        </tp:docstring>
       </arg>
       <tp:docstring>
         Emitted when a search result is received from the server.
       </tp:docstring>
     </signal>
-    <signal name="SearchStateChanged"
-      tp:name-for-bindings="Search_State_Changed">
-      <arg name="State" type="u" tp:type="Channel_Contact_Search_State">
-        <tp:docstring>An integer representing the new search state</tp:docstring>
-      </arg>
+
+    <property name="Server" tp:name-for-bindings="Server"
+      type="s" access="read">
       <tp:docstring>
-        Emitted when the search state (as returned by the GetSearchState
-        method) changes.
+        <p>For protocols which support searching for contacts on multiple
+          servers with different DNS names (like XMPP), the DNS name of the
+          server being searched by this channel, e.g.
+          "characters.shakespeare.lit".  Otherwise, the empty string.</p>
+
+        <tp:rationale>
+          <p>XEP 0055 defines a mechanism for XMPP clients to search services
+            of their choice for contacts, such as users.jabber.org (the "Jabber
+            User Directory").</p>
+        </tp:rationale>
+
+        <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 querying multiple different servers;
+          implementations SHOULD use a sensible default if possible if this
+          property is not specified in a channel request.</p>
+
+        <tp:rationale>
+          <p>This allows a client to perform searches on a protocol it knows
+            nothing about without requiring the user to guess a valid server's
+            hostname.</p>
+        </tp:rationale>
       </tp:docstring>
-    </signal>
-    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-    <p>A channel type for searching server-stored user directories. A new channel
-    should be requested by a client for each search attempt, and it should be
-    closed when the search is completed or the required result has been found
-    in order to free unused handles. The search can be cancelled at any time
-    by calling the channel Close method, although depending upon the protocol
-    the connection manager may not be able to prevent the server from sending
-    further results.</p>
-
-    <p>Before searching, the GetSearchKeys method should be used to discover any
-    instructions sent by the server, and the valid search keys which can be
-    provided to the Search method. A search request is then started by
-    providing some of these terms to the Search method, and the search status
-    will be set to CHANNEL_CONTACT_SEARCH_STATE_DURING. When results are
-    returned by the server, the SearchResultReceived signal is emitted for each
-    contact found, and when the search is complete, the search status will be
-    set to CHANNEL_SEARCH_STATE_AFTER.</p>
-    </tp:docstring>
+    </property>
+
   </interface>
 </node>
 <!-- vim:set sw=2 sts=2 et ft=xml: -->