From cb96c025c4597704a0c904c9bbbf85eff89ba0a0 Mon Sep 17 00:00:00 2001 From: Will Thompson Date: Tue, 7 Sep 2010 19:50:48 +0100 Subject: Move to undrafted ContactSearch interface --- extensions/Channel_Type_Contact_Search.xml | 455 ----------------------------- extensions/Makefile.am | 1 - extensions/all.xml | 1 - 3 files changed, 457 deletions(-) delete mode 100644 extensions/Channel_Type_Contact_Search.xml (limited to 'extensions') diff --git a/extensions/Channel_Type_Contact_Search.xml b/extensions/Channel_Type_Contact_Search.xml deleted file mode 100644 index 15694169f..000000000 --- a/extensions/Channel_Type_Contact_Search.xml +++ /dev/null @@ -1,455 +0,0 @@ - - - Copyright © 2005-2009 Collabora Limited - Copyright © 2005-2009 Nokia Corporation - Copyright © 2006 INdT - -

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.

- -

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.

- -

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.

- - - - - -

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.

- -

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 SearchState will change from - Not_Started to In_Progress. As results are - returned by the server, the - SearchResultReceived signal is emitted - for each contact found; when the search is complete, the search state - will be set to Completed. If the search fails after Search - has been called, the state will change to Failed. A - running search can be cancelled by calling - Stop.

- -

If the protocol supports limiting the number of results returned by a - search and subsequently requesting more results, after - Limit results have been received the - search state will be set to More_Available. Clients may - call More to request another - Limit results. If allowed by the - connection manager, clients may specify the "page size" by specifying - Limit when calling - CreateChannel. -

- -

The client should call the channel's Close - method when it is finished with the channel, so that any handles held - only by the channel can be released.

- -

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).

- -

It does not make sense to request this channel type using EnsureChannel; - clients SHOULD request channels of this type using - CreateChannel - instead.

- - -

A contact search channel that is already in use for a different - search isn't useful.

- - - - - - The search has not started - - - The search is in progress - - - The search has paused, but more results can be retrieved - by calling More. - - - The search has been completed - - - The search has failed - - - - - - The current state of this search channel object. Change notification - is via SearchStateChanged. - - - - - - The new search state - - - - If the new state is Failed, the name of a D-Bus error - describing what went wrong. Otherwise, the empty string. - - - - -

Additional information about the state transition, which may - include the following well-known keys:

- -
-
debug-message (s)
-
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
-
- - -

This argument allows for future extensions. For instance, - if moving to state Failed because the server - rejected one of our search terms, we could define a key - that indicates which terms were invalid.

- - - - -

Emitted when the SearchState property - changes. The implementation MUST NOT make transitions other than the - following:

- -
    -
  • Not_Started → In_Progress
    • -
  • In_Progress → More_Available
    • -
  • More_Available → In_Progress
    • -
  • In_Progress → Completed
    • -
  • In_Progress → Failed
    • -
- - - - - -

Any of the following search keys, with the indicated result for - the search:

- -
-
The empty string
-
Search for the search term in some implementation-dependent - set of fields, using an implementation-dependent algorithm - (e.g. searching for each word mentioned) - - The "one big search box" approach to searching, as is familiar - from Google. The Sametime plugin to Pidgin appears to search in - this way. - -
- -
A VCard_Field
-
Search for the search term in fields matching that name (for - instance, nickname would search nicknames, and - tel would search any available phone number, - regardless of its work/home/mobile/... status).
- -
A VCard_Field followed by - ";" and a - VCard_Type_Parameter of the form - "type=..."
-
Search for the search term in fields of that name and type - only (for instance, tel;type=mobile).
- -
x-telepathy-identifier
-
Search for contacts whose identifier in the IM protocol - matches the search term (e.g. contains it as a substring) - - 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. - -
- -
x-gender
-
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. - - Examples in XEP-0055 suggest this usage, and at least Gadu-Gadu - also supports limiting search results by gender. - -
- -
x-n-family
-
Search for the search term in contacts' family names - (the first component of the vCard field n). - - Gadu-Gadu and TOC seem to support this mode of searching. - -
- -
x-n-given
-
Search for the search term in contacts' given names - (the second component of the vCard field n). - - As for x-n-family. - -
- -
x-online
-
For the search term "yes", search only for contacts who are - currently online. The results for other search terms are undefined. - Gadu-Gadu appears to support this. -
- -
x-adr-locality
-
Search for the search term as a locality or city (the fourth - component of the vCard field adr). - - Gadu-Gadu and TOC appear to support this. - -
-
- - - - - -

