Tp::ChannelDispatchOperation Class Reference

| Home · All Classes · All Namespaces · Modules · Functions · Files

Signals | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | List of all members
Tp::ChannelDispatchOperation Class Reference
ChannelDispatchOperation proxies

The ChannelDispatchOperation class represents a Telepathy channel dispatch operation. More...

`#include <TelepathyQt/ChannelDispatchOperation>`

Inherits Tp::StatefulDBusProxy, and Tp::OptionalInterfaceFactory< ChannelDispatchOperation >.

## Signals
void | channelLost (const Tp::ChannelPtr &channel, const QString &errorName, const QString &errorMessage)
Signals inherited from Tp::DBusProxy
void | invalidated (Tp::DBusProxy *proxy, const QString &errorName, const QString &errorMessage)
Signals inherited from Tp::Object
void | propertyChanged (const QString &propertyName)

## Public Member Functions
virtual | ~ChannelDispatchOperation ()
ConnectionPtr | connection () const
AccountPtr | account () const
QList< ChannelPtr > | channels () const
QStringList | possibleHandlers () const
PendingOperation * | handleWith (const QString &handler)
PendingOperation * | claim ()
PendingOperation * | claim (const AbstractClientHandlerPtr &handler)
Public Member Functions inherited from Tp::StatefulDBusProxy
| StatefulDBusProxy (const QDBusConnection &dbusConnection, const QString &busName, const QString &objectPath, const Feature &featureCore)
virtual | ~StatefulDBusProxy ()
Public Member Functions inherited from Tp::DBusProxy
| DBusProxy (const QDBusConnection &dbusConnection, const QString &busName, const QString &objectPath, const Feature &featureCore)
virtual | ~DBusProxy ()
QDBusConnection | dbusConnection () const
QString | busName () const
QString | objectPath () const
bool | isValid () const
QString | invalidationReason () const
QString | invalidationMessage () const
Public Member Functions inherited from Tp::Object
virtual | ~Object ()
Public Member Functions inherited from Tp::RefCounted
| RefCounted ()
virtual | ~RefCounted ()
Public Member Functions inherited from Tp::ReadyObject
| ReadyObject (RefCounted *object, const Feature &featureCore)
| ReadyObject (DBusProxy *proxy, const Feature &featureCore)
virtual | ~ReadyObject ()
virtual bool | isReady (const Features &features=Features()) const
virtual PendingReady * | becomeReady (const Features &requestedFeatures=Features())
virtual Features | requestedFeatures () const
virtual Features | actualFeatures () const
virtual Features | missingFeatures () const
Public Member Functions inherited from Tp::OptionalInterfaceFactory< ChannelDispatchOperation >
| OptionalInterfaceFactory (ChannelDispatchOperation *this_)
| ~OptionalInterfaceFactory ()
QStringList | interfaces () const
bool | hasInterface (const QString &name) const
Interface * | optionalInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
Interface * | interface () const

## Static Public Member Functions
static ChannelDispatchOperationPtr | create (const QDBusConnection &bus, const QString &objectPath, const QVariantMap &immutableProperties, const QList< ChannelPtr > &initialChannels, const AccountFactoryConstPtr &accountFactory, const ConnectionFactoryConstPtr &connectionFactory, const ChannelFactoryConstPtr &channelFactory, const ContactFactoryConstPtr &contactFactory)
Static Public Member Functions inherited from Tp::StatefulDBusProxy
static QString | uniqueNameFrom (const QDBusConnection &bus, const QString &wellKnownOrUnique)
static QString | uniqueNameFrom (const QDBusConnection &bus, const QString &wellKnownOrUnique, QString &error, QString &message)

## Static Public Attributes
static const Feature | FeatureCore

## Protected Member Functions
| ChannelDispatchOperation (const QDBusConnection &bus, const QString &objectPath, const QVariantMap &immutableProperties, const QList< ChannelPtr > &initialChannels, const AccountFactoryConstPtr &accountFactory, const ConnectionFactoryConstPtr &connectionFactory, const ChannelFactoryConstPtr &channelFactory, const ContactFactoryConstPtr &contactFactory)
Client::ChannelDispatchOperationInterface * | baseInterface () const
Protected Member Functions inherited from Tp::DBusProxy
void | setBusName (const QString &busName)
void | invalidate (const QString &reason, const QString &message)
void | invalidate (const QDBusError &error)
Protected Member Functions inherited from Tp::Object
| Object ()
void | notify (const char *propertyName)
Protected Member Functions inherited from Tp::ReadyObject
ReadinessHelper * | readinessHelper () const
Protected Member Functions inherited from Tp::OptionalInterfaceFactory< ChannelDispatchOperation >
void | setInterfaces (const QStringList &interfaces)

