Tp::AbstractClientHandler Class Reference

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

#include <TelepathyQt/AbstractClientHandler>

Inherits Tp::AbstractClient.

Inherited by Tp::SimpleStreamTubeHandler.

Classes
class	Capabilities
	The AbstractClientHandler::Capabilities class provides a wrapper around the capabilities of a handler. More...
class	HandlerInfo
	The AbstractClientHandler::HandlerInfo class provides a wrapper around the additional info about the channels passed to handleChannels(). More...

Public Member Functions
virtual	~AbstractClientHandler ()
ChannelClassSpecList	handlerFilter () const
Capabilities	handlerCapabilities () const
virtual bool	bypassApproval () const =0
virtual void	handleChannels (const MethodInvocationContextPtr<> &context, const AccountPtr &account, const ConnectionPtr &connection, const QList< ChannelPtr > &channels, const QList< ChannelRequestPtr > &requestsSatisfied, const QDateTime &userActionTime, const HandlerInfo &handlerInfo)=0
bool	wantsRequestNotification () const
virtual void	addRequest (const ChannelRequestPtr &request)
virtual void	removeRequest (const ChannelRequestPtr &request, const QString &errorName, const QString &errorMessage)
Public Member Functions inherited from Tp::AbstractClient
	AbstractClient ()
virtual	~AbstractClient ()
bool	isRegistered () const
Public Member Functions inherited from Tp::RefCounted
	RefCounted ()
virtual	~RefCounted ()

Protected Member Functions
	AbstractClientHandler (const ChannelClassSpecList &channelFilter, const Capabilities &capabilities=Capabilities(), bool wantsRequestNotification=false)

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

~AbstractClientHandler()

Tp::AbstractClientHandler::~AbstractClientHandler ( )

virtual

Class destructor.

AbstractClientHandler()

Tp::AbstractClientHandler::AbstractClientHandler ( const ChannelClassSpecList &  channelFilter, const Capabilities &  capabilities = Capabilities(), bool  wantsRequestNotification = false  )

protected

Construct a new AbstractClientHandler object.

Parameters

channelFilter	A specification of the channels in which this observer is interested.
wantsRequestNotification	Whether this handler wants to receive channel requests notification via addRequest() and removeRequest().
capabilities	The set of additional capabilities supported by this handler.

Member Function Documentation

handlerFilter()

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

handlerCapabilities()

AbstractClientHandler::Capabilities Tp::AbstractClientHandler::handlerCapabilities

(

)

const

Return the set of additional capabilities supported by this handler.

Returns

The capabilities as an AbstractClientHandler::Capabilities object.

bypassApproval()

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.

handleChannels()

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

context	A MethodInvocationContextPtr object that must be used to indicate whether this method finished processing.
account	The account with which the channels are associated.
connection	The connection with which the channels are associated.
channels	The channels to be handled.
requestsSatisfied	The requests satisfied by these channels.
userActionTime	The 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.
handlerInfo	Additional information about these channels.

Implemented in Tp::SimpleStreamTubeHandler.

wantsRequestNotification()

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.

addRequest()

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_QT_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

channelRequest

The newly created channel request.

See also

removeRequest()

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

channelRequest	The channel request that failed.
errorName	The name of the D-Bus error with which the request failed. If this is TP_QT_ERROR_NOT_YOURS, this indicates that the request succeeded, but all the resulting channels were given to some other handler.
errorMessage	Any message supplied with the D-Bus error.