Tp::ContactManager Class Reference [Connection proxies]

The ContactManager class is responsible for managing contacts. More...

#include <TelepathyQt4/ContactManager>

List of all members.

Classes

• struct ContactListChannel

Signals

• void presencePublicationRequested (const Tp::Contacts &contacts)
• void presencePublicationRequested (const Tp::Contacts &contacts, const Tp::Channel::GroupMemberChangeDetails &details)
• void groupAdded (const QString &group)
• void groupRemoved (const QString &group)
• void groupMembersChanged (const QString &group, const Tp::Contacts &groupMembersAdded, const Tp::Contacts &groupMembersRemoved)
• void groupMembersChanged (const QString &group, const Tp::Contacts &groupMembersAdded, const Tp::Contacts &groupMembersRemoved, const Tp::Channel::GroupMemberChangeDetails &details)
• void allKnownContactsChanged (const Tp::Contacts &contactsAdded, const Tp::Contacts &contactsRemoved)
• void allKnownContactsChanged (const Tp::Contacts &contactsAdded, const Tp::Contacts &contactsRemoved, const Tp::Channel::GroupMemberChangeDetails &details)

Public Member Functions

• ConnectionPtr connection () const
• QSet< Contact::Feature > supportedFeatures () const
• Contacts allKnownContacts () const
• QStringList allKnownGroups () const
• PendingOperation * addGroup (const QString &group)
• PendingOperation * removeGroup (const QString &group)
• Contacts groupContacts (const QString &group) const
• PendingOperation * addContactsToGroup (const QString &group, const QList< ContactPtr > &contacts)
• PendingOperation * removeContactsFromGroup (const QString &group, const QList< ContactPtr > &contacts)
• bool canRequestPresenceSubscription () const
• bool subscriptionRequestHasMessage () const
• PendingOperation * requestPresenceSubscription (const QList< ContactPtr > &contacts, const QString &message=QString())
• bool canRemovePresenceSubscription () const
• bool subscriptionRemovalHasMessage () const
• bool canRescindPresenceSubscriptionRequest () const
• bool subscriptionRescindingHasMessage () const
• PendingOperation * removePresenceSubscription (const QList< ContactPtr > &contacts, const QString &message=QString())
• bool canAuthorizePresencePublication () const
• bool publicationAuthorizationHasMessage () const
• PendingOperation * authorizePresencePublication (const QList< ContactPtr > &contacts, const QString &message=QString())
• bool publicationRejectionHasMessage () const
• bool canRemovePresencePublication () const
• bool publicationRemovalHasMessage () const
• PendingOperation * removePresencePublication (const QList< ContactPtr > &contacts, const QString &message=QString())
• PendingOperation * removeContacts (const QList< ContactPtr > &contacts, const QString &message=QString())
• bool canBlockContacts () const
• PendingOperation * blockContacts (const QList< ContactPtr > &contacts, bool value=true)
• PendingContacts * contactsForHandles (const UIntList &handles, const QSet< Contact::Feature > &features=QSet< Contact::Feature >())
• PendingContacts * contactsForHandles (const ReferencedHandles &handles, const QSet< Contact::Feature > &features=QSet< Contact::Feature >())
• PendingContacts * contactsForIdentifiers (const QStringList &identifiers, const QSet< Contact::Feature > &features=QSet< Contact::Feature >())
• PendingContacts * upgradeContacts (const QList< ContactPtr > &contacts, const QSet< Contact::Feature > &features)
• ContactPtr lookupContactByHandle (uint handle)
• void requestContactAvatar (Contact *contact)

Protected Member Functions

• void connectNotify (const char *)

---

Detailed Description

The ContactManager class is responsible for managing contacts.

---

Member Function Documentation

ConnectionPtr Tp::ContactManager::connection

(

)

const

QSet< Contact::Feature > Tp::ContactManager::supportedFeatures

(

)

const

Contacts Tp::ContactManager::allKnownContacts

