diff options
| -rw-r--r-- | extensions/Channel_Type_Contact_Search.xml | 175 | ||||
| -rw-r--r-- | src/search-channel.c | 12 |
2 files changed, 160 insertions, 27 deletions
diff --git a/extensions/Channel_Type_Contact_Search.xml b/extensions/Channel_Type_Contact_Search.xml index 410db9594..204ecf11d 100644 --- a/extensions/Channel_Type_Contact_Search.xml +++ b/extensions/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 @@ -28,23 +28,42 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ closed when the search is completed or the required result has been found in order to free unused handles.</p> - <p>The search can be cancelled at any time by calling the channel's - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> - method. Depending on the protocol, the connection manager may not be - able to prevent the server from sending further results; if this is the - case, it MUST ignore any further results.</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 - Not_Started to In_Progress. As results are returned by the server, the + <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 Completed.</p> + 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> <tp:enum name="Channel_Contact_Search_State" type="u"> @@ -57,6 +76,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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> <property name="SearchState" tp:name-for-bindings="Search_State" @@ -72,9 +94,42 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <arg name="State" type="u" tp:type="Channel_Contact_Search_State"> <tp:docstring>The new search state</tp:docstring> </arg> - <tp:docstring> - Emitted when the <tp:member-ref>SearchState</tp:member-ref> property - changes. + <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> @@ -108,7 +163,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <dd>Search for the search term in fields of that name and type only (for instance, <code>tel;type=mobile</code>).</dd> - <dt>x-telepathy-identifier</dt> + <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> @@ -160,6 +215,31 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ 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> @@ -169,8 +249,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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"] - (for XMPP XEP-0055, without extensibility via Data Forms). + 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> @@ -230,6 +310,40 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </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"> @@ -237,12 +351,25 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ valid at least until this Channel closes</tp:docstring> </arg> <arg name="Info" type="a(sasas)" tp:type="Contact_Info_Field[]"> - <tp:docstring>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. + <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> diff --git a/src/search-channel.c b/src/search-channel.c index e02a9de6b..4165e5b94 100644 --- a/src/search-channel.c +++ b/src/search-channel.c @@ -77,7 +77,8 @@ struct _GabbleSearchChannelPrivate static const gchar *states[] = { "not started", "in progress", - "completed" + "completed", + "failed", }; static void channel_iface_init (gpointer, gpointer); @@ -772,6 +773,7 @@ gabble_search_channel_set_property (GObject *object, case PROP_SEARCH_STATE: { GabbleChannelContactSearchState state = g_value_get_uint (value); + GHashTable *details; g_return_if_fail (state < NUM_GABBLE_CHANNEL_CONTACT_SEARCH_STATES); /* The search state can only go forward because it can't find @@ -781,8 +783,12 @@ gabble_search_channel_set_property (GObject *object, DEBUG ("moving from %s to %s", states[priv->state], states[state]); priv->state = state; + + details = g_hash_table_new_full (g_str_hash, g_str_equal, NULL, + (GDestroyNotify) tp_g_value_slice_free); gabble_svc_channel_type_contact_search_emit_search_state_changed ( - chan, state); + chan, state, "", details); + g_hash_table_unref (details); break; } case PROP_SERVER: @@ -821,7 +827,7 @@ gabble_search_channel_class_init (GabbleSearchChannelClass *klass) param_spec = g_param_spec_uint ("search-state", "Search state", "The current state of the search represented by this channel", GABBLE_CHANNEL_CONTACT_SEARCH_STATE_NOT_STARTED, - GABBLE_CHANNEL_CONTACT_SEARCH_STATE_COMPLETED, + GABBLE_CHANNEL_CONTACT_SEARCH_STATE_FAILED, GABBLE_CHANNEL_CONTACT_SEARCH_STATE_NOT_STARTED, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); g_object_class_install_property (object_class, PROP_SEARCH_STATE, |