Home · All Classes · All Namespaces · Modules · Functions · Files
Signals | Public Member Functions | Static Public Member Functions | Protected Member Functions
Tp::Client::ChannelInterfaceConferenceInterface Class Reference

#include <TelepathyQt4/Channel>

Inherits Tp::AbstractInterface.

List of all members.

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions


Detailed Description

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


Constructor & Destructor Documentation

Tp::Client::ChannelInterfaceConferenceInterface::ChannelInterfaceConferenceInterface ( const QString busName,
const QString objectPath,
QObject parent = 0 
)

Creates a ChannelInterfaceConferenceInterface 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.
Tp::Client::ChannelInterfaceConferenceInterface::ChannelInterfaceConferenceInterface ( const QDBusConnection connection,
const QString busName,
const QString objectPath,
QObject parent = 0 
)

Creates a ChannelInterfaceConferenceInterface 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.
Tp::Client::ChannelInterfaceConferenceInterface::ChannelInterfaceConferenceInterface ( Tp::DBusProxy proxy)

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

Parameters:
proxyThe proxy to use. It will also be the QObject::parent() for this object.
Tp::Client::ChannelInterfaceConferenceInterface::ChannelInterfaceConferenceInterface ( const Tp::Client::ChannelInterface mainInterface) [explicit]

Creates a ChannelInterfaceConferenceInterface associated with the same object as the given proxy. Additionally, the created proxy will have the same parent as the given proxy.

Parameters:
mainInterfaceThe proxy to use.
Tp::Client::ChannelInterfaceConferenceInterface::ChannelInterfaceConferenceInterface ( const Tp::Client::ChannelInterface mainInterface,
QObject parent 
)

Creates a ChannelInterfaceConferenceInterface associated with the same object as the given proxy. However, a different parent object can be specified.

Parameters:
mainInterfaceThe proxy to use.
parentPassed to the parent class constructor.

Member Function Documentation

static QLatin1String Tp::Client::ChannelInterfaceConferenceInterface::staticInterfaceName ( ) [inline, static]

Returns the name of the interface "org.freedesktop.Telepathy.Channel.Interface.Conference", which this class represents.

Returns:
The D-Bus interface name.
Tp::PendingVariant* Tp::Client::ChannelInterfaceConferenceInterface::requestPropertyChannels ( ) const [inline]

Asynchronous getter for the remote object property Channels of 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:
A pending variant which will emit finished when the property has been retrieved.
Tp::PendingVariant* Tp::Client::ChannelInterfaceConferenceInterface::requestPropertyInitialChannels ( ) const [inline]

Asynchronous getter for the remote object property InitialChannels of 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:
A pending variant which will emit finished when the property has been retrieved.
Tp::PendingVariant* Tp::Client::ChannelInterfaceConferenceInterface::requestPropertyInitialInviteeHandles ( ) const [inline]

Asynchronous getter for the remote object property InitialInviteeHandles of 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:
A pending variant which will emit finished when the property has been retrieved.
Tp::PendingVariant* Tp::Client::ChannelInterfaceConferenceInterface::requestPropertyInitialInviteeIDs ( ) const [inline]

Asynchronous getter for the remote object property InitialInviteeIDs of 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:
A pending variant which will emit finished when the property has been retrieved.
Tp::PendingVariant* Tp::Client::ChannelInterfaceConferenceInterface::requestPropertyInvitationMessage ( ) const [inline]

Asynchronous getter for the remote object property InvitationMessage of 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:
A pending variant which will emit finished when the property has been retrieved.
Tp::PendingVariant* Tp::Client::ChannelInterfaceConferenceInterface::requestPropertyOriginalChannels ( ) const [inline]

Asynchronous getter for the remote object property OriginalChannels of 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:
A pending variant which will emit finished when the property has been retrieved.
Tp::PendingVariantMap* Tp::Client::ChannelInterfaceConferenceInterface::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.
void Tp::Client::ChannelInterfaceConferenceInterface::ChannelMerged ( const QDBusObjectPath channel,
uint  channelSpecificHandle,
const QVariantMap &  properties 
) [signal]

Represents the signal ChannelMerged on the remote object.

Emitted when a new channel is added to the value of Channels .

Parameters:
channelThe channel that was added to Channels.
channelSpecificHandleA new channel-specific handle for the TargetHandle of Channel, as will appear in OriginalChannels, or 0 if a global handle is used for Channel's TargetHandle on the Group interface of this channel.
propertiesChannel's immutable properties.
void Tp::Client::ChannelInterfaceConferenceInterface::ChannelRemoved ( const QDBusObjectPath channel,
const QVariantMap &  details 
) [signal]

Represents the signal ChannelRemoved on the remote object.

Emitted when a channel is removed from the value of Channels , either because it closed or because it was split using the org.freedesktop.Telepathy.Channel.Interface.Splittable.DRAFT.Split method.

If a channel is removed because it was closed, ChannelInterface::Closed() should be emitted before this signal.

Parameters:
channelThe 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() , with the same semantics.
void Tp::Client::ChannelInterfaceConferenceInterface::invalidate ( Tp::DBusProxy proxy,
const QString error,
const QString message 
) [protected, virtual]

Reimplemented from Tp::AbstractInterface.


Copyright © 2008-2011 Collabora Ltd. and Nokia Corporation
Telepathy-Qt4 0.6.5