(

)

const

Return a list of relevant contacts (a reasonable guess as to what should be displayed as "the contact list").

This may include any or all of: contacts whose presence the user receives, contacts who are allowed to see the user's presence, contacts stored in some persistent contact list on the server, contacts who the user has blocked from communicating with them, or contacts who are relevant in some other way.

User interfaces displaying a contact list will probably want to filter this list and display some suitable subset of it.

On protocols where there is no concept of presence or a centrally-stored contact list (like IRC), this method may return an empty list.

Returns:

Some contacts

QStringList Tp::ContactManager::allKnownGroups

(

)

const

Return a list of user-defined contact list groups' names.

This method requires Connection::FeatureRosterGroups to be enabled.

Returns:

List of user-defined contact list groups names.

PendingOperation * Tp::ContactManager::addGroup

(

const QString &

group

)

Attempt to add an user-defined contact list group named group.

This method requires Connection::FeatureRosterGroups to be enabled.

On some protocols (e.g. XMPP) empty groups are not represented on the server, so disconnecting from the server and reconnecting might cause empty groups to vanish.

The returned pending operation will finish successfully if the group already exists.

FIXME: currently, the returned pending operation will finish as soon as the CM EnsureChannel has returned. At this point however the NewChannels mechanism hasn't yet populated our contactListGroupChannels member, which means one has to wait for groupAdded before being able to actually do something with the group (which is error-prone!). This is fd.o #29728.

Parameters:

group

Group name.

Returns:

A pending operation which will return when an attempt has been made to add an user-defined contact list group.

See also:

groupAdded(), addContactsToGroup()

PendingOperation * Tp::ContactManager::removeGroup

(

const QString &

group

)

Attempt to remove an user-defined contact list group named group.

This method requires Connection::FeatureRosterGroups to be enabled.

FIXME: currently, the returned pending operation will finish as soon as the CM close() has returned. At this point however the invalidated() mechanism hasn't yet removed the channel from our contactListGroupChannels member, which means contacts can seemingly still be added to the group etc. until the change is picked up (and groupRemoved is emitted). This is fd.o #29728.

Parameters:

group

Group name.

Returns:

A pending operation which will return when an attempt has been made to remove an user-defined contact list group.

See also:

groupRemoved(), removeContactsFromGroup()

Contacts Tp::ContactManager::groupContacts

(

const QString &

group

)

const

Return the contacts in the given user-defined contact list group named group.

This method requires Connection::FeatureRosterGroups to be enabled.

Parameters:

group

Group name.

Returns:

List of contacts on a user-defined contact list group, or an empty list if the group does not exist.

See also:

allKnownGroups(), contactGroups()

PendingOperation * Tp::ContactManager::addContactsToGroup	(	const QString &	group,
		const QList< ContactPtr > &	contacts
	)

Attempt to add the given contacts to the user-defined contact list group named group.

This method requires Connection::FeatureRosterGroups to be enabled.

Parameters:

	group	Group name.
	contacts	Contacts to add.

Returns:

A pending operation which will return when an attempt has been made to add the contacts to the user-defined contact list group.

PendingOperation * Tp::ContactManager::removeContactsFromGroup	(	const QString &	group,
		const QList< ContactPtr > &	contacts
	)

Attempt to remove the given contacts from the user-defined contact list group named group.

This method requires Connection::FeatureRosterGroups to be enabled.

Parameters:

	group	Group name.
	contacts	Contacts to remove.

Returns:

A pending operation which will return when an attempt has been made to remove the contacts from the user-defined contact list group.

bool Tp::ContactManager::canRequestPresenceSubscription

(

)

const

Return whether subscribing to additional contacts' presence is supported on this channel.

In some protocols, the list of contacts whose presence can be seen is fixed, so we can't subscribe to the presence of additional contacts.

Notably, in link-local XMPP, you can see the presence of everyone on the local network, and trying to add more subscriptions would be meaningless.

