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

# Connection Class Reference
[Connection proxies]

`#include <TelepathyQt4/Connection>`

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

List of all members.

## Public Types

- enum Status { StatusDisconnected, StatusConnecting, StatusConnected, StatusUnknown }

## Signals

- void statusChanged (Tp::Connection::Status newStatus, Tp::ConnectionStatusReason newStatusReason)
- void selfHandleChanged (uint newHandle)
- void selfContactChanged ()

## Public Member Functions

- PendingConnect (Connection *parent, const Features &requestedFeatures)
- Private (Connection *parent)
- ~Private ()
- void init ()
- void introspectCapabilities ()
- void introspectSelfHandle ()
- void introspectContacts ()
- void checkFeatureRosterGroupsReady ()
- HandleContext ()
- virtual ~Connection ()
- Status status () const
- ConnectionStatusReason statusReason () const
- uint selfHandle () const
- ContactPtr selfContact () const
- SimpleStatusSpecMap allowedPresenceStatuses () const
- PendingOperation * setSelfPresence (const QString &status, const QString &statusMessage)
- ConnectionCapabilities * capabilities () const
- PendingChannel * createChannel (const QVariantMap &request)
- PendingChannel * ensureChannel (const QVariantMap &request)
- PendingReady * requestConnect (const Features &requestedFeatures=Features())
- PendingOperation * requestDisconnect ()
- PendingHandles * requestHandles (uint handleType, const QStringList &names)
- PendingHandles * referenceHandles (uint handleType, const UIntList &handles)
- PendingContactAttributes * contactAttributes (const UIntList &handles, const QStringList &interfaces, bool reference=true)
- QStringList contactAttributeInterfaces () const
- ContactManager * contactManager () const
- Client::DBus::PropertiesInterface * propertiesInterface () const
- Client::ConnectionInterfaceAliasingInterface * aliasingInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- Client::ConnectionInterfaceAvatarsInterface * avatarsInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- Client::ConnectionInterfaceCapabilitiesInterface * capabilitiesInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- Client::ConnectionInterfaceContactCapabilitiesInterface * contactCapabilitiesInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- Client::ConnectionInterfacePresenceInterface * presenceInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- Client::ConnectionInterfaceSimplePresenceInterface * simplePresenceInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- Client::ConnectionInterfaceRequestsInterface * requestsInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const

## Static Public Member Functions

- static void introspectMain (Private *self)
- static void introspectSelfContact (Private *self)
- static void introspectSimplePresence (Private *self)
- static void introspectRoster (Private *self)
- static void introspectRosterGroups (Private *self)
- static ConnectionPtr create (const QString &busName, const QString &objectPath)
- static ConnectionPtr create (const QDBusConnection &bus, const QString &busName, const QString &objectPath)

## Public Attributes

- Connection * parent
- Client::ConnectionInterface * baseInterface
- Client::DBus::PropertiesInterface * properties
- Client::ConnectionInterfaceSimplePresenceInterface * simplePresence
- ReadinessHelper * readinessHelper
- uint pendingStatus
- uint pendingStatusReason
- uint status
- uint statusReason
- SimpleStatusSpecMap simplePresenceStatuses
- ContactPtr selfContact
- QStringList contactAttributeInterfaces
- uint selfHandle
- ConnectionCapabilities * caps
- QMap< uint,
  ContactManager::ContactListChannel > contactListChannels
- uint contactListChannelsReady
- QList< ChannelPtr > contactListGroupChannels
- uint featureRosterGroupsTodo
- HandleContext * handleContext
- ContactManager * contactManager
- int refcount
- QMutex lock
- QMap< uint, Type > types

## Static Public Attributes

- static QMap< QPair< QString,
  QString >, HandleContext * > handleContexts
- static QMutex handleContextsLock
- static const Feature FeatureCore
- static const Feature FeatureSelfContact
- static const Feature FeatureSimplePresence
- static const Feature FeatureRoster
- static const Feature FeatureRosterGroups

## Protected Member Functions

- Connection (const QString &busName, const QString &objectPath)
- Connection (const QDBusConnection &bus, const QString &busName, const QString &objectPath)
- Client::ConnectionInterface * baseInterface () const

## Detailed Description

Object representing a Telepathy connection.

It adds the following features compared to using ConnectionInterface directly:

- Connection status tracking
- Getting the list of supported interfaces automatically
- Getting the valid presence statuses automatically
- Shared optional interface proxy instances

The remote object state accessor functions on this object (status(), statusReason(), and so on) don't make any DBus calls; instead, they return 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. Their return value is mostly undefined until the introspection process is completed; a status change to StatusConnected indicates that the introspection process is finished. See the individual accessor descriptions for details on which functions can be used in the different states.

