Home · Modules · All Classes · All Namespaces
Public Slots | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
Tp::Client::ChannelDispatcherInterface Class Reference

#include <TelepathyQt/ChannelDispatcher>

Inheritance diagram for Tp::Client::ChannelDispatcherInterface:
Inheritance graph
[legend]

Public Slots

QDBusPendingReply< QDBusObjectPath > CreateChannel (const QDBusObjectPath &account, const QVariantMap &requestedProperties, qlonglong userActionTime, const QString &preferredHandler, int timeout=-1)
 
QDBusPendingReply< QDBusObjectPath > EnsureChannel (const QDBusObjectPath &account, const QVariantMap &requestedProperties, qlonglong userActionTime, const QString &preferredHandler, int timeout=-1)
 
QDBusPendingReply< QDBusObjectPath > CreateChannelWithHints (const QDBusObjectPath &account, const QVariantMap &requestedProperties, qlonglong userActionTime, const QString &preferredHandler, const QVariantMap &hints, int timeout=-1)
 
QDBusPendingReply< QDBusObjectPath > EnsureChannelWithHints (const QDBusObjectPath &account, const QVariantMap &requestedProperties, qlonglong userActionTime, const QString &preferredHandler, const QVariantMap &hints, int timeout=-1)
 
QDBusPendingReply< Tp::ObjectPathList, Tp::NotDelegatedMapDelegateChannels (const Tp::ObjectPathList &channels, qlonglong userActionTime, const QString &preferredHandler, int timeout=-1)
 
QDBusPendingReply PresentChannel (const QDBusObjectPath &channel, qlonglong userActionTime, int timeout=-1)
 

Public Member Functions

 ChannelDispatcherInterface (const QString &busName, const QString &objectPath, QObject *parent=0)
 
 ChannelDispatcherInterface (const QDBusConnection &connection, const QString &busName, const QString &objectPath, QObject *parent=0)
 
 ChannelDispatcherInterface (Tp::DBusProxy *proxy)
 
Tp::PendingVariantrequestPropertyInterfaces () const
 
Tp::PendingVariantrequestPropertySupportsRequestHints () const
 
Tp::PendingVariantMaprequestAllProperties () const
 
- Public Member Functions inherited from Tp::AbstractInterface
virtual ~AbstractInterface ()
 
bool isValid () const
 
QString invalidationReason () const
 
QString invalidationMessage () const
 
void setMonitorProperties (bool monitorProperties)
 
bool isMonitoringProperties () const
 

Static Public Member Functions

static QLatin1String staticInterfaceName ()
 

Protected Member Functions

virtual void invalidate (Tp::DBusProxy *, const QString &, const QString &)
 
- Protected Member Functions inherited from Tp::AbstractInterface
 AbstractInterface (DBusProxy *proxy, const QLatin1String &interface)
 
 AbstractInterface (const QString &busName, const QString &path, const QLatin1String &interface, const QDBusConnection &connection, QObject *parent)
 
PendingVariantinternalRequestProperty (const QString &name) const
 
PendingOperationinternalSetProperty (const QString &name, const QVariant &newValue)
 
PendingVariantMapinternalRequestAllProperties () const
 

Additional Inherited Members

- Signals inherited from Tp::AbstractInterface
void propertiesChanged (const QVariantMap &changedProperties, const QStringList &invalidatedProperties)
 
- Protected Slots inherited from Tp::AbstractInterface

Detailed Description

Proxy class providing a 1:1 mapping of the D-Bus interface "org.freedesktop.Telepathy.ChannelDispatcher".

Constructor & Destructor Documentation

◆ ChannelDispatcherInterface() [1/3]

Tp::Client::ChannelDispatcherInterface::ChannelDispatcherInterface ( const QString &  busName,
const QString &  objectPath,
QObject *  parent = 0 
)

Creates a ChannelDispatcherInterface associated with the given object on the session bus.

Parameters
busNameName of the service the object is on.
objectPathPath to the object on the service.
parentPassed to the parent class constructor.

◆ ChannelDispatcherInterface() [2/3]

Tp::Client::ChannelDispatcherInterface::ChannelDispatcherInterface ( const QDBusConnection &  connection,
const QString &  busName,
const QString &  objectPath,
QObject *  parent = 0 
)

Creates a ChannelDispatcherInterface associated with the given object on the given bus.

Parameters
connectionThe bus via which the object can be reached.
busNameName of the service the object is on.
objectPathPath to the object on the service.
parentPassed to the parent class constructor.

