Interface Channel.Type.ContactSearch

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{sa(sasas)}: Result)

Properties

SearchState u ( Channel_Contact_Search_State) Read only
Limit u Read only Immutable, Sometimes requestable
AvailableSearchKeys as Read only Immutable
Server s Read only Immutable, Sometimes requestable

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{sa(sasas)}
Added in 0.19.10. as stable API. Changes from draft 2: Contact_Search_Result_Map keys are now identifiers rather than handles; consequently, the values need not include x-telepathy-identifier.
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.

Connections that support contact search channels SHOULD have an entry in RequestableChannelClasses with the ChannelType fixed to this interface, and no other fixed properties. That requestable channel class MAY also have the Server and Limit properties in its list of allowed properties, depending on the protocol.

Rationale:

The requestable channel class would normally also have TargetHandleType fixed to None, but the initial implementation of ContactSearch (in telepathy-gabble) didn't do this.

All channels of this type should have TargetHandleType None (and hence TargetHandle 0 and TargetID "").

Requests for channels of this type need only optionally specify the Server property (if it is an allowed property in the connection's RequestableChannelClasses).

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.

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.Error.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{sa(sasas)}: Result)

Parameters

  • Result — a{sa(sasas)} (Contact_Search_Result_Map)
    • A mapping from contact identifier to an array of fields representing information about this contact.
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
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannel signals.
Depending on the protocol, this property may be requestable, which means that it may be allowed in the properties hash of a channel request such as in the CreateChannel and EnsureChannel methods on Requests and ChannelDispatcher. If supported on this protocol, the property should appear in either the Fixed_Properties or Allowed_Properties of a RequestableChannelClass advertised by the CM.

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 SHOULD be requestable 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
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannel signals.
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).
Rationale:
It can be in the NewChannels signal for round-trip reduction.
(Permalink)

Server — s

Read only
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannel signals.
Depending on the protocol, this property may be requestable, which means that it may be allowed in the properties hash of a channel request such as in the CreateChannel and EnsureChannel methods on Requests and ChannelDispatcher. If supported on this protocol, the property should appear in either the Fixed_Properties or Allowed_Properties of a RequestableChannelClass advertised by the CM.

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 SHOULD be requestable 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{sa(sasas)}

A map from contact identifier to search result, emitted in the SearchResultReceived signal.
  • Contact_Identifier — s
    • The identifier of a contact matching the search terms.
    Rationale:
    This is an identifier rather than a handle in case we make handles immortal; see fd.o#23155 and fd.o#13347 comment 5.
  • 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.