Home · All Classes · All Namespaces · Modules · Functions · Files
Classes | Public Member Functions | Protected Member Functions | List of all members
Tp::AbstractClientObserver Class Referenceabstract

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

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();
}

Registering an observer

AbstractClientPtr observer = AbstractClientPtr::dynamicCast(
SharedPtr<MyObserver>(new MyObserver(
ChannelClassSpecList() << ChannelClassSpec::textChat())));
registrar->registerClient(observer, "myobserver");
See also
AbstractClient

Constructor & Destructor Documentation

Tp::AbstractClientObserver::~AbstractClientObserver ( )
virtual

Class destructor.

Tp::AbstractClientObserver::AbstractClientObserver ( const ChannelClassSpecList channelFilter,
bool  shouldRecover = false 
)
protected

Construct a new AbstractClientObserver object.

Parameters
channelFilterA specification of the channels in which this observer is interested.
shouldRecoverWhether upon the startup of this observer, observeChannels() will be called for every already existing channel matching its observerChannelFilter().

Member Function Documentation

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()
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
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.

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 observed.
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). 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().
requestsSatisfiedThe requests satisfied by these channels.
observerInfoAdditional information about these channels.


Copyright © 2008-2011 Collabora Ltd. and Nokia Corporation
Telepathy-Qt 0.9.7