Public Member Functions

virtual ~AbstractClientApprover ()
ChannelClassSpecList approverFilter () const
virtual void addDispatchOperation (const MethodInvocationContextPtr<> &context, const ChannelDispatchOperationPtr &dispatchOperation)=0

Protected Member Functions

AbstractClientApprover (const ChannelClassSpecList &channelFilter)

Detailed Description

The AbstractClientApprover class represents a Telepathy approver.

Approvers are clients that notify the user that new channels have been created, and allow the user to accept or reject those channels.

Approvers can also select which channel handler will be used for the channel, for instance by offering the user a list of possible handlers rather than just an accept/reject choice. However, the channel dispatcher must be able to prioritize possible handlers on its own using some reasonable heuristic, probably based on user configuration.

It is possible (and useful) to have an approver and a channel handler in the same process; this is particularly useful if a channel handler wants to claim responsibility for particular channels itself.

All approvers are notified simultaneously. For instance, in a desktop system, there might be one approver that displays a notification-area icon, one that is part of a contact list window and highlights contacts there, and one that is part of a full-screen media player.

Any approver can approve the handling of a channel dispatch operation with a particular channel handler by calling the ChannelDispatchOperation::handleWith() method. Approvers can also attempt to claim channels by calling ChannelDispatchOperation::claim(). If this succeeds, the approver may handle the channels itself (if it is also a handler), or close the channels in order to reject them.

Approvers wishing to reject channels should call the ChannelDispatchOperation::claim() method, then (if it succeeds) close the channels in any way they see fit.

The first approver to reply gets its decision acted on; any other approvers that reply at approximately the same time will get an error, indicating that the channel has already been dealt with.

Approvers should usually prompt the user and ask for confirmation, rather than dispatching the channel to a handler straight away.

To become an approver one should inherit AbstractClientApprover and implement the pure virtual addDispatchOperation() method. After that the object representing the approver must be registered using ClientRegistrar::registerClient().

When new channels in which the approver has registered an interest are ready to be dispatched, the method addDispatchOperation() is invoked. The new channels are represented by a ChannelDispatchOperation object, which is passed to the addDispatchOperation() method. All approvers are notified simultaneously.

Usage

Implementing an approver

 class MyApprover : public AbstractClientApprover
 {
 public:
     MyApprover(const ChannelClassSpecSpecList &channelFilter);
     ~MyApprover() { }

     void addDispatchOperation(const MethodInvocationContextPtr<> &context,
             const ChannelDispatchOperationPtr &dispatchOperation);
 };

 MyApprover::MyApprover(const ChannelClassSpecList &channelFilter)
     : AbstractClientApprover(channelFilter)
 {
 }

 void MyApprover::addDispatchOperation(
         const MethodInvocationContextPtr<> &context,
         const ChannelDispatchOperationPtr &dispatchOperation)
 {
     // do something with dispatchOperation

     context->setFinished();
 }

Registering an approver

 ClientRegistrar registrar = ClientRegistrar::create();
 AbstractClientPtr approver = AbstractClientPtr::dynamicCast(
         SharedPtr<MyApprover>(new MyApprover(
             ChannelClassSpecList() << ChannelClassSpec::textChat())));
 registrar->registerClient(approver, "myapprover");

See also:: AbstractClient

Constructor & Destructor Documentation

Tp::AbstractClientApprover::~AbstractClientApprover ( ) [virtual]

Class destructor.

Tp::AbstractClientApprover::AbstractClientApprover ( const ChannelClassSpecList & channelFilter ) [protected]

Construct a new AbstractClientApprover object.

Parameters:

channelFilter A specification of the channels in which this approver is interested.

Member Function Documentation

ChannelClassSpecList Tp::AbstractClientApprover::approverFilter ( ) const

Return the property containing a specification of the channels that this channel approver is interested. The addDispatchOperation() method should be called by the channel dispatcher whenever at least one of the channels in a channel dispatch operation matches this description.

This method works in exactly the same way as the AbstractClientObserver::observerChannelFilter() method. In particular, the returned value cannot change while the handler process continues to own the corresponding client bus name.

In the .client file, represented in the same way as observer channel filter, the group is TP_QT4_IFACE_CLIENT_APPROVER followed by ApproverChannelFilter instead.

Returns:: A specification of the channels that this channel approver is interested as a list of ChannelClassSpec objects.

See also:: addDispatchOperation()

void Tp::AbstractClientApprover::addDispatchOperation	(	const MethodInvocationContextPtr<> &	context,
		const ChannelDispatchOperationPtr &	dispatchOperation
	)		`[pure virtual]`

Called by the channel dispatcher when a dispatch operation in which the approver has registered an interest is created, or when the approver starts up while such channel dispatch operations already exist.

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 approvers must reimplement this method.

Parameters:

context	A MethodInvocationContextPtr object that must be used to indicate whether this method finished processing.
dispatchOperation	The dispatch operation to be processed.