Returns:

Whether Contact::requestPresenceSubscription and requestPresenceSubscription are likely to succeed

bool Tp::ContactManager::subscriptionRequestHasMessage

(

)

const

Return whether a message can be sent when subscribing to contacts' presence.

If no message will actually be sent, user interfaces should avoid prompting the user for a message, and use an empty string for the message argument.

Returns:

Whether the message argument to Contact::requestPresenceSubscription and requestPresenceSubscription is actually used

PendingOperation * Tp::ContactManager::requestPresenceSubscription	(	const QList< ContactPtr > &	contacts,
		const QString &	message = QString()
	)

Attempt to subscribe to the presence of the given contacts.

This operation is sometimes called "adding contacts to the buddy list" or "requesting authorization".

This method requires Connection::FeatureRoster to be ready.

On most protocols, the contacts will need to give permission before the user will be able to receive their presence: if so, they will be in presence state Contact::PresenceStateAsk until they authorize or deny the request.

The returned PendingOperation will return successfully when a request to subscribe to the contacts' presence has been submitted, or fail if this cannot happen. In particular, it does not wait for the contacts to give permission for the presence subscription.

Parameters:

	contacts	Contacts whose presence is desired
	message	A message from the user which is either transmitted to the contacts, or ignored, depending on the protocol

Returns:

A pending operation which will return when an attempt has been made to subscribe to the contacts' presence

bool Tp::ContactManager::canRemovePresenceSubscription

(

)

const

Return whether the user can stop receiving the presence of a contact whose presence they have subscribed to.

Returns:

Whether removePresenceSubscription and Contact::removePresenceSubscription are likely to succeed for contacts with subscription state Contact::PresenceStateYes

bool Tp::ContactManager::subscriptionRemovalHasMessage

(

)

const

Return whether a message can be sent when removing an existing subscription to the presence of a contact.

If no message will actually be sent, user interfaces should avoid prompting the user for a message, and use an empty string for the message argument.

Returns:

Whether the message argument to Contact::removePresenceSubscription and removePresenceSubscription is actually used, for contacts with subscription state Contact::PresenceStateYes

bool Tp::ContactManager::canRescindPresenceSubscriptionRequest

(

)

const

Return whether the user can cancel a request to subscribe to a contact's presence before that contact has responded.

Returns:

Whether removePresenceSubscription and Contact::removePresenceSubscription are likely to succeed for contacts with subscription state Contact::PresenceStateAsk

bool Tp::ContactManager::subscriptionRescindingHasMessage

(

)

const

Return whether a message can be sent when cancelling a request to subscribe to the presence of a contact.

If no message will actually be sent, user interfaces should avoid prompting the user for a message, and use an empty string for the message argument.

Returns:

Whether the message argument to Contact::removePresenceSubscription and removePresenceSubscription is actually used, for contacts with subscription state Contact::PresenceStateAsk

PendingOperation * Tp::ContactManager::removePresenceSubscription	(	const QList< ContactPtr > &	contacts,
		const QString &	message = QString()
	)

Attempt to stop receiving the presence of the given contacts, or cancel a request to subscribe to their presence that was previously sent.

This method requires Connection::FeatureRoster to be ready.

Parameters:

contacts

Contacts whose presence is no longer required A message from the user which is either transmitted to the contacts, or ignored, depending on the protocol

Returns:

A pending operation which will return when an attempt has been made to remove any subscription to the contacts' presence

bool Tp::ContactManager::canAuthorizePresencePublication

(

)

const

Return true if the publication of the user's presence to contacts can be authorized.

