Home · Modules · All Classes · All Namespaces
Public Member Functions | List of all members
Tp::ConnectionLowlevel Class Reference

The ConnectionLowlevel class extends Connection with support to low-level features. More...

#include <TelepathyQt/ConnectionLowlevel>

Inherits QObject, and Tp::RefCounted.

Public Member Functions

 ~ConnectionLowlevel ()
 
bool isValid () const
 
ConnectionPtr connection () const
 
PendingReadyrequestConnect (const Features &requestedFeatures=Features())
 
PendingOperationrequestDisconnect ()
 
SimpleStatusSpecMap allowedPresenceStatuses () const
 
uint maxPresenceStatusMessageLength () const
 
PendingOperationsetSelfPresence (const QString &status, const QString &statusMessage)
 
PendingChannelcreateChannel (const QVariantMap &request)
 
PendingChannelcreateChannel (const QVariantMap &request, int timeout)
 
PendingChannelensureChannel (const QVariantMap &request)
 
PendingChannelensureChannel (const QVariantMap &request, int timeout)
 
PendingHandlesrequestHandles (HandleType handleType, const QStringList &names)
 
PendingHandlesreferenceHandles (HandleType handleType, const UIntList &handles)
 
PendingContactAttributescontactAttributes (const UIntList &handles, const QStringList &interfaces, bool reference=true)
 
QStringList contactAttributeInterfaces () const
 
void injectContactIds (const HandleIdentifierMap &contactIds)
 
void injectContactId (uint handle, const QString &contactId)
 
- Public Member Functions inherited from Tp::RefCounted
 RefCounted ()
 
virtual ~RefCounted ()
 

Detailed Description

The ConnectionLowlevel class extends Connection with support to low-level features.

Constructor & Destructor Documentation

◆ ~ConnectionLowlevel()

Tp::ConnectionLowlevel::~ConnectionLowlevel ( )

Member Function Documentation

◆ isValid()

bool Tp::ConnectionLowlevel::isValid ( ) const

◆ connection()

ConnectionPtr Tp::ConnectionLowlevel::connection ( ) const

◆ requestConnect()

PendingReady * Tp::ConnectionLowlevel::requestConnect ( const Features requestedFeatures = Features())

Start an asynchronous request that the connection be connected.

When using a full-fledged Telepathy setup with an Account Manager service, the Account methods Account::setRequestedPresence() and Account::reconnect() must be used instead.

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

Parameters
requestedFeaturesThe features which should be enabled
Returns
A PendingReady which will emit PendingReady::finished when the Connection has reached ConnectionStatusConnected, and initial setup for basic functionality, plus the given features, has succeeded or failed.

◆ requestDisconnect()

PendingOperation * Tp::ConnectionLowlevel::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.

When using a full-fledged Telepathy setup with an Account Manager service, Account::setRequestedPresence() with Presence::offline() as an argument should generally be used instead.

Returns
A PendingOperation which will emit PendingOperation::finished when the request has been made.

◆ allowedPresenceStatuses()

SimpleStatusSpecMap Tp::ConnectionLowlevel::allowedPresenceStatuses ( ) const

Return a dictionary of presence statuses valid for use in this connection.

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

This method requires Connection::FeatureSimplePresence to be ready.

Returns
The allowed statuses as a map from string identifiers to SimpleStatusSpec objects.

◆ maxPresenceStatusMessageLength()

uint Tp::ConnectionLowlevel::maxPresenceStatusMessageLength ( ) const

Return the maximum length for a presence status message.

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

This method requires Connection::FeatureSimplePresence to be ready.

Returns
The maximum length, or 0 if there is no limit.

◆ setSelfPresence()

PendingOperation * Tp::ConnectionLowlevel::setSelfPresence ( const QString &  status,
const QString &  statusMessage 
)

Set the self presence status.

This should generally only be called by an Account Manager. In typical usage, Account::setRequestedPresence() should be used instead.

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 ConnectionStatus).

Parameters
statusThe desired status.
statusMessageThe desired status message.
Returns
A PendingOperation which will emit PendingOperation::finished when the call has finished.
See also
allowedPresenceStatuses()

◆ createChannel() [1/2]

PendingChannel * Tp::ConnectionLowlevel::createChannel ( const QVariantMap &  request)

Same as createChannel(request, -1)

◆ createChannel() [2/2]

PendingChannel * Tp::ConnectionLowlevel::createChannel ( const QVariantMap &  request,
int  timeout 
)

Asynchronously creates a channel satisfying the given request.