◆ ChannelDispatcherInterface() [3/3]

Tp::Client::ChannelDispatcherInterface::ChannelDispatcherInterface ( Tp::DBusProxy proxy)

Creates a ChannelDispatcherInterface associated with the same object as the given proxy.

Parameters
proxyThe proxy to use. It will also be the QObject::parent() for this object.

Member Function Documentation

◆ staticInterfaceName()

static QLatin1String Tp::Client::ChannelDispatcherInterface::staticInterfaceName ( )
inlinestatic

Returns the name of the interface "org.freedesktop.Telepathy.ChannelDispatcher", which this class represents.

Returns
The D-Bus interface name.

◆ requestPropertyInterfaces()

Tp::PendingVariant* Tp::Client::ChannelDispatcherInterface::requestPropertyInterfaces ( ) const
inline

Asynchronous getter for the remote object property Interfaces of type QStringList.

A list of the extra interfaces provided by this channel dispatcher.

Returns
A pending variant which will emit finished when the property has been retrieved.

◆ requestPropertySupportsRequestHints()

Tp::PendingVariant* Tp::Client::ChannelDispatcherInterface::requestPropertySupportsRequestHints ( ) const
inline

Asynchronous getter for the remote object property SupportsRequestHints of type bool.

If True, the channel dispatcher is new enough to support CreateChannelWithHints and EnsureChannelWithHints, in addition to the older CreateChannel and EnsureChannel methods, and also new enough to emit SucceededWithChannel before the older Succeeded signal. If False or missing, only the metadata-less variants are supported.

Returns
A pending variant which will emit finished when the property has been retrieved.

◆ requestAllProperties()

Tp::PendingVariantMap* Tp::Client::ChannelDispatcherInterface::requestAllProperties ( ) const
inline

Request all of the DBus properties on the interface.

Returns
A pending variant map which will emit finished when the properties have been retrieved.

◆ CreateChannel

QDBusPendingReply<QDBusObjectPath> Tp::Client::ChannelDispatcherInterface::CreateChannel ( const QDBusObjectPath &  account,
const QVariantMap &  requestedProperties,
qlonglong  userActionTime,
const QString &  preferredHandler,
int  timeout = -1 
)
inlineslot

Begins a call to the D-Bus method CreateChannel on the remote object.

Equivalent to calling CreateChannelWithHints() with an empty Hints parameter.

Note that timeout is ignored as of now. It will be used once http://bugreports.qt.nokia.com/browse/QTBUG-11775 is fixed.

Parameters
account
The Account for which the new channel is to be created.
requestedProperties
\htmlonly
<p>A dictionary containing desirable properties.</p>

<p>This parameter is used in the same way as the corresponding
  parameter to
   \endhtmlonly CreateChannelWithHints() \htmlonly .</p>
\endhtmlonly
userActionTime
\htmlonly
<p>The time at which user action occurred, or 0 if this channel
  request is for some reason not involving user action.</p>

<p>This parameter is used in the same way as the corresponding
  parameter to
   \endhtmlonly CreateChannelWithHints() \htmlonly .</p>
\endhtmlonly
preferredHandler
\htmlonly
<p>Either the well-known bus name (starting with
  <code>org.freedesktop.Telepathy.Client.</code>)
  of the preferred handler for this
  channel, or an empty string to indicate that any handler would be
  acceptable.</p>

<p>This parameter is used in the same way as the corresponding
  parameter to
   \endhtmlonly CreateChannelWithHints() \htmlonly .</p>
\endhtmlonly
timeoutThe timeout in milliseconds.
Returns
A ChannelRequest object.

◆ EnsureChannel

QDBusPendingReply<QDBusObjectPath> Tp::Client::ChannelDispatcherInterface::EnsureChannel ( const QDBusObjectPath &  account,
const QVariantMap &  requestedProperties,
qlonglong  userActionTime,
const QString &  preferredHandler,
int  timeout = -1 
)
inlineslot

Begins a call to the D-Bus method EnsureChannel on the remote object.

Equivalent to calling EnsureChannelWithHints() with an empty Hints parameter.

Note that timeout is ignored as of now. It will be used once http://bugreports.qt.nokia.com/browse/QTBUG-11775 is fixed.

Parameters
account
The Account for which the new channel is to be created.
requestedProperties
\htmlonly
<p>A dictionary containing desirable properties.</p>

<p>This parameter is used in the same way as the corresponding
  parameter to
   \endhtmlonly CreateChannelWithHints() \htmlonly .</p>
