| Home · All Classes · All Namespaces · Modules · Functions · Files |
The AbstractClientHandler class represents a Telepathy handler. More...
#include <TelepathyQt4/AbstractClientHandler>
Inherits Tp::AbstractClient.
Inherited by Tp::SimpleStreamTubeHandler.
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.
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(); }
ClientRegistrar registrar = ClientRegistrar::create(); AbstractClientPtr handler = AbstractClientPtr::dynamicCast( SharedPtr<MyHandler>(new MyHandler( ChannelClassSpecList() << ChannelClassSpec::textChat()))); registrar->registerClient(handler, "myhandler");
| 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.
| 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. |
| bool Tp::AbstractClientHandler::isRegistered | ( | ) | const |
Return whether this handler is registered.
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.
| AbstractClientHandler::Capabilities Tp::AbstractClientHandler::handlerCapabilities | ( | ) | const |
Return the set of additional capabilities supported by this handler.
| bool Tp::AbstractClientHandler::bypassApproval | ( | ) | const [pure virtual] |
Return whether channels destined for this handler are automatically handled, without invoking approvers.
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.
| 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. |
| dispatchOperation | The 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). |
| 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.
| 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.
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.
| channelRequest | The newly created channel request. |
| 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.
| channelRequest | The channel request that failed. |
| errorName | The 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. |
| errorMessage | Any message supplied with the D-Bus error. |
| Copyright © 2008-2011 Collabora Ltd. and Nokia Corporation | Telepathy-Qt4 0.8.0 |