This is always true, unless the protocol has no concept of authorizing publication (in which case contacts' publication status can never be Contact::PresenceStateAsk).

bool Tp::ContactManager::publicationAuthorizationHasMessage

(

)

const

Return whether a message can be sent when authorizing a request from a contact that the user's presence is published to them.

If no message will actually be sent, user interfaces should avoid prompting the user for a message, and use an empty string for the message argument.

Returns:

Whether the message argument to Contact::authorizePresencePublication and authorizePresencePublication is actually used, for contacts with subscription state Contact::PresenceStateAsk

PendingOperation * Tp::ContactManager::authorizePresencePublication	(	const QList< ContactPtr > &	contacts,
		const QString &	message = QString()
	)

If the given contacts have asked the user to publish presence to them, grant permission for this publication to take place.

This method requires Connection::FeatureRoster to be ready.

Parameters:

contacts

Contacts who should be allowed to receive the user's presence A message from the user which is either transmitted to the contacts, or ignored, depending on the protocol

Returns:

A pending operation which will return when an attempt has been made to authorize publication of the user's presence to the contacts

bool Tp::ContactManager::publicationRejectionHasMessage

(

)

const

Return whether a message can be sent when rejecting a request from a contact that the user's presence is published to them.

If no message will actually be sent, user interfaces should avoid prompting the user for a message, and use an empty string for the message argument.

Returns:

Whether the message argument to Contact::removePresencePublication and removePresencePublication is actually used, for contacts with subscription state Contact::PresenceStateAsk

bool Tp::ContactManager::canRemovePresencePublication

(

)

const

Return true if the publication of the user's presence to contacts can be removed, even after permission has been given.

(Rejecting requests for presence to be published is always allowed.)

Returns:

Whether removePresencePublication and Contact::removePresencePublication are likely to succeed for contacts with subscription state Contact::PresenceStateYes

bool Tp::ContactManager::publicationRemovalHasMessage

(

)

const

Return whether a message can be sent when revoking earlier permission that the user's presence is published to a contact.

If no message will actually be sent, user interfaces should avoid prompting the user for a message, and use an empty string for the message argument.

Returns:

Whether the message argument to Contact::removePresencePublication and removePresencePublication is actually used, for contacts with subscription state Contact::PresenceStateYes

PendingOperation * Tp::ContactManager::removePresencePublication	(	const QList< ContactPtr > &	contacts,
		const QString &	message = QString()
	)

If the given contacts have asked the user to publish presence to them, deny this request (this should always succeed, unless a network error occurs).

This method requires Connection::FeatureRoster to be ready.

If the given contacts already have permission to receive the user's presence, attempt to revoke that permission (this might not be supported by the protocol - canRemovePresencePublication indicates whether it is likely to succeed).

Parameters:

contacts

Contacts who should no longer be allowed to receive the user's presence A message from the user which is either transmitted to the contacts, or ignored, depending on the protocol

Returns:

A pending operation which will return when an attempt has been made to remove any publication of the user's presence to the contacts

PendingOperation * Tp::ContactManager::removeContacts	(	const QList< ContactPtr > &	contacts,
		const QString &	message = QString()
	)

Remove completely contacts from the server. It has the same effect than calling removePresencePublication() and removePresenceSubscription(), but also remove from 'stored' list if it exists.

Parameters:

contacts

Contacts who should be removed A message from the user which is either transmitted to the contacts, or ignored, depending on the protocol

Returns:

A pending operation which will return when an attempt has been made to remove any publication of the user's presence to the contacts

bool Tp::ContactManager::canBlockContacts

(

)

const

Return whether this protocol has a list of blocked contacts.

Returns:

Whether blockContacts is likely to succeed

PendingOperation * Tp::ContactManager::blockContacts	(	const QList< ContactPtr > &	contacts,
		bool	value = true
	)

Set whether the given contacts are blocked. Blocked contacts cannot send messages to the user; depending on the protocol, blocking a contact may have other effects.

This method requires Connection::FeatureRoster to be ready.

Parameters:

	contacts	Contacts who should be added to, or removed from, the list of blocked contacts
	value	If true, add the contacts to the list of blocked contacts; if false, remove them from the list

Returns:

A pending operation which will return when an attempt has been made to take the requested action

PendingContacts * Tp::ContactManager::contactsForHandles	(	const UIntList &	handles,
		const QSet< Contact::Feature > &	features = QSet<Contact::Feature>()
	)

PendingContacts * Tp::ContactManager::contactsForHandles	(	const ReferencedHandles &	handles,
		const QSet< Contact::Feature > &	features = QSet<Contact::Feature>()
	)

PendingContacts * Tp::ContactManager::contactsForIdentifiers	(	const QStringList &	identifiers,
		const QSet< Contact::Feature > &	features = QSet<Contact::Feature>()
	)

PendingContacts * Tp::ContactManager::upgradeContacts	(	const QList< ContactPtr > &	contacts,
		const QSet< Contact::Feature > &	features
	)

ContactPtr Tp::ContactManager::lookupContactByHandle

(

uint

handle

)

void Tp::ContactManager::requestContactAvatar

(

Contact *

contact

)

void Tp::ContactManager::presencePublicationRequested

(

const Tp::Contacts &

contacts

)

[signal]

Deprecated:

Use presencePublicationRequested(const Tp::Contacts &contacts, const Tp::Channel::GroupMemberChangeDetails &details) instead.

const Tp::Channel::GroupMemberChangeDetails &details);

