Home · Modules · All Classes · All Namespaces
Classes | Public Types | Signals | Public Member Functions | Static Public Attributes | Protected Member Functions | List of all members
Tp::Contact Class Reference

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

#include <TelepathyQt/Contact>

Inherits Tp::Object.

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 publishStateChanged (Tp::Contact::PresenceState state, const QString &message)
 
void blockStatusChanged (bool blocked)
 
void addedToGroup (const QString &group)
 
void removedFromGroup (const QString &group)
 
void clientTypesChanged (const QStringList &clientTypes)
 
- Signals inherited from Tp::Object
void propertyChanged (const QString &propertyName)
 

Public Member Functions

 ~Contact ()
 
ContactManagerPtr manager () const
 
ReferencedHandles handle () const
 
QString id () const
 
Features requestedFeatures () const
 
Features actualFeatures () const
 
QString alias () const
 
QMap< QString, QString > vcardAddresses () const
 
QStringList uris () 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
 
PendingOperationrefreshInfo ()
 
PendingContactInforequestInfo ()
 
bool isSubscriptionStateKnown () const
 
bool isSubscriptionRejected () const
 
PresenceState subscriptionState () const
 
bool isPublishStateKnown () const
 
bool isPublishCancelled () const
 
PresenceState publishState () const
 
QString publishStateMessage () const
 
PendingOperationrequestPresenceSubscription (const QString &message=QString())
 
PendingOperationremovePresenceSubscription (const QString &message=QString())
 
PendingOperationauthorizePresencePublication (const QString &message=QString())
 
PendingOperationremovePresencePublication (const QString &message=QString())
 
bool isBlocked () const
 
PendingOperationblock ()
 
PendingOperationblockAndReportAbuse ()
 
PendingOperationunblock ()
 
QStringList groups () const
 
PendingOperationaddToGroup (const QString &group)
 
PendingOperationremoveFromGroup (const QString &group)
 
QStringList clientTypes () const
 
PendingStringListrequestClientTypes ()
 
- Public Member Functions inherited from Tp::Object
virtual ~Object ()
 
- Public Member Functions inherited from Tp::RefCounted
 RefCounted ()
 
virtual ~RefCounted ()
 

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
 
static const Feature FeatureAddresses
 
static const Feature FeatureClientTypes
 

Protected Member Functions

 Contact (ContactManager *manager, const ReferencedHandles &handle, const Features &requestedFeatures, const QVariantMap &attributes)
 
virtual void augment (const Features &requestedFeatures, const QVariantMap &attributes)
 
- Protected Member Functions inherited from Tp::Object
 Object ()
 
void notify (const char *propertyName)
 

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

◆ PresenceState

Enumerator
PresenceStateNo 
PresenceStateAsk 
PresenceStateYes 

Constructor & Destructor Documentation

◆ ~Contact()

Tp::Contact::~Contact ( )

Class destructor.

◆ Contact()

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

Construct a new Contact object.

Parameters
managerContactManager owning this contact.
handleThe contact handle.
requestedFeaturesThe contact requested features.
attributesThe contact attributes.

Member Function Documentation

◆ manager()

ContactManagerPtr Tp::Contact::manager ( ) const

Return the contact nanager owning this contact.

Returns
A pointer to the ContactManager object.

◆ handle()

ReferencedHandles Tp::Contact::handle ( ) const

Return the handle of this contact.

Returns
The handle as a ReferencedHandles object.

◆ id()

QString Tp::Contact::id ( ) const

Return the identifier of this contact.

Returns
The identifier.

◆ requestedFeatures()

Features Tp::Contact::requestedFeatures ( ) const

Return the features requested on this contact.

Returns
The requested features as a set of Feature objects.

◆ actualFeatures()

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.

◆ alias()

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.

◆ vcardAddresses()

QMap< QString, QString > Tp::Contact::vcardAddresses ( ) const

Return the various vcard addresses that identify this contact.

This method requires Contact::FeatureAddresses to be ready.

