Telepathy::Client::Connection Class Reference
[Connection proxies]

#include <TelepathyQt4/Client/Connection>

Inheritance diagram for Telepathy::Client::Connection:

Inheritance graph
[legend]
Collaboration diagram for Telepathy::Client::Connection:

Collaboration graph
[legend]

List of all members.

Classes

class  PendingConnect

Public Types

enum  Feature {
  FeatureCore = 0, FeatureSelfContact = 1, FeatureSimplePresence = 2, FeatureRoster = 4,
  _Padding = 0xFFFFFFFF
}
enum  Status { StatusDisconnected = Telepathy::ConnectionStatusDisconnected, StatusConnecting = Telepathy::ConnectionStatusConnecting, StatusConnected = Telepathy::ConnectionStatusConnected, StatusUnknown = 0xFFFFFFFF }

Signals

void statusChanged (uint newStatus, uint newStatusReason)
void selfHandleChanged (uint newHandle)
void selfContactChanged ()

Public Member Functions

 Connection (const QString &serviceName, const QString &objectPath, QObject *parent=0)
 Connection (const QDBusConnection &bus, const QString &serviceName, const QString &objectPath, QObject *parent=0)
 ~Connection ()
uint status () const
uint statusReason () const
QStringList interfaces () const
uint selfHandle () const
SimpleStatusSpecMap allowedPresenceStatuses () const
PendingOperationsetSelfPresence (const QString &status, const QString &statusMessage)
QSharedPointer< ContactselfContact () const
template<class Interface >
Interface * optionalInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
ConnectionInterfaceAliasingInterfacealiasingInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
ConnectionInterfaceAvatarsInterfaceavatarsInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
ConnectionInterfaceCapabilitiesInterfacecapabilitiesInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
ConnectionInterfacePresenceInterfacepresenceInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
ConnectionInterfaceSimplePresenceInterfacesimplePresenceInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
ConnectionInterfaceRequestsInterfacerequestsInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
DBus::PropertiesInterfacepropertiesInterface () const
PendingChannelcreateChannel (const QVariantMap &request)
PendingChannelensureChannel (const QVariantMap &request)
PendingOperationrequestConnect (const QSet< uint > &requestedFeatures=QSet< uint >())
PendingOperationrequestDisconnect ()
PendingHandlesrequestHandles (uint handleType, const QStringList &names)
PendingHandlesreferenceHandles (uint handleType, const UIntList &handles)
PendingContactAttributesgetContactAttributes (const UIntList &handles, const QStringList &interfaces, bool reference=true)
QStringList contactAttributeInterfaces () const
ContactManagercontactManager () const
bool isReady (const QSet< uint > &features=QSet< uint >()) const
PendingReadybecomeReady (const QSet< uint > &requestedFeatures=QSet< uint >())
QSet< uint > requestedFeatures () const
QSet< uint > actualFeatures () const
QSet< uint > missingFeatures () const

Protected Member Functions

ConnectionInterfacebaseInterface () const

Friends

struct Private
class PendingChannel
class PendingConnect
class PendingContactAttributes
class PendingHandles
class ReferencedHandles


Detailed Description

Object representing a Telepathy connection.

It adds the following features compared to using ConnectionInterface directly:

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

Enumerator:
FeatureCore 
FeatureSelfContact 
FeatureSimplePresence 
FeatureRoster 
_Padding 

Enumerator:
StatusDisconnected 
StatusConnecting 
StatusConnected 
StatusUnknown 


Constructor & Destructor Documentation

Telepathy::Client::Connection::Connection ( const QString &  serviceName,
const QString &  objectPath,
QObject *  parent = 0 
)

Construct a new Connection object.

Parameters:
serviceName Connection service name.
objectPath Connection object path.
parent Object parent.

Telepathy::Client::Connection::Connection ( const QDBusConnection &  bus,
const QString &  serviceName,
const QString &  objectPath,
QObject *  parent = 0 
)

Construct a new Connection object.

Parameters:
bus QDBusConnection to use.
serviceName Connection service name.
objectPath Connection object path.
parent Object parent.

Telepathy::Client::Connection::~Connection (  ) 

Class destructor.


Member Function Documentation

QSet< uint > Telepathy::Client::Connection::actualFeatures (  )  const

