Tp::Service::ChannelInterfaceConferenceAdaptor Class Reference

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

Signals | Public Member Functions | List of all members
Tp::Service::ChannelInterfaceConferenceAdaptor Class Reference
Channel service implementation

`#include <TelepathyQt/_gen/svc-channel.h>`

Inherits Tp::AbstractAdaptor.

## Signals
void | ChannelMerged (const QDBusObjectPath &channel, uint channelSpecificHandle, const QVariantMap &properties)
void | ChannelRemoved (const QDBusObjectPath &channel, const QVariantMap &details)

## Public Member Functions
Tp::ObjectPathList | Channels () const
Tp::ObjectPathList | InitialChannels () const
Tp::UIntList | InitialInviteeHandles () const
QStringList | InitialInviteeIDs () const
QString | InvitationMessage () const
Tp::ChannelOriginatorMap | OriginalChannels () const
Public Member Functions inherited from Tp::AbstractAdaptor
| AbstractAdaptor (const QDBusConnection &connection, QObject *adaptee, QObject *parent)
| ~AbstractAdaptor ()
QDBusConnection | dbusConnection () const
QObject * | adaptee () const

## Detailed Description

Adaptor class providing a 1:1 mapping of the D-Bus interface "org.freedesktop.Telepathy.Channel.Interface.Conference".

## Member Function Documentation

Tp::ObjectPathList Tp::Service::ChannelInterfaceConferenceAdaptor::Channels | ( |  | ) | const

Return the value of the exported D-Bus object property `Channels` of type `Tp::ObjectPathList`.

Adaptees should export this property as a Qt property named 'channels' with type Tp::ObjectPathList.

The individual ChannelInterface s that are continued by this conference, which have the same ChannelInterface::ChannelType as this one, but with ChannelInterface::TargetHandleType = CONTACT.

This property MUST NOT be requestable; instead, the InitialChannels property may be specified when requesting a channel.

This is consistent with requesting InitialInviteeHandles and InitialInviteeIDs , rather than requesting ChannelInterfaceGroupInterface::Members and some hypothetical ID version of that property.

Change notification is via the ChannelMerged() and ChannelRemoved() signals.

Returns
  The value of exported property `Channels`.

Tp::ObjectPathList Tp::Service::ChannelInterfaceConferenceAdaptor::InitialChannels | ( |  | ) | const

Return the value of the exported D-Bus object property `InitialChannels` of type `Tp::ObjectPathList`.

Adaptees should export this property as a Qt property named 'initialChannels' with type Tp::ObjectPathList.

The initial value of Channels .

This property SHOULD be requestable. Omitting it from a request is equivalent to providing it with an empty list as value. Requests where its value has at least two channel paths SHOULD be expected to succeed on any implementation of this interface. If InitialInviteeHandles and InitialInviteeIDs are Allowed_Properties in ConnectionInterfaceRequestsInterface::RequestableChannelClasses , then requests with zero or one channel paths SHOULD also succeed; otherwise, clients SHOULD NOT make requests with zero or one paths for this property.

In GSM, a pair of calls can be merged into a conference, but you can't start a conference call from zero or one existing calls. In XMPP and MSN, you can create a new chatroom, or upgrade one 1-1 channel into a chatroom; however, on these protocols, it is also possible to fake GSM-style merging by upgrading the first channel, then inviting the targets of all the other channels into it.

If possible, the Channels ' states SHOULD NOT be altered by merging them into a conference. However, depending on the protocol, the Channels MAY be placed in a "frozen" state by placing them in this property's value or by calling org.freedesktop.Telepathy.Channel.Interface.MergeableConference.DRAFT.Merge on them.

In Jingle, nothing special will happen to merged calls. UIs MAY automatically place calls on hold before merging them, if that is the desired behaviour; this SHOULD always work. Not doing an implicit hold/unhold seems to preserve least-astonishment.

In GSM, the calls that are merged go into a state similar to Hold, but they cannot be unheld, only split from the conference call using org.freedesktop.Telepathy.Channel.Interface.Splittable.DRAFT.Split .

Depending on the protocol, it might be signalled to remote users that this channel is a continuation of all the requested channels, or that it is only a continuation of the first channel in the list.

