Tp::AbstractClientObserver Class Reference [Client proxies]

The AbstractClientObserver class provides an object representing a Telepathy observer. More...

#include <TelepathyQt4/AbstractClientObserver>

Inherits Tp::AbstractClient.

List of all members.

Public Member Functions

• virtual ~AbstractClientObserver ()
• TELEPATHY_QT4_DEPRECATED
  ChannelClassList observerChannelFilter () const
• 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 QVariantMap &observerInfo)=0

Protected Member Functions

• TELEPATHY_QT4_DEPRECATED AbstractClientObserver (const ChannelClassList &channelFilter)
• TELEPATHY_QT4_DEPRECATED AbstractClientObserver (const ChannelClassList &channelFilter, bool shouldRecover)
• AbstractClientObserver (const ChannelClassSpecList &channelFilter, bool shouldRecover=false)

---

Detailed Description

The AbstractClientObserver class provides an object representing 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 ChannelClassList &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 QVariantMap &observerInfo);
 };

 MyObserver::MyObserver(const ChannelClassList &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 QVariantMap &observerInfo)
 {
     // do something, log messages, ...

     context->setFinished();
 }

Registering an observer

 ChannelClassList filters;
 QMap<QString, QDBusVariant> filter;
 filter.insert(QLatin1String(TELEPATHY_INTERFACE_CHANNEL ".ChannelType"),
               QDBusVariant(QLatin1String(TELEPATHY_INTERFACE_CHANNEL_TYPE_TEXT)));
 filter.insert(QLatin1String(TELEPATHY_INTERFACE_CHANNEL ".TargetHandleType"),
               QDBusVariant((uint) Tp::HandleTypeContact));
 filters.append(filter);
 ClientRegistrar registrar = ClientRegistrar::create();
 AbstractClientPtr observer = AbstractClientPtr::dynamicCast(
         SharedPtr<MyObserver>(new MyObserver(filter)));
 registrar->registerClient(observer, "myobserver");

See also:

AbstractClient

---

Constructor & Destructor Documentation

Tp::AbstractClientObserver::~AbstractClientObserver

(

)

[virtual]

Class destructor.

Tp::AbstractClientObserver::AbstractClientObserver

(

const ChannelClassList &

channelFilter

)

[protected]

Construct a new AbstractClientObserver object.

Note that using this constructor the shouldRecover() method will return false, meaning that on crash the observer won't be able to "catch up" on channels that match its observerChannelFilter() automatically.

Parameters:

channelFilter

A specification of the channels in which this observer is interested.

Tp::AbstractClientObserver::AbstractClientObserver	(	const ChannelClassList &	channelFilter,
		bool	shouldRecover
	)			[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().

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

ChannelClassList Tp::AbstractClientObserver::observerChannelFilter

(

)

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.

Only certain types have useful semantics for matching like this, so only certain types are allowed:

See the Telepathy D-Bus API 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.

See also:

observeChannels()

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 D-Bus API 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.

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 QVariantMap &	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. No keys are currently defined. If keys are defined for this dictionary, all will be optional; observers may safely ignore any entry in this dictionary.