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

Classes | Signals | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions

# Tp::Channel Class Reference
[Channel proxies]

The Channel class provides an object representing a Telepathy channel. More...

`#include <TelepathyQt4/Channel>`

Inherits Tp::StatefulDBusProxy, OptionalInterfaceFactory< Channel >, Tp::ReadyObject, and Tp::RefCounted.

Inherited by Tp::ContactSearchChannel, Tp::FileTransferChannel, Tp::RoomListChannel, Tp::StreamedMediaChannel, and Tp::TextChannel.

List of all members.

## Classes

- class GroupMemberChangeDetails

## Signals

- void groupCanAddContactsChanged (bool canAddContacts)
- void groupCanRemoveContactsChanged (bool canRemoveContacts)
- void groupCanRescindContactsChanged (bool canRescindContacts)
- void groupHandleOwnersChanged (const Tp::HandleOwnerMap &owners, const Tp::UIntList &added, const Tp::UIntList &removed)
- void conferenceChannelMerged (const Tp::ChannelPtr &channel)
- void conferenceChannelRemoved (const Tp::ChannelPtr &channel)
- void conferenceChannelRemoved (const Tp::ChannelPtr &channel, const Tp::Channel::GroupMemberChangeDetails &details)

## Public Member Functions

- virtual ~Channel ()
- ConnectionPtr connection () const
- QVariantMap immutableProperties () const
- QString channelType () const
- uint targetHandleType () const
- uint targetHandle () const
- bool isRequested () const
- ContactPtr initiatorContact () const
- PendingOperation * requestClose ()
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelInterfaceAnonymityInterface * anonymityInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelInterfaceConferenceInterface * conferenceInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelInterfaceMessagesInterface * messagesInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelInterfaceServicePointInterface * servicePointInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelInterfaceTubeInterface * tubeInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelTypeContactSearchInterface * contactSearchInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelTypeServerTLSConnectionInterface * serverTLSConnectionInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelTypeFileTransferInterface * fileTransferInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelTypeStreamTubeInterface * streamTubeInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const

## Static Public Member Functions

- static ChannelPtr create (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties)

## Static Public Attributes

- static const Feature FeatureCore
- static const Feature FeatureConferenceInitialInviteeContacts

## Protected Member Functions

- Channel (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties)
- void connectNotify (const char *)

## Group interface

Cached access to state of the group interface on the associated remote object, if the interface is present. Almost all methods return undefined values if the list returned by interfaces() doesn't include TELEPATHY_INTERFACE_CHANNEL_INTERFACE_GROUP or if the object is not ready.

Some methods can be used when targetHandleType() == HandleTypeContact, such as groupFlags(), groupCanAddContacts(), groupCanRemoveContacts(), groupSelfContact() and groupContacts().

As the Group interface state can change freely during the lifetime of the channel due to events like new contacts joining the group, the cached state is automatically kept in sync with the remote object's state by hooking to the change notification signals present in the D-Bus interface.

As the cached value changes, change notification signals are emitted.

Signals are emitted to indicate that properties have changed, for groupMembersChanged(), groupSelfContactChanged(), etc.

Check the individual signals' descriptions for details.

- uint groupFlags () const
- bool groupCanAddContacts () const
- bool groupCanAddContactsWithMessage () const
- bool groupCanAcceptContactsWithMessage () const
- PendingOperation * groupAddContacts (const QList< ContactPtr > &contacts, const QString &message=QString())
- bool groupCanRescindContacts () const
- bool groupCanRescindContactsWithMessage () const
- bool groupCanRemoveContacts () const
- bool groupCanRemoveContactsWithMessage () const
- bool groupCanRejectContactsWithMessage () const
- bool groupCanDepartWithMessage () const
- PendingOperation * groupRemoveContacts (const QList< ContactPtr > &contacts, const QString &message=QString(), uint reason=ChannelGroupChangeReasonNone)
- Contacts groupContacts () const
- Contacts groupLocalPendingContacts () const
- Contacts groupRemotePendingContacts () const
- GroupMemberChangeDetails groupLocalPendingContactChangeInfo (const ContactPtr &contact) const
- GroupMemberChangeDetails groupSelfContactRemoveInfo () const
- bool groupAreHandleOwnersAvailable () const
- HandleOwnerMap groupHandleOwners () const
- bool groupIsSelfContactTracked () const
- ContactPtr groupSelfContact () const
- TELEPATHY_QT4_DEPRECATED bool hasConferenceInterface () const
- bool isConference () const
- Contacts conferenceInitialInviteeContacts () const
- TELEPATHY_QT4_DEPRECATED bool conferenceSupportsNonMerges () const
- QList< ChannelPtr > conferenceChannels () const
- QList< ChannelPtr > conferenceInitialChannels () const
- QHash< uint, ChannelPtr > conferenceOriginalChannels () const
- TELEPATHY_QT4_DEPRECATED bool hasMergeableConferenceInterface () const
- bool supportsConferenceMerging () const
- PendingOperation * conferenceMergeChannel (const ChannelPtr &channel)
- TELEPATHY_QT4_DEPRECATED bool hasSplittableInterface () const
- bool supportsConferenceSplitting () const
- TELEPATHY_QT4_DEPRECATED
  PendingOperation * splitChannel ()
