path: root/spec/Channel_Type_Contact_Search.xml

<?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">
    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
    <tp:added version="0.19.10">
      as stable API. Changes from draft 2:
      <tp:type>Contact_Search_Result_Map</tp:type> keys are now identifiers
      rather than handles; consequently, the values need not include
      <tt>x-telepathy-identifier</tt>.
    </tp:added>

    <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. Channels of this type should have <tp:dbus-ref
        namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>
        <code>None</code> (and hence <tp:dbus-ref
        namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref> <code>0</code> and
        <tp:dbus-ref namespace='ofdT.Channel'>TargetID</tp:dbus-ref>
        <code>""</code>). Requests for channels of this type need only
        optionally specify the <tp:member-ref>Server</tp:member-ref> property
        (if it is an allowed property in the connection's <tp:dbus-ref
        namespace='ofdT.Connection.Interface.Requests'>RequestableChannelClasses</tp:dbus-ref>).</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.</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:immutable='yes' tp:requestable='sometimes'>
      <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 SHOULD be requestable 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:immutable='yes'>
      <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).

        <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.Error.<tp:error-ref>Cancelled</tp:error-ref></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 identifier to search result, emitted in
        the <tp:member-ref>SearchResultReceived</tp:member-ref>
        signal.</tp:docstring>

      <tp:member name="Contact_Identifier" type="s">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          The identifier of a contact matching the search terms.

          <tp:rationale>
            This is an identifier rather than a handle in case we make handles
            immortal; see <a
              href="https://bugs.freedesktop.org/show_bug.cgi?id=23155">fd.o#23155</a>
            and <a
              href="https://bugs.freedesktop.org/show_bug.cgi?id=13347#c5">fd.o#13347
            comment 5</a>.
          </tp:rationale>
        </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>
        </tp:docstring>
      </tp:member>
    </tp:mapping>

    <signal name="SearchResultReceived"
      tp:name-for-bindings="Search_Result_Received">
      <arg name="Result" type="a{sa(sasas)}" tp:type="Contact_Search_Result_Map">
        <tp:docstring>A mapping from contact identifier to an array of fields
          representing information about this contact.</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:requestable='sometimes' tp:immutable='yes'>
      <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 SHOULD be requestable 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: -->