Tp::Connection Class Reference

| Home · All Classes · All Namespaces · Modules · Functions · Files

Classes | Signals | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | List of all members
Tp::Connection Class Reference
Connection proxies

The Connection class represents a Telepathy connection. More...

`#include <TelepathyQt/Connection>`

Inherits Tp::StatefulDBusProxy, and Tp::OptionalInterfaceFactory< Connection >.

## Classes
class | ErrorDetails
| The Connection::ErrorDetails class represents the details of a connection error. More...

## Signals
void | statusChanged (Tp::ConnectionStatus newStatus)
void | selfHandleChanged (uint newHandle)
void | selfContactChanged ()
void | accountBalanceChanged (const Tp::CurrencyAmount &accountBalance)
Signals inherited from Tp::DBusProxy
void | invalidated (Tp::DBusProxy *proxy, const QString &errorName, const QString &errorMessage)
Signals inherited from Tp::Object
void | propertyChanged (const QString &propertyName)

## Public Member Functions
virtual | ~Connection ()
ChannelFactoryConstPtr | channelFactory () const
ContactFactoryConstPtr | contactFactory () const
QString | cmName () const
QString | protocolName () const
ConnectionStatus | status () const
ConnectionStatusReason | statusReason () const
const ErrorDetails & | errorDetails () const
uint | selfHandle () const
ContactPtr | selfContact () const
CurrencyAmount | accountBalance () const
ConnectionCapabilities | capabilities () const
ContactManagerPtr | contactManager () const
Public Member Functions inherited from Tp::StatefulDBusProxy
| StatefulDBusProxy (const QDBusConnection &dbusConnection, const QString &busName, const QString &objectPath, const Feature &featureCore)
virtual | ~StatefulDBusProxy ()
Public Member Functions inherited from Tp::DBusProxy
| DBusProxy (const QDBusConnection &dbusConnection, const QString &busName, const QString &objectPath, const Feature &featureCore)
virtual | ~DBusProxy ()
QDBusConnection | dbusConnection () const
QString | busName () const
QString | objectPath () const
bool | isValid () const
QString | invalidationReason () const
QString | invalidationMessage () const
Public Member Functions inherited from Tp::Object
virtual | ~Object ()
Public Member Functions inherited from Tp::RefCounted
| RefCounted ()
virtual | ~RefCounted ()
Public Member Functions inherited from Tp::ReadyObject
| ReadyObject (RefCounted *object, const Feature &featureCore)
| ReadyObject (DBusProxy *proxy, const Feature &featureCore)
virtual | ~ReadyObject ()
virtual bool | isReady (const Features &features=Features()) const
virtual PendingReady * | becomeReady (const Features &requestedFeatures=Features())
virtual Features | requestedFeatures () const
virtual Features | actualFeatures () const
virtual Features | missingFeatures () const
Public Member Functions inherited from Tp::OptionalInterfaceFactory< Connection >
| OptionalInterfaceFactory (Connection *this_)
| ~OptionalInterfaceFactory ()
QStringList | interfaces () const
bool | hasInterface (const QString &name) const
Interface * | optionalInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
Interface * | interface () const

## Static Public Member Functions
static ConnectionPtr | create (const QString &busName, const QString &objectPath, const ChannelFactoryConstPtr &channelFactory, const ContactFactoryConstPtr &contactFactory)
static ConnectionPtr | create (const QDBusConnection &bus, const QString &busName, const QString &objectPath, const ChannelFactoryConstPtr &channelFactory, const ContactFactoryConstPtr &contactFactory)
Static Public Member Functions inherited from Tp::StatefulDBusProxy
static QString | uniqueNameFrom (const QDBusConnection &bus, const QString &wellKnownOrUnique)
static QString | uniqueNameFrom (const QDBusConnection &bus, const QString &wellKnownOrUnique, QString &error, QString &message)

## Static Public Attributes
static const Feature | FeatureCore
static const Feature | FeatureSelfContact
static const Feature | FeatureSimplePresence
static const Feature | FeatureRoster
static const Feature | FeatureRosterGroups
static const Feature | FeatureAccountBalance
static const Feature | FeatureConnected

