Tp::Contact Class Reference [Connection proxies]

The Contact class represents a Telepathy contact. More...

#include <TelepathyQt4/Contact>

Inherits Tp::Object.

List of all members.

Classes

• class InfoFields

  The Contact::InfoFields class represents the information of a Telepathy contact. More...
  

Public Types

• enum PresenceState { PresenceStateNo, PresenceStateAsk, PresenceStateYes }

Signals

• void aliasChanged (const QString &alias)
• void avatarTokenChanged (const QString &avatarToken)
• void avatarDataChanged (const Tp::AvatarData &avatarData)
• void presenceChanged (const Tp::Presence &presence)
• void capabilitiesChanged (const Tp::ContactCapabilities &caps)
• void locationUpdated (const Tp::LocationInfo &location)
• void infoFieldsChanged (const Tp::Contact::InfoFields &infoFields)
• void subscriptionStateChanged (Tp::Contact::PresenceState state)
• void subscriptionStateChanged (Tp::Contact::PresenceState state, const Tp::Channel::GroupMemberChangeDetails &details)
• void publishStateChanged (Tp::Contact::PresenceState state, const QString &message)
• void publishStateChanged (Tp::Contact::PresenceState state, const Tp::Channel::GroupMemberChangeDetails &details)
• void blockStatusChanged (bool blocked)
• void blockStatusChanged (bool blocked, const Tp::Channel::GroupMemberChangeDetails &details)
• void addedToGroup (const QString &group)
• void removedFromGroup (const QString &group)

Public Member Functions

• ~Contact ()
• ContactManagerPtr manager () const
• ReferencedHandles handle () const
• QString id () const
• Features requestedFeatures () const
• Features actualFeatures () const
• QString alias () const
• bool isAvatarTokenKnown () const
• QString avatarToken () const
• AvatarData avatarData () const
• void requestAvatarData ()
• Presence presence () const
• ContactCapabilities capabilities () const
• LocationInfo location () const
• bool isContactInfoKnown () const
• InfoFields infoFields () const
• PendingOperation * refreshInfo ()
• PendingContactInfo * requestInfo ()
• bool isSubscriptionStateKnown () const
• bool isSubscriptionRejected () const
• PresenceState subscriptionState () const
• bool isPublishStateKnown () const
• bool isPublishCancelled () const
• PresenceState publishState () const
• QString publishStateMessage () const
• PendingOperation * requestPresenceSubscription (const QString &message=QString())
• PendingOperation * removePresenceSubscription (const QString &message=QString())
• PendingOperation * authorizePresencePublication (const QString &message=QString())
• PendingOperation * removePresencePublication (const QString &message=QString())
• bool isBlocked () const
• PendingOperation * block (bool value=true)
• QStringList groups () const
• PendingOperation * addToGroup (const QString &group)
• PendingOperation * removeFromGroup (const QString &group)

Static Public Attributes

• static const Feature FeatureAlias
• static const Feature FeatureAvatarData
• static const Feature FeatureAvatarToken
• static const Feature FeatureCapabilities
• static const Feature FeatureInfo
• static const Feature FeatureLocation
• static const Feature FeatureSimplePresence

Protected Member Functions

• Contact (ContactManager *manager, const ReferencedHandles &handle, const Features &requestedFeatures, const QVariantMap &attributes)
• virtual void augment (const Features &requestedFeatures, const QVariantMap &attributes)
• void connectNotify (const char *)

---

Detailed Description

The Contact class represents a Telepathy contact.

The accessor functions on this object (id(), alias(), and so on) don't make any D-Bus calls; instead, they return/use values cached from a previous introspection run. The introspection process populates their values in the most efficient way possible based on what the service implements.

To avoid unnecessary D-Bus traffic, some accessors only return valid information after specific features have been enabled. For instance, to retrieve the contact avatar token, it is necessary to enable the feature Contact::FeatureAvatarToken. See the individual methods descriptions for more details.