\endhtmlonly
userActionTime
\htmlonly
<p>The time at which user action occurred, or 0 if this channel
  request is for some reason not involving user action.</p>

<p>This parameter is used in the same way as the corresponding
  parameter to
   \endhtmlonly CreateChannelWithHints() \htmlonly .</p>
\endhtmlonly
preferredHandler
\htmlonly
<p>Either the well-known bus name (starting with
  <code>org.freedesktop.Telepathy.Client.</code>)
  of the preferred handler for this
  channel, or an empty string to indicate that any handler would be
  acceptable. The behaviour and rationale are the same as for the
  corresponding parameter to
   \endhtmlonly EnsureChannelWithHints() \htmlonly .</p>
\endhtmlonly
timeoutThe timeout in milliseconds.
Returns
A ChannelRequest object.

◆ CreateChannelWithHints

QDBusPendingReply<QDBusObjectPath> Tp::Client::ChannelDispatcherInterface::CreateChannelWithHints ( const QDBusObjectPath &  account,
const QVariantMap &  requestedProperties,
qlonglong  userActionTime,
const QString &  preferredHandler,
const QVariantMap &  hints,
int  timeout = -1 
)
inlineslot

Begins a call to the D-Bus method CreateChannelWithHints on the remote object.

Start a request to create a channel. This initially just creates a ChannelRequestInterface object, which can be used to continue the request and track its success or failure.

The request can take a long time - in the worst case, the channel dispatcher has to ask the account manager to put the account online, the account manager has to ask the operating system to obtain an Internet connection, and the operating system has to ask the user whether to activate an Internet connection using an on-demand mechanism like dialup.

This means that using a single D-Bus method call and response to represent the whole request will tend to lead to that call timing out, which is not the behaviour we want.

If this method is called for an Account that is disabled, invalid or otherwise unusable, no error is signalled until ChannelRequestInterface::Proceed() is called, at which point ChannelRequestInterface::Failed() is emitted with an appropriate error.

This means there's only one code path for errors, apart from InvalidArgument for "that request makes no sense".

It also means that the request will proceed if the account is enabled after calling CreateChannel, but before calling Proceed.

Note that timeout is ignored as of now. It will be used once http://bugreports.qt.nokia.com/browse/QTBUG-11775 is fixed.

Parameters
account
The Account for which the new channel is to be created.
requestedProperties
\htmlonly
<p>A dictionary containing desirable properties. This has the same
  semantics as the corresponding parameter to
   \endhtmlonly ConnectionInterfaceRequestsInterface::CreateChannel() \htmlonly .
</p>

<p>Certain properties will not necessarily make sense in this
  dictionary: for instance,
   \endhtmlonly \link ChannelInterface::requestPropertyTargetHandle() ChannelInterface::TargetHandle \endlink \htmlonly 
  can only be given if the requester is able to interact with a
   \endhtmlonly ConnectionInterface \htmlonly 
  to the desired account.</p>
\endhtmlonly
userActionTime
\htmlonly
<p>The time at which user action occurred, or 0 if this channel
  request is for some reason not involving user action.
  The  \endhtmlonly \link ChannelRequestInterface::requestPropertyUserActionTime() ChannelRequestInterface::UserActionTime \endlink \htmlonly 
  property will be set to this value, and it will eventually be
  passed as the <code>User_Action_Time</code> parameter of  \endhtmlonly ClientHandlerInterface::HandleChannels() \htmlonly .</p>
\endhtmlonly
preferredHandler
\htmlonly
<p>Either the well-known bus name (starting with
  <code>org.freedesktop.Telepathy.Client.</code>)
  of the preferred handler for this
  channel, or an empty string to indicate that any handler would be
  acceptable. The channel dispatcher SHOULD dispatch as many as
  possible of the resulting channels (ideally, all of them)
  to that handler—irrespective of whether that handler's  \endhtmlonly \link ClientHandlerInterface::requestPropertyHandlerChannelFilter() ClientHandlerInterface::HandlerChannelFilter \endlink \htmlonly 
  matches the channel—and SHOULD remember the preferred handler
  so it can try to dispatch subsequent channels in the same bundle
  to the same handler.</p>