## Protected Member Functions
| Connection (const QDBusConnection &bus, const QString &busName, const QString &objectPath, const ChannelFactoryConstPtr &channelFactory, const ContactFactoryConstPtr &contactFactory, const Feature &coreFeature)
Client::ConnectionInterface * | baseInterface () const
Protected Member Functions inherited from Tp::DBusProxy
void | setBusName (const QString &busName)
void | invalidate (const QString &reason, const QString &message)
void | invalidate (const QDBusError &error)
Protected Member Functions inherited from Tp::Object
| Object ()
void | notify (const char *propertyName)
Protected Member Functions inherited from Tp::ReadyObject
ReadinessHelper * | readinessHelper () const
Protected Member Functions inherited from Tp::OptionalInterfaceFactory< Connection >
void | setInterfaces (const QStringList &interfaces)

## Additional Inherited Members
Public Types inherited from Tp::OptionalInterfaceFactory< Connection >
enum | InterfaceSupportedChecking

## Detailed Description

The Connection class represents a Telepathy connection.

This models a connection to a single user account on a communication service.

Contacts, and server-stored lists (such as subscribed contacts, block lists, or allow lists) on a service are all represented using the ContactManager object on the connection, which is valid only for the lifetime of the connection object.

The remote object accessor functions on this object (status(), statusReason(), 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 connection self contact, it is necessary to enable the feature Connection::FeatureSelfContact. See the individual methods descriptions for more details.

Connection features can be enabled by constructing a ConnectionFactory 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 becomeReady() 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 statusChanged()(), selfContactChanged(), etc.

# Usage

## Creating a connection object

The easiest way to create connection objects is through Account. One can just use the Account::connection method to get an account active connection.

If you already know the object path, you can just call create(). For example:

ConnectionPtr conn = Connection::create(busName, objectPath);

A ConnectionPtr object is returned, which will automatically keep track of object lifetime.

You can also provide a D-Bus connection as a QDBusConnection:

*
* ConnectionPtr conn = Connection::create(QDBusConnection::sessionBus(),
* busName, objectPath);
*
*

## Making connection ready to use

A Connection object needs to become ready before usage, meaning that the introspection process finished and the object accessors can be used.

To make the object ready, use becomeReady() and wait for the PendingOperation::finished() signal to be emitted.

*
* class MyClass : public QObject
* {
* QOBJECT
*
* public:
* MyClass(QObject *parent = 0);
* ~MyClass() { }
*
* private Q_SLOTS:
* void onConnectionReady(Tp::PendingOperation*);
*
* private:
* ConnectionPtr conn;
* };
*
* MyClass::MyClass(const QString &busName, const QString &objectPath,
* QObject *parent)
* : QObject(parent)
* conn(Connection::create(busName, objectPath))
* {
* // connect and become ready
* connect(conn->requestConnect(),
* SIGNAL(finished(Tp::PendingOperation*)),
* SLOT(onConnectionReady(Tp::PendingOperation*)));
* }
*
* void MyClass::onConnectionReady(Tp::PendingOperation *op)
* {
* if (op->isError()) {
* qWarning() << "Account cannot become ready:" <<
* op->errorName() << "-" << op->errorMessage();
* return;
* }
*
* // Connection is now ready
* }
*
*

See Asynchronous Object Model, Shared Pointer Usage

## Constructor & Destructor Documentation

Tp::Connection::~Connection | ( |  | ) |
| virtual

Class destructor.

Tp::Connection::Connection | ( | const QDBusConnection & | bus,
|  | const QString & | busName,
|  | const QString & | objectPath,
|  | const ChannelFactoryConstPtr & | channelFactory,
|  | const ContactFactoryConstPtr & | contactFactory,
|  | const Feature & | coreFeature
| ) |  |
| protected

Construct a new connection object using the given bus.

A warning is printed if the factories are not for bus.

Parameters

  bus | QDBusConnection to use.
  busName | The connection's well-known bus name (sometimes called a "service name").
  objectPath | The connection object path.
  channelFactory | The channel factory to use.
  contactFactory | The contact factory to use.
  coreFeature | The core feature of the Connection subclass. The corresponding introspectable should depend on Connection::FeatureCore.

## Member Function Documentation

ConnectionPtr Tp::Connection::create | ( | const QString & | busName,
|  | const QString & | objectPath,
|  | const ChannelFactoryConstPtr & | channelFactory,
|  | const ContactFactoryConstPtr & | contactFactory
| ) |  |
| static

Create a new connection object using QDBusConnection::sessionBus().

A warning is printed if the factories are not for QDBusConnection::sessionBus().

Parameters

  busName | The connection well-known bus name (sometimes called a "service name").
  objectPath | The connection object path.
  channelFactory | The channel factory to use.
  contactFactory | The contact factory to use.

Returns
  A ConnectionPtr object pointing to the newly created Connection object.

ConnectionPtr Tp::Connection::create | ( | const QDBusConnection & | bus,
|  | const QString & | busName,
|  | const QString & | objectPath,
|  | const ChannelFactoryConstPtr & | channelFactory,
|  | const ContactFactoryConstPtr & | contactFactory
| ) |  |
| static

Create a new connection object using the given bus.

A warning is printed if the factories are not for bus.

Parameters

  bus | QDBusConnection to use.
  busName | The connection well-known bus name (sometimes called a "service name").
  objectPath | The connection object path.
  channelFactory | The channel factory to use.
  contactFactory | The contact factory to use.

Returns
  A ConnectionPtr object pointing to the newly created Connection object.

ChannelFactoryConstPtr Tp::Connection::channelFactory | ( |  | ) | const

Return the channel factory used by this connection.

Only read access is provided. This allows constructing object instances and examining the object construction settings, but not changing settings. Allowing changes would lead to tricky situations where objects constructed at different times by the account would have unpredictably different construction settings (eg. subclass).

Returns
  A read-only pointer to the ChannelFactory object.

ContactFactoryConstPtr Tp::Connection::contactFactory | ( |  | ) | const

Return the contact factory used by this connection.

Only read access is provided. This allows constructing object instances and examining the object construction settings, but not changing settings. Allowing changes would lead to tricky situations where objects constructed at different times by the account would have unpredictably different construction settings (eg. subclass).

Returns
  A read-only pointer to the ContactFactory object.

QString Tp::Connection::cmName | ( |  | ) | const

Return the connection manager name of this connection.

Returns
  The connection manager name.

QString Tp::Connection::protocolName | ( |  | ) | const

Return the protocol name of this connection.

Returns
  The protocol name.

ConnectionStatus Tp::Connection::status | ( |  | ) | const

Return the status of this connection.

Change notification is via the statusChanged() signal.

This method requires Connection::FeatureCore to be ready.

Returns
  The status as ConnectionStatus.

See Also
  statusChanged(), statusReason(), errorDetails()

ConnectionStatusReason Tp::Connection::statusReason | ( |  | ) | const

Return the reason for this connection status.

The validity and change rules are the same as for status().

The status reason should be only used as a fallback in error handling when the application doesn't understand an error name given as the invalidation reason, which may in some cases be domain/UI-specific.

This method requires Connection::FeatureCore to be ready.

Returns
  The status reason as ConnectionStatusReason.

See Also
  invalidated(), invalidationReason()

const Connection::ErrorDetails & Tp::Connection::errorDetails | ( |  | ) | const

Return detailed information about the reason for the connection going invalidated().

Some services may provide additional error information in the ConnectionError D-Bus signal, when a Connection is disconnected / has become unusable. If the service didn't provide any, or has not been invalidated yet, an invalid instance is returned.

The information provided by invalidationReason() and this method should always be used in error handling in preference to statusReason(). The status reason can be used as a fallback, however, if the client doesn't understand what a particular value returned by invalidationReason() means, as it may be domain-specific with some services.

Returns
  The error details as a Connection::ErrorDetails object.

See Also
  status(), statusReason(), invalidationReason()

uint Tp::Connection::selfHandle | ( |  | ) | const

Return the handle representing the user on this connection.

Note that if the connection is not yet in the ConnectionStatusConnected state, the value of this property may be zero.

Change notification is via the selfHandleChanged() signal.

This method requires Connection::FeatureCore to be ready.

Returns
  The user handle.

See Also
  selfHandleChanged(), selfContact()

ContactPtr Tp::Connection::selfContact | ( |  | ) | const

Return the object representing the user on this connection.

Note that if the connection is not yet in the ConnectionStatusConnected state, the value of this property may be null.

Change notification is via the selfContactChanged() signal.

This method requires Connection::FeatureSelfContact to be ready.

Returns
  A pointer to the Contact object, or a null ContactPtr if unknown.

See Also
  selfContactChanged(), selfHandle()

CurrencyAmount Tp::Connection::accountBalance | ( |  | ) | const

Return the user's balance on the account corresponding to this connection.

A negative amount may be possible on some services, and indicates that the user owes money to the service provider.

Change notification is via the accountBalanceChanged() signal.

This method requires Connection::FeatureAccountBalance to be ready.

Returns
  The account balance as #CurrencyAmount.

See Also
  accountBalanceChanged()

ConnectionCapabilities Tp::Connection::capabilities | ( |  | ) | const

Return the capabilities for this connection.

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

This property cannot change after the connection has gone to state ConnectionStatusConnected, so there is no change notification.

This method requires Connection::FeatureCore to be ready.

Returns
  The capabilities of this connection.

ContactManagerPtr Tp::Connection::contactManager | ( |  | ) | const

Return the ContactManager object for this connection.

The contact manager is responsible for all contact handling in this connection, including adding, removing, authorizing, etc.

Returns
  A pointer to the ContactManager object.

void Tp::Connection::statusChanged | ( | Tp::ConnectionStatus | newStatus | ) |
| signal

Indicates that the connection's status has changed and that all previously requested features are now ready to use for the new status.

Legitimate uses for this signal, apart from waiting for a given connection status to be ready, include updating an animation based on the connection being in ConnectionStatusConnecting, ConnectionStatusConnected and ConnectionStatusDisconnected, and otherwise showing progress indication to the user. It should, however, NEVER be used for error handling:

This signal doesn't contain the status reason as an argument, because statusChanged() shouldn't be used for error-handling. There are numerous cases in which a Connection may become unusable without there being a status change to ConnectionStatusDisconnected. All of these cases, and being disconnected itself, are signaled by invalidated() with appropriate error names. On the other hand, the reason for the status going to ConnectionStatusConnecting or ConnectionStatusConnected will always be ConnectionStatusReasonRequested, so signaling that would be useless.

The status reason, as returned by statusReason(), may however be used as a fallback for error handling in slots connected to the invalidated() signal, if the client doesn't understand a particular (likely domain-specific if so) error name given by invalidateReason().

Parameters

  newStatus | The new status of the connection, as would be returned by status().

void Tp::Connection::selfHandleChanged | ( | uint | newHandle | ) |
| signal

Emitted when the value of selfHandle() changes.

Parameters

  newHandle | The new connection self handle.

See Also
  selfHandle()

void Tp::Connection::selfContactChanged | ( |  | ) |
| signal

Emitted when the value of selfContact() changes.

See Also
  selfContact()

void Tp::Connection::accountBalanceChanged | ( | const Tp::CurrencyAmount & | accountBalance | ) |
| signal

Emitted when the value of accountBalance() changes.

Parameters

  accountBalance | The new user's balance of this connection.

See Also
  accountBalance()

Client::ConnectionInterface * Tp::Connection::baseInterface | ( |  | ) | const
| protected

Return the Client::ConnectionInterface interface proxy object for this connection. This method is protected since the convenience methods provided by this class should generally be used instead of calling D-Bus methods directly.

Returns
  A pointer to the existing Client::ConnectionInterface object for this Connection object.

## Member Data Documentation

const Feature Tp::Connection::FeatureCore
| static

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

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

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

const Feature Tp::Connection::FeatureSelfContact
| static

Feature used to retrieve the connection self contact.

See self contact specific methods' documentation for more details.

See Also
  selfContact(), selfContactChanged()

const Feature Tp::Connection::FeatureSimplePresence
| static

Feature used to retrieve/keep track of the connection self presence.

See simple presence specific methods' documentation for more details.

const Feature Tp::Connection::FeatureRoster
| static

Feature used to enable roster support on Connection::contactManager.

See ContactManager roster specific methods' documentation for more details.

See Also
  ContactManager::allKnownContacts()

const Feature Tp::Connection::FeatureRosterGroups
| static

Feature used to enable roster groups support on Connection::contactManager.

See ContactManager roster groups specific methods' documentation for more details.

See Also
  ContactManager::allKnownGroups()

const Feature Tp::Connection::FeatureAccountBalance
| static

Feature used to retrieve/keep track of the connection account balance.

See account balance specific methods' documentation for more details.

See Also
  accountBalance(), accountBalanceChanged()

const Feature Tp::Connection::FeatureConnected
| static

When this feature is prepared, it means that the connection status() is ConnectionStatusConnected.

Note that if ConnectionFactory is being used with FeatureConnected set, Connection objects will only be signalled by the library when the corresponding connection is in status() ConnectionStatusConnected.