- PendingOperation * conferenceSplitChannel ()
- void groupFlagsChanged (uint flags, uint added, uint removed)
- void groupMembersChanged (const Tp::Contacts &groupMembersAdded, const Tp::Contacts &groupLocalPendingMembersAdded, const Tp::Contacts &groupRemotePendingMembersAdded, const Tp::Contacts &groupMembersRemoved, const Tp::Channel::GroupMemberChangeDetails &details)
- void groupSelfContactChanged ()
- bool groupSelfHandleIsLocalPending () const
- PendingOperation * groupAddSelfHandle ()

## Optional interface proxy factory

Factory functions fabricating proxies for optional Channel interfaces and interfaces for specific channel types.

- TELEPATHY_QT4_DEPRECATED
  Client::DBus::PropertiesInterface * propertiesInterface () const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelInterfaceCallStateInterface * callStateInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelInterfaceChatStateInterface * chatStateInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelInterfaceDTMFInterface * DTMFInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelInterfaceHoldInterface * holdInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelInterfaceMediaSignallingInterface * mediaSignallingInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelInterfacePasswordInterface * passwordInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- template<class Interface > Interface * typeInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelTypeRoomListInterface * roomListInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelTypeStreamedMediaInterface * streamedMediaInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelTypeTextInterface * textInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelTypeTubesInterface * tubesInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
- Client::ChannelInterface * baseInterface () const
- TELEPATHY_QT4_DEPRECATED
  Client::ChannelInterfaceGroupInterface * groupInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const

## Detailed Description

The Channel class provides an object representing a Telepathy channel.

All communication in the Telepathy framework is carried out via channel objects which are created and managed by connections. Specialized classes for some specific channel types such as StreamedMediaChannel, TextChannel, FileTransferChannel are provided.

It adds the following features compared to using Client::ChannelInterface directly:

- Life cycle tracking
- Getting the channel type, handle type, handle and interfaces automatically
- High-level methods for the Group/Conference/MergeableConference/Splittable interfaces
- A fake group implementation when handle type is HandleTypeContact

The remote object state accessor functions on this object (interfaces(), channelType(), targetHandleType(), targetHandle(), requested(), initiatorContact(), and so on) don't make any D-Bus calls; instead, they return/use values cached from a previous introspection run. The introspection process populates their values in the most efficient way possible based on what the service implements. Their return value is mostly undefined until the introspection process is completed, i.e. isReady() returns true. See the individual accessor descriptions for more details.

Additionally, the state of the group interface on the remote object (if present) will be cached in the introspection process, and also tracked for any changes.

To avoid unnecessary D-Bus traffic, some methods only return valid information after a specific feature has been enabled by calling becomeReady() with the desired set of features as an argument, and waiting for the resulting PendingOperation to finish. For instance, to retrieve the initial invitee contacts of a conference channel, it is necessary to call becomeReady() with Channel::FeatureConferenceInitialInviteeContacts included in the argument. The required features are documented by each method.

Each channel is owned by a connection. If the Connection object becomes dead (as signaled by Connection::invalidated()), the Channel object will also get invalidated.

## Usage

### Creating a channel object

Channel objects can be created in various ways, but the preferred way is trough Account channel creation methods such as Account::ensureTextChat(), Account::createFileTransfer(), which uses the channel dispatcher.

If you already know the object path, you can just call create(). For example:

     ChannelPtr chan = Channel::create(connection, objectPath,
             immutableProperties);

### Making channel ready to use

A Channel object needs to become ready before usage, meaning that the introspection process finished and the object accessors can be used.

To make the object ready, use becomeReady() and wait for the PendingOperation::finished() signal to be emitted.

     class MyClass : public QObject
     {
         QOBJECT

     public:
         MyClass(QObject *parent = 0);
         ~MyClass() { }

     private Q_SLOTS:
         void onChannelReady(Tp::PendingOperation*);

     private:
         ChannelPtr chan;
     };

     MyClass::MyClass(const ConnectionPtr &connection,
             const QString &objectPath, const QVariantMap &immutableProperties)
         : QObject(parent)
           chan(Channel::create(connection, objectPath, immutableProperties))
     {
         connect(chan->becomeReady(),
                 SIGNAL(finished(Tp::PendingOperation*)),
                 SLOT(onChannelReady(Tp::PendingOperation*)));
     }

     void MyClass::onChannelReady(Tp::PendingOperation *op)
     {
         if (op->isError()) {
             qWarning() << "Channel cannot become ready:" <<
                 op->errorName() << "-" << op->errorMessage();
             return;
         }

         // Channel is now ready
     }