This signal is emitted whenever some contacts request for presence publication.

Parameters:

	contacts	A set of contacts which requested presence publication.
	details	The request details.

void Tp::ContactManager::presencePublicationRequested	(	const Tp::Contacts &	contacts,
		const Tp::Channel::GroupMemberChangeDetails &	details
	)			[signal]

void Tp::ContactManager::groupAdded

(

const QString &

group

)

[signal]

void Tp::ContactManager::groupRemoved

(

const QString &

group

)

[signal]

void Tp::ContactManager::groupMembersChanged	(	const QString &	group,
		const Tp::Contacts &	groupMembersAdded,
		const Tp::Contacts &	groupMembersRemoved
	)			[signal]

Deprecated:

Use groupMembersChanged(const QString &group, const Tp::Contacts &groupMembersAdded, const Tp::Contacts &groupMembersRemoved, const Tp::Channel::GroupMemberChangeDetails &details) instead.

void Tp::ContactManager::groupMembersChanged	(	const QString &	group,
		const Tp::Contacts &	groupMembersAdded,
		const Tp::Contacts &	groupMembersRemoved,
		const Tp::Channel::GroupMemberChangeDetails &	details
	)			[signal]

This signal is emitted whenever some contacts got removed or added from a group.

Parameters:

	group	The name of the group that changed.
	groupMembersAdded	A set of contacts which were added to the group group.
	groupMembersRemoved	A set of contacts which were removed from the group group.
	details	The change details.

void Tp::ContactManager::allKnownContactsChanged	(	const Tp::Contacts &	contactsAdded,
		const Tp::Contacts &	contactsRemoved
	)			[signal]

Deprecated:

Use allKnownContactsChanged(const Tp::Contacts &contactsAdded, const Tp::Contacts &contactsRemoved, const Tp::Channel::GroupMemberChangeDetails &details) instead.

void Tp::ContactManager::allKnownContactsChanged	(	const Tp::Contacts &	contactsAdded,
		const Tp::Contacts &	contactsRemoved,
		const Tp::Channel::GroupMemberChangeDetails &	details
	)			[signal]

This signal is emitted whenever some contacts got removed or added from ContactManager's known contact list. It is useful for monitoring which contacts are currently known by ContactManager.

Parameters:

	contactsAdded	A set of contacts which were added to the known contact list.
	contactsRemoved	A set of contacts which were removed from the known contact list.
	details	The change details.

Note:

Please note that, in some protocols, this signal could stream newly added contacts with both presence subscription and publication state set to No. Be sure to watch over publication and/or subscription state changes if that is the case.

void Tp::ContactManager::connectNotify

(

const char *

signalName

)

[protected]