In MSN, the conference steals the underlying switchboard (protocol construct) from one of its component channels, so the conference appears to remote users to be a continuation of that channel and no other. The connection manager has to make some arbitrary choice, so we arbitrarily mandate that it SHOULD choose the first channel in the list as the one to continue.

Returns
  The value of exported property `InitialChannels`.

Tp::UIntList Tp::Service::ChannelInterfaceConferenceAdaptor::InitialInviteeHandles | ( |  | ) | const

Return the value of the exported D-Bus object property `InitialInviteeHandles` of type `Tp::UIntList`.

Adaptees should export this property as a Qt property named 'initialInviteeHandles' with type Tp::UIntList.

A list of additional contacts invited to this conference when it was created.

If it is possible to invite new contacts when creating a conference (as opposed to merging several channels into one new conference channel), this property SHOULD be requestable, and appear in the allowed properties in ConnectionInterfaceRequestsInterface::RequestableChannelClasses . Otherwise, this property SHOULD NOT be requestable, and its value SHOULD always be the empty list.

On GSM you have to place a 1-1 call before you can merge it into a conference; on the other hand, you can invite new contacts to XMPP Muji calls and XMPP/MSN/Skype ad-hoc chat rooms without starting a 1-1 channel with them first.

If included in a request, the given contacts are automatically invited into the new channel, as if they had been added with ChannelInterfaceGroupInterface::AddMembers() (InitialInviteeHandles, InvitationMessage ) immediately after the channel was created.

This is a simple convenience API for the common case that a UI upgrades a 1-1 chat to a multi-user chat solely in order to invite someone else to participate.

If the local user was not the initiator of this channel, the ChannelInterfaceGroupInterface::SelfHandle SHOULD appear in the value of this property, together with any other contacts invited at the same time (if that information is known).

InitialInviteeHandles, InitialInviteeIDs and InitialChannels MAY be combined in a single request.

For example, if you have a 1-1 channel C1 with Rob, and you want to invite Sjoerd to join the discussion, you can do so by requesting a channel with InitialChannels=[C1] and InitialInviteeHandles=[sjoerd], or InitialChannels=[C1] and InitialInviteeIDs=["sjoerd@example.com"].

If a request includes some combination of InitialInviteeHandles, InitialInviteeIDs and InitialChannels, then the value of InitialInviteeHandles on the resulting channel SHOULD be the union of the handles from InitialInviteeHandles, the handles corresponding to the InitialInviteeIDs, and the target handles of the InitialChannels, with any duplicate handles removed. Because this property is immutable, its value SHOULD be computed before the channel is announced via the NewChannels signal.

This simplifies identification of new channels in clients - they only have to look at one of the properties, not both. For example, after either of the requests mentioned above, the NewChannels signal would announce the channel with InitialChannels=[C1], InitialInviteeHandles=[rob, sjoerd], and InitialInviteeIDs=["rob@example.net", "sjoerd.example.com"].

Returns
  The value of exported property `InitialInviteeHandles`.

QStringList Tp::Service::ChannelInterfaceConferenceAdaptor::InitialInviteeIDs | ( |  | ) | const

Return the value of the exported D-Bus object property `InitialInviteeIDs` of type `QStringList`.

Adaptees should export this property as a Qt property named 'initialInviteeIDs' with type QStringList.

A list of additional contacts invited to this conference when it was created.

This property SHOULD be requestable if and only if InitialInviteeHandles is requestable. Its semantics are the same, except that it takes a list of the string representations of contact handles; invitations are sent to any contact present in either or both of these properties.

When a channel is created, the values of InitialInviteeHandles and InitialInviteeIDs MUST correspond to each other. In particular, this means that the value of InitialInviteeIDs will include the TargetID of each channel in InitialChannels, and the ID corresponding to each handle in InitialInviteeHandles.

Returns
  The value of exported property `InitialInviteeIDs`.

QString Tp::Service::ChannelInterfaceConferenceAdaptor::InvitationMessage | ( |  | ) | const

Return the value of the exported D-Bus object property `InvitationMessage` of type `QString`.

Adaptees should export this property as a Qt property named 'invitationMessage' with type QString.

The message that was sent to the InitialInviteeHandles when they were invited.