Contact features can be enabled by constructing a ContactFactory and enabling the desired features, and passing it to AccountManager, Account or ClientRegistrar when creating them as appropriate. However, if a particular feature is only ever used in a specific circumstance, such as an user opening some settings dialog separate from the general view of the application, features can be later enabled as needed by calling ContactManager::upgradeContacts() with the additional features, and waiting for the resulting PendingOperation to finish.

As an addition to accessors, signals are emitted to indicate that properties have changed, for example aliasChanged(), avatarTokenChanged(), etc.

See Asynchronous Object Model, Shared Pointer Usage

---

Member Enumeration Documentation

enum Tp::Contact::PresenceState

Enumerator:

PresenceStateNo
PresenceStateAsk
PresenceStateYes

---

Constructor & Destructor Documentation

Tp::Contact::~Contact

(

)

Class destructor.

Tp::Contact::Contact	(	ContactManager *	manager,
		const ReferencedHandles &	handle,
		const Features &	requestedFeatures,
		const QVariantMap &	attributes
	)			[protected]

Construct a new Contact object.

Parameters:

	manager	ContactManager owning this contact.
	handle	The contact handle.
	requestedFeatures	The contact requested features.
	attributes	The contact attributes.

---

Member Function Documentation

ContactManagerPtr Tp::Contact::manager

(

)

const

Return the contact nanager owning this contact.

Returns:

A pointer to the ContactManager object.

ReferencedHandles Tp::Contact::handle

(

)

const

Return the handle of this contact.

Returns:

The handle as a ReferencedHandles object.

QString Tp::Contact::id

(

)

const

Return the identifier of this contact.

Returns:

The identifier.

Features Tp::Contact::requestedFeatures

(

)

const

Return the features requested on this contact.

Returns:

The requested features as a set of Feature objects.

Features Tp::Contact::actualFeatures

(

)

const

Return the features that are actually enabled on this contact.

Returns:

The actual features as a set of Feature objects.

QString Tp::Contact::alias

(

)

const

Return the alias of this contact.

Change notification is via the aliasChanged() signal.

This method requires Contact::FeatureAlias to be ready.

Returns:

The alias.

bool Tp::Contact::isAvatarTokenKnown

(

)

const

Return whether the avatar token of this contact is known.

This method requires Contact::FeatureAvatarToken to be ready.

Returns:

true if the avatar token is known, false otherwise.

See also:

avatarToken()

QString Tp::Contact::avatarToken

(

)

const

Return the avatar token for this contact.

Change notification is via the avatarTokenChanged() signal.

This method requires Contact::FeatureAvatarToken to be ready.

Returns:

The avatar token.

See also:

isAvatarTokenKnown(), avatarTokenChanged(), avatarData()

AvatarData Tp::Contact::avatarData

(

)

const

Return the actual avatar for this contact.

Change notification is via the avatarDataChanged() signal.

This method requires Contact::FeatureAvatarData to be ready.

Returns:

The avatar as an AvatarData object.

See also:

avatarDataChanged(), avatarToken()

void Tp::Contact::requestAvatarData

(

)

Start a request to retrieve the avatar for this contact.

Force the request of the avatar data. This method returns directly, emitting avatarTokenChanged() and avatarDataChanged() signals once the token and data are fetched from the server.

This is only useful if the avatar token is unknown; see isAvatarTokenKnown(). It happens in the case of offline XMPP contacts, because the server does not send the token for them and an explicit request of the avatar data is needed.

This method requires Contact::FeatureAvatarData to be ready.

See also:

avatarData(), avatarDataChanged(), avatarToken(), avatarTokenChanged()

Presence Tp::Contact::presence

(

)

const

Return the actual presence of this contact.

Change notification is via the presenceChanged() signal.

This method requires Contact::FeatureSimplePresence to be ready.

Returns:

The presence as a Presence object.

ContactCapabilities Tp::Contact::capabilities

(

)

const

Return the capabilities for this contact.

User interfaces can use this information to show or hide UI components.