## Member Enumeration Documentation

enum Status

Enumerator:

  StatusDisconnected |
  StatusConnecting |
  StatusConnected |
  StatusUnknown |

## Constructor & Destructor Documentation

~Private | ( |  | ) |

~Connection | ( |  | ) | `[virtual]`

Class destructor.

Connection | ( | const QString & | busName,
|  | const QString & | objectPath |
| ) |  |  | `[protected]`

Construct a new Connection object.

Parameters:

  | busName | The connection's well-known or unique bus name (sometimes called a "service name")
  | objectPath | The connection's object path

Connection | ( | const QDBusConnection & | bus,
|  | const QString & | busName,
|  | const QString & | objectPath |
| ) |  |  | `[protected]`

Construct a new Connection object.

Parameters:

  | bus | QDBusConnection to use
  | busName | The connection's well-known or unique bus name (sometimes called a "service name")
  | objectPath | The connection's object path

## Member Function Documentation

PendingConnect | ( | Connection * | parent,
|  | const Features & | requestedFeatures |
| ) |  |  |

Private | ( | Connection * | parent | ) |

void init | ( |  | ) |

static void introspectMain | ( | Private * | self | ) | `[static]`

void introspectCapabilities | ( |  | ) |

void introspectSelfHandle | ( |  | ) |

void introspectContacts | ( |  | ) |

static void introspectSelfContact | ( | Private * | self | ) | `[static]`

static void introspectSimplePresence | ( | Private * | self | ) | `[static]`

static void introspectRoster | ( | Private * | self | ) | `[static]`

static void introspectRosterGroups | ( | Private * | self | ) | `[static]`

void checkFeatureRosterGroupsReady | ( |  | ) |

HandleContext | ( |  | ) | `[inline]`

ConnectionPtr create | ( | const QString & | busName,
|  | const QString & | objectPath |
| ) |  |  | `[static]`

ConnectionPtr create | ( | const QDBusConnection & | bus,
|  | const QString & | busName,
|  | const QString & | objectPath |
| ) |  |  | `[static]`

Status status | ( |  | ) | const

ConnectionStatusReason statusReason | ( |  | ) | const

uint selfHandle | ( |  | ) | const

ContactPtr selfContact | ( |  | ) | const

SimpleStatusSpecMap allowedPresenceStatuses | ( |  | ) | const

Return a dictionary of presence statuses valid for use with the new(er) Telepathy SimplePresence interface on the remote object.

The value is undefined if the list returned by interfaces() doesn't contain TELEPATHY_INTERFACE_CONNECTION_INTERFACE_SIMPLE_PRESENCE.

The value may have changed arbitrarily during the time the Connection spends in status StatusConnecting, again staying fixed for the entire time in StatusConnected.

Returns:
  Dictionary from string identifiers to structs for each valid status.

PendingOperation * setSelfPresence | ( | const QString & | status,
|  | const QString & | statusMessage |
| ) |  |  |

Set the self presence status.

status must be one of the allowed statuses returned by allowedPresenceStatuses().

Note that clients SHOULD set the status message for the local user to the empty string, unless the user has actually provided a specific message (i.e. one that conveys more information than the Status).

Parameters:

  | status | The desired status.
  | statusMessage | The desired status message.

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

See also:
  allowedPresenceStatuses()

ConnectionCapabilities * capabilities | ( |  | ) | const

Return the capabilities that are expected to be available on this connection, i.e. those for which createChannel() can reasonably be expected to succeed. User interfaces can use this information to show or hide UI components.

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

This method requires Connection::FeatureCore to be enabled.

Returns:
  An object representing the connection capabilities or 0 if FeatureCore is not ready.

PendingChannel * createChannel | ( | const QVariantMap & | request | ) |

Asynchronously creates a channel satisfying the given request.

The request MUST contain the following keys: org.freedesktop.Telepathy.Account.ChannelType org.freedesktop.Telepathy.Account.TargetHandleType

Upon completion, the reply to the request can be retrieved through the returned PendingChannel object. The object also provides access to the parameters with which the call was made and a signal to connect to get notification of the request finishing processing. See the documentation for that class for more info.

The returned PendingChannel object should be freed using its QObject::deleteLater() method after it is no longer used. However, all PendingChannel objects resulting from requests to a particular Connection will be freed when the Connection itself is freed. Conversely, this means that the PendingChannel object should not be used after the Connection is destroyed.

See also:
  PendingChannel

Parameters:

  | request | A dictionary containing the desirable properties.

Returns:
  Pointer to a newly constructed PendingChannel object, tracking the progress of the request.

