Home · All Classes · All Namespaces · Modules · Functions · Files
Classes | Public Member Functions | Protected Member Functions
Tp::AbstractClientHandler Class Reference

The AbstractClientHandler class represents a Telepathy handler. More...

#include <TelepathyQt4/AbstractClientHandler>

Inherits Tp::AbstractClient.

Inherited by Tp::SimpleStreamTubeHandler.

List of all members.

Classes

Public Member Functions

Protected Member Functions


Detailed Description

The AbstractClientHandler class represents a Telepathy handler.

Handlers are the user interface for a channel. They turn an abstract channel into something the user wants to see, like a text message stream or an audio and/or video call.

For its entire lifetime, each channel on a connection known to the channel dispatcher is either being processed by the channel dispatcher, or being handled by precisely one handler.

Because each channel is only handled by one handler, handlers may perform actions that only make sense to do once, such as acknowledging text messages, transferring the file, etc.

When a new incoming channel is offered to approvers by the channel dispatcher, it also offers the approvers a list of all the running or activatable handlers whose filter indicates that they are able to handle the channel. The approvers can choose one of those channel handlers to handle the channel.

When a new outgoing channel appears, the channel dispatcher passes it to an appropriate channel handler automatically.

To become an handler one should inherit AbstractClientHandler and implement the pure virtual bypassApproval() and handleChannels() methods. After that the object representing the handler must be registered using ClientRegistrar::registerClient().

When new channels in which the approver has registered an interest are ready to be handled, the method handleChannels() is invoked.

Usage

Implementing a handler

 class MyHandler : public AbstractClientHandler
 {
 public:
     MyHandler(const ChannelClassSpecList &channelFilter);
     ~MyHandler() { }

     void bypassApproval() const;

     void handleChannels(const MethodInvocationContextPtr<> &context,
             const AccountPtr &account,
             const ConnectionPtr &connection,
             const QList<ChannelPtr> &channels,
             const QList<ChannelRequestPtr> &requestsSatisfied,
             const QDateTime &userActionTime,
             const AbstractClientHandler::HandlerInfo &handlerInfo);
 };

 MyHandler::MyHandler(const ChannelClassSpecList &channelFilter)
     : AbstractClientHandler(channelFilter)
 {
 }

 void MyHandler::bypassApproval() const
 {
     return false;
 }

 void MyHandler::handleChannels(const MethodInvocationContextPtr<> &context,
         const AccountPtr &account,
         const ConnectionPtr &connection,
         const QList<ChannelPtr> &channels,
         const QList<ChannelRequestPtr> &requestsSatisfied,
         const QDateTime &userActionTime,
         const AbstractClientHandler::HandlerInfo &handlerInfo)
 {
     // do something

     context->setFinished();
 }

Registering a handler

 ClientRegistrar registrar = ClientRegistrar::create();
 AbstractClientPtr handler = AbstractClientPtr::dynamicCast(
         SharedPtr<MyHandler>(new MyHandler(
             ChannelClassSpecList() << ChannelClassSpec::textChat())));
 registrar->registerClient(handler, "myhandler");
See also:
AbstractClient

Constructor & Destructor Documentation

Tp::AbstractClientHandler::~AbstractClientHandler ( ) [virtual]

Class destructor.

Tp::AbstractClientHandler::AbstractClientHandler ( const ChannelClassSpecList channelFilter,
const Capabilities capabilities = Capabilities(),
bool  wantsRequestNotification = false 
) [protected]

Construct a new AbstractClientHandler object.

Parameters:
channelFilterA specification of the channels in which this observer is interested.
wantsRequestNotificationWhether this handler wants to receive channel requests notification via addRequest() and removeRequest().
capabilitiesThe set of additional capabilities supported by this handler.

Member Function Documentation

bool Tp::AbstractClientHandler::isRegistered ( ) const

Return whether this handler is registered.

Returns:
true if registered, false otherwise.
ChannelClassSpecList Tp::AbstractClientHandler::handlerFilter ( ) const

Return the property containing a specification of the channels that this channel handler can deal with. It will be offered to approvers as a potential channel handler for bundles that contain only suitable channels, or for suitable channels that must be handled separately.

This method works in exactly the same way as the AbstractClientObserver::observerChannelFilter() method. In particular, the returned value cannot change while the handler process continues to own the corresponding client bus name.

In the .client file, represented in the same way as observer channel filter, the group is TP_QT4_IFACE_CLIENT_HANDLER suffixed by HandlerChannelFilter instead.