If ContactManager::supportedFeatures() contains Contact::FeatureCapabilities, the returned object will be a ContactCapabilities object, where CapabilitiesBase::isSpecificToContact() will be true; if that feature isn't present, this returned object is the subset of Contact::manager()connection()capabilities() and CapabilitiesBase::isSpecificToContact() will be false.

Change notification is via the capabilitiesChanged() signal.

This method requires Contact::FeatureCapabilities to be ready.

Returns:

An object representing the contact capabilities.

LocationInfo Tp::Contact::location

(

)

const

Return the location for this contact.

Change notification is via the locationUpdated() signal.

This method requires Contact::FeatureLocation to be ready.

Returns:

The contact location as a LocationInfo object.

bool Tp::Contact::isContactInfoKnown

(

)

const

Return whether the info card for this contact has been received.

With some protocols (notably XMPP) information is not pushed from the server and must be requested explicitely using refreshInfo() or requestInfo(). This method can be used to know if the information is received from the server or if an explicit request is needed.

This method requires Contacat::FeatureInfo to be ready.

Returns:

true if the information is known; false otherwise.

Contact::InfoFields Tp::Contact::infoFields

(

)

const

Return the information for this contact.

Note that this method only return cached information. In order to refresh the information use refreshInfo().

Change notification is via the infoFieldsChanged() signal.

This method requires Contact::FeatureInfo to be ready.

Returns:

The contact info as a Contact::InfoFields object.

PendingOperation * Tp::Contact::refreshInfo

(

)

Refresh information for the given contact.

Once the information is retrieved infoFieldsChanged() will be emitted.

This method requires Contact::FeatureInfo to be ready.

Returns:

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

See also:

infoFieldsChanged()

PendingContactInfo * Tp::Contact::requestInfo

(

)

Start a request to retrieve the information for this contact.

This method is useful for UIs that don't care about notification of changes in the contact information but want to show the contact information (e.g. right-click on a contact and show the contact info).

Returns:

A PendingContactInfo, which will emit PendingContactInfo::finished when the information has been retrieved or an error occurred.

bool Tp::Contact::isSubscriptionStateKnown

(

)

const

Return whether the presence subscription state of this contact is known.

Returns:

true if the presence subscription state is known, false otherwise.

See also:

subscriptionState(), isSubscriptionRejected()

bool Tp::Contact::isSubscriptionRejected

(

)

const

Return whether a request to see this contact's presence was denied.

Returns:

if the a request to see the presence subscription was denied, false otherwise.

See also:

isSubscriptionStateKnown(), subscriptionState()

Contact::PresenceState Tp::Contact::subscriptionState

(

)

const

