TelepathyQt4: ChannelDispatcherInterface Class Reference

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

# ChannelDispatcherInterface Class Reference

`#include <TelepathyQt4/ChannelDispatcher>`

Inherits Tp::AbstractInterface.

List of all members.

## Public Slots

- QDBusPendingReply
  < QDBusObjectPath > CreateChannel (const QDBusObjectPath &account, const QVariantMap &requestedProperties, qlonglong userActionTime, const QString &preferredHandler)
- QDBusPendingReply
  < QDBusObjectPath > EnsureChannel (const QDBusObjectPath &account, const QVariantMap &requestedProperties, qlonglong userActionTime, const QString &preferredHandler)

## 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)
- QStringList Interfaces () const TELEPATHY_GNUC_DEPRECATED

## Static Public Member Functions

- static const char * staticInterfaceName ()

## Protected Member Functions

- virtual void invalidate (Tp::DBusProxy *, const QString &, const QString &)

## Properties

- QStringList Interfaces

## Detailed Description

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

## Constructor & Destructor Documentation

ChannelDispatcherInterface | ( | const QString & | busName,
|  | const QString & | objectPath,
|  | QObject * | parent = `0` |
| ) |  |  |

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

Parameters:

  | busName | Name of the service the object is on.
  | objectPath | Path to the object on the service.
  | parent | Passed to the parent class constructor.

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:

  | connection | The bus via which the object can be reached.
  | busName | Name of the service the object is on.
  | objectPath | Path to the object on the service.
  | parent | Passed to the parent class constructor.

ChannelDispatcherInterface | ( | Tp::DBusProxy * | proxy | ) |

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

Parameters:

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

## Member Function Documentation

static const char* staticInterfaceName | ( |  | ) | `[inline, static]`

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

Returns:
  The D-Bus interface name.

QStringList Interfaces | ( |  | ) | const`[inline]`

Getter for the remote object property "Interfaces".

Don't use this: it blocks the main loop.

Returns:
  The value of the property, or a default-constructed value if the property is not readable.

QDBusPendingReply<QDBusObjectPath> CreateChannel | ( | const QDBusObjectPath & | account,
|  | const QVariantMap & | requestedProperties,
|  | qlonglong | userActionTime,
|  | const QString & | preferredHandler |
| ) |  |  | `[inline, slot]`

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

Start a request to create a channel. This initially just creates a <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> object, which can be used to continue the request and track its success or failure.

<tp:rationale>

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. </tp:rationale>

If this method is called for an Account that is disabled, invalid or otherwise unusable, no error is signalled until <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref> is called, at which point <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref> is emitted with an appropriate error.

<tp:rationale>

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. </tp:rationale>

Parameters:

  | account | The Account for which the new channel is to be created.
  | requestedProperties |

A dictionary containing desirable properties. This has the same semantics as the corresponding parameter to <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.

Certain properties will not necessarily make sense in this dictionary: for instance, <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> can only be given if the requester is able to interact with a <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> to the desired account.

Parameters:

  | userActionTime |

The time at which user action occurred, or 0 if this channel request is for some reason not involving user action. The <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref> property will be set to this value, and it will eventually be passed as the `User_Action_Time` parameter of <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>.

Parameters:

  | preferredHandler |

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. 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.

<tp:rationale>

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.

This is partly so the channel dispatcher can call <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> on it, and partly so the channel dispatcher can recover state if it crashes and is restarted. </tp:rationale>

If this is a well-known bus name and the handler has the Requests interface, the channel dispatcher SHOULD call <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Interface.Requests">AddRequest</tp:dbus-ref> on that Handler after this method has returned.

<tp:rationale>

This ordering allows a Handler which calls CreateChannel with itself as the preferred handler to associate the call to AddRequest with that call. </tp:rationale>

This is copied to the ChannelRequest that is returned, as the <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelRequest">PreferredHandler</tp:dbus-ref> property.

Returns:

A ChannelRequest object.

QDBusPendingReply<QDBusObjectPath> EnsureChannel | ( | const QDBusObjectPath & | account,
|  | const QVariantMap & | requestedProperties,
|  | qlonglong | userActionTime,
|  | const QString & | preferredHandler |
| ) |  |  | `[inline, slot]`

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

Start a request to ensure that a channel exists, creating it if necessary. This initially just creates a <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> 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 <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref> is called, at which point <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref> is emitted with an appropriate error.

<tp:rationale>

The rationale is as for <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatcher">CreateChannel</tp:dbus-ref>. </tp:rationale>

Parameters:

  | account | The Account for which the new channel is to be created.
  | requestedProperties |

A dictionary containing desirable properties. This has the same semantics as the corresponding parameter to <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>.

Certain properties will not necessarily make sense in this dictionary: for instance, <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> can only be given if the requester is able to interact with a <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> to the desired account.

Parameters:

  | userActionTime |

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

This parameter is used in the same way as the corresponding parameter to <tp:member-ref>CreateChannel</tp:member-ref>.

Parameters:

  | preferredHandler |

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. The behaviour and rationale are the same as for the corresponding parameter to <tp:member-ref>CreateChannel</tp:member-ref>, except as noted here.

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, <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref> returns `Yours=False`) 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.

<tp:rationale>

An address book application, for example, might call <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatcher">EnsureChannel</tp:dbus-ref> 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 <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatcher">EnsureChannel</tp:dbus-ref> in response to the user double-clicking an entry in the contact list, with itself as the `Preferred_Handler`; 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 `Preferred_Handler` is not used. </tp:rationale>

Returns:

A ChannelRequest object.

virtual void invalidate | ( | Tp::DBusProxy * | ,
|  | const QString & | ,
|  | const QString & |  |
| ) |  |  | `[protected, virtual]`

## Property Documentation

QStringList Interfaces`[read]`

Represents property "Interfaces" on the remote object.

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