See Asynchronous Object Model, Shared Pointer Usage

## Constructor & Destructor Documentation

Tp::Channel::~Channel | ( |  | ) | `[virtual]`

Class destructor.

Tp::Channel::Channel | ( | const ConnectionPtr & | connection,
|  | const QString & | objectPath,
|  | const QVariantMap & | immutableProperties |
| ) |  |  | `[protected]`

Construct a new Channel object.

Parameters:

  | connection | Connection owning this channel, and specifying the service.
  | objectPath | The object path of this channel.
  | immutableProperties | The immutable properties of this channel.

## Member Function Documentation

ChannelPtr Tp::Channel::create | ( | const ConnectionPtr & | connection,
|  | const QString & | objectPath,
|  | const QVariantMap & | immutableProperties |
| ) |  |  | `[static]`

Create a new Channel object.

Parameters:

  | connection | Connection owning this channel, and specifying the service.
  | objectPath | The object path of this channel.
  | immutableProperties | The immutable properties of this channel.

Returns:
  A ChannelPtr object pointing to the newly created Channel object.

Reimplemented in Tp::ContactSearchChannel, Tp::FileTransferChannel, Tp::IncomingFileTransferChannel, Tp::OutgoingFileTransferChannel, Tp::RoomListChannel, Tp::StreamedMediaChannel, and Tp::TextChannel.

ConnectionPtr Tp::Channel::connection | ( |  | ) | const

Return the connection owning this channel.

This method requires Channel::FeatureCore to be enabled.

Returns:
  The connection owning this channel.

QVariantMap Tp::Channel::immutableProperties | ( |  | ) | const

Return the immutable properties of the channel.

If the channel is ready (isReady() returns true), the following keys are guaranteed to be present: org.freedesktop.Telepathy.Channel.ChannelType, org.freedesktop.Telepathy.Channel.TargetHandleType, org.freedesktop.Telepathy.Channel.TargetHandle and org.freedesktop.Telepathy.Channel.Requested.

The keys and values in this map are defined by the Telepathy D-Bus specification, or by third-party extensions to that specification. These are the properties that cannot change over the lifetime of the channel; they're announced in the result of the request, for efficiency.

Returns:
  A map in which the keys are D-Bus property names and the values are the corresponding values.

QString Tp::Channel::channelType | ( |  | ) | const

Return the D-Bus interface name for the type of this channel.

This method requires Channel::FeatureCore to be enabled.

Returns:
  D-Bus interface name for the type of this channel.

uint Tp::Channel::targetHandleType | ( |  | ) | const

Return the type of the handle returned by targetHandle() as specified in HandleType.

This method requires Channel::FeatureCore to be enabled.

Returns:
  The type of the handle returned by targetHandle().

uint Tp::Channel::targetHandle | ( |  | ) | const

Return the handle of the remote party with which this channel communicates.

This method requires Channel::FeatureCore to be enabled.

Returns:
  The handle, which is of the type targetHandleType() indicates.

bool Tp::Channel::isRequested | ( |  | ) | const

Return whether this channel was created in response to a local request.

This method requires Channel::FeatureCore to be enabled.

Returns:
  `true` if this channel was created in response to a local request, `false` otherwise.

ContactPtr Tp::Channel::initiatorContact | ( |  | ) | const

Return the contact who initiated this channel.

This method requires Channel::FeatureCore to be enabled.

Returns:
  The contact who initiated this channel, or a null ContactPtr object if it can't be retrieved.

PendingOperation * Tp::Channel::requestClose | ( |  | ) |

Start an asynchronous request that this channel be closed.

The returned PendingOperation object will signal the success or failure of this request; under normal circumstances, it can be expected to succeed.

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

uint Tp::Channel::groupFlags | ( |  | ) | const

Return a set of flags indicating the capabilities and behaviour of the group on this channel.

This method requires Channel::FeatureCore to be enabled.

Returns:
  Bitfield combination of flags, as defined in ChannelGroupFlag.

See also:
  groupFlagsChanged()

bool Tp::Channel::groupCanAddContacts | ( |  | ) | const

Return whether contacts can be added or invited to this channel.

This method requires Channel::FeatureCore to be enabled.

Returns:
  `true` if contacts can be added or invited to this channel, `false` otherwise.

See also:
  groupAddContacts()

bool Tp::Channel::groupCanAddContactsWithMessage | ( |  | ) | const

Return whether a message is expected when adding/inviting contacts, who are not already members, to this channel.

This method requires Channel::FeatureCore to be enabled.

Returns:
  `true` if a message is expected, `false` otherwise.

See also:
  groupAddContacts()

bool Tp::Channel::groupCanAcceptContactsWithMessage | ( |  | ) | const

Return whether a message is expected when accepting contacts' requests to join this channel.

This method requires Channel::FeatureCore to be enabled.