Returns
The vcard addresses identifying this contact.
See also
ContactManager::contactsForVCardAddresses(), uris()

◆ uris()

QStringList Tp::Contact::uris ( ) const

Return the various URI addresses that identify this contact.

This method requires Contact::FeatureAddresses to be ready.

Returns
The URI addresses identifying this contact.
See also
ContactManager::contactsForUris(), vcardAddresses()

◆ isAvatarTokenKnown()

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()

◆ 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()

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()

◆ requestAvatarData()

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()

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.

◆ capabilities()

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.

◆ location()

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.

◆ isContactInfoKnown()

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.

◆ infoFields()

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.

◆ refreshInfo()

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()

◆ requestInfo()

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.

◆ isSubscriptionStateKnown()

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()

◆ 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()

◆ 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()

◆ isPublishStateKnown()

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()

◆ 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()

◆ 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()

◆ publishStateMessage()

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()

◆ requestPresenceSubscription()

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()

◆ 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()

◆ authorizePresencePublication()

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()

◆ 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()

◆ isBlocked()

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()

◆ block()

PendingOperation * Tp::Contact::block ( )

Block this contact. 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.

Returns
A PendingOperation which will emit PendingOperation::finished when an attempt has been made to take the requested action.
See also
blockAndReportAbuse(), unblock()

◆ blockAndReportAbuse()

PendingOperation * Tp::Contact::blockAndReportAbuse ( )

Block this contact and additionally report abusive behaviour to the server.

If reporting abusive behaviour is not supported by the protocol, this method has the same effect as block().

This method requires Connection::FeatureRoster to be ready.

Returns
A PendingOperation which will emit PendingOperation::finished when an attempt has been made to take the requested action.
See also
ContactManager::canReportAbuse(), block(), unblock()

◆ unblock()

PendingOperation * Tp::Contact::unblock ( )

Unblock this contact.

This method requires Connection::FeatureRoster to be ready.

Returns
A PendingOperation which will emit PendingOperation::finished when an attempt has been made to take the requested action.
See also
block(), blockAndReportAbuse()

◆ groups()

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()

◆ addToGroup()

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
groupThe 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()

◆ 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
groupThe 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()

◆ clientTypes()

QStringList Tp::Contact::clientTypes ( ) const

Return the client types of this contact, if known.

Client types are represented using the values documented by the XMPP registrar, with some additional types. A contact can set one or more client types, or can simply advertise itself as unknown - in this case, an empty list is returned.

This method returns cached information and is more appropriate for "lazy" client type finding, for instance displaying the client types (if available) of everyone in your contact list. For getting latest up-to-date information from the server you should use requestClientTypes() instead.

This method requires FeatureClientTypes to be ready.

Returns
A list of the client types advertised by this contact.
See also
requestClientTypes(), clientTypesChanged()

◆ requestClientTypes()

PendingStringList * Tp::Contact::requestClientTypes ( )

Return the current client types of the given contact.

If necessary, this method will make a request to the server for up-to-date information and wait for a reply. Therefore, this method is more appropriate for use in a "Contact Information..." dialog; it can be used to show progress information (while waiting for the method to return), and can distinguish between various error conditions.

This method requires FeatureClientTypes to be ready.

Returns
A list of the client types advertised by this contact.
See also
clientTypes(), clientTypesChanged()

◆ aliasChanged

void Tp::Contact::aliasChanged ( const QString &  alias)
signal

Emitted when the value of alias() changes.

Parameters
aliasThe new alias of this contact.
See also
alias()

◆ avatarTokenChanged

void Tp::Contact::avatarTokenChanged ( const QString &  avatarToken)
signal

Emitted when the value of avatarToken() changes.

Parameters
avatarTokenThe new avatar token of this contact.
See also
avatarToken()

◆ avatarDataChanged

void Tp::Contact::avatarDataChanged ( const Tp::AvatarData avatarData)
signal

Emitted when the value of avatarData() changes.

Parameters
avatarDataThe new avatar of this contact.
See also
avatarData()

◆ presenceChanged

