The ContactSearchChannel class represents a Telepathy channel of type ContactSearch. More...

#include <TelepathyQt4/ContactSearchChannel>

Inherits Tp::Channel.

Classes

class SearchStateChangeDetails
The ContactSearchChannel::SearchStateChangeDetails class provides a wrapper around the details for a search state change. More...

Public Types

typedef QHash< ContactPtr,
Contact::InfoFields > SearchResult

Signals

void searchStateChanged (Tp::ChannelContactSearchState state, const QString &errorName, const Tp::ContactSearchChannel::SearchStateChangeDetails &details)
void searchResultReceived (const Tp::ContactSearchChannel::SearchResult &result)

Public Member Functions

virtual ~ContactSearchChannel ()
ChannelContactSearchState searchState () const
uint limit () const
QStringList availableSearchKeys () const
QString server () const
PendingOperation * search (const QString &searchKey, const QString &searchTerm)
PendingOperation * search (const ContactSearchMap &searchTerms)
void continueSearch ()
void stopSearch ()

Static Public Member Functions

static ContactSearchChannelPtr create (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties)

Static Public Attributes

static const Feature FeatureCore

Protected Member Functions

ContactSearchChannel (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties, const Feature &coreFeature)

Detailed Description

The ContactSearchChannel class represents a Telepathy channel of type ContactSearch.

Member Typedef Documentation

typedef QHash<ContactPtr, Contact::InfoFields> Tp::ContactSearchChannel::SearchResult

Constructor & Destructor Documentation

Tp::ContactSearchChannel::~ContactSearchChannel ( ) [virtual]

Class destructor.

Tp::ContactSearchChannel::ContactSearchChannel	(	const ConnectionPtr &	connection,
		const QString &	objectPath,
		const QVariantMap &	immutableProperties,
		const Feature &	coreFeature
	)		`[protected]`

Construct a new ContactSearchChannel object.

Parameters:

connection	Connection owning this channel, and specifying the service.
objectPath	The channel object path.
immutableProperties	The channel immutable properties.
coreFeature	The core feature of the channel type, if any. The corresponding introspectable should depend on ContactSearchChannel::FeatureCore.

Member Function Documentation

ContactSearchChannelPtr Tp::ContactSearchChannel::create	(	const ConnectionPtr &	connection,
		const QString &	objectPath,
		const QVariantMap &	immutableProperties
	)		`[static]`

Create a new ContactSearchChannel object.

Parameters:

connection	Connection owning this channel, and specifying the service.
objectPath	The channel object path.
immutableProperties	The channel immutable properties.

Returns:: A ContactSearchChannelPtr object pointing to the newly created ContactSearchChannel object.

Reimplemented from Tp::Channel.

ChannelContactSearchState Tp::ContactSearchChannel::searchState ( ) const

Return the current search state of this channel.

Change notification is via the searchStateChanged() signal.

This method requires ContactSearchChannel::FeatureCore to be ready.

Returns:: The current search state as ChannelContactSearchState.

See also:: searchStateChanged()

uint Tp::ContactSearchChannel::limit ( ) const

Return the maximum number of results that should be returned by calling search(), where 0 represents no limit.

For example, if the terms passed to search() match Antonius, Bridget and Charles and this property is 2, the search service will only return Antonius and Bridget.

This method requires ContactSearchChannel::FeatureCore to be ready.

Returns:: The maximum number of results, or 0 if there is no limit.

See also:: availableSearchKeys(), search()

QStringList Tp::ContactSearchChannel::availableSearchKeys ( ) const

Return 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 method requires ContactSearchChannel::FeatureCore to be ready.

Returns:: The supported search keys.

See also:: limit(), search()

QString Tp::ContactSearchChannel::server ( ) const

Return the DNS name of the server being searched by this channel.

This method requires ContactSearchChannel::FeatureCore to be ready.

Returns:: 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, an empty string.

PendingOperation * Tp::ContactSearchChannel::search	(	const QString &	searchKey,
		const QString &	searchTerm
	)

Send a request to start a search for contacts on this connection.

This may only be called while the searchState() is ChannelContactSearchStateNotStarted; a valid search request will cause the searchStateChanged() signal to be emitted with the state ChannelContactSearchStateInProgress.

Search results are signalled by searchResultReceived().

This method requires ContactSearchChannel::FeatureCore to be ready.

This is an overloaded method for search(const ContactSearchMap &searchTerms).

Parameters:

searchKey	The search key.
searchTerm	The search term.

Returns:: A PendingOperation which will emit PendingOperation::finished when the search has started.

See also:: searchState(), searchStateChanged(), searchResultReceived()

PendingOperation * Tp::ContactSearchChannel::search ( const ContactSearchMap & terms )

Send a request to start a search for contacts on this connection.

This may only be called while the searchState() is ChannelContactSearchStateNotStarted; a valid search request will cause the searchStateChanged() signal to be emitted with the state ChannelContactSearchStateInProgress.

Search results are signalled by searchResultReceived().

This method requires ContactSearchChannel::FeatureCore to be ready.

Parameters:

terms The search terms.

Returns:: A PendingOperation which will emit PendingOperation::finished when the search has started.

See also:: searchState(), searchStateChanged(), searchResultReceived()

void Tp::ContactSearchChannel::continueSearch ( )

Request that a search which searchState() is ChannelContactSearchStateMoreAvailable move back to state ChannelContactSearchStateInProgress and continue listing up to limit() more results.

void Tp::ContactSearchChannel::stopSearch ( )

Stop the current search.

This may not be called while the searchState() is ChannelContactSearchStateNotStarted. If called while the searchState() is ChannelContactSearchStateInProgress, searchStateChanged() will be emitted, with the state ChannelContactSearchStateFailed and the error TP_QT4_ERROR_CANCELLED.

Returns:: A PendingOperation which will emit PendingOperation::finished when the call has finished.

See also:: searchState(), searchStateChanged()

void Tp::ContactSearchChannel::searchStateChanged	(	Tp::ChannelContactSearchState	state,
		const QString &	errorName,
		const Tp::ContactSearchChannel::SearchStateChangeDetails &	details
	)		`[signal]`

Emitted when the value of searchState() changes.

Parameters:

state	The new state.
errorName	The name of the error if any.
details	The details for the state change.

See also:: searchState()

void Tp::ContactSearchChannel::searchResultReceived ( const Tp::ContactSearchChannel::SearchResult & result ) [signal]

Emitted when a result for a search is received. It can be emitted multiple times until the searchState() goes to ChannelContactSearchStateCompleted or ChannelContactSearchStateFailed.

Parameters:

result The search result.

See also:: searchState()

Member Data Documentation

const Feature Tp::ContactSearchChannel::FeatureCore [static]

Feature representing the core that needs to become ready to make the ContactSearchChannel object usable.

Note that this feature must be enabled in order to use most ContactSearchChannel methods. See specific methods documentation for more details.

When calling isReady(), becomeReady(), this feature is implicitly added to the requested features.

Reimplemented from Tp::Channel.