<?xml version="1.0" ?>
<node name="/Channel_Type_Contact_Search" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <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
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.</p>

<p>This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.</p>

<p>You should have received a copy of the GNU Lesser General Public
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.DRAFT2"
    tp:causes-havoc='experimental'>
    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
    <tp:changed version="0.17.27">(draft 2)</tp:changed>

    <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>

      <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>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
        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>

    <tp:enum name="Channel_Contact_Search_State" type="u">
      <tp:enumvalue suffix="Not_Started" value="0">
        <tp:docstring>The search has not started</tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="In_Progress" value="1">
        <tp:docstring>The search is in progress</tp:docstring>
      </tp:enumvalue>
      <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="4">
        <tp:docstring>The search has failed</tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <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>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>
      </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>
        </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>
        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>
    </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. 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.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: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
          <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>

    <tp:mapping name="Contact_Search_Result_Map">
      <tp:docstring>A map from contact handle to search result.</tp:docstring>
      <tp:member name="Contact" type="u" tp:type="Contact_Handle">
        <tp:docstring>
          An integer handle for the contact.
        </tp:docstring>
      </tp:member>

      <tp:member 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</tp:dbus-ref>
            interface. It is possible that a separate call to <tp:dbus-ref
              namespace="org.freedesktop.Telepathy.Connection.Interface.ContactInfo">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>
      </tp:member>
    </tp:mapping>

    <signal name="SearchResultReceived"
      tp:name-for-bindings="Search_Result_Received">
      <arg name="Result" type="a{ua(sasas)}" tp:type="Contact_Search_Result_Map">
        <tp:docstring>A mapping from contact handle to an array of fields
          representing information about this contact. Handles in this mapping
          MUST remain valid until the Channel closes.</tp:docstring>
      </arg>
      <tp:docstring>
        Emitted when a some search results are received from the server.
        This signal can be fired arbitrarily many times so clients MUST NOT
        assume they'll get only one signal.
      </tp:docstring>
    </signal>

    <property name="Server" tp:name-for-bindings="Server"
      type="s" access="read">
      <tp:docstring>
        <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>
    </property>

  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
