Home · Modules · All Classes · All Namespaces
Signals | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | List of all members
Tp::ChannelRequest Class Reference

The ChannelRequest class represents a Telepathy channel request. More...

#include <TelepathyQt/ChannelRequest>

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

Signals

void failed (const QString &errorName, const QString &errorMessage)
 
void succeeded (const Tp::ChannelPtr &channel)
 
- 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 ~ChannelRequest ()
 
AccountPtr account () const
 
QDateTime userActionTime () const
 
QString preferredHandler () const
 
QualifiedPropertyValueMapList requests () const
 
ChannelRequestHints hints () const
 
QVariantMap immutableProperties () const
 
PendingOperationcancel ()
 
ChannelPtr channel () const
 
- 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 PendingReadybecomeReady (const Features &requestedFeatures=Features())
 
virtual Features requestedFeatures () const
 
virtual Features actualFeatures () const
 
virtual Features missingFeatures () const
 
- Public Member Functions inherited from Tp::OptionalInterfaceFactory< ChannelRequest >
 OptionalInterfaceFactory (ChannelRequest *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 ChannelRequestPtr create (const QDBusConnection &bus, const QString &objectPath, const QVariantMap &immutableProperties, const AccountFactoryConstPtr &accountFactory, const ConnectionFactoryConstPtr &connectionFactory, const ChannelFactoryConstPtr &channelFactory, const ContactFactoryConstPtr &contactFactory)
 
static ChannelRequestPtr create (const AccountPtr &account, const QString &objectPath, const QVariantMap &immutableProperties)
 
- 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

 ChannelRequest (const QDBusConnection &bus, const QString &objectPath, const QVariantMap &immutableProperties, const AccountFactoryConstPtr &accountFactory, const ConnectionFactoryConstPtr &connectionFactory, const ChannelFactoryConstPtr &channelFactory, const ContactFactoryConstPtr &contactFactory)
 
 ChannelRequest (const AccountPtr &account, const QString &objectPath, const QVariantMap &immutableProperties)
 
Client::ChannelRequestInterfacebaseInterface () 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
ReadinessHelperreadinessHelper () const
 
- Protected Member Functions inherited from Tp::OptionalInterfaceFactory< ChannelRequest >
void setInterfaces (const QStringList &interfaces)
 

Additional Inherited Members

- Public Types inherited from Tp::OptionalInterfaceFactory< ChannelRequest >
enum  InterfaceSupportedChecking
 

Detailed Description

The ChannelRequest class represents a Telepathy channel request.

A channel request is an object in the channel dispatcher representing an ongoing request for some channels to be created or found. There can be any number of channel request objects at the same time.

A channel request can be cancelled by any client (not just the one that requested it). This means that the channel dispatcher will close the resulting channel, or refrain from requesting it at all, rather than dispatching it to a handler.

See Asynchronous Object Model

Constructor & Destructor Documentation

◆ ~ChannelRequest()

Tp::ChannelRequest::~ChannelRequest ( )
virtual

Class destructor.

◆ ChannelRequest() [1/2]

Tp::ChannelRequest::ChannelRequest ( const QDBusConnection &  bus,
const QString &  objectPath,
const QVariantMap &  immutableProperties,
const AccountFactoryConstPtr &  accountFactory,
const ConnectionFactoryConstPtr &  connectionFactory,
const ChannelFactoryConstPtr &  channelFactory,
const ContactFactoryConstPtr &  contactFactory 
)
protected

Construct a new channel request object using the given bus and the given factories.

Parameters
busQDBusConnection to use.
objectPathThe channel request object path.
accountFactoryThe account factory to use.
connectionFactoryThe connection factory to use.
channelFactoryThe channel factory to use.
contactFactoryThe contact factory to use.
immutablePropertiesThe immutable properties of the channel request.
Returns
A ChannelRequestPtr object pointing to the newly created ChannelRequest.

◆ ChannelRequest() [2/2]

Tp::ChannelRequest::ChannelRequest ( const AccountPtr &  account,
const QString &  objectPath,
const QVariantMap &  immutableProperties 
)
protected

Construct a new channel request object using the given account.

The constructed instance will use the factories from the account.

Parameters
accountAccount to use.
objectPathThe channel request object path.
immutablePropertiesThe immutable properties of the channel request.
Returns
A ChannelRequestPtr object pointing to the newly created ChannelRequest.

Member Function Documentation

◆ create() [1/2]

ChannelRequestPtr Tp::ChannelRequest::create ( const QDBusConnection &  bus,
const QString &  objectPath,
const QVariantMap &  immutableProperties,
const AccountFactoryConstPtr &  accountFactory,
const ConnectionFactoryConstPtr &  connectionFactory,
const ChannelFactoryConstPtr &  channelFactory,
const ContactFactoryConstPtr &  contactFactory 
)
static

Create a new channel request object using the given bus and the given factories.

Parameters
busQDBusConnection to use.
objectPathThe channel request object path.
immutablePropertiesThe channel request immutable properties.
accountFactoryThe account factory to use.
connectionFactoryThe connection factory to use.
channelFactoryThe channel factory to use.
contactFactoryThe contact factory to use.
Returns
A ChannelRequestPtr object pointing to the newly created ChannelRequest object.

◆ create() [2/2]

ChannelRequestPtr Tp::ChannelRequest::create ( const AccountPtr &  account,
const QString &  objectPath,
const QVariantMap &  immutableProperties 
)
static

Create a new channel request object for the given account.

The returned instance will use factories from the account.

Parameters
accountThe account that the request was made through.
objectPathThe channel request object path.
immutablePropertiesThe channel request immutable properties.
Returns
A ChannelRequestPtr object pointing to the newly created ChannelRequest object.

◆ account()

AccountPtr Tp::ChannelRequest::account ( ) const

Return the account on which this request was made.

This method can be used even before the ChannelRequest is ready, in which case the account object corresponding to the immutable properties is returned. In this case, the Account object is not necessarily ready either. This is useful for eg. matching ChannelRequests from ClientHandlerInterface::addRequest() with existing accounts in the application: either by object path, or if account factories are in use, even by object identity.

If the account is not provided in the immutable properties, this will only return a non-NULL AccountPtr once ChannelRequest::FeatureCore is ready on this object.

Returns
A pointer to the Account object.

◆ userActionTime()

QDateTime Tp::ChannelRequest::userActionTime ( ) const

Return the time at which the user action occurred, or 0 if this channel request is for some reason not involving user action.

Unix developers: this corresponds to the _NET_WM_USER_TIME property in EWMH.

This property is set when the channel request is created, and can never change.

This method can be used even before the ChannelRequest is ready: in this case, the user action time from the immutable properties, if any, is returned.

Returns
The time at which the user action occurred as QDateTime.

◆ preferredHandler()

QString Tp::ChannelRequest::preferredHandler ( ) const

Return either the well-known bus name (starting with org.freedesktop.Telepathy.Client.) of the preferred handler for this channel, or an empty string to indicate that any handler would be acceptable.

This property is set when the channel request is created, and can never change.

This method can be used even before the ChannelRequest is ready: in this case, the preferred handler from the immutable properties, if any, is returned.

Returns
The preferred handler, or an empty string if any handler would be acceptable.

◆ requests()

QualifiedPropertyValueMapList Tp::ChannelRequest::requests ( ) const

Return the desirable properties for the channel or channels to be created, as specified when placing the request in the first place.

This property is set when the channel request is created, and can never change.

This method can be used even before the ChannelRequest is ready: in this case, the requested channel properties from the immutable properties, if any, are returned. This is useful for e.g. matching ChannelRequests from ClientHandlerInterface::addRequest() with existing requests in the application (by the target ID or handle, most likely).

Returns
The requested desirable channel properties as a list of QualifiedPropertyValueMap objects.

◆ hints()

ChannelRequestHints Tp::ChannelRequest::hints ( ) const

Return the dictionary of metadata provided by the channel requester when requesting the channel.

This property is set when the channel request is created, and can never change.

This method can be used even before the ChannelRequest is ready: in this case, the requested channel properties from the immutable properties, if any, are returned. This is useful for e.g. matching ChannelRequests from ClientHandlerInterface::addRequest() with existing requests in the application (by the target ID or handle, most likely).

See also
Account::supportsRequestHints()
Returns
The hints in the request as a ChannelRequestHints object, if any.

◆ immutableProperties()

QVariantMap Tp::ChannelRequest::immutableProperties ( ) const

Return all of the immutable properties passed to this object when created.

This is useful for e.g. getting to domain-specific properties of channel requests.

Returns
The immutable properties as QVariantMap.

◆ cancel()

PendingOperation * Tp::ChannelRequest::cancel ( )

Cancel the channel request.

If failed() is emitted in response to this method, the error will be TP_QT_ERROR_CANCELLED.

If the channel has already been dispatched to a handler, then it's too late to call this method, and the channel request will no longer exist.

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

◆ channel()

ChannelPtr Tp::ChannelRequest::channel ( ) const

Return the Channel which this request succeeded with, if any.

This will only ever be populated if Account::requestsSucceedWithChannel() is true, and succeeded() has already been emitted on this ChannelRequest. Note that a PendingChannelRequest being successfully finished already implies succeeded() has been emitted.

Returns
A pointer to the Channel object, or a null ChannelPtr if there isn't any.

◆ failed

void Tp::ChannelRequest::failed ( const QString &  errorName,
const QString &  errorMessage 
)
signal

Emitted when the channel request has failed. No further methods must not be called on it.

Parameters
errorNameThe name of a D-Bus error.
errorMessageThe error message.
See also
succeeded()

◆ succeeded

void Tp::ChannelRequest::succeeded ( const Tp::ChannelPtr &  channel)
signal

Emitted when the channel request has succeeded. No further methods must not be called on it.

The channel parameter can be used to observe the channel resulting from the request (e.g. for it getting closed). The pointer may be NULL if the Channel Dispatcher implementation is too old. Whether a non-NULL channel can be expected can be checked with Account::requestsSucceedWithChannel().

If there is a channel, it will be of the subclass determined by and made ready (or not) according to the settings of the ChannelFactory on the Account the request was made through.

Parameters
channelPointer to a proxy for the resulting channel, if the Channel Dispatcher reported it.
See also
failed()

◆ baseInterface()

Client::ChannelRequestInterface * Tp::ChannelRequest::baseInterface ( ) const
protected

Return the ChannelRequestInterface for this ChannelRequest 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::ChannelRequestInterface object for this ChannelRequest object.

Member Data Documentation

◆ FeatureCore

const Feature Tp::ChannelRequest::FeatureCore
static

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

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

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