Interface Channel.Type.ContactSearch.DRAFT2

Interface Index (Compact) | Summary | Description | Methods | Signals | Properties | Types

Methods

Search (a{ss}: Terms) → nothing
More () → nothing
Stop () → nothing

Signals

SearchStateChanged (u: State, s: Error, a{sv}: Details)
SearchResultReceived (a{ua(sasas)}: Result)

Properties

SearchState u (Channel_Contact_Search_State) Read only
Limit u Read only
AvailableSearchKeys as Read only
Server s Read only

Types

Contact_Search_Key Simple Type s
Channel_Contact_Search_State Enum u
Contact_Search_Map Mapping a{ss}
Contact_Search_Result_Map Mapping a{ua(sasas)}
WARNING: This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Do not include this interface in libraries that care about compatibility.
Changed in 0.17.27. (draft 2)
Objects implementing this interface must also implement:

Description

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.

Rationale:

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

Methods

(Permalink)

Search (a{ss}: Terms) → nothing

Parameters

  • Terms — a{ss} (Contact_Search_Map)
    • 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.

Possible Errors

  • Not Available
    • The SearchState is no longer Not_Started, so this method is no longer available.
  • Invalid Argument
    • The search terms included something this connection manager cannot search for.
  • Network Error
    • Raised when there is an error reading from or writing to the network.
(Permalink)

More () → nothing

Request that a search in SearchState More_Available move back to state In_Progress and continue listing up to Limit more results.

Possible Errors

(Permalink)

Stop () → nothing

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.

Rationale:

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.

Possible Errors

Signals

(Permalink)

SearchStateChanged (u: State, s: Error, a{sv}: Details)

Parameters

  • State — u (Channel_Contact_Search_State)
    • The new search state
  • Error — s (DBus_Error_Name)
    • If the new state is Failed, the name of a D-Bus error describing what went wrong. Otherwise, the empty string.
  • Details — a{sv} (String_Variant_Map)

    • 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
    Rationale:

    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
(Permalink)

SearchResultReceived (a{ua(sasas)}: Result)

Parameters

  • Result — a{ua(sasas)} (Contact_Search_Result_Map)
    • 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.

Properties

Accessed using the org.freedesktop.DBus.Properties interface.
(Permalink)

SearchState — u (Channel_Contact_Search_State)

Read only
The current state of this search channel object. Change notification is via SearchStateChanged.
(Permalink)

Limit — u

Read only

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.

(Permalink)

AvailableSearchKeys — as

Read only
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.
Rationale:
It can be in the NewChannels signal for round-trip reduction.
(Permalink)

Server — s

Read only

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.

Rationale:

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.

Rationale:

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.

Types

Simple Type (Permalink)

Contact_Search_Key — s

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)
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.
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)
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.
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.
Rationale:
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).
Rationale:
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).
Rationale:
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.
Rationale:
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).
Rationale:
Gadu-Gadu and TOC appear to support this.
Enum (Permalink)

Channel_Contact_Search_State — u

  • Not_Started (0)
    • The search has not started
  • In_Progress (1)
    • The search is in progress
  • More_Available (2)
    • The search has paused, but more results can be retrieved by calling More.
  • Completed (3)
    • The search has been completed
  • Failed (4)
    • The search has failed
Mapping (Permalink)

Contact_Search_Map — a{ss}

A map from search keys to search terms.
  • Key — s (Contact_Search_Key)
    • The search key to match against
  • Term — s
    • 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
Mapping (Permalink)

Contact_Search_Result_Map — a{ua(sasas)}

A map from contact handle to search result.
  • Contact — u (Contact_Handle)
    • An integer handle for the contact.
  • Info — a(sasas) (Contact_Info_Field_List)

    • An array of fields representing information about this contact, in the same format used in the ContactInfo 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.

    Rationale:

    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.