Returns:
  `true` if a message is expected, `false` otherwise.

See also:
  groupAddContacts()

PendingOperation * Tp::Channel::groupAddContacts | ( | const QList< ContactPtr > & | contacts,
|  | const QString & | message = `QString()` |
| ) |  |  |

Add contacts to this channel.

Contacts on the local pending list (those waiting for permission to join the channel) can always be added. If groupCanAcceptContactsWithMessage() returns `true`, an optional message is expected when doing this; if not, the message parameter is likely to be ignored (so the user should not be asked for a message, and the message parameter should be left empty).

Other contacts can only be added if groupCanAddContacts() returns `true`. If groupCanAddContactsWithMessage() returns `true`, an optional message is expected when doing this, and if not, the message parameter is likely to be ignored.

This method requires Channel::FeatureCore to be enabled.

Parameters:

  | contacts | Contacts to be added.
  | message | A string message, which can be blank if desired.

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

See also:
  groupCanAddContacts()

bool Tp::Channel::groupCanRescindContacts | ( |  | ) | const

Return whether contacts in groupRemotePendingContacts() can be removed from this channel (i.e. whether an invitation can be rescinded).

This method requires Channel::FeatureCore to be enabled.

Returns:
  `true` if contacts can be removed, `false` otherwise.

See also:
  groupRemoveContacts()

bool Tp::Channel::groupCanRescindContactsWithMessage | ( |  | ) | const

Return whether a message is expected when removing contacts who are in groupRemotePendingContacts() from this channel, i.e. rescinding an invitation.

This method requires Channel::FeatureCore to be enabled.

Returns:
  `true` if a message is expected, `false` otherwise.

See also:
  groupRemoveContacts()

bool Tp::Channel::groupCanRemoveContacts | ( |  | ) | const

Return if contacts in groupContacts() can be removed from this channel.

Note that contacts in local pending lists, and the groupSelfContact(), can always be removed from the channel.

This method requires Channel::FeatureCore to be enabled.

Returns:
  `true` if contacts can be removed, `false` otherwise.

See also:
  groupRemoveContacts()

bool Tp::Channel::groupCanRemoveContactsWithMessage | ( |  | ) | const

Return whether a message is expected when removing contacts who are in groupContacts() from this channel.

This method requires Channel::FeatureCore to be enabled.

Returns:
  `true` if a message is expected, `false` otherwise.

See also:
  groupRemoveContacts()

bool Tp::Channel::groupCanRejectContactsWithMessage | ( |  | ) | const

Return whether a message is expected when removing contacts who are in groupLocalPendingContacts() from this channel, i.e. rejecting a request to join.

This method requires Channel::FeatureCore to be enabled.

Returns:
  `true` if a message is expected, `false` otherwise.

See also:
  groupRemoveContacts()

bool Tp::Channel::groupCanDepartWithMessage | ( |  | ) | const

Return whether a message is expected when removing the groupSelfContact() from this channel, i.e. departing from the channel.

Returns:
  `true` if a message is expected, `false` otherwise.

See also:
  groupRemoveContacts()

PendingOperation * Tp::Channel::groupRemoveContacts | ( | const QList< ContactPtr > & | contacts,
|  | const QString & | message = `QString()`,
|  | uint | reason = `ChannelGroupChangeReasonNone` |
| ) |  |  |

Remove contacts from this channel.

Contacts on the local pending list (those waiting for permission to join the channel) can always be removed. If groupCanRejectContactsWithMessage() returns `true`, an optional message is expected when doing this; if not, the message parameter is likely to be ignored (so the user should not be asked for a message, and the message parameter should be left empty).

The groupSelfContact() can also always be removed, as a way to leave the group with an optional departure message and/or departure reason indication. If groupCanDepartWithMessage() returns `true`, an optional message is expected when doing this, and if not, the message parameter is likely to be ignored.

Contacts in the group can only be removed (e.g. kicked) if groupCanRemoveContacts() returns `true`. If groupCanRemoveContactsWithMessage() returns `true`, an optional message is expected when doing this, and if not, the message parameter is likely to be ignored.

Contacts in the remote pending list (those who have been invited to the channel) can only be removed (have their invitations rescinded) if groupCanRescindContacts() returns `true`. If groupCanRescindContactsWithMessage() returns `true`, an optional message is expected when doing this, and if not, the message parameter is likely to be ignored.

This method requires Channel::FeatureCore to be enabled.

Parameters:

  | contacts | Contacts to be removed.
  | message | A string message, which can be blank if desired.
  | reason | Reason of the change, as specified in ChannelGroupChangeReason

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

See also:
  groupCanRemoveContacts()

Contacts Tp::Channel::groupContacts | ( |  | ) | const

TODO: have parameters on these like Contacts groupContacts(bool includeSelfContact = true);

Return the current contacts of the group.

This method requires Channel::FeatureCore to be enabled.

Returns:
  List of contact of the group.

