[Telepathy-commits] [telepathy-spec/master] Re-draft and resurrect the ContactSearch channel type
Simon McVittie
simon.mcvittie at collabora.co.uk
Tue Feb 17 05:42:33 PST 2009
Summary of changes:
* SearchState is a property now
* AvailableSearchKeys is an immutable property (so you get it in
NewChannels for round-trip reduction)
* Search terms are all strings
* Search terms can't be "mandatory" (what would that even mean?)
* Search terms are vCard fields, plus some defined extensions
* Results are defined in terms of ContactInfo (interface synergy!)
---
spec/Channel_Type_Contact_Search.xml | 270 ++++++++++++++++++++++-----------
spec/all.xml | 1 +
2 files changed, 181 insertions(+), 90 deletions(-)
diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml
index 0b166bb..92e495a 100644
--- a/spec/Channel_Type_Contact_Search.xml
+++ b/spec/Channel_Type_Contact_Search.xml
@@ -18,58 +18,32 @@ Lesser General Public License for more details.</p>
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:causes-havoc='not well-tested'>
+ <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch.DRAFT"
+ tp:causes-havoc='experimental'>
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
- <tp:struct name="Search_Key_Info">
- <tp:docstring>A struct representing details on search strings.</tp:docstring>
- <tp:member type="b" name="Is_Mandatory">
- <tp:docstring>Booleans indicating if the search key is mandatory.
- </tp:docstring>
- </tp:member>
- <tp:member type="g" name="Type_Signature">
- <tp:docstring>The type signature of the value for this search key.
- </tp:docstring>
- </tp:member>
- </tp:struct>
+ <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 in order to free unused handles.</p>
- <tp:mapping name="Search_Key_Info_Map">
- <tp:docstring>A dictionary mapping string search key names to its search details.
- </tp:docstring>
- <tp:member type="s" name="Term"/>
- <tp:member type="(bg)" tp:type="Search_Key_Info" name="Details"/>
- </tp:mapping>
+ <p>The search can be cancelled at
+ any time by calling the channel's Close 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 AvailableSearchKeys property should be
+ inspected to determine the valid search keys which can be provided
+ to the Search method. A search request is then started by providing
+ some of these terms to the Search method, and the search status will
+ be set to During. As results are returned by the server, the
+ SearchResultReceived signal is emitted for each contact found;
+ when the search is complete, the search status will be set to
+ After.</p>
+ </tp:docstring>
- <method name="GetSearchKeys" tp:name-for-bindings="Get_Search_Keys">
- <arg direction="out" type="s">
- <tp:docstring>
- A string with any instructions from the server
- </tp:docstring>
- </arg>
- <arg direction="out" type="a{s(bg)}" tp:type="Search_Key_Info_Map">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- A dictionary mapping string search key names to its search details.
- </tp:docstring>
- </arg>
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Returns any instructions from the server along with a dictionary of
- search key names to their types, and a boolean indicating if the key is
- mandatory. The following well-known search key names should be used
- where appropriate:</p>
- <dl>
- <dt>s:first</dt><dd>The desired contact's given name</dd>
- <dt>s:last</dt><dd>The desired contact's family name</dd>
- <dt>s:nick</dt><dd>The desired contact's nickname</dd>
- <dt>s:email</dt><dd>The e-mail address of the desired contact</dd>
- </dl>
- </tp:docstring>
- <tp:possible-errors>
- <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
- <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
- <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
- </tp:possible-errors>
- </method>
<tp:enum name="Channel_Contact_Search_State" type="u">
<tp:enumvalue suffix="Before" value="0">
<tp:docstring>The search has not started</tp:docstring>
@@ -81,17 +55,142 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:docstring>The search has been completed</tp:docstring>
</tp:enumvalue>
</tp:enum>
- <method name="GetSearchState" tp:name-for-bindings="Get_Search_State">
- <arg direction="out" type="u" tp:type="Channel_Contact_Search_State">
- <tp:docstring>The search state represented as one of the values of
- ChannelContactSearchState</tp:docstring>
+
+ <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>
<tp:docstring>
- Returns the current state of this search channel object.
+ Emitted when the <tp:member-ref>SearchState</tp:member-ref> property
+ changes.
</tp:docstring>
- </method>
- <method name="Search">
- <arg direction="in" name="Terms" type="a{sv}" tp:type="String_Variant_Map">
+ </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>;type=</code>" and a
+ <tp:type>VCard_Type_Parameter</tp:type></dt>
+ <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>
+ <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 x-jabber)
+ 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 suppor 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 x-family.
+ </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="SearchKeys" type="as" access="read"
+ tp:name-for-bindings="Search_Keys">
+ <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).
+ </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>
@@ -99,54 +198,45 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:docstring>
Send a request to start a search for contacts on this connection. A
valid search request will cause the SearchStateChanged signal to be
- emitted with the status CHANNEL_CONTACT_SEARCH_STATE_DURING.
+ emitted with the status During.
</tp:docstring>
<tp:possible-errors>
- <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The <tp:member-ref>SearchState</tp:member-ref> is no longer Before,
+ 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:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
</tp:possible-errors>
</method>
+
<signal name="SearchResultReceived"
tp:name-for-bindings="Search_Result_Received">
<arg name="Contact" type="u" tp:type="Contact_Handle">
- <tp:docstring>An integer handle for the contact</tp:docstring>
+ <tp:docstring>An integer handle for the contact, which will remain
+ valid at least until this Channel closes</tp:docstring>
</arg>
- <arg name="Values" type="a{sv}" tp:type="String_Variant_Map">
- <tp:docstring>A dictionary mapping search key names to values for this contact</tp:docstring>
+ <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>
</arg>
<tp:docstring>
Emitted when a search result is received from the server.
</tp:docstring>
</signal>
- <signal name="SearchStateChanged"
- tp:name-for-bindings="Search_State_Changed">
- <arg name="State" type="u" tp:type="Channel_Contact_Search_State">
- <tp:docstring>An integer representing the new search state</tp:docstring>
- </arg>
- <tp:docstring>
- Emitted when the search state (as returned by the GetSearchState
- method) changes.
- </tp:docstring>
- </signal>
- <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 it should be
- closed when the search is completed or the required result has been found
- in order to free unused handles. The search can be cancelled at any time
- by calling the channel Close method, although depending upon the protocol
- the connection manager may not be able to prevent the server from sending
- further results.</p>
-
- <p>Before searching, the GetSearchKeys method should be used to discover any
- instructions sent by the server, and the valid search keys which can be
- provided to the Search method. A search request is then started by
- providing some of these terms to the Search method, and the search status
- will be set to CHANNEL_CONTACT_SEARCH_STATE_DURING. When results are
- returned by the server, the SearchResultReceived signal is emitted for each
- contact found, and when the search is complete, the search status will be
- set to CHANNEL_SEARCH_STATE_AFTER.</p>
- </tp:docstring>
+
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/all.xml b/spec/all.xml
index 7fc0e75..3987b3b 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -51,6 +51,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Channel_Type_Stream_Tube.xml"/>
<xi:include href="Channel_Type_DBus_Tube.xml"/>
<xi:include href="Channel_Type_File_Transfer.xml"/>
+<xi:include href="Channel_Type_Contact_Search.xml"/>
<xi:include href="Channel_Interface_Call_Merging.xml"/>
<xi:include href="Channel_Interface_Call_State.xml"/>
--
1.5.6.5
More information about the telepathy-commits
mailing list