This property SHOULD be requestable, and appear in the allowed properties in ConnectionInterfaceRequestsInterface::RequestableChannelClasses , in protocols where invitations can have an accompanying text message.

This allows invitations with a message to be sent when using InitialInviteeHandles or InitialInviteeIDs .

If the local user was not the initiator of this channel, the message with which they were invited (if any) SHOULD appear in the value of this property.

Returns
  The value of exported property `InvitationMessage`.

Tp::ChannelOriginatorMap Tp::Service::ChannelInterfaceConferenceAdaptor::OriginalChannels | ( |  | ) | const

Return the value of the exported D-Bus object property `OriginalChannels` of type `Tp::ChannelOriginatorMap`.

Adaptees should export this property as a Qt property named 'originalChannels' with type Tp::ChannelOriginatorMap.

On GSM conference calls, it is possible to have the same phone number in a conference twice; for instance, it could be the number of a corporate switchboard. This is represented using channel-specific handles; whether or not a channel uses channel-specific handles is reported in ChannelInterfaceGroupInterface::GroupFlags . The ChannelInterfaceGroupInterface::HandleOwners property specifies the mapping from opaque channel-specific handles to actual numbers; this property specifies the original 1-1 channel corresponding to each channel-specific handle in the conference.

In protocols where this situation cannot arise, such as XMPP, this property MAY remain empty.

For example, consider this situation:

1. Place a call (with path `/call/to/simon`) to the contact `+441234567890` (which is assigned the handle h, say), and ask to be put through to Simon McVittie;
2. Put that call on hold;
3. Place another call (with path `/call/to/jonny`) to `+441234567890`, and ask to be put through to Jonny Lamb;
4. Request a new channel with InitialChannels : `['/call/to/simon', '/call/to/jonny']`.

The new channel will have the following properties, for some handles s and j:

> `{
> ... ChannelInterfaceGroupInterface::GroupFlags : Channel_Specific_Handles | (other flags),
> ... ChannelInterfaceGroupInterface::Members : [self_handle, s, j],
> ... ChannelInterfaceGroupInterface::HandleOwners : { s: h, j: h },
> ... InitialChannels : ['/call/to/simon', '/call/to/jonny'],
> ... Channels : ['/call/to/simon', '/call/to/jonny'],
> ... OriginalChannels : { s: '/call/to/simon', j: '/call/to/jonny' },
> # ...standard properties like ChannelType: Group elided...
> }`

Change notification is via the ChannelMerged() and ChannelRemoved() signals: if Channel_Specific_Handle in the former is non-zero, this property SHOULD be updated to map that handle to the merged channel's path.

Returns
  The value of exported property `OriginalChannels`.

void Tp::Service::ChannelInterfaceConferenceAdaptor::ChannelMerged | ( | const QDBusObjectPath & | channel,
|  | uint | channelSpecificHandle,
|  | const QVariantMap & | properties
| ) |  |
| signal

Represents the exported D-Bus signal `ChannelMerged` on this object.

Adaptees should export this signal as a Qt signal with the following signature: void channelMerged(const QDBusObjectPath& channel, uint channelSpecificHandle, const QVariantMap& properties);

The adaptee signal will be automatically relayed as a D-Bus signal once emitted.

Parameters

  channel |
      The channel that was added to Channels.
  channelSpecificHandle |
      A new channel-specific handle for the TargetHandle of Channel, as
      will appear in OriginalChannels, or 0 if a global handle is used
      for Channel&apos;s TargetHandle on the Group interface of this
      channel.
  properties |
      Channel&apos;s immutable properties.

void Tp::Service::ChannelInterfaceConferenceAdaptor::ChannelRemoved | ( | const QDBusObjectPath & | channel,
|  | const QVariantMap & | details
| ) |  |
| signal

Represents the exported D-Bus signal `ChannelRemoved` on this object.

Adaptees should export this signal as a Qt signal with the following signature: void channelRemoved(const QDBusObjectPath& channel, const QVariantMap& details);

The adaptee signal will be automatically relayed as a D-Bus signal once emitted.

Parameters

  channel |
      The channel that was removed from Channels.
  details | Additional information about the removal, which may include the same well-known keys as the Details argument of \\\ ChannelInterfaceGroupInterface::MembersChangedDetailed() \\htmlonly , with the same semantics.