ConnectionInterfaceAliasingInterface * Telepathy::Client::Connection::aliasingInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

Convenience function for getting an Aliasing interface proxy.

Parameters:
check Passed to optionalInterface()
Returns:
optionalInterface<ConnectionInterfaceAliasingInterface>(check)

SimpleStatusSpecMap Telepathy::Client::Connection::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.

References FeatureSimplePresence, isReady(), and Telepathy::warning().

ConnectionInterfaceAvatarsInterface * Telepathy::Client::Connection::avatarsInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

Convenience function for getting an Avatars interface proxy.

Parameters:
check Passed to optionalInterface()
Returns:
optionalInterface<ConnectionInterfaceAvatarsInterface>(check)

ConnectionInterface * Telepathy::Client::Connection::baseInterface (  )  const [protected]

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.

Referenced by Telepathy::Client::Connection::Connection::PendingConnect::PendingConnect(), and requestDisconnect().

PendingReady * Telepathy::Client::Connection::becomeReady ( const QSet< uint > &  requestedFeatures = QSet<uint>()  ) 

Return a pending operation which will succeed when this object finishes its initial setup, or will fail if a fatal error occurs during this initial setup.

If an empty set is used FeatureCore will be considered as the requested feature.

Parameters:
requestedFeatures The features which should be enabled
Returns:
A PendingReady object which will emit finished when this object has finished or failed initial setup for basic functionality plus the given features

ConnectionInterfaceCapabilitiesInterface * Telepathy::Client::Connection::capabilitiesInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

Convenience function for getting a Capabilities interface proxy.

Parameters:
check Passed to optionalInterface()
Returns:
optionalInterface<ConnectionInterfaceCapabilitiesInterface>(check)

QStringList Telepathy::Client::Connection::contactAttributeInterfaces (  )  const

ContactManager * Telepathy::Client::Connection::contactManager (  )  const

PendingChannel * Telepathy::Client::Connection::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.

References Telepathy::debug(), PendingChannel, StatusConnected, TELEPATHY_ERROR_INVALID_ARGUMENT, TELEPATHY_ERROR_NOT_AVAILABLE, TELEPATHY_ERROR_NOT_IMPLEMENTED, TELEPATHY_INTERFACE_CHANNEL, TELEPATHY_INTERFACE_CONNECTION_INTERFACE_REQUESTS, and Telepathy::warning().

PendingChannel * Telepathy::Client::Connection::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.

References Telepathy::debug(), PendingChannel, StatusConnected, TELEPATHY_ERROR_INVALID_ARGUMENT, TELEPATHY_ERROR_NOT_AVAILABLE, TELEPATHY_ERROR_NOT_IMPLEMENTED, TELEPATHY_INTERFACE_CHANNEL, TELEPATHY_INTERFACE_CONNECTION_INTERFACE_REQUESTS, and Telepathy::warning().

