#include <TelepathyQt4/Client/Connection>
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 |
PendingOperation * | setSelfPresence (const QString &status, const QString &statusMessage) |
QSharedPointer< Contact > | selfContact () const |
template<class Interface > | |
Interface * | optionalInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const |
ConnectionInterfaceAliasingInterface * | aliasingInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const |
ConnectionInterfaceAvatarsInterface * | avatarsInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const |
ConnectionInterfaceCapabilitiesInterface * | capabilitiesInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const |
ConnectionInterfacePresenceInterface * | presenceInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const |
ConnectionInterfaceSimplePresenceInterface * | simplePresenceInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const |
ConnectionInterfaceRequestsInterface * | requestsInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const |
DBus::PropertiesInterface * | propertiesInterface () const |
PendingChannel * | createChannel (const QVariantMap &request) |
PendingChannel * | ensureChannel (const QVariantMap &request) |
PendingOperation * | requestConnect (const QSet< uint > &requestedFeatures=QSet< uint >()) |
PendingOperation * | requestDisconnect () |
PendingHandles * | requestHandles (uint handleType, const QStringList &names) |
PendingHandles * | referenceHandles (uint handleType, const UIntList &handles) |
PendingContactAttributes * | getContactAttributes (const UIntList &handles, const QStringList &interfaces, bool reference=true) |
QStringList | contactAttributeInterfaces () const |
ContactManager * | contactManager () const |
bool | isReady (const QSet< uint > &features=QSet< uint >()) const |
PendingReady * | becomeReady (const QSet< uint > &requestedFeatures=QSet< uint >()) |
QSet< uint > | requestedFeatures () const |
QSet< uint > | actualFeatures () const |
QSet< uint > | missingFeatures () const |
Protected Member Functions | |
ConnectionInterface * | baseInterface () const |
Friends | |
struct | Private |
class | PendingChannel |
class | PendingConnect |
class | PendingContactAttributes |
class | PendingHandles |
class | ReferencedHandles |
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.
Telepathy::Client::Connection::Connection | ( | const QString & | serviceName, | |
const QString & | objectPath, | |||
QObject * | parent = 0 | |||
) |
Construct a new Connection object.
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.
bus | QDBusConnection to use. | |
serviceName | Connection service name. | |
objectPath | Connection object path. | |
parent | Object parent. |
Telepathy::Client::Connection::~Connection | ( | ) |
Class destructor.
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.
check | Passed to optionalInterface() |
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.
References FeatureSimplePresence, isReady(), and Telepathy::warning().
ConnectionInterfaceAvatarsInterface * Telepathy::Client::Connection::avatarsInterface | ( | InterfaceSupportedChecking | check = CheckInterfaceSupported |
) | const [inline] |
Convenience function for getting an Avatars interface proxy.
check | Passed to optionalInterface() |
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.
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.
requestedFeatures | The features which should be enabled |
ConnectionInterfaceCapabilitiesInterface * Telepathy::Client::Connection::capabilitiesInterface | ( | InterfaceSupportedChecking | check = CheckInterfaceSupported |
) | const [inline] |
Convenience function for getting a Capabilities interface proxy.
check | Passed to optionalInterface() |
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.
request | A dictionary containing the desirable properties. |
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.
request | A dictionary containing the desirable properties. |
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.
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. |
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.
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.
features | The features which should be tested |
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 |
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.
Interface | Class of the optional interface to get. |
check | Should an instance be returned even if it can't be determined that the remote object supports the requested interface. |
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.
check | Passed to optionalInterface() |
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.
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.
handleType | Type of the handles given, as specified in HandleType. | |
handles | Handles to request a reference to. |
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.
requestedFeatures | The features which should be enabled |
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.
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.
handleType | Type for the handles to request, as specified in HandleType. | |
names | Names of the entities to request handles for. |
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.
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).
status | The desired status. | |
statusMessage | The desired status message. |
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.
check | Passed to optionalInterface() |
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.
Referenced by contactAttributeInterfaces().
void Telepathy::Client::Connection::statusChanged | ( | uint | newStatus, | |
uint | newStatusReason | |||
) | [signal] |
uint Telepathy::Client::Connection::statusReason | ( | ) | const |
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] |
Reimplemented from Telepathy::Client::StatefulDBusProxy.
friend class ReferencedHandles [friend] |