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.
Connections that support contact search channels SHOULD have an entry
in
The requestable channel class would normally also have None
, but the initial implementation of ContactSearch
(in telepathy-gabble) didn't do this.
All channels of this type should have None
(and hence 0
and
""
).
Requests for channels of this type need only
optionally specify the
Before searching, the
Not_Started
to In_Progress
. As results are
returned by the server, the
Completed
. If the search fails after Search
has been called, the state will change to Failed
. A
running search can be cancelled by calling
If the protocol supports limiting the number of results returned by a
search and subsequently requesting more results, after
More_Available
. Clients may
call
The client should call the channel's
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
A contact search channel that is already in use for a different search isn't useful.
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:
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
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:
nickname
would search nicknames, and
tel
would search any available phone number,
regardless of its work/home/mobile/... status).;
" and a
type=...
"tel;type=mobile
).x-telepathy-identifier
x-jabber
) or not exist at all.
x-gender
x-n-family
n
).
x-n-given
n
).
x-n-family
.
x-online
x-adr-locality
adr
).
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
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.
More_Available
move back to state In_Progress
and continue listing up to More_Available
.
Stop the current search. This may not be called while the
org.freedesktop.Telepathy.Error.
.
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
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.
An array of fields representing information about this
contact, in the same format used in the
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 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.
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.