Tp::AbstractClientHandler Class Reference [Client proxies]

The AbstractClientHandler class provides an object representing a Telepathy handler. More...

#include <TelepathyQt4/AbstractClientHandler>

Inherits Tp::AbstractClient.

List of all members.

Classes

• class Capabilities

Public Member Functions

• virtual ~AbstractClientHandler ()
• TELEPATHY_QT4_DEPRECATED
  ChannelClassList handlerChannelFilter () const
• ChannelClassSpecList handlerFilter () const
• TELEPATHY_QT4_DEPRECATED
  QStringList capabilities () const
• Capabilities handlerCapabilities () const
• virtual bool bypassApproval () const =0
• virtual void handleChannels (const MethodInvocationContextPtr<> &context, const AccountPtr &account, const ConnectionPtr &connection, const QList< ChannelPtr > &channels, const QList< ChannelRequestPtr > &requestsSatisfied, const QDateTime &userActionTime, const QVariantMap &handlerInfo)=0
• bool wantsRequestNotification () const
• virtual void addRequest (const ChannelRequestPtr &request)
• virtual void removeRequest (const ChannelRequestPtr &request, const QString &errorName, const QString &errorMessage)

Protected Member Functions

• TELEPATHY_QT4_DEPRECATED AbstractClientHandler (const ChannelClassList &channelFilter, bool wantsRequestNotification=false)
• TELEPATHY_QT4_DEPRECATED AbstractClientHandler (const ChannelClassList &channelFilter, const QStringList &capabilities, bool wantsRequestNotification=false)
• AbstractClientHandler (const ChannelClassSpecList &channelFilter, const Capabilities &capabilities=Capabilities(), bool wantsRequestNotification=false)

---

Detailed Description

The AbstractClientHandler class provides an object representing a Telepathy handler.

Handlers are the user interface for a channel. They turn an abstract channel into something the user wants to see, like a text message stream or an audio and/or video call.

For its entire lifetime, each channel on a connection known to the channel dispatcher is either being processed by the channel dispatcher, or being handled by precisely one handler.

Because each channel is only handled by one handler, handlers may perform actions that only make sense to do once, such as acknowledging text messages, transferring the file, etc.

When a new incoming channel is offered to approvers by the channel dispatcher, it also offers the approvers a list of all the running or activatable handlers whose filter indicates that they are able to handle the channel. The approvers can choose one of those channel handlers to handle the channel.

When a new outgoing channel appears, the channel dispatcher passes it to an appropriate channel handler automatically.

To become an handler one should inherit AbstractClientHandler and implement the pure virtual bypassApproval() and handleChannels() methods. After that the object representing the handler must be registered using ClientRegistrar::registerClient().

When new channels in which the approver has registered an interest are ready to be handled, the method handleChannels() is invoked.

Usage

Implementing a handler

 class MyHandler : public AbstractClientHandler
 {
 public:
     MyHandler(const ChannelClassList &channelFilter);
     ~MyHandler() { }

     void bypassApproval() const;

     void handleChannels(const MethodInvocationContextPtr<> &context,
             const AccountPtr &account,
             const ConnectionPtr &connection,
             const QList<ChannelPtr> &channels,
             const QList<ChannelRequestPtr> &requestsSatisfied,
             const QDateTime &userActionTime,
             const QVariantMap &handlerInfo);
 };

 MyHandler::MyHandler(const ChannelClassList &channelFilter)
     : AbstractClientHandler(channelFilter)
 {
 }

 void MyHandler::bypassApproval() const
 {
     return false;
 }

 void MyHandler::handleChannels(const MethodInvocationContextPtr<> &context,
         const AccountPtr &account,
         const ConnectionPtr &connection,
         const QList<ChannelPtr> &channels,
         const QList<ChannelRequestPtr> &requestsSatisfied,
         const QDateTime &userActionTime,
         const QVariantMap &handlerInfo)
 {
     // do something

     context->setFinished();
 }

Registering a handler

 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 handler = AbstractClientPtr::dynamicCast(
         SharedPtr<MyHandler>(new MyHandler(filter)));
 registrar->registerClient(handler, "myhandler");

See also:

AbstractClient

---

Constructor & Destructor Documentation

Tp::AbstractClientHandler::~AbstractClientHandler

(

)

[virtual]

Class destructor.

Tp::AbstractClientHandler::AbstractClientHandler	(	const ChannelClassList &	channelFilter,
		bool	wantsRequestNotification = false
	)			[protected]

Construct a new AbstractClientHandler object.

Parameters:

	channelFilter	A specification of the channels in which this observer is interested.
	wantsRequestNotification	Whether this handler wants to receive channel requests notification via addRequest() and removeRequest().

Tp::AbstractClientHandler::AbstractClientHandler	(	const ChannelClassList &	channelFilter,
		const QStringList &	capabilities,
		bool	wantsRequestNotification = false
	)			[protected]

Construct a new AbstractClientHandler object.

Parameters:

	channelFilter	A specification of the channels in which this observer is interested.
	wantsRequestNotification	Whether this handler wants to receive channel requests notification via addRequest() and removeRequest().
	capabilities	The set of additional capabilities supported by this handler. See the capabilities() method documetation for more details.

Tp::AbstractClientHandler::AbstractClientHandler	(	const ChannelClassSpecList &	channelFilter,
		const Capabilities &	capabilities = Capabilities(),
		bool	wantsRequestNotification = false
	)			[protected]

