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.