PendingChannel * ensureChannel | ( | const QVariantMap & | request | ) |

Asynchronously ensures a channel exists satisfying the given request.

The request MUST contain the following keys: org.freedesktop.Telepathy.Account.ChannelType org.freedesktop.Telepathy.Account.TargetHandleType

Upon completion, the reply to the request can be retrieved through the returned PendingChannel object. The object also provides access to the parameters with which the call was made and a signal to connect to get notification of the request finishing processing. See the documentation for that class for more info.

The returned PendingChannel object should be freed using its QObject::deleteLater() method after it is no longer used. However, all PendingChannel objects resulting from requests to a particular Connection will be freed when the Connection itself is freed. Conversely, this means that the PendingChannel object should not be used after the Connection is destroyed.

See also:
  PendingChannel

Parameters:

  | request | A dictionary containing the desirable properties.

Returns:
  Pointer to a newly constructed PendingChannel object, tracking the progress of the request.

PendingReady * requestConnect | ( | const Features & | requestedFeatures = `Features()` | ) |

Start an asynchronous request that the connection be connected.

The returned PendingOperation will finish successfully when the connection has reached StatusConnected and the requested features are all ready, or finish with an error if a fatal error occurs during that process.

Parameters:

  | requestedFeatures | The features which should be enabled

Returns:
  A PendingReady object which will emit finished when the Connection has reached StatusConnected, and initial setup for basic functionality, plus the given features, has succeeded or failed

PendingOperation * requestDisconnect | ( |  | ) |

Start an asynchronous request that the connection be disconnected. The returned PendingOperation object will signal the success or failure of this request; under normal circumstances, it can be expected to succeed.

Returns:
  A PendingOperation, which will emit finished when the request finishes.

PendingHandles * requestHandles | ( | uint | handleType,
|  | const QStringList & | names |
| ) |  |  |

Request handles of the given type for the given entities (contacts, rooms, lists, etc.).

Upon completion, the reply to the request can be retrieved through the returned PendingHandles object. The object also provides access to the parameters with which the call was made and a signal to connect to to get notification of the request finishing processing. See the documentation for that class for more info.

The returned PendingHandles object should be freed using its QObject::deleteLater() method after it is no longer used. However, all PendingHandles objects resulting from requests to a particular Connection will be freed when the Connection itself is freed. Conversely, this means that the PendingHandles object should not be used after the Connection is destroyed.

See also:
  PendingHandles

Parameters:

  | handleType | Type for the handles to request, as specified in HandleType.
  | names | Names of the entities to request handles for.

Returns:
  Pointer to a newly constructed PendingHandles object, tracking the progress of the request.

PendingHandles * referenceHandles | ( | uint | handleType,
|  | const UIntList & | handles |
| ) |  |  |

Request a reference to the given handles. Handles not explicitly requested (via requestHandles()) but eg. observed in a signal need to be referenced to guarantee them staying valid.

Upon completion, the reply to the operation can be retrieved through the returned PendingHandles object. The object also provides access to the parameters with which the call was made and a signal to connect to to get notification of the request finishing processing. See the documentation for that class for more info.

The returned PendingHandles object should be freed using its QObject::deleteLater() method after it is no longer used. However, all PendingHandles objects resulting from requests to a particular Connection will be freed when the Connection itself is freed. Conversely, this means that the PendingHandles object should not be used after the Connection is destroyed.

See also:
  PendingHandles

Parameters:

  | handleType | Type of the handles given, as specified in HandleType.
  | handles | Handles to request a reference to.

Returns:
  Pointer to a newly constructed PendingHandles object, tracking the progress of the request.

PendingContactAttributes * contactAttributes | ( | const UIntList & | handles,
|  | const QStringList & | interfaces,
|  | bool | reference = `true` |
| ) |  |  |

Requests attributes for contacts. Optionally, the handles of the contacts will be referenced automatically. Essentially, this method wraps ConnectionInterfaceContactsInterface::GetContactAttributes(), integrating it with the rest of the handle-referencing machinery.

Upon completion, the reply to the request can be retrieved through the returned PendingContactAttributes object. The object also provides access to the parameters with which the call was made and a signal to connect to to get notification of the request finishing processing. See the documentation for that class for more info.

If the remote object doesn't support the Contacts interface (as signified by the list returned by interfaces() not containing TELEPATHY_INTERFACE_CONNECTION_INTERFACE_CONTACTS), the returned PendingContactAttributes instance will fail instantly with the error TELEPATHY_ERROR_NOT_IMPLEMENTED.

Similarly, if the connection isn't both connected and ready (`status() == StatusConnected && isReady()`), the returned PendingContactAttributes instance will fail instantly with the error TELEPATHY_ERROR_NOT_AVAILABLE.