In typical usage, only the Channel Dispatcher should call this. Ordinary applications should use the Account::createChannel() family of methods (which invoke the Channel Dispatcher's services).

The request MUST contain the following keys: org.freedesktop.Telepathy.Channel.ChannelType org.freedesktop.Telepathy.Channel.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.

Parameters
requestA dictionary containing the desirable properties.
timeoutThe D-Bus timeout in milliseconds used for the method call. If timeout is -1, a default implementation-defined value that is suitable for inter-process communications (generally, 25 seconds) will be used.
Returns
A PendingChannel which will emit PendingChannel::finished when the channel has been created, or an error occurred.
See also
PendingChannel, ensureChannel(), Account::createChannel(), Account::createAndHandleChannel(), Account::ensureChannel(), Account::ensureAndHandleChannel()

◆ ensureChannel() [1/2]

PendingChannel * Tp::ConnectionLowlevel::ensureChannel ( const QVariantMap &  request)

Same as ensureChannel(request, -1)

◆ ensureChannel() [2/2]

PendingChannel * Tp::ConnectionLowlevel::ensureChannel ( const QVariantMap &  request,
int  timeout 
)

Asynchronously ensures a channel exists satisfying the given request.

In typical usage, only the Channel Dispatcher should call this. Ordinary applications should use the Account::ensureChannel() family of methods (which invoke the Channel Dispatcher's services).

The request MUST contain the following keys: org.freedesktop.Telepathy.Channel.ChannelType org.freedesktop.Telepathy.Channel.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.

Parameters
requestA dictionary containing the desirable properties.
timeoutThe D-Bus timeout in milliseconds used for the method call. If timeout is -1, a default implementation-defined value that is suitable for inter-process communications (generally, 25 seconds) will be used.
Returns
A PendingChannel which will emit PendingChannel::finished when the channel is ensured to exist, or an error occurred.
See also
PendingChannel, createChannel(), Account::createChannel(), Account::createAndHandleChannel(), Account::ensureChannel(), Account::ensureAndHandleChannel()

◆ requestHandles()

PendingHandles * Tp::ConnectionLowlevel::requestHandles ( HandleType  handleType,
const QStringList &  names 
)

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

Typically one doesn't need to request and use handles directly; instead, string identifiers and/or Contact objects are used in most APIs. File a bug for APIs in which there is no alternative to using handles. In particular however using low-level DBus interfaces for which there is no corresponding high-level (or one is implementing that abstraction) functionality does and will always require using bare handles.

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.

Parameters
handleTypeType for the handles to request, as specified in HandleType.
namesNames of the entities to request handles for.
Returns
A PendingHandles which will emit PendingHandles::finished when the handles have been requested, or an error occurred.
See also
PendingHandles

◆ referenceHandles()

PendingHandles * Tp::ConnectionLowlevel::referenceHandles ( HandleType  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.

Typically one doesn't need to reference and use handles directly; instead, string identifiers and/or Contact objects are used in most APIs. File a bug for APIs in which there is no alternative to using handles. In particular however using low-level DBus interfaces for which there is no corresponding high-level (or one is implementing that abstraction) functionality does and will always require using bare handles.

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
handleTypeType of the handles given, as specified in HandleType.
handlesHandles to request a reference to.
Returns
A PendingHandles which will emit PendingHandles::finished when the handles have been referenced, or an error occurred.

◆ contactAttributes()

PendingContactAttributes * Tp::ConnectionLowlevel::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.

This is very low-level API the Contact/ContactManager API provides a higher level of abstraction for the same functionality.

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 TP_QT_IFACE_CONNECTION_INTERFACE_CONTACTS), the returned PendingContactAttributes instance will fail instantly with the error TP_QT_ERROR_NOT_IMPLEMENTED.

Similarly, if the connection isn't both connected and ready (status() == ConnectionStatusConnected && isReady(Connection::FeatureCore)), the returned PendingContactAttributes instance will fail instantly with the error TP_QT_ERROR_NOT_AVAILABLE.

This method requires Connection::FeatureCore to be ready.

See also
PendingContactAttributes
Parameters
handlesA list of handles of type HandleTypeContact
interfacesD-Bus interfaces for which the client requires information
referenceWhether the handles should additionally be referenced.
Returns
A PendingContactAttributes which will emit PendingContactAttributes::fininshed when the contact attributes have been retrieved, or an error occurred.

◆ contactAttributeInterfaces()

QStringList Tp::ConnectionLowlevel::contactAttributeInterfaces ( ) const

◆ injectContactIds()

void Tp::ConnectionLowlevel::injectContactIds ( const HandleIdentifierMap contactIds)

◆ injectContactId()

void Tp::ConnectionLowlevel::injectContactId ( uint  handle,
const QString &  contactId 
)