Contacts Tp::Channel::groupLocalPendingContacts | ( |  | ) | const

Return the contacts currently waiting for local approval to join the group.

This method requires Channel::FeatureCore to be enabled.

Returns:
  List of contacts currently waiting for local approval to join the group.

Contacts Tp::Channel::groupRemotePendingContacts | ( |  | ) | const

Return the contacts currently waiting for remote approval to join the group.

This method requires Channel::FeatureCore to be enabled.

Returns:
  List of contacts currently waiting for remote approval to join the group.

Channel::GroupMemberChangeDetails Tp::Channel::groupLocalPendingContactChangeInfo | ( | const ContactPtr & | contact | ) | const

Return information of a local pending contact change. If no information is available, an object for which GroupMemberChangeDetails::isValid() returns `false` is returned.

This method requires Channel::FeatureCore to be enabled.

Parameters:

  | contact | A Contact object that is on the local pending contacts list.

Returns:
  The change info in a GroupMemberChangeDetails object.

Channel::GroupMemberChangeDetails Tp::Channel::groupSelfContactRemoveInfo | ( |  | ) | const

Return information on the removal of the local user from the group. If the user hasn't been removed from the group, an object for which GroupMemberChangeDetails::isValid() Return `false` is returned.

This method should be called only after the channel has been closed. This is useful for getting the remove information after missing the corresponding groupMembersChanged() signal, as the local user being removed usually causes the remote Channel to be closed.

The returned information is not guaranteed to be correct if groupIsSelfHandleTracked() Return false and a self handle change has occurred on the remote object.

This method requires Channel::FeatureCore to be enabled.

Returns:
  The remove info in a GroupMemberChangeDetails object.

bool Tp::Channel::groupAreHandleOwnersAvailable | ( |  | ) | const

Return whether globally valid handles can be looked up using the channel-specific handle on this channel using this object.

Handle owner lookup is only available if:

- The object is ready
- The list returned by interfaces() contains TELEPATHY_INTERFACE_CHANNEL_INTERFACE_GROUP
- The set of flags returned by groupFlags() contains GroupFlagProperties and GroupFlagChannelSpecificHandles

If this function Return `false`, the return value of groupHandleOwners() is undefined and groupHandleOwnersChanged() will never be emitted.

The value returned by this function will stay fixed for the entire time the object is ready, so no change notification is provided.

This method requires Channel::FeatureCore to be enabled.

Returns:
  If handle owner lookup functionality is available.

HandleOwnerMap Tp::Channel::groupHandleOwners | ( |  | ) | const

Return a mapping of handles specific to this channel to globally valid handles.

The mapping includes at least all of the channel-specific handles in this channel's members, local-pending and remote-pending sets as keys. Any handle not in the keys of this mapping is not channel-specific in this channel. Handles which are channel-specific, but for which the owner is unknown, appear in this mapping with 0 as owner.

This method requires Channel::FeatureCore to be enabled.

Returns:
  A mapping from group-specific handles to globally valid handles.

bool Tp::Channel::groupIsSelfContactTracked | ( |  | ) | const

Return whether the value returned by groupSelfContact() is guaranteed to stay synchronized with what groupInterface()->GetSelfHandle() would return. Older services not providing group properties don't necessarily emit the SelfHandleChanged signal either, so self contact changes can't be reliably tracked.

This method requires Channel::FeatureCore to be enabled.

Returns:
  Whether or not changes to the self contact are tracked.

ContactPtr Tp::Channel::groupSelfContact | ( |  | ) | const

Return a Contact object representing the user in the group if at all possible, otherwise a Contact object representing the user globally.

This method requires Channel::FeatureCore to be enabled.

Returns:
  A contact object representing the user.

bool Tp::Channel::hasConferenceInterface | ( |  | ) | const

Return whether this channel implements the org.freedesktop.Telepathy.Channel.Interface.Conference interface.

This method requires Channel::FeatureCore to be enabled.

Deprecated:
  Use isConference() instead.

Returns:
  `true` if the interface is supported, `false` otherwise.

bool Tp::Channel::isConference | ( |  | ) | const

Return whether this channel implements the org.freedesktop.Telepathy.Channel.Interface.Conference interface.

This method requires Channel::FeatureCore to be enabled.

Returns:
  `true` if the interface is supported, `false` otherwise.

Contacts Tp::Channel::conferenceInitialInviteeContacts | ( |  | ) | const

Return a list of contacts invited to this conference when it was created.

This method requires Channel::FeatureConferenceInitialInviteeContacts to be enabled.

Returns:
  A list of contacts.

bool Tp::Channel::conferenceSupportsNonMerges | ( |  | ) | const

Return whether requests to create a conference channel with InitialChannels omitted, empty, or one element long are expected to succeed.

If false, InitialChannels must be supplied in all requests for this channel class, and contain at least two channels.

This method requires Channel::FeatureCore to be enabled.