See also:
  PendingContactAttributes

Parameters:

  | handles | A list of handles of type HandleTypeContact
  | interfaces | D-Bus interfaces for which the client requires information
  | reference | Whether the handles should additionally be referenced.

Returns:
  Pointer to a newly constructed PendingContactAttributes, tracking the progress of the request.

QStringList contactAttributeInterfaces | ( |  | ) | const

ContactManager* contactManager | ( |  | ) | const

DBus::PropertiesInterface * propertiesInterface | ( |  | ) | const`[inline]`

Convenience function for getting a Properties interface proxy. The Properties interface is not necessarily reported by the services, so a `check` parameter is not provided, and the interface is always assumed to be present.

See also:
  optionalInterface()

Returns:
  `optionalInterface<DBus::PropertiesInterface>(BypassInterfaceCheck)`

ConnectionInterfaceAliasingInterface * aliasingInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

Convenience function for getting an Aliasing interface proxy.

Parameters:

  | check | Passed to optionalInterface()

Returns:
  `optionalInterface<ConnectionInterfaceAliasingInterface>(check)`

ConnectionInterfaceAvatarsInterface * avatarsInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

Convenience function for getting an Avatars interface proxy.

Parameters:

  | check | Passed to optionalInterface()

Returns:
  `optionalInterface<ConnectionInterfaceAvatarsInterface>(check)`

ConnectionInterfaceCapabilitiesInterface * capabilitiesInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

Convenience function for getting a Capabilities interface proxy.

Parameters:

  | check | Passed to optionalInterface()

Returns:
  `optionalInterface<ConnectionInterfaceCapabilitiesInterface>(check)`

Client::ConnectionInterfaceContactCapabilitiesInterface* contactCapabilitiesInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

ConnectionInterfacePresenceInterface * presenceInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

Convenience function for getting a Presence interface proxy.

Parameters:

  | check | Passed to optionalInterface()

Returns:
  `optionalInterface<ConnectionInterfacePresenceInterface>(check)`

ConnectionInterfaceSimplePresenceInterface * simplePresenceInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

Convenience function for getting a SimplePresence interface proxy.

Parameters:

  | check | Passed to optionalInterface()

Returns:
  `optionalInterface<ConnectionInterfaceSimplePresenceInterface>(check)`

Client::ConnectionInterfaceRequestsInterface* requestsInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

void statusChanged | ( | Tp::Connection::Status | newStatus,
|  | Tp::ConnectionStatusReason | newStatusReason |
| ) |  |  | `[signal]`

void selfHandleChanged | ( | uint | newHandle | ) | `[signal]`

void selfContactChanged | ( |  | ) | `[signal]`

Client::ConnectionInterface* baseInterface | ( |  | ) | const`[protected]`

## Member Data Documentation

Connection* parent

Client::ConnectionInterface * baseInterface

Get the ConnectionInterface 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 ConnectionInterface for this Connection.

Client::DBus::PropertiesInterface* properties

Client::ConnectionInterfaceSimplePresenceInterface* simplePresence

ReadinessHelper* readinessHelper

uint pendingStatus

uint pendingStatusReason

Connection::Status status

Return the connection's status.

The returned value may have changed whenever statusChanged() is emitted.

Returns:
  The status, as defined in Connection::Status.

ConnectionStatusReason statusReason

Return the reason for the connection's status (which is returned by status()). The validity and change rules are the same as for status().

Returns:
  The reason, as defined in ConnectionStatusReason.

SimpleStatusSpecMap simplePresenceStatuses

ContactPtr selfContact

QStringList contactAttributeInterfaces

uint selfHandle

Return the handle which represents the user on this connection, which will remain valid for the lifetime of this connection, or until a change in the user's identifier is signalled by the selfHandleChanged signal. If the connection is not yet in the StatusConnected state, the value of this property MAY be zero.

Returns:
  Self handle.

ConnectionCapabilities* caps

QMap<uint, ContactManager::ContactListChannel> contactListChannels

uint contactListChannelsReady

QList<ChannelPtr> contactListGroupChannels

uint featureRosterGroupsTodo

QMap<QPair<QString, QString>, HandleContext *> handleContexts `[static]`

QMutex handleContextsLock `[static]`

HandleContext* handleContext

ContactManager * contactManager

int refcount

QMutex lock

QMap<uint, Type> types

const Feature FeatureCore `[static]`

const Feature FeatureSelfContact `[static]`

const Feature FeatureSimplePresence `[static]`

const Feature FeatureRoster `[static]`

const Feature FeatureRosterGroups `[static]`