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

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

 ClientRegistrar registrar = ClientRegistrar::create();
 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:

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

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:

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

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.