Tp::ConnectionLowlevel Class Reference [Connection proxies]

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

#include <TelepathyQt4/ConnectionLowlevel>

Inherits QObject, and Tp::RefCounted.

List of all members.

Public Member Functions

• ~ConnectionLowlevel ()
• bool isValid () const
• ConnectionPtr connection () const
• PendingReady * requestConnect (const Features &requestedFeatures=Features())
• PendingOperation * requestDisconnect ()
• SimpleStatusSpecMap allowedPresenceStatuses () const
• uint maxPresenceStatusMessageLength () const
• PendingOperation * setSelfPresence (const QString &status, const QString &statusMessage)
• PendingChannel * createChannel (const QVariantMap &request)
• PendingChannel * createChannel (const QVariantMap &request, int timeout)
• PendingChannel * ensureChannel (const QVariantMap &request)
• PendingChannel * ensureChannel (const QVariantMap &request, int timeout)
• PendingHandles * requestHandles (HandleType handleType, const QStringList &names)
• PendingHandles * referenceHandles (HandleType handleType, const UIntList &handles)
• PendingContactAttributes * contactAttributes (const UIntList &handles, const QStringList &interfaces, bool reference=true)
• QStringList contactAttributeInterfaces () const
• void injectContactIds (const HandleIdentifierMap &contactIds)
• void injectContactId (uint handle, const QString &contactId)

---

Detailed Description

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

---

Constructor & Destructor Documentation

Tp::ConnectionLowlevel::~ConnectionLowlevel

(

)

---

Member Function Documentation

bool Tp::ConnectionLowlevel::isValid

(

)

const

ConnectionPtr Tp::ConnectionLowlevel::connection

(

)

const

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:

requestedFeatures

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

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.

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.

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.

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:

	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()

PendingChannel * Tp::ConnectionLowlevel::createChannel

(

const QVariantMap &

request

)

Same as createChannel(request, -1)

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:

	request	A dictionary containing the desirable properties.
	timeout	The 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()

PendingChannel * Tp::ConnectionLowlevel::ensureChannel

(

const QVariantMap &

request

)

Same as ensureChannel(request, -1)

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:

	request	A dictionary containing the desirable properties.
	timeout	The 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()

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:

	handleType	Type for the handles to request, as specified in HandleType.
	names	Names 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

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:

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

Returns:

A PendingHandles which will emit PendingHandles::finished when the handles have been referenced, or an error occurred.

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

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

This method requires Connection::FeatureCore to be ready.

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:

A PendingContactAttributes which will emit PendingContactAttributes::fininshed when the contact attributes have been retrieved, or an error occurred.

QStringList Tp::ConnectionLowlevel::contactAttributeInterfaces

(

)

const

void Tp::ConnectionLowlevel::injectContactIds

(

const HandleIdentifierMap &

contactIds

)

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