Note that this method will always return false if the Channel supports the Conference interface, even if Conference.DRAFT is also supported.

Deprecated:
  Use ConnectionCapabilities conference methods instead.

Returns:
  Whether the channels supports non merges.

QList< ChannelPtr > Tp::Channel::conferenceChannels | ( |  | ) | const

Return the individual channels that are part of this conference.

Change notification is via the conferenceChannelMerged and conferenceChannelRemoved signals.

Note that the returned channels are not guaranteed to be ready. Calling Channel::becomeReady() may be needed.

This method requires Channel::FeatureCore to be enabled.

Returns:
  A List of individual channels that are part of this conference.

QList< ChannelPtr > Tp::Channel::conferenceInitialChannels | ( |  | ) | const

Return the initial value of conferenceChannels().

Note that the returned channels are not guaranteed to be ready. Calling Channel::becomeReady() may be needed.

This method requires Channel::FeatureCore to be enabled.

Returns:
  A list of individual channels that were initially part of this conference.

QHash< uint, ChannelPtr > Tp::Channel::conferenceOriginalChannels | ( |  | ) | const

Return a map between channel specific handles and the corresponding channels of this conference.

This method is only relevant on GSM conference calls where 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 groupFlags(). The groupHandleOwners() 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 method will return an empty hash.

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 conference channel with initial channels: ['/call/to/simon', '/call/to/jonny'].

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