## Additional Inherited Members
Public Types inherited from Tp::OptionalInterfaceFactory< ChannelDispatchOperation >
enum | InterfaceSupportedChecking

## Detailed Description

The ChannelDispatchOperation class represents a Telepathy channel dispatch operation.

One of the channel dispatcher's functions is to offer incoming channels to Approver clients for approval. An approver should generally ask the user whether they want to participate in the requested communication channels (join the chat or chatroom, answer the call, accept the file transfer, or whatever is appropriate). A collection of channels offered in this way is represented by a ChannelDispatchOperation object.

If the user wishes to accept the communication channels, the approver should call handleWith() to indicate the user's or approver's preferred handler for the channels (the empty string indicates no particular preference, and will cause any suitable handler to be used).

If the user wishes to reject the communication channels, or if the user accepts the channels and the approver will handle them itself, the approver should call claim(). If the resulting PendingOperation succeeds, the approver immediately has control over the channels as their primary handler, and may do anything with them (in particular, it may close them in whatever way seems most appropriate).

There are various situations in which the channel dispatch operation will be closed, causing the DBusProxy::invalidated() signal to be emitted. If this happens, the approver should stop prompting the user.

Because all approvers are launched simultaneously, the user might respond to another approver; if this happens, the invalidated signal will be emitted with the error code TP_QT_ERROR_OBJECT_REMOVED.

If a channel closes, the signal channelLost() is emitted. If all channels close, there is nothing more to dispatch, so the invalidated signal will be emitted with the error code TP_QT_ERROR_OBJECT_REMOVED.

If the channel dispatcher crashes or exits, the invalidated signal will be emitted with the error code TP_QT_DBUS_ERROR_NAME_HAS_NO_OWNER. In a high-quality implementation, the dispatcher should be restarted, at which point it will create new channel dispatch operations for any undispatched channels, and the approver will be notified again.

## Constructor & Destructor Documentation

Tp::ChannelDispatchOperation::~ChannelDispatchOperation | ( |  | ) |
| virtual

Class destructor.

Tp::ChannelDispatchOperation::ChannelDispatchOperation | ( | const QDBusConnection & | bus,
|  | const QString & | objectPath,
|  | const QVariantMap & | immutableProperties,
|  | const QList< ChannelPtr > & | initialChannels,
|  | const AccountFactoryConstPtr & | accountFactory,
|  | const ConnectionFactoryConstPtr & | connectionFactory,
|  | const ChannelFactoryConstPtr & | channelFactory,
|  | const ContactFactoryConstPtr & | contactFactory
| ) |  |
| protected

Construct a new channel dispatch operation object using the given bus, the given factories and the given initial channels.

Parameters

  bus | QDBusConnection to use
  objectPath | The channel dispatch operation object path.
  immutableProperties | The channel dispatch operation immutable properties.
  initialChannels | The channels this CDO has initially (further tracking is done internally).
  accountFactory | The account factory to use.
  connectionFactory | The connection factory to use.
  channelFactory | The channel factory to use.
  contactFactory | The contact factory to use.

## Member Function Documentation

ChannelDispatchOperationPtr Tp::ChannelDispatchOperation::create | ( | const QDBusConnection & | bus,
|  | const QString & | objectPath,
|  | const QVariantMap & | immutableProperties,
|  | const QList< ChannelPtr > & | initialChannels,
|  | const AccountFactoryConstPtr & | accountFactory,
|  | const ConnectionFactoryConstPtr & | connectionFactory,
|  | const ChannelFactoryConstPtr & | channelFactory,
|  | const ContactFactoryConstPtr & | contactFactory
| ) |  |
| static

Create a new channel dispatch operation object using the given bus, the given factories and the given initial channels.

Parameters

  bus | QDBusConnection to use.
  objectPath | The channel dispatch operation object path.
  immutableProperties | The channel dispatch operation immutable properties.
  initialChannels | The channels this CDO has initially (further tracking is done internally).
  accountFactory | The account factory to use.
  connectionFactory | The connection factory to use.
  channelFactory | The channel factory to use.
  contactFactory | The contact factory to use.

Returns
  A ChannelDispatchOperationPtr object pointing to the newly created ChannelDispatchOperation object.

ConnectionPtr Tp::ChannelDispatchOperation::connection | ( |  | ) | const

Return the connection with which the channels for this dispatch operation are associated.

This method requires ChannelDispatchOperation::FeatureCore to be ready.

Returns
  A pointer to the Connection object.

AccountPtr Tp::ChannelDispatchOperation::account | ( |  | ) | const

Return the account with which the connection and channels for this dispatch operation are associated.