Construct a new AbstractClientHandler object.

Parameters:

	channelFilter	A specification of the channels in which this observer is interested.
	wantsRequestNotification	Whether this handler wants to receive channel requests notification via addRequest() and removeRequest().
	capabilities	The set of additional capabilities supported by this handler.

---

Member Function Documentation

ChannelClassList Tp::AbstractClientHandler::handlerChannelFilter

(

)

const

Return the property containing a specification of the channels that this channel handler can deal with. It will be offered to approvers as a potential channel handler for bundles that contain only suitable channels, or for suitable channels that must be handled separately.

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_HANDLER suffixed by HandlerChannelFilter instead.

Returns:

A specification of the channels that this channel handler can deal with.

ChannelClassSpecList Tp::AbstractClientHandler::handlerFilter

(

)

const

Return the property containing a specification of the channels that this channel handler can deal with. It will be offered to approvers as a potential channel handler for bundles that contain only suitable channels, or for suitable channels that must be handled separately.

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_HANDLER suffixed by HandlerChannelFilter instead.

Returns:

A specification of the channels that this channel handler can deal with.

QStringList Tp::AbstractClientHandler::capabilities

(

)

const

Return the set of additional capabilities supported by this handler. This describes things like support for streamed media codecs and NAT traversal mechanisms.

See the Telepathy D-Bus API Specification for more details.

Deprecated:

Use handlerCapabilities() instead, it offers a high-level interface to the capability set.

Returns:

The set of additional capabilities supported by this handler.

AbstractClientHandler::Capabilities Tp::AbstractClientHandler::handlerCapabilities

(

)

const

Return the set of additional capabilities supported by this handler.

Returns:

The set of additional capabilities supported by this handler.

bool Tp::AbstractClientHandler::bypassApproval

(

)

const [pure virtual]

Return whether channels destined for this handler are automatically handled, without invoking approvers.

Returns:

Whether channels destined for this handler are automatically handled.

void Tp::AbstractClientHandler::handleChannels	(	const MethodInvocationContextPtr<> &	context,
		const AccountPtr &	account,
		const ConnectionPtr &	connection,
		const QList< ChannelPtr > &	channels,
		const QList< ChannelRequestPtr > &	requestsSatisfied,
		const QDateTime &	userActionTime,
		const QVariantMap &	handlerInfo
	)			[pure virtual]

Called by the channel dispatcher when this handler should handle these channels, or when this handler should present channels that it is already handling to the user (e.g. bring them into the foreground).

Clients are expected to know what channels they're already handling, and which channel object corresponds to which window or tab.

After handleChannels() replies successfully by calling MethodInvocationContext::setFinished(), the client process is considered to be responsible for the channel until it its unique name disappears from the bus.

If a process has multiple client bus names - some temporary and some long-lived - and drops one of the temporary bus names in order to reduce the set of channels that it will handle, any channels that it is already handling will remain unaffected.

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 handlers 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 handled.
	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).
	requestsSatisfied	The requests satisfied by these channels.
	userActionTime	The time at which user action occurred, or 0 if this channel is to be handled for some reason not involving user action. Handlers should use this for focus-stealing prevention, if applicable.
	handlerInfo	Additional information about these channels. No keys are currently defined. If keys are defined for this dictionary, all will be optional; handlers may safely ignore any entry in this dictionary.

bool Tp::AbstractClientHandler::wantsRequestNotification

(

)

const

Return whether this handler wants to receive notification of channel requests via addRequest() and removeRequest().

This property is set by the constructor and cannot be changed after that.

Returns:

Whether this handler wants to receive channel requests notification.

void Tp::AbstractClientHandler::addRequest

(

const ChannelRequestPtr &

channelRequest

)

[virtual]

Called by the channel dispatcher to indicate that channels have been requested, and that if the request is successful, they will probably be handled by this handler.

This allows the UI to start preparing to handle the channels in advance (e.g. render a window with an "in progress" message), improving perceived responsiveness.

If the request succeeds and is given to the expected handler, the requestsSatisfied parameter to handleChannels() can be used to match the channel to a previous addRequest() call.

This lets the UI direct the channels to the window that it already opened.

If the request fails, the expected handler is notified by the channel dispatcher calling its removeRequest() method.

This lets the UI close the window or display the error.

The channel dispatcher will attempt to ensure that handleChannels() is called on the same handler that received addRequest(). If that isn't possible, removeRequest() will be called on the handler that previously received addRequest(), with the special error TELEPATHY_ERROR_NOT_YOURS, which indicates that some other handler received the channel instead.

Expected handling is for the UI to close the window it previously opened.

Specialized handlers that want to be notified of newly requested channel should reimplement this method.

Parameters:

channelRequest

The newly created channel request.

See also:

removeRequest()

void Tp::AbstractClientHandler::removeRequest	(	const ChannelRequestPtr &	channelRequest,
		const QString &	errorName,
		const QString &	errorMessage
	)			[virtual]

Called by the ChannelDispatcher to indicate that a request previously passed to addRequest() has failed and should be disregarded.

Specialized handlers that want to be notified of removed channel requests should reimplement this method.

Parameters:

	channelRequest	The channel request that failed.
	errorName	The name of the D-Bus error with which the request failed. If this is TELEPATHY_ERROR_NOT_YOURS, this indicates that the request succeeded, but all the resulting channels were given to some other handler.
	errorMessage	Any message supplied with the D-Bus error.