Returns:
A specification of the channels that this channel handler can deal with as a list of ChannelClassSpec objects.
AbstractClientHandler::Capabilities Tp::AbstractClientHandler::handlerCapabilities ( ) const

Return the set of additional capabilities supported by this handler.

Returns:
The capabilities as an AbstractClientHandler::Capabilities object.
bool Tp::AbstractClientHandler::bypassApproval ( ) const [pure virtual]

Return whether channels destined for this handler are automatically handled, without invoking approvers.

Returns:
true if automatically handled, false otherwise.

Implemented in Tp::SimpleStreamTubeHandler.

void Tp::AbstractClientHandler::handleChannels ( const MethodInvocationContextPtr<> &  context,
const AccountPtr &  account,
const ConnectionPtr &  connection,
const QList< ChannelPtr > &  channels,
const QList< ChannelRequestPtr > &  requestsSatisfied,
const QDateTime userActionTime,
const HandlerInfo handlerInfo 
) [pure virtual]

Called by the channel dispatcher when this handler should handle these channels, or when this handler should present channels that it is already handling to the user (e.g. bring them into the foreground).

Clients are expected to know what channels they're already handling, and which channel object corresponds to which window or tab.

After handleChannels() replies successfully by calling MethodInvocationContext::setFinished(), the client process is considered to be responsible for the channel until it its unique name disappears from the bus.

If a process has multiple client bus names - some temporary and some long-lived - and drops one of the temporary bus names in order to reduce the set of channels that it will handle, any channels that it is already handling will remain unaffected.

The received context object should be stored until this method is finished processing and then MethodInvocationContext::setFinished() or MethodInvocationContext::setFinishedWithError() should be called on the received context object.

Specialized handlers must reimplement this method.

Parameters:
contextA MethodInvocationContextPtr object that must be used to indicate whether this method finished processing.
accountThe account with which the channels are associated.
connectionThe connection with which the channels are associated.
channelsThe channels to be handled.
dispatchOperationThe dispatch operation for these channels. The object will be invalid (DBusProxy::isValid() will be false) if there is no dispatch operation in place (because the channels were requested, not incoming).
requestsSatisfiedThe requests satisfied by these channels.
userActionTimeThe time at which user action occurred, or 0 if this channel is to be handled for some reason not involving user action. Handlers should use this for focus-stealing prevention, if applicable.
handlerInfoAdditional information about these channels.

Implemented in Tp::SimpleStreamTubeHandler.

bool Tp::AbstractClientHandler::wantsRequestNotification ( ) const

Return whether this handler wants to receive notification of channel requests via addRequest() and removeRequest().

This property is set by the constructor and cannot be changed after that.

Returns:
true if receiving channel requests notification is desired, false otherwise.
void Tp::AbstractClientHandler::addRequest ( const ChannelRequestPtr &  channelRequest) [virtual]

Called by the channel dispatcher to indicate that channels have been requested, and that if the request is successful, they will probably be handled by this handler.

This allows the UI to start preparing to handle the channels in advance (e.g. render a window with an "in progress" message), improving perceived responsiveness.

If the request succeeds and is given to the expected handler, the requestsSatisfied parameter to handleChannels() can be used to match the channel to a previous addRequest() call.

This lets the UI direct the channels to the window that it already opened.

If the request fails, the expected handler is notified by the channel dispatcher calling its removeRequest() method.

This lets the UI close the window or display the error.

The channel dispatcher will attempt to ensure that handleChannels() is called on the same handler that received addRequest(). If that isn't possible, removeRequest() will be called on the handler that previously received addRequest(), with the special error TP_QT4_ERROR_NOT_YOURS, which indicates that some other handler received the channel instead.

Expected handling is for the UI to close the window it previously opened.

Specialized handlers that want to be notified of newly requested channel should reimplement this method.

Parameters:
channelRequestThe newly created channel request.
See also:
removeRequest()
void Tp::AbstractClientHandler::removeRequest ( const ChannelRequestPtr &  channelRequest,
const QString errorName,
const QString errorMessage 
) [virtual]

Called by the ChannelDispatcher to indicate that a request previously passed to addRequest() has failed and should be disregarded.

Specialized handlers that want to be notified of removed channel requests should reimplement this method.

Parameters:
channelRequestThe channel request that failed.
errorNameThe name of the D-Bus error with which the request failed. If this is TP_QT4_ERROR_NOT_YOURS, this indicates that the request succeeded, but all the resulting channels were given to some other handler.
errorMessageAny message supplied with the D-Bus error.


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