If supported by the protocol, the maximum number of results that - should be returned, where 0 represents no limit. If the - protocol does not support limiting results, this should be - 0.

- -

For example, if the terms passed to - Search match Antonius, - Bridget and Charles and this property is - 2, the search service SHOULD only return Antonius - and Bridget.

- -

This property cannot change during the lifetime of the channel. - This property SHOULD be in the Allowed_Properties of a - Requestable_Channel_Class if and only if the - protocol supports specifying a limit; implementations SHOULD use - 0 as the default if possible, or a protocol-specific - sensible default otherwise.

- - - - - - 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). - This property cannot change during the lifetime of a channel. - - - It can be in the NewChannels - signal for round-trip reduction. - - - - - - A map from search keys to search terms. - - - The search key to match against - - - - - - 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 - - - - - - - - A dictionary mapping search key names to the desired values - - - - Send a request to start a search for contacts on this connection. This - may only be called while the SearchState - is Not_Started; a valid search request will cause the - SearchStateChanged signal to be emitted - with the state In_Progress. - - - - - The SearchState is no longer - Not_Started, so this method is no longer available. - - - - - The search terms included something this connection manager cannot - search for. - - - - - - - - - Request that a search in SearchState - More_Available move back to state In_Progress - and continue listing up to Limit more results. - - - - - The SearchState is not - More_Available. - - - - - - - -

Stop the current search. This may not be called while the - SearchState is Not_Started. If called - while the SearchState is In_Progress, - SearchStateChanged will be emitted, - with the state Failed and the error - org.freedesktop.Telepathy.Errors.Cancelled.

- -

Calling this method on a search in state Completed or Failed - succeeds, but has no effect.

- - -

Specifying Stop to succeed when the search has finished means that - clients who call Stop just before receiving - SearchStateChanged don't have to - handle a useless error.

- - -

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.

- - - - - The SearchState is Not_Started, so - this method is not yet available. - - - - - - - A map from contact handle to search result. - - - An integer handle for the contact. - - - - - -

An array of fields representing information about this - contact, in the same format used in the ContactInfo.DRAFT - interface. It is possible that a separate call to RequestContactInfo - would return more information than this signal provides.

- -

This array SHOULD include the x-telepathy-identifier - field, whose values matches the result of calling InspectHandles - on the Contact handle.

- - -

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.

- - - - - - - - A mapping from contact handle to an array of fields - representing information about this contact. Handles in this mapping - MUST remain valid until the Channel closes. - - - 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. - - - - - -

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.

- - -

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").

- - -

This property cannot change during the lifetime of the channel. - This property SHOULD be in the Allowed_Properties of a - Requestable_Channel_Class 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.

- - -

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.

- - - - - - - diff --git a/extensions/Makefile.am b/extensions/Makefile.am index 6cc215001..bf725734b 100644 --- a/extensions/Makefile.am +++ b/extensions/Makefile.am @@ -18,7 +18,6 @@ EXTRA_DIST = \ Connection_Future.xml \ Connection_Interface_Gabble_Decloak.xml \ Connection_Interface_Mail_Notification.xml \ - Channel_Type_Contact_Search.xml \ Gabble_Plugin_Gateways.xml \ Gabble_Plugin_Test.xml \ OLPC_Activity_Properties.xml \ diff --git a/extensions/all.xml b/extensions/all.xml index 7ea6c0cfc..cd099b7e9 100644 --- a/extensions/all.xml +++ b/extensions/all.xml @@ -42,7 +42,6 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

- -- cgit v1.2.3