{ groupFlags(): ChannelGroupFlagChannelSpecificHandles | (other flags), groupMembers(): [self handle, s, j], groupHandleOwners(): { s: h, j: h }, conferenceInitialChannels(): ['/call/to/simon', '/call/to/jonny'], conferenceChannels(): ['/call/to/simon', '/call/to/jonny'], conferenceOriginalChannels(): { s: '/call/to/simon', j: '/call/to/jonny' }, # ... }

Note that the returned channels are not guaranteed to be ready. Calling Channel::becomeReady() may be needed.

This method requires Channel::FeatureCore to be enabled.

Returns:
  A map of channel specific handles to channels.

bool Tp::Channel::hasMergeableConferenceInterface | ( |  | ) | const

Return whether this channel implements the org.freedesktop.Telepathy.Channel.Interface.MergeableConference interface.

This method requires Channel::FeatureCore to be enabled.

Deprecated:
  Use supportsConferenceMerging() instead.

Returns:
  `true` if the interface is supported, `false` otherwise.

bool Tp::Channel::supportsConferenceMerging | ( |  | ) | const

Return whether this channel implements the org.freedesktop.Telepathy.Channel.Interface.MergeableConference interface.

This method requires Channel::FeatureCore to be enabled.

Returns:
  `true` if the interface is supported, `false` otherwise.

PendingOperation * Tp::Channel::conferenceMergeChannel | ( | const ChannelPtr & | channel | ) |

Request that the given channel be incorporated into this channel.

This method requires Channel::FeatureCore to be enabled.

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

bool Tp::Channel::hasSplittableInterface | ( |  | ) | const

Return whether this channel implements the org.freedesktop.Telepathy.Channel.Interface.Splittable interface.

This method requires Channel::FeatureCore to be enabled.

Deprecated:
  Use supportsConferenceSplitting() instead.

Returns:
  `true` if the interface is supported, `false` otherwise.

bool Tp::Channel::supportsConferenceSplitting | ( |  | ) | const

Return whether this channel implements the org.freedesktop.Telepathy.Channel.Interface.Splittable interface.

This method requires Channel::FeatureCore to be enabled.

Returns:
  `true` if the interface is supported, `false` otherwise.

PendingOperation * Tp::Channel::splitChannel | ( |  | ) |

Request that this channel is removed from any Conference of which it is a part.

This method requires Channel::FeatureCore to be enabled.

Deprecated:
  Use conferenceSplitChannel() instead.

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

PendingOperation * Tp::Channel::conferenceSplitChannel | ( |  | ) |

Request that this channel is removed from any Conference of which it is a part.

This method requires Channel::FeatureCore to be enabled.

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

DBus::PropertiesInterface * Tp::Channel::propertiesInterface | ( |  | ) | const`[inline]`

Convenience function for getting a Properties interface proxy. The Properties interface is not necessarily reported by the services, so a `check` parameter is not provided, and the interface is always assumed to be present.

Deprecated:
  Use optionalInterface() instead.

Returns:
  `optionalInterface<DBus::PropertiesInterface>(BypassInterfaceCheck)`

TELEPATHY_QT4_DEPRECATED Client::ChannelInterfaceAnonymityInterface* Tp::Channel::anonymityInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

ChannelInterfaceCallStateInterface * Tp::Channel::callStateInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

Convenience function for getting a CallState interface proxy.

Deprecated:
  Use optionalInterface() instead.

Parameters:

  | check | Passed to optionalInterface()

Returns:
  `optionalInterface<ChannelInterfaceCallStateInterface>(check)`

ChannelInterfaceChatStateInterface * Tp::Channel::chatStateInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

Convenience function for getting a ChatState interface proxy.

Deprecated:
  Use optionalInterface() instead.

Parameters:

  | check | Passed to optionalInterface()

Returns:
  `optionalInterface<ChannelInterfaceChatStateInterface>(check)`

TELEPATHY_QT4_DEPRECATED Client::ChannelInterfaceConferenceInterface* Tp::Channel::conferenceInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

ChannelInterfaceDTMFInterface * Tp::Channel::DTMFInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

Convenience function for getting a DTMF interface proxy.

Deprecated:
  Use optionalInterface() instead.

Parameters:

  | check | Passed to optionalInterface()

Returns:
  `optionalInterface<ChannelInterfaceDTMFInterface>(check)`

ChannelInterfaceHoldInterface * Tp::Channel::holdInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

Convenience function for getting a Hold interface proxy.

Deprecated:
  Use optionalInterface() instead.

Parameters:

  | check | Passed to optionalInterface()

Returns:
  `optionalInterface<ChannelInterfaceHoldInterface>(check)`

ChannelInterfaceMediaSignallingInterface * Tp::Channel::mediaSignallingInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

Convenience function for getting a MediaSignalling interface proxy.

Deprecated:
  Use optionalInterface() instead.

Parameters:

  | check | Passed to optionalInterface()

Returns:
  `optionalInterface<ChannelInterfaceMediaSignallingInterface>(check)`

TELEPATHY_QT4_DEPRECATED Client::ChannelInterfaceMessagesInterface* Tp::Channel::messagesInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

ChannelInterfacePasswordInterface * Tp::Channel::passwordInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

Convenience function for getting a Password interface proxy.

Deprecated:
  Use optionalInterface() instead.

Parameters:

  | check | Passed to optionalInterface()

Returns:
  `optionalInterface<ChannelInterfacePasswordInterface>(check)`

TELEPATHY_QT4_DEPRECATED Client::ChannelInterfaceServicePointInterface* Tp::Channel::servicePointInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

TELEPATHY_QT4_DEPRECATED Client::ChannelInterfaceTubeInterface* Tp::Channel::tubeInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

template<class Interface >

template< class Interface > Interface * Tp::Channel::typeInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

Return a pointer to a valid instance of a given Channel type interface class, associated with the same remote object the Channel is associated with, and destroyed together with the Channel.

If the interface name returned by channelType() isn't equivalent to the name of the requested interface, or the Channel is not ready, `0` is returned. This check can be bypassed by specifying BypassInterfaceCheck for `check`, in which case a valid instance is always returned.

Convenience functions are provided for well-known channel types. However, there is no convenience getter for TypeContactList because the proxy for that interface doesn't actually have any functionality.

See also:
  OptionalInterfaceFactory::interface

Template Parameters:

  | Interface | Class of the optional interface to get.

Parameters:

  | check | Should an instance be returned even if it can't be determined that the remote object is of the requested channel type.

Returns:
  Pointer to an instance of the interface class, or `0`.

TELEPATHY_QT4_DEPRECATED Client::ChannelTypeContactSearchInterface* Tp::Channel::contactSearchInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

ChannelTypeRoomListInterface * Tp::Channel::roomListInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

Convenience function for getting a TypeRoomList interface proxy.

Deprecated:
  Use interface() instead.

Parameters:

  | check | Passed to typeInterface()

Returns:
  `typeInterface<ChannelTypeRoomListInterface>(check)`

TELEPATHY_QT4_DEPRECATED Client::ChannelTypeServerTLSConnectionInterface* Tp::Channel::serverTLSConnectionInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

ChannelTypeStreamedMediaInterface * Tp::Channel::streamedMediaInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

Convenience function for getting a TypeStreamedMedia interface proxy.

Deprecated:
  Use interface() instead.

Parameters:

  | check | Passed to typeInterface()

Returns:
  `typeInterface<ChannelTypeStreamedMediaInterface>(check)`

ChannelTypeTextInterface * Tp::Channel::textInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

Convenience function for getting a TypeText interface proxy.

Deprecated:
  Use interface() instead.

Parameters:

  | check | Passed to typeInterface()

Returns:
  `typeInterface<ChannelTypeTextInterface>(check)`

TELEPATHY_QT4_DEPRECATED Client::ChannelTypeFileTransferInterface* Tp::Channel::fileTransferInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

ChannelTypeTubesInterface * Tp::Channel::tubesInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

Convenience function for getting a TypeTubes interface proxy.

Deprecated:
  Use interface() instead.

Parameters:

  | check | Passed to typeInterface()

Returns:
  `typeInterface<ChannelTypeTubesInterface>(check)`

TELEPATHY_QT4_DEPRECATED Client::ChannelTypeStreamTubeInterface* Tp::Channel::streamTubeInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline]`

void Tp::Channel::groupFlagsChanged | ( | uint | flags,
|  | uint | added,
|  | uint | removed |
| ) |  |  | `[signal]`

Emitted when the value returned by groupFlags() changes.

Parameters:

  | flags | The value which would now be returned by groupFlags().
  | added | Flags added compared to the previous value.
  | removed | Flags removed compared to the previous value.

void Tp::Channel::groupCanAddContactsChanged | ( | bool | canAddContacts | ) | `[signal]`

void Tp::Channel::groupCanRemoveContactsChanged | ( | bool | canRemoveContacts | ) | `[signal]`

void Tp::Channel::groupCanRescindContactsChanged | ( | bool | canRescindContacts | ) | `[signal]`

void Tp::Channel::groupMembersChanged | ( | const Tp::Contacts & | groupMembersAdded,
|  | const Tp::Contacts & | groupLocalPendingMembersAdded,
|  | const Tp::Contacts & | groupRemotePendingMembersAdded,
|  | const Tp::Contacts & | groupMembersRemoved,
|  | const Tp::Channel::GroupMemberChangeDetails & | details |
| ) |  |  | `[signal]`

Emitted when the value returned by groupContacts(), groupLocalPendingContacts() or groupRemotePendingContacts() changes.

Parameters:

  | groupMembersAdded | The contacts that were added to this channel.
  | groupLocalPendingMembersAdded | The local pending contacts that were added to this channel.
  | groupRemotePendingMembersAdded | The remote pending contacts that were added to this channel.
  | groupMembersRemoved | The contacts removed from this channel.
  | details | Additional details such as the contact requesting or causing the change.

void Tp::Channel::groupHandleOwnersChanged | ( | const Tp::HandleOwnerMap & | owners,
|  | const Tp::UIntList & | added,
|  | const Tp::UIntList & | removed |
| ) |  |  | `[signal]`

void Tp::Channel::groupSelfContactChanged | ( |  | ) | `[signal]`

Emitted when the value returned by groupSelfContact() changes.

void Tp::Channel::conferenceChannelMerged | ( | const Tp::ChannelPtr & | channel | ) | `[signal]`

Emitted when a new channel is added to the value of conferenceChannels().

Parameters:

  | channel | The channel that was added to conferenceChannels().

void Tp::Channel::conferenceChannelRemoved | ( | const Tp::ChannelPtr & | channel | ) | `[signal]`

Deprecated:
  Use conferenceChannelRemoved(const Tp::ChannelPtr &channel, const Tp::Channel::GroupMemberChangeDetails &details) instead.

void Tp::Channel::conferenceChannelRemoved | ( | const Tp::ChannelPtr & | channel,
|  | const Tp::Channel::GroupMemberChangeDetails & | details |
| ) |  |  | `[signal]`

Emitted when a new channel is removed from the value of conferenceChannels().

Parameters:

  | channel | The channel that was removed from conferenceChannels().
  | details | The change details.

Client::ChannelInterface * Tp::Channel::baseInterface | ( |  | ) | const`[protected]`

Return the ChannelInterface for this Channel 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 ChannelInterface for this Channel

ChannelInterfaceGroupInterface * Tp::Channel::groupInterface | ( | InterfaceSupportedChecking | check = `CheckInterfaceSupported` | ) | const`[inline, protected]`

Convenience function for getting a Group interface proxy.

Deprecated:
  Use optionalInterface() instead.

Parameters:

  | check | Passed to optionalInterface()

Returns:
  `optionalInterface<ChannelInterfaceGroupInterface>(check)`

bool Tp::Channel::groupSelfHandleIsLocalPending | ( |  | ) | const`[protected]`

Return whether the local user is in the "local pending" state. This indicates that the local user needs to take action to accept an invitation, an incoming call, etc.

This method requires Channel::FeatureCore to be enabled.

Returns:
  Whether the local user is in this channel's local-pending set.

void Tp::Channel::connectNotify | ( | const char * | signalName | ) | `[protected]`

Reimplemented in Tp::StreamedMediaChannel.

PendingOperation * Tp::Channel::groupAddSelfHandle | ( |  | ) | `[protected, slot]`

Attempt to add the local user to this channel. In some channel types, such as Text and StreamedMedia, this is used to accept an invitation or an incoming call.

This method requires Channel::FeatureCore to be enabled.

Returns:
  A pending operation which will emit finished on success or failure

## Member Data Documentation

const Feature Tp::Channel::FeatureCore `[static]`

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

Note that this feature must be enabled in order to use most Channel methods. See specific methods documentation for more details.

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

Reimplemented in Tp::ContactSearchChannel, Tp::FileTransferChannel, Tp::IncomingFileTransferChannel, and Tp::OutgoingFileTransferChannel.

const Feature Tp::Channel::FeatureConferenceInitialInviteeContacts `[static]`

Feature used in order to access the conference initial invitee contacts info.

See conferenceInitialInviteeContacts() documentation for more details.