diff options
Diffstat (limited to 'qt4/spec/Channel_Type_Contact_Search.xml')
| -rw-r--r-- | qt4/spec/Channel_Type_Contact_Search.xml | 462 |
1 files changed, 0 insertions, 462 deletions
diff --git a/qt4/spec/Channel_Type_Contact_Search.xml b/qt4/spec/Channel_Type_Contact_Search.xml deleted file mode 100644 index fefa77a26..000000000 --- a/qt4/spec/Channel_Type_Contact_Search.xml +++ /dev/null @@ -1,462 +0,0 @@ -<?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: --> |