[telepathy-gabble/master] Update to even newer spec draft
Will Thompson
will.thompson at collabora.co.uk
Wed Aug 26 09:21:54 PDT 2009
---
extensions/Channel_Type_Contact_Search.xml | 85 +++++++++++++++++++---------
src/search-channel.c | 15 +++++
tests/twisted/constants.py | 5 +-
3 files changed, 76 insertions(+), 29 deletions(-)
diff --git a/extensions/Channel_Type_Contact_Search.xml b/extensions/Channel_Type_Contact_Search.xml
index 204ecf1..b0e905f 100644
--- a/extensions/Channel_Type_Contact_Search.xml
+++ b/extensions/Channel_Type_Contact_Search.xml
@@ -43,6 +43,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
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
@@ -73,10 +84,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:enumvalue suffix="In_Progress" value="1">
<tp:docstring>The search is in progress</tp:docstring>
</tp:enumvalue>
- <tp:enumvalue suffix="Completed" value="2">
+ <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="3">
+ <tp:enumvalue suffix="Failed" value="4">
<tp:docstring>The search has failed</tp:docstring>
</tp:enumvalue>
</tp:enum>
@@ -127,6 +142,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<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>
@@ -215,35 +232,33 @@ 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>
+ <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>
@@ -310,6 +325,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</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
diff --git a/src/search-channel.c b/src/search-channel.c
index 70637d7..d94e88c 100644
--- a/src/search-channel.c
+++ b/src/search-channel.c
@@ -49,6 +49,7 @@ enum
PROP_SEARCH_STATE,
PROP_AVAILABLE_SEARCH_KEYS,
PROP_SERVER,
+ PROP_LIMIT,
LAST_PROPERTY
};
@@ -77,6 +78,7 @@ struct _GabbleSearchChannelPrivate
static const gchar *states[] = {
"not started",
"in progress",
+ "more available",
"completed",
"failed",
};
@@ -364,6 +366,8 @@ change_search_state (GabbleSearchChannel *chan,
switch (state)
{
case GABBLE_CHANNEL_CONTACT_SEARCH_STATE_NOT_STARTED:
+ /* Gabble shouldn't ever get into state More_Available */
+ case GABBLE_CHANNEL_CONTACT_SEARCH_STATE_MORE_AVAILABLE:
g_assert_not_reached ();
return;
case GABBLE_CHANNEL_CONTACT_SEARCH_STATE_IN_PROGRESS:
@@ -833,6 +837,9 @@ gabble_search_channel_get_property (GObject *object,
case PROP_SERVER:
g_value_set_string (value, chan->priv->server);
break;
+ case PROP_LIMIT:
+ g_value_set_uint (value, 0);
+ break;
case PROP_CHANNEL_PROPERTIES:
g_value_take_boxed (value,
tp_dbus_properties_mixin_make_properties_hash (object,
@@ -846,6 +853,7 @@ gabble_search_channel_get_property (GObject *object,
TP_IFACE_CHANNEL, "Interfaces",
GABBLE_IFACE_CHANNEL_TYPE_CONTACT_SEARCH, "AvailableSearchKeys",
GABBLE_IFACE_CHANNEL_TYPE_CONTACT_SEARCH, "Server",
+ GABBLE_IFACE_CHANNEL_TYPE_CONTACT_SEARCH, "Limit",
NULL));
break;
default:
@@ -881,6 +889,7 @@ gabble_search_channel_class_init (GabbleSearchChannelClass *klass)
{ "SearchState", "search-state", NULL },
{ "AvailableSearchKeys", "available-search-keys", NULL },
{ "Server", "server", NULL },
+ { "Limit", "limit", NULL },
{ NULL }
};
GObjectClass *object_class = G_OBJECT_CLASS (klass);
@@ -920,6 +929,12 @@ gabble_search_channel_class_init (GabbleSearchChannelClass *klass)
G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
g_object_class_install_property (object_class, PROP_SERVER, param_spec);
+ param_spec = g_param_spec_uint ("limit", "Result limit",
+ "Always 0 for unlimited in Gabble",
+ 0, 0, 0, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
+ g_object_class_install_property (object_class, PROP_LIMIT,
+ param_spec);
+
/* Emitted when we get a reply from the server about which search keys it
* supports. Its three arguments are the components of a GError. If the
* server gave us a set of search keys, and they were sane, all components
diff --git a/tests/twisted/constants.py b/tests/twisted/constants.py
index e4740e7..074104c 100644
--- a/tests/twisted/constants.py
+++ b/tests/twisted/constants.py
@@ -85,8 +85,9 @@ CONTACT_SEARCH_STATE = CHANNEL_TYPE_CONTACT_SEARCH + '.SearchState'
SEARCH_NOT_STARTED = 0
SEARCH_IN_PROGRESS = 1
-SEARCH_COMPLETED = 2
-SEARCH_FAILED = 3
+SEARCH_MORE_AVAILABLE = 2
+SEARCH_COMPLETED = 3
+SEARCH_FAILED = 4
TUBE_CHANNEL_STATE_LOCAL_PENDING = 0
TUBE_CHANNEL_STATE_REMOTE_PENDING = 1
--
1.5.6.5
More information about the telepathy-commits
mailing list