PendingContactAttributes * Telepathy::Client::Connection::getContactAttributes ( 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.

References Telepathy::debug(), Telepathy::Client::PendingContactAttributes::failImmediately(), Telepathy::Client::ConnectionInterfaceContactsInterface::GetContactAttributes(), Telepathy::HandleTypeContact, interfaces(), isReady(), PendingContactAttributes, TELEPATHY_ERROR_NOT_AVAILABLE, TELEPATHY_ERROR_NOT_IMPLEMENTED, TELEPATHY_INTERFACE_CONNECTION_INTERFACE_CONTACTS, and Telepathy::warning().

QStringList Telepathy::Client::Connection::interfaces (  )  const

Return a list of optional interfaces supported by this object. The contents of the list is undefined unless the Connection has status StatusConnecting or StatusConnected. The returned value stays constant for the entire time the connection spends in each of these states; however interfaces might have been added to the supported set by the time StatusConnected is reached.

Returns:
Names of the supported interfaces.

References isReady(), and Telepathy::warning().

Referenced by contactAttributeInterfaces(), getContactAttributes(), Telepathy::Client::ContactManager::isSupported(), and optionalInterface().

bool Telepathy::Client::Connection::isReady ( const QSet< uint > &  features = QSet<uint>()  )  const

Return whether this object has finished its initial setup.

This is mostly useful as a sanity check, in code that shouldn't be run until the object is ready. To wait for the object to be ready, call becomeReady() and connect to the finished signal on the result.

Parameters:
features The features which should be tested
Returns:
true if the object has finished its initial setup for basic functionality plus the given features

Referenced by allowedPresenceStatuses(), getContactAttributes(), interfaces(), and selfContact().

QSet< uint > Telepathy::Client::Connection::missingFeatures (  )  const

template<class Interface >
Telepathy::Client::Connection::optionalInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

Get a pointer to a valid instance of a given Connection optional interface class, associated with the same remote object the Connection is associated with, and destroyed at the same time the Connection is destroyed.

If the list returned by interfaces() doesn't contain the name of the interface requested 0 is returned. This check can be bypassed by specifying BypassInterfaceCheck for check, in which case a valid instance is always returned.

If the object is not ready, the list returned by interfaces() isn't guaranteed to yet represent the full set of interfaces supported by the remote object. Hence the check might fail even if the remote object actually supports the requested interface; using BypassInterfaceCheck is suggested when the Connection is not suitably ready.

See also:
OptionalInterfaceFactory::interface
Template Parameters:
Interface Class of the optional interface to get.
Parameters:
check Should an instance be returned even if it can't be determined that the remote object supports the requested interface.
Returns:
Pointer to an instance of the interface class, or 0.

References Telepathy::Client::DBusProxy::CheckInterfaceSupported, and interfaces().

ConnectionInterfacePresenceInterface * Telepathy::Client::Connection::presenceInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

Convenience function for getting a Presence interface proxy.

Parameters:
check Passed to optionalInterface()
Returns:
optionalInterface<ConnectionInterfacePresenceInterface>(check)

DBus::PropertiesInterface * Telepathy::Client::Connection::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)

References Telepathy::Client::DBusProxy::BypassInterfaceCheck.

PendingHandles * Telepathy::Client::Connection::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.

References Telepathy::debug(), and PendingHandles.

PendingOperation * Telepathy::Client::Connection::requestConnect ( const QSet< uint > &  requestedFeatures = QSet<uint>()  ) 

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

References PendingConnect.

PendingOperation * Telepathy::Client::Connection::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.

References baseInterface().

QSet< uint > Telepathy::Client::Connection::requestedFeatures (  )  const

PendingHandles * Telepathy::Client::Connection::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.

References Telepathy::debug(), and PendingHandles.

ConnectionInterfaceRequestsInterface* Telepathy::Client::Connection::requestsInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

QSharedPointer< Contact > Telepathy::Client::Connection::selfContact (  )  const

References isReady(), and Telepathy::warning().

void Telepathy::Client::Connection::selfContactChanged (  )  [signal]

uint Telepathy::Client::Connection::selfHandle (  )  const

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.

void Telepathy::Client::Connection::selfHandleChanged ( uint  newHandle  )  [signal]

PendingOperation * Telepathy::Client::Connection::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()

References simplePresenceInterface(), TELEPATHY_ERROR_NOT_IMPLEMENTED, and TELEPATHY_INTERFACE_CONNECTION_INTERFACE_SIMPLE_PRESENCE.

ConnectionInterfaceSimplePresenceInterface * Telepathy::Client::Connection::simplePresenceInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

Convenience function for getting a SimplePresence interface proxy.

Parameters:
check Passed to optionalInterface()
Returns:
optionalInterface<ConnectionInterfaceSimplePresenceInterface>(check)

Referenced by setSelfPresence().

uint Telepathy::Client::Connection::status (  )  const

Return the connection's status.

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

Returns:
The status, as defined in Status.

Referenced by contactAttributeInterfaces().

void Telepathy::Client::Connection::statusChanged ( uint  newStatus,
uint  newStatusReason 
) [signal]

uint Telepathy::Client::Connection::statusReason (  )  const

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 Status.


Friends And Related Function Documentation

friend class PendingChannel [friend]

Referenced by createChannel(), and ensureChannel().

friend class PendingConnect [friend]

Referenced by requestConnect().

friend class PendingContactAttributes [friend]

Referenced by getContactAttributes().

friend class PendingHandles [friend]

Referenced by referenceHandles(), and requestHandles().

friend struct Private [friend]

friend class ReferencedHandles [friend]


Generated on Thu Mar 5 18:52:06 2009 for TelepathyQt4-0.1.1 by  doxygen 1.5.8