MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9
   Home · All Classes · All Namespaces · Modules · Functions · Files

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


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  
)

Copyright © 2008-2011 Collabora Ltd. and Nokia Corporation
Telepathy-Qt4 0.6.5