<div class="rationale">
  <p>This must be the well-known bus name, not the unique name,
    to ensure that all handlers do indeed have the Client API,
    and the Client object on the handler can be located easily.</p>

  <p>This is partly so the channel dispatcher can call
     \endhtmlonly ClientHandlerInterface::HandleChannels() \htmlonly 
    on it, and partly so the channel dispatcher
    can recover state if it crashes and is restarted.</p>

  <p>The filter should be disregarded for ease of use of this
    interface: clients will usually use this argument to request
    channels be sent to themself, and this should trump the filter
    not matching. This also allows a client to become the handler
    for a channel produced by one of its own requests, while not
    being a candidate to handle other channels of that type.</p>
</div>

<p>If this is a well-known bus name and the handler has the
  Requests interface, the channel dispatcher SHOULD
  call  \endhtmlonly ClientInterfaceRequestsInterface::AddRequest() \htmlonly 
  on that Handler after this method has returned.</p>

<div class="rationale">
  <p>This ordering allows a Handler which calls CreateChannel with
    itself as the preferred handler to associate the call to
    AddRequest with that call.</p>
</div>

<p>This is copied to the ChannelRequest that is returned,
  as the  \endhtmlonly \link ChannelRequestInterface::requestPropertyPreferredHandler() ChannelRequestInterface::PreferredHandler \endlink \htmlonly 
  property.</p>
\endhtmlonly
hints
Additional information about the channel request, which will be 
used as the value for the resulting request&apos;s Hints property. 
See the Hints property&apos;s documentation for rationale.
timeoutThe timeout in milliseconds.
Returns
A ChannelRequest object.

◆ EnsureChannelWithHints

QDBusPendingReply<QDBusObjectPath> Tp::Client::ChannelDispatcherInterface::EnsureChannelWithHints ( const QDBusObjectPath &  account,
const QVariantMap &  requestedProperties,
qlonglong  userActionTime,
const QString &  preferredHandler,
const QVariantMap &  hints,
int  timeout = -1 
)
inlineslot

Begins a call to the D-Bus method EnsureChannelWithHints on the remote object.

Start a request to ensure that a channel exists, creating it if necessary. This initially just creates a ChannelRequestInterface object, which can be used to continue the request and track its success or failure.

If this method is called for an Account that is disabled, invalid or otherwise unusable, no error is signalled until ChannelRequestInterface::Proceed() is called, at which point ChannelRequestInterface::Failed() is emitted with an appropriate error.

Note that timeout is ignored as of now. It will be used once http://bugreports.qt.nokia.com/browse/QTBUG-11775 is fixed.

Parameters
account
The Account for which the new channel is to be created.
requestedProperties
\htmlonly
<p>A dictionary containing desirable properties. This has the same
  semantics as the corresponding parameter to
   \endhtmlonly ConnectionInterfaceRequestsInterface::EnsureChannel() \htmlonly .
</p>

<p>Certain properties will not necessarily make sense in this
  dictionary: for instance,
   \endhtmlonly \link ChannelInterface::requestPropertyTargetHandle() ChannelInterface::TargetHandle \endlink \htmlonly 
  can only be given if the requester is able to interact with a
   \endhtmlonly ConnectionInterface \htmlonly 
  to the desired account.</p>
\endhtmlonly
userActionTime
\htmlonly
<p>The time at which user action occurred, or 0 if this channel
  request is for some reason not involving user action.</p>

<p>This parameter is used in the same way as the corresponding
  parameter to
   \endhtmlonly CreateChannelWithHints() \htmlonly .</p>
\endhtmlonly
preferredHandler
\htmlonly
<p>Either the well-known bus name (starting with
  <code>org.freedesktop.Telepathy.Client.</code>)
  of the preferred handler for this
  channel, or an empty string to indicate that any handler would be
  acceptable. The behaviour and rationale are the same as for the
  corresponding parameter to
   \endhtmlonly CreateChannelWithHints() \htmlonly , except
  as noted here.</p>

<p>If any new channels are created in response to this
  request, the channel dispatcher SHOULD dispatch as many as
  possible of the resulting channels (ideally, all of them)
  to that handler, and SHOULD remember the preferred handler
  so it can try to dispatch subsequent channels in the same bundle
  to the same handler. If the requested channel already exists (that
  is,  \endhtmlonly ConnectionInterfaceRequestsInterface::EnsureChannel() \htmlonly 
  returns <code>Yours=False</code>) then the channel dispatcher
  SHOULD re-dispatch the channel to its existing handler, and MUST
  NOT dispatch it to this client (unless it is the existing handler);
  the request is still deemed to have succeeded in this case.</p>