void Tp::Contact::presenceChanged ( const Tp::Presence presence)
signal

Emitted when the value of presence() changes.

Parameters
presenceThe new presence of this contact.
See also
presence()

◆ capabilitiesChanged

void Tp::Contact::capabilitiesChanged ( const Tp::ContactCapabilities caps)
signal

Emitted when the value of capabilities() changes.

Parameters
capsThe new capabilities of this contact.
See also
capabilities()

◆ locationUpdated

void Tp::Contact::locationUpdated ( const Tp::LocationInfo location)
signal

Emitted when the value of location() changes.

Parameters
locationThe new location of this contact.
See also
location()

◆ infoFieldsChanged

void Tp::Contact::infoFieldsChanged ( const Tp::Contact::InfoFields infoFields)
signal

Emitted when the value of infoFields() changes.

Parameters
infoFieldsThe new info of this contact.
See also
infoFields()

◆ subscriptionStateChanged

void Tp::Contact::subscriptionStateChanged ( Tp::Contact::PresenceState  state)
signal

Emitted when the value of subscriptionState() changes.

Parameters
stateThe new subscription state of this contact.
See also
subscriptionState()

◆ publishStateChanged

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

Emitted when the value of publishState() changes.

Parameters
stateThe new publish state of this contact.
messageThe new user-defined status message of this contact.
See also
publishState()

◆ blockStatusChanged

void Tp::Contact::blockStatusChanged ( bool  blocked)
signal

Emitted when the value of isBlocked() changes.

Parameters
blockedThe new block status of this contact.
See also
isBlocked()

◆ addedToGroup

void Tp::Contact::addedToGroup ( const QString &  group)
signal

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

Parameters
groupThe group name.
See also
groups(), removedFromGroup()

◆ removedFromGroup

void Tp::Contact::removedFromGroup ( const QString &  group)
signal

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

Parameters
groupThe group name.
See also
groups(), addedToGroup()

◆ clientTypesChanged

void Tp::Contact::clientTypesChanged ( const QStringList &  clientTypes)
signal

Emitted when the client types of this contact change or become known.

Parameters
clientTypesThe contact's client types
See also
clientTypes(), requestClientTypes()

◆ augment()

void Tp::Contact::augment ( const Features requestedFeatures,
const QVariantMap &  attributes 
)
protectedvirtual

Member Data Documentation

◆ FeatureAlias

const Feature Tp::Contact::FeatureAlias
static

Feature used in order to access contact alias info.

See also
alias(), aliasChanged()

◆ FeatureAvatarData

const Feature Tp::Contact::FeatureAvatarData
static

Feature used in order to access contact avatar data info.

Enabling this feature will also enable FeatureAvatarToken.

See also
avatarData(), avatarDataChanged()

◆ FeatureAvatarToken

const Feature Tp::Contact::FeatureAvatarToken
static

Feature used in order to access contact avatar token info.

See also
isAvatarTokenKnown(), avatarToken(), avatarTokenChanged()

◆ FeatureCapabilities

const Feature Tp::Contact::FeatureCapabilities
static

Feature used in order to access contact capabilities info.

See also
capabilities(), capabilitiesChanged()

◆ FeatureInfo

const Feature Tp::Contact::FeatureInfo
static

Feature used in order to access contact info fields.

See also
infoFields(), infoFieldsChanged()

◆ FeatureLocation

const Feature Tp::Contact::FeatureLocation
static

Feature used in order to access contact location info.

See also
location(), locationUpdated()

◆ FeatureSimplePresence

const Feature Tp::Contact::FeatureSimplePresence
static

Feature used in order to access contact presence info.

See also
presence(), presenceChanged()

◆ FeatureAddresses

const Feature Tp::Contact::FeatureAddresses
static

Feature used in order to access contact addressable addresses info.

See also
vcardAddresses(), uris()

◆ FeatureClientTypes

const Feature Tp::Contact::FeatureClientTypes
static

Feature used in order to access contact client types info.

See also
clientTypes(), requestClientTypes(), clientTypesChanged()