diff options
Diffstat (limited to 'spec/spec/Channel_Type_Contact_Search.xml')
| -rw-r--r-- | spec/spec/Channel_Type_Contact_Search.xml | 481 |
1 files changed, 481 insertions, 0 deletions
diff --git a/spec/spec/Channel_Type_Contact_Search.xml b/spec/spec/Channel_Type_Contact_Search.xml new file mode 100644 index 000000000..98789ab40 --- /dev/null +++ b/spec/spec/Channel_Type_Contact_Search.xml @@ -0,0 +1,481 @@ +<?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.</p> + + <p>Connections that support contact search channels SHOULD have an entry + in <tp:dbus-ref namespace='ofdT.Connection.Interface.Requests' + >RequestableChannelClasses</tp:dbus-ref> with the <tp:dbus-ref + namespace='ofdT.Channel'>ChannelType</tp:dbus-ref> fixed to this + interface, and no other fixed properties. That requestable + channel class MAY also have the Server and Limit properties in its + list of allowed properties, depending on the protocol.</p> + + <tp:rationale> + <p>The requestable channel class would normally also have <tp:dbus-ref + namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref> fixed to + <code>None</code>, but the initial implementation of ContactSearch + (in telepathy-gabble) didn't do this.</p> + </tp:rationale> + + <p>All 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>).</p> + + <p>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: --> |