Return the presence subscription state of this contact (i.e. whether the local user can retrieve information about this contact's presence).

Returns:

The presence subscription state as Contact::PresenceState.

See also:

isSubscriptionStateKnown(), isSubscriptionRejected()

bool Tp::Contact::isPublishStateKnown

(

)

const

Return whether the presence publish state of this contact is known.

Returns:

true if the presence publish state is known, false otherwise.

See also:

publishState(), isPublishCancelled()

bool Tp::Contact::isPublishCancelled

(

)

const

Return whether a request to publish presence information to this contact was cancelled.

Returns:

true if a request to publish presence information was cancelled, false otherwise.

See also:

isPublishStateKnown(), publishState()

Contact::PresenceState Tp::Contact::publishState

(

)

const

Return the presence publish state of this contact (i.e. whether this contact can retrieve information about the local user's presence).

Returns:

The presence publish state as Contact::PresenceState.

See also:

isSubscriptionStateKnown(), isSubscriptionRejected()

QString Tp::Contact::publishStateMessage

(

)

const

If the publishState() is Contact::PresenceStateAsk, return an optional message that was sent by the contact asking to receive the local user's presence; omitted if none was given.

Returns:

The message that was sent by the contact asking to receive the local user's presence.

See also:

publishState()

PendingOperation * Tp::Contact::requestPresenceSubscription

(

const QString &

message = QString()

)

Start a request that this contact allow the local user to subscribe to their presence (i.e. that this contact's subscribe attribute becomes Contact::PresenceStateYes)

This method requires Connection::FeatureRoster to be ready.

Returns:

A PendingOperation which will emit PendingOperation::finished when the request has been made.

See also:

subscriptionState(), removePresenceSubscription()

PendingOperation * Tp::Contact::removePresenceSubscription

(

const QString &

message = QString()

)

Start a request for the local user to stop receiving presence from this contact.

This method requires Connection::FeatureRoster to be ready.

Returns:

A PendingOperation which will emit PendingOperation::finished when the request has been made.

See also:

subscriptionState(), requestPresenceSubscription()

PendingOperation * Tp::Contact::authorizePresencePublication

(

const QString &

message = QString()

)

Start a request to authorize this contact's request to see the local user presence (i.e. that this contact publish attribute becomes Contact::PresenceStateYes).

This method requires Connection::FeatureRoster to be ready.

Returns:

A PendingOperation which will emit PendingOperation::finished when the request has been made.

See also:

publishState(), removePresencePublication()

PendingOperation * Tp::Contact::removePresencePublication

(

const QString &

message = QString()

)

Start a request for the local user to stop sending presence to this contact.

This method requires Connection::FeatureRoster to be ready.

Returns:

A PendingOperation which will emit PendingOperation::finished when the request has been made.

See also:

publishState(), authorizePresencePublication()

bool Tp::Contact::isBlocked

(

)

const

Return whether this contact is blocked.

Change notification is via the blockStatusChanged() signal.

Returns:

true if blocked, false otherwise.

See also:

block()

PendingOperation * Tp::Contact::block

(

bool

value = true

)

Start a request to block/unblock this contact.

This method requires Connection::FeatureRoster to be ready.

Parameters:

value

Whether the contact should be blocked.

Returns:

A PendingOperation which will emit PendingOperation::finished when an attempt has been made to take the requested action.

See also:

isBlocked()

QStringList Tp::Contact::groups

(

)

const

Return the names of the user-defined roster groups to which the contact belongs.

Change notification is via the addedToGroup() and removedFromGroup() signals.

This method requires Connection::FeatureRosterGroups to be ready.

Returns:

A list of user-defined contact list groups names.

See also:

addToGroup(), removedFromGroup()

PendingOperation * Tp::Contact::addToGroup

(

const QString &

group

)

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

This method requires Connection::FeatureRosterGroups to be ready.

Parameters:

group

The group name.

Returns:

A PendingOperation which will emit PendingOperation::finished when an attempt has been made to to add the contact to the user-defined contact list group.

See also:

groups(), removeFromGroup()

PendingOperation * Tp::Contact::removeFromGroup

(

const QString &

group

)

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

This method requires Connection::FeatureRosterGroups to be ready.

Parameters:

group

The group name.

Returns:

A PendingOperation which will emit PendingOperation::finished when an attempt has been made to to remote the contact to the user-defined contact list group.

See also:

groups(), addToGroup()

void Tp::Contact::aliasChanged

(

const QString &

alias

)

[signal]

Emitted when the value of alias() changes.

Parameters:

alias

The new alias of this contact.

See also:

alias()

void Tp::Contact::avatarTokenChanged

(

const QString &

avatarToken

)

[signal]

Emitted when the value of avatarToken() changes.

Parameters:

avatarToken

The new avatar token of this contact.

See also:

avatarToken()

void Tp::Contact::avatarDataChanged

(

const Tp::AvatarData &

avatarData

)

[signal]

void Tp::Contact::presenceChanged

(

const Tp::Presence &

presence

)

[signal]

Emitted when the value of presence() changes.

Parameters:

presence

The new presence of this contact.

See also:

presence()

void Tp::Contact::capabilitiesChanged

(

const Tp::ContactCapabilities &

caps

)

[signal]

Emitted when the value of capabilities() changes.

Parameters:

caps

The new capabilities of this contact.

See also:

capabilities()

void Tp::Contact::locationUpdated

(

const Tp::LocationInfo &

location

)

[signal]

Emitted when the value of location() changes.

Parameters:

caps

The new location of this contact.

See also:

location()

void Tp::Contact::infoFieldsChanged

(

const Tp::Contact::InfoFields &

infoFields

)

[signal]

Emitted when the value of infoFields() changes.

Parameters:

InfoFields

The new info of this contact.

See also:

infoFields()

void Tp::Contact::subscriptionStateChanged

(

Tp::Contact::PresenceState

state

)

[signal]

Emitted when the value of subscriptionState() changes.

Parameters:

state

The new subscription state of this contact.

See also:

subscriptionState()

void Tp::Contact::subscriptionStateChanged	(	Tp::Contact::PresenceState	state,
		const Tp::Channel::GroupMemberChangeDetails &	details
	)			[signal]

Deprecated:

Use subscriptionStateChanged(Tp::Contact::PresenceState state) instead.

void Tp::Contact::publishStateChanged	(	Tp::Contact::PresenceState	state,
		const QString &	message
	)			[signal]

Emitted when the value of publishState() changes.

Parameters:

state

The new publish state of this contact.

See also:

publishState()

void Tp::Contact::publishStateChanged	(	Tp::Contact::PresenceState	state,
		const Tp::Channel::GroupMemberChangeDetails &	details
	)			[signal]

Deprecated:

Use publishStateChanged(Tp::Contact::PresenceState state, const QString &message) instead.

void Tp::Contact::blockStatusChanged

(

bool

blocked

)

[signal]

Emitted when the value of isBlocked() changes.

Parameters:

status

The new block status of this contact.

See also:

isBlocked()

void Tp::Contact::blockStatusChanged	(	bool	blocked,
		const Tp::Channel::GroupMemberChangeDetails &	details
	)			[signal]

Deprecated:

Use blockStatusChanged(bool blocked) instead.

void Tp::Contact::addedToGroup

(

const QString &

group

)

[signal]

Emitted when this contact is added to group of the contact list.

Parameters:

group

The group name.

See also:

groups(), removedFromGroup()

void Tp::Contact::removedFromGroup

(

const QString &

group

)

[signal]

Emitted when this contact is removed from group of the contact list.

Parameters:

group

The group name.

See also:

groups(), addedToGroup()

void Tp::Contact::augment	(	const Features &	requestedFeatures,
		const QVariantMap &	attributes
	)			[protected, virtual]

void Tp::Contact::connectNotify

(

const char *

signalName

)

[protected]

---

Member Data Documentation

const Feature Tp::Contact::FeatureAlias [static]

Feature used in order to access contact alias info.

See alias specific methods' documentation for more details.

See also:

alias(), aliasChanged()

const Feature Tp::Contact::FeatureAvatarData [static]

Feature used in order to access contact avatar data info.

Enabling this feature will also enable FeatureAvatarToken.

See avatar data specific methods' documentation for more details.

See also:

avatarData(), avatarDataChanged()

const Feature Tp::Contact::FeatureAvatarToken [static]

Feature used in order to access contact avatar token info.

See avatar token specific methods' documentation for more details.

See also:

isAvatarTokenKnown(), avatarToken(), avatarTokenChanged()

const Feature Tp::Contact::FeatureCapabilities [static]

Feature used in order to access contact capabilities info.

See capabilities specific methods' documentation for more details.

See also:

capabilities(), capabilitiesChanged()

const Feature Tp::Contact::FeatureInfo [static]

Feature used in order to access contact info fields.

See info fields specific methods' documentation for more details.

See also:

infoFields(), infoFieldsChanged()

const Feature Tp::Contact::FeatureLocation [static]

Feature used in order to access contact location info.

See location specific methods' documentation for more details.

See also:

location(), locationUpdated()

const Feature Tp::Contact::FeatureSimplePresence [static]

Feature used in order to access contact presence info.

See presence specific methods' documentation for more details.

See also:

presence(), presenceChanged()