The AbstractClientObserver class represents a Telepathy observer. More...
#include <TelepathyQt/AbstractClientObserver>
Inherits Tp::AbstractClient.
Classes | |
| class | ObserverInfo |
| The AbstractClientObserver::ObserverInfo class provides a wrapper around the additional info about the channels passed to observeChannels(). More... | |
Public Member Functions | |
| virtual | ~AbstractClientObserver () |
| ChannelClassSpecList | observerFilter () const |
| bool | shouldRecover () const |
| virtual void | observeChannels (const MethodInvocationContextPtr<> &context, const AccountPtr &account, const ConnectionPtr &connection, const QList< ChannelPtr > &channels, const ChannelDispatchOperationPtr &dispatchOperation, const QList< ChannelRequestPtr > &requestsSatisfied, const ObserverInfo &observerInfo)=0 |
 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 | |
| AbstractClientObserver (const ChannelClassSpecList &channelFilter, bool shouldRecover=false) | |
Detailed Description
The AbstractClientObserver class represents a Telepathy observer.
Observers are clients that monitor the creation of new channels. This functionality can be used for things like message logging.
Observers should not modify the state of a channel except via user interaction.
Observers must not carry out actions that exactly one process must take responsibility for (e.g. acknowledging text messages, or carrying out the actual file transfer), since arbitrarily many observers can be activated for each channel. The handler is responsible for such tasks.
Handlers may, of course, delegate responsibility for these tasks to other clients (including those run as observers), but this must be done explicitly via a request from the handler to the observer.
Whenever a collection of new channels is signalled, the channel dispatcher will notify all running or activatable observers whose filter indicates that they are interested in some of the channels.
Observers are activated for all channels in which they have registered an interest - incoming, outgoing or automatically created - although of course the filter property can be set to filter specific channels.
To become an observer one should inherit AbstractClientObserver and implement the pure virtual observeChannels() method. After that the object representing the observer must be registered using ClientRegistrar::registerClient().
When new channels in which the observer has registered an interest are announced, the method observeChannels() is invoked. All observers are notified simultaneously.
Usage
Implementing an observer
Registering an observer
- See also
- AbstractClient
Constructor & Destructor Documentation
◆ ~AbstractClientObserver()
|
virtual |
Class destructor.
◆ AbstractClientObserver()
|
protected |
Construct a new AbstractClientObserver object.
- Parameters
-
channelFilter A specification of the channels in which this observer is interested. shouldRecover Whether upon the startup of this observer, observeChannels() will be called for every already existing channel matching its observerChannelFilter().
Member Function Documentation
◆ observerFilter()
| ChannelClassSpecList Tp::AbstractClientObserver::observerFilter | ( | ) | const |
Return the property containing a specification of the channels that this channel observer is interested. The observeChannels() method should be called by the channel dispatcher whenever any of the newly created channels match this description.
See the Telepathy specification for documentation about the allowed types and how to define filters.
This property never changes while the observer process owns its client bus name. If an observer wants to add extra channels to its list of interests at runtime, it can register an additional client bus name using ClientRegistrar::registerClient(). To remove those filters, it can release the bus name using ClientRegistrar::unregisterClient().
The same principle is applied to approvers and handlers.
- Returns
- A specification of the channels that this channel observer is interested as a list of ChannelClassSpec objects.
- See also
- observeChannels()
◆ shouldRecover()
| bool Tp::AbstractClientObserver::shouldRecover | ( | ) | const |
Return whether upon the startup of this observer, observeChannels() will be called for every already existing channel matching its observerChannelFilter().
- Parameters
-
◆ observeChannels()
|
pure virtual |
Called by the channel dispatcher when channels in which the observer has registered an interest are announced.
If the announced channels contains channels that match the observerChannelFilter(), and some that do not, then only a subset of the channels (those that do match the filter) are passed to this method.
If the channel dispatcher will split up the channels from a single announcement and dispatch them separately (for instance because no installed handler can handle all of them), it will call this method several times.
The observer must not call MethodInvocationContext::setFinished() until it is ready for a handler for the channel to run (which may change the channel's state). For instance 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 observers 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 observed. 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). If the Observer calls ChannelDispatchOperation::claim() or ChannelDispatchOperation::handleWith() on this object, it must be careful to avoid deadlock, since these methods cannot return until the observer has returned from observeChannels(). requestsSatisfied The requests satisfied by these channels. observerInfo Additional information about these channels.