This method requires ChannelDispatchOperation::FeatureCore to be ready.

Returns
  A pointer to the Account object.

QList< ChannelPtr > Tp::ChannelDispatchOperation::channels | ( |  | ) | const

Return the channels to be dispatched.

This method requires ChannelDispatchOperation::FeatureCore to be ready.

Returns
  A list of pointers to Channel objects.

QStringList Tp::ChannelDispatchOperation::possibleHandlers | ( |  | ) | const

Return the well known bus names (starting with org.freedesktop.Telepathy.Client.) of the possible Handlers for this dispatch operation channels with the preferred handlers first.

As a result, approvers should use the first handler by default, unless they have a reason to do otherwise.

This method requires ChannelDispatchOperation::FeatureCore to be ready.

Returns
  List of possible handlers names.

PendingOperation * Tp::ChannelDispatchOperation::handleWith | ( | const QString & | handler | ) |

Called by an approver to accept a channel bundle and request that the given handler be used to handle it.

If successful, this method will cause the ChannelDispatchOperation object to disappear, emitting invalidated with error TP_QT_ERROR_OBJECT_REMOVED.

However, this method may fail because the dispatch has already been completed and the object has already gone. If this occurs, it indicates that another approver has asked for the bundle to be handled by a particular handler. The approver must not attempt to interact with the channels further in this case, unless it is separately invoked as the handler.

Approvers which are also channel handlers should use claim() instead of this method to request that they can handle a channel bundle themselves.

Parameters

  handler | The well-known bus name (starting with org.freedesktop.Telepathy.Client.) of the channel handler that should handle the channel, or an empty string if the client has no preferred channel handler.

Returns
  A PendingOperation which will emit PendingOperation::finished when the call has finished.

PendingOperation * Tp::ChannelDispatchOperation::claim | ( |  | ) |

Called by an approver to claim channels for closing them.

Returns
  A PendingOperation which will emit PendingOperation::finished when the call has finished.

PendingOperation * Tp::ChannelDispatchOperation::claim | ( | const AbstractClientHandlerPtr & | handler | ) |

Called by an approver to claim channels for handling internally. If this method is called successfully, the handler becomes the handler for the channel, but does not have the AbstractClientHandler::handleChannels() method called on it.

Approvers wishing to reject channels must call this method to claim ownership of them, and must not call requestClose() on the channels unless/until this method returns successfully.

The channel dispatcher can't know how best to close arbitrary channel types, so it leaves it up to the approver to do so. For instance, for text channels it is necessary to acknowledge any messages that have already been displayed to the user first - ideally, the approver would display and then acknowledge the messages - or to call Channel::requestClose() if the destructive behaviour of that method is desired.

Similarly, an approver for streamed media channels can close the channel with a reason (e.g. "busy") if desired. The channel dispatcher, which is designed to have no specific knowledge of particular channel types, can't do that.

If successful, this method will cause the ChannelDispatchOperation object to disappear, emitting Finished, in the same way as for handleWith().

This method may fail because the dispatch operation has already been completed. Again, see handleWith() for more details. The approver must not attempt to interact with the channels further in this case.

Parameters

  handler | The channel handler, that should remain registered during the lifetime of channels(), otherwise dispatching will fail if the channel dispatcher restarts.

Returns
  A PendingOperation which will emit PendingOperation::finished when the call has finished.

See Also
  claim(), handleWith()

void Tp::ChannelDispatchOperation::channelLost | ( | const Tp::ChannelPtr & | channel,
|  | const QString & | errorName,
|  | const QString & | errorMessage
| ) |  |
| signal

Emitted when a channel has closed before it could be claimed or handled. If this is emitted for the last remaining channel in a channel dispatch operation, it will immediately be followed by invalidated() with error TP_QT_ERROR_OBJECT_REMOVED.

Parameters

  channel | The channel that was closed.
  error | The name of a D-Bus error indicating why the channel closed.
  errorMessage | The error message.

Client::ChannelDispatchOperationInterface * Tp::ChannelDispatchOperation::baseInterface | ( |  | ) | const
| protected

Return the ChannelDispatchOperationInterface for this ChannelDispatchOperation class. This method is protected since the convenience methods provided by this class should always be used instead of the interface by users of the class.

Returns
  A pointer to the existing Client::ChannelDispatchOperationInterface object for this ChannelDispatchOperation object.

## Member Data Documentation

const Feature Tp::ChannelDispatchOperation::FeatureCore
| static

Feature representing the core that needs to become ready to make the ChannelDispatchOperation object usable.

Note that this feature must be enabled in order to use most ChannelDispatchOperation methods.

When calling isReady(), becomeReady(), this feature is implicitly added to the requested features.