<div class="rationale">
  <p>An address book application, for example, might call  \endhtmlonly ChannelDispatcherInterface::EnsureChannel() \htmlonly 
    to ensure that a text channel with a particular contact is
    displayed to the user; it does not care whether a new channel was
    made. An IM client might call  \endhtmlonly ChannelDispatcherInterface::EnsureChannel() \htmlonly 
    in response to the user double-clicking an entry in the contact
    list, with itself as the <code>Preferred_Handler</code>; if the
    user already has a conversation with that contact in another
    application, they would expect the existing window to be
    presented, rather than their double-click leading to an error
    message.  So the request should succeed, even if its
    <code>Preferred_Handler</code> is not used.</p>
</div>
\endhtmlonly
hints
Additional information about the channel request, which will be 
used as the value for the resulting request&apos;s Hints property.
timeoutThe timeout in milliseconds.
Returns
A ChannelRequest object.

◆ DelegateChannels

QDBusPendingReply<Tp::ObjectPathList, Tp::NotDelegatedMap> Tp::Client::ChannelDispatcherInterface::DelegateChannels ( const Tp::ObjectPathList channels,
qlonglong  userActionTime,
const QString &  preferredHandler,
int  timeout = -1 
)
inlineslot

Begins a call to the D-Bus method DelegateChannels on the remote object.

Called by a ClientHandlerInterface to redispatch a bunch of channels it is currently handling.

For each Channel in Channels, if another ClientHandlerInterface can be found, ClientHandlerInterface::HandleChannels() will be called on it until a ClientHandlerInterface accepts it.

This method returns once all the Channels have either been accepted or rejected by Handlers.

If this method fails, the original ClientHandlerInterface is still handling the channels.

Note that timeout is ignored as of now. It will be used once http://bugreports.qt.nokia.com/browse/QTBUG-11775 is fixed.

Parameters
channels
\htmlonly
<p>The list of channels to redispatch. The caller has to be the current
   \endhtmlonly ClientHandlerInterface \htmlonly 
  of all of these channels
</p>
\endhtmlonly
userActionTime
\htmlonly
<p>The time at which user action occurred, or 0 if this channels
  delegation is for some reason not involving user action.</p>

<p>This parameter is used in the same way as the corresponding
  parameter to
   \endhtmlonly CreateChannelWithHints() \htmlonly .</p>
\endhtmlonly
preferredHandler
\htmlonly
<p>Either the well-known bus name (starting with
  <code>org.freedesktop.Telepathy.Client.</code>)
  of the preferred new handler for these
  channels, or an empty string to indicate that any handler would be
  acceptable. The behaviour and rationale are the same as for the
  corresponding parameter to
   \endhtmlonly CreateChannelWithHints() \htmlonly .</p>
\endhtmlonly
timeoutThe timeout in milliseconds.
Returns
\htmlonly
<p>The list of channels which have been delegated; the caller is no
longer handling these channels.</p>

<p>The client should remove these channels from its
 \endhtmlonly \link ClientHandlerInterface::requestPropertyHandledChannels() ClientHandlerInterface::HandledChannels \endlink \htmlonly 
property.</p>
\endhtmlonly
\htmlonly
<p>The list of channels which have NOT been delegated; the caller is still
handling these channels.</p>
\endhtmlonly

◆ PresentChannel

QDBusPendingReply Tp::Client::ChannelDispatcherInterface::PresentChannel ( const QDBusObjectPath &  channel,
qlonglong  userActionTime,
int  timeout = -1 
)
inlineslot

Begins a call to the D-Bus method PresentChannel on the remote object.

Equivalent of calling ChannelDispatcherInterface::EnsureChannel() with a Requested_Properties which would result in ensuring Channel.

If Channel is handled, its handler will be asked to present it the user (e.g. bring it into the foreground).

Note that timeout is ignored as of now. It will be used once http://bugreports.qt.nokia.com/browse/QTBUG-11775 is fixed.

Parameters
channel
\htmlonly
<p>The channel to present.</p>
\endhtmlonly
userActionTime
\htmlonly
<p>The time at which user action occurred, or 0 if this channel
  request is for some reason not involving user action.</p>

<p>This parameter is used in the same way as the corresponding
  parameter to
   \endhtmlonly EnsureChannelWithHints() \htmlonly .</p>
\endhtmlonly
timeoutThe timeout in milliseconds.

◆ invalidate()

void Tp::Client::ChannelDispatcherInterface::invalidate ( Tp::DBusProxy proxy,
const QString &  error,
const QString &  message 
)
protectedvirtual

Reimplemented from Tp::AbstractInterface.