| Home · All Classes · All Namespaces · Modules · Functions · Files |
The AbstractClientObserver class represents a Telepathy observer. More...
#include <TelepathyQt4/AbstractClientObserver>
Inherits Tp::AbstractClient.
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.
class MyObserver : public AbstractClientObserver { public: MyObserver(const ChannelClassSpecList &channelFilter); ~MyObserver() { } void observeChannels(const MethodInvocationContextPtr<> &context, const AccountPtr &account, const ConnectionPtr &connection, const QList<ChannelPtr> &channels, const ChannelDispatchOperationPtr &dispatchOperation, const QList<ChannelRequestPtr> &requestsSatisfied, const AbstractClientObserver::ObserverInfo &observerInfo); }; MyObserver::MyObserver(const ChannelClassSpecList &channelFilter) : AbstractClientObserver(channelFilter) { } void MyObserver::observeChannels(const MethodInvocationContextPtr<> &context, const AccountPtr &account, const ConnectionPtr &connection, const QList<ChannelPtr> &channels, const ChannelDispatchOperationPtr &dispatchOperation, const QList<ChannelRequestPtr> &requestsSatisfied, const AbstractClientObserver::ObserverInfo &observerInfo) { // do something, log messages, ... context->setFinished(); }
ClientRegistrar registrar = ClientRegistrar::create(); AbstractClientPtr observer = AbstractClientPtr::dynamicCast( SharedPtr<MyObserver>(new MyObserver( ChannelClassSpecList() << ChannelClassSpec::textChat()))); registrar->registerClient(observer, "myobserver");
| Tp::AbstractClientObserver::~AbstractClientObserver | ( | ) | [virtual] |
Class destructor.
| Tp::AbstractClientObserver::AbstractClientObserver | ( | const ChannelClassSpecList & | channelFilter, | |
| bool | shouldRecover = false |
|||
| ) | [protected] |
Construct a new AbstractClientObserver object.
| 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(). |
| 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.
| 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().
| \c | true if this observer observerChannels() will be called for every already existing channel matching its observerChannelFilter(), false otherwise. |
| void Tp::AbstractClientObserver::observeChannels | ( | const MethodInvocationContextPtr<> & | context, | |
| const AccountPtr & | account, | |||
| const ConnectionPtr & | connection, | |||
| const QList< ChannelPtr > & | channels, | |||
| const ChannelDispatchOperationPtr & | dispatchOperation, | |||
| const QList< ChannelRequestPtr > & | requestsSatisfied, | |||
| const ObserverInfo & | observerInfo | |||
| ) | [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.
| 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. |
| Copyright © 2008-2011 Collabora Ltd. and Nokia Corporation |
Telepathy-Qt4 0.6.5
|