Tp::AbstractClientApprover Class Reference [Client proxies]

The AbstractClientApprover class provides an object representing a Telepathy approver. More...

#include <TelepathyQt4/AbstractClientApprover>

Inherits Tp::AbstractClient.

List of all members.

Public Member Functions

• virtual ~AbstractClientApprover ()
• TELEPATHY_QT4_DEPRECATED
  ChannelClassList approverChannelFilter () const
• ChannelClassSpecList approverFilter () const
• virtual void addDispatchOperation (const MethodInvocationContextPtr<> &context, const QList< ChannelPtr > &channels, const ChannelDispatchOperationPtr &dispatchOperation)=0

Protected Member Functions

• TELEPATHY_QT4_DEPRECATED AbstractClientApprover (const ChannelClassList &channelFilter)
• AbstractClientApprover (const ChannelClassSpecList &channelFilter)

---

Detailed Description

The AbstractClientApprover class provides an object representing 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 ChannelClassList &channelFilter);
     ~MyApprover() { }

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

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

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

     context->setFinished();
 }

Registering an approver

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

See also:

AbstractClient

---

Constructor & Destructor Documentation

Tp::AbstractClientApprover::~AbstractClientApprover

(

)

[virtual]

Class destructor.

Tp::AbstractClientApprover::AbstractClientApprover

(

const ChannelClassList &

channelFilter

)

[protected]

Construct a new AbstractClientApprover object.

Parameters:

channelFilter

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

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

ChannelClassList Tp::AbstractClientApprover::approverChannelFilter

(

)

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 TELEPATHY_INTERFACE_CLIENT_APPROVER followed by ApproverChannelFilter instead.

Returns:

A specification of the channels that this channel approver is interested.

See also:

addDispatchOperation()

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 TELEPATHY_INTERFACE_CLIENT_APPROVER followed by ApproverChannelFilter instead.

Returns:

A specification of the channels that this channel approver is interested.

See also:

addDispatchOperation()

void Tp::AbstractClientApprover::addDispatchOperation	(	const MethodInvocationContextPtr<> &	context,
		const QList< ChannelPtr > &	channels,
		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.
	channels	The channels to be dispatched. This argument always contains all of the channels in the channel dispatch operation, even if not all of them actually match the approver filter. The actual channels to be dispatched may reduce as channels are closed: this is signalled by ChannelDispatchOperation::channelLost signal on the received dispatchOperation object. Approvers should connect to ChannelDispatchOperation::channelLost() and ChannelDispatchOperation::invalidated() signals (if desired) before returning from addDispatchOperation, since those signals are guaranteed not to be emitted until after all addDispatchOperation() calls have returned (with success or failure) or timed out.
	dispatchOperation	The dispatch operation to be processed.