The Channel class represents a Telepathy channel. More...

#include <TelepathyQt/Channel>

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

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

Classes
class	GroupMemberChangeDetails
	The Channel::GroupMemberChangeDetails class represents the details of a group membership change. More...

Signals
void	groupFlagsChanged (Tp::ChannelGroupFlags flags, Tp::ChannelGroupFlags added, Tp::ChannelGroupFlags removed)

void	groupCanAddContactsChanged (bool canAddContacts)

void	groupCanRemoveContactsChanged (bool canRemoveContacts)

void	groupCanRescindContactsChanged (bool canRescindContacts)

void	groupMembersChanged (const Tp::Contacts &groupMembersAdded, const Tp::Contacts &groupLocalPendingMembersAdded, const Tp::Contacts &groupRemotePendingMembersAdded, const Tp::Contacts &groupMembersRemoved, const Tp::Channel::GroupMemberChangeDetails &details)

void	groupHandleOwnersChanged (const Tp::HandleOwnerMap &owners, const Tp::UIntList &added, const Tp::UIntList &removed)

void	groupSelfContactChanged ()

void	conferenceChannelMerged (const Tp::ChannelPtr &channel)

void	conferenceChannelRemoved (const Tp::ChannelPtr &channel, const Tp::Channel::GroupMemberChangeDetails &details)

Signals inherited from Tp::DBusProxy
void	invalidated (Tp::DBusProxy *proxy, const QString &errorName, const QString &errorMessage)

Signals inherited from Tp::Object
void	propertyChanged (const QString &propertyName)

Public Member Functions
virtual	~Channel ()

ConnectionPtr	connection () const

QVariantMap	immutableProperties () const

QString	channelType () const

HandleType	targetHandleType () const

uint	targetHandle () const

QString	targetId () const

ContactPtr	targetContact () const

bool	isRequested () const

ContactPtr	initiatorContact () const

PendingOperation *	requestClose ()

PendingOperation *	requestLeave (const QString &message=QString(), ChannelGroupChangeReason reason=ChannelGroupChangeReasonNone)

bool	isConference () const

Contacts	conferenceInitialInviteeContacts () const

QList< ChannelPtr >	conferenceChannels () const

QList< ChannelPtr >	conferenceInitialChannels () const

QHash< uint, ChannelPtr >	conferenceOriginalChannels () const

bool	supportsConferenceMerging () const

PendingOperation *	conferenceMergeChannel (const ChannelPtr &channel)

bool	supportsConferenceSplitting () const

PendingOperation *	conferenceSplitChannel ()

Public Member Functions inherited from Tp::StatefulDBusProxy
	StatefulDBusProxy (const QDBusConnection &dbusConnection, const QString &busName, const QString &objectPath, const Feature &featureCore)

virtual	~StatefulDBusProxy ()

Public Member Functions inherited from Tp::DBusProxy
	DBusProxy (const QDBusConnection &dbusConnection, const QString &busName, const QString &objectPath, const Feature &featureCore)

virtual	~DBusProxy ()

QDBusConnection	dbusConnection () const

QString	busName () const

QString	objectPath () const

bool	isValid () const

QString	invalidationReason () const

QString	invalidationMessage () const

Public Member Functions inherited from Tp::Object
virtual	~Object ()

Public Member Functions inherited from Tp::RefCounted
	RefCounted ()

virtual	~RefCounted ()

Public Member Functions inherited from Tp::ReadyObject
	ReadyObject (RefCounted *object, const Feature &featureCore)

	ReadyObject (DBusProxy *proxy, const Feature &featureCore)

virtual	~ReadyObject ()

virtual bool	isReady (const Features &features=Features()) const

virtual PendingReady *	becomeReady (const Features &requestedFeatures=Features())

virtual Features	requestedFeatures () const

virtual Features	actualFeatures () const

virtual Features	missingFeatures () const

Public Member Functions inherited from Tp::OptionalInterfaceFactory< Channel >
	OptionalInterfaceFactory (Channel *this_)

	~OptionalInterfaceFactory ()

QStringList	interfaces () const

bool	hasInterface (const QString &name) const

Interface *	optionalInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const

Interface *	interface () const

Static Public Member Functions
static ChannelPtr	create (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties)

Static Public Member Functions inherited from Tp::StatefulDBusProxy
static QString	uniqueNameFrom (const QDBusConnection &bus, const QString &wellKnownOrUnique)

static QString	uniqueNameFrom (const QDBusConnection &bus, const QString &wellKnownOrUnique, QString &error, QString &message)

Static Public Attributes
static const Feature	FeatureCore

static const Feature	FeatureConferenceInitialInviteeContacts

Protected Member Functions
	Channel (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties, const Feature &coreFeature)

Client::ChannelInterface *	baseInterface () const

Protected Member Functions inherited from Tp::DBusProxy
void	setBusName (const QString &busName)

void	invalidate (const QString &reason, const QString &message)

void	invalidate (const QDBusError &error)

Protected Member Functions inherited from Tp::Object
	Object ()

void	notify (const char *propertyName)

Protected Member Functions inherited from Tp::ReadyObject
ReadinessHelper *	readinessHelper () const

Protected Member Functions inherited from Tp::OptionalInterfaceFactory< Channel >
void	setInterfaces (const QStringList &interfaces)

Group interface
Cached access to state of the group interface on the associated remote object, if the interface is present. 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 such as groupMembersChanged(), groupSelfContactChanged(), etc., are emitted to indicate that properties have changed. Check the individual signals' descriptions for details.
ChannelGroupFlags	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(), ChannelGroupChangeReason reason=ChannelGroupChangeReasonNone)

Contacts	groupContacts (bool includeSelfContact=true) const

Contacts	groupLocalPendingContacts (bool includeSelfContact=true) const

Contacts	groupRemotePendingContacts (bool includeSelfContact=true) const

GroupMemberChangeDetails	groupLocalPendingContactChangeInfo (const ContactPtr &contact) const

GroupMemberChangeDetails	groupSelfContactRemoveInfo () const

bool	groupAreHandleOwnersAvailable () const

HandleOwnerMap	groupHandleOwners () const

bool	groupIsSelfContactTracked () const

ContactPtr	groupSelfContact () const

bool	groupSelfHandleIsLocalPending () const

PendingOperation *	groupAddSelfHandle ()

Additional Inherited Members
Public Types inherited from Tp::OptionalInterfaceFactory< Channel >
enum	InterfaceSupportedChecking

Detailed Description

The Channel class represents a Telepathy channel.

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

The remote object accessor functions on this object (channelType(), targetHandleType(), 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.

To avoid unnecessary D-Bus traffic, some accessors only return valid information after specific features have been enabled. For instance, to retrieve the initial invitee contacts in a conference channel, it is necessary to enable the feature Channel::FeatureConferenceInitialInviteeContacts. See the individual methods descriptions for more details.

Channel features can be enabled by constructing a ChannelFactory and enabling the desired features, and passing it to AccountManager, Account or ClientRegistrar when creating them as appropriate. However, if a particular feature is only ever used in a specific circumstance, such as an user opening some settings dialog separate from the general view of the application, features can be later enabled as needed by calling becomeReady() with the additional features, and waiting for the resulting PendingOperation to finish.

Each channel is owned by a connection. If the Connection object becomes 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

◆ ~Channel()

Tp::Channel::~Channel ( )

virtual

Class destructor.

◆ Channel()

Tp::Channel::Channel	(	const ConnectionPtr &	connection,
		const QString &	objectPath,
		const QVariantMap &	immutableProperties,
		const Feature &	coreFeature
	)

protected

Construct a new Channel object.

Parameters

connection	Connection owning this channel, and specifying the service.
objectPath	The channel object path.
immutableProperties	The channel immutable properties.
coreFeature	The core feature of the channel type. The corresponding introspectable should depend on Channel::FeatureCore.

Member Function Documentation

◆ create()

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 channel object path.
immutableProperties	The channel immutable properties.

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

Todo:: immutableProperties should be used to populate the corresponding accessors (such as channelType()) already on construction, not only when making FeatureCore ready (fd.o #41654)

◆ connection()

ConnectionPtr Tp::Channel::connection ( ) const

Return the connection owning this channel.

Returns: A pointer to the Connection object.

◆ immutableProperties()

QVariantMap Tp::Channel::immutableProperties ( ) const

Return the immutable properties of the channel.

If the channel is ready (isReady(Channel::FeatureCore) 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 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: The immutable properties as QVariantMap.

◆ channelType()

QString Tp::Channel::channelType ( ) const

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

This method requires Channel::FeatureCore to be ready.

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

◆ targetHandleType()

HandleType Tp::Channel::targetHandleType ( ) const

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

This method requires Channel::FeatureCore to be ready.

Returns: The target handle type as HandleType.

See also: targetHandle(), targetId()

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

Returns: An integer representing the target handle, which is of the type targetHandleType() indicates.

See also: targetHandleType(), targetId()

◆ targetId()

QString Tp::Channel::targetId ( ) const

Return the persistent unique ID of the remote party with which this channel communicates.

If targetHandleType() is HandleTypeContact, this will be the ID of the remote contact, and similarly the unique ID of the room when targetHandleType() is HandleTypeRoom.

This is not necessarily the best identifier to display to the user, though. In particular, for contacts, their alias should be displayed instead. It can be used for matching channels and UI elements for them across reconnects, though, at which point the old channels and contacts are invalidated.

This method requires Channel::FeatureCore to be ready.

Returns: The target identifier.

See also: targetHandle(), targetContact()

◆ targetContact()

ContactPtr Tp::Channel::targetContact ( ) const

Return the contact with which this channel communicates for its lifetime, if applicable.

This method requires Channel::FeatureCore to be ready.

Returns: A pointer to the Contact object, or a null ContactPtr if targetHandleType() is not HandleTypeContact.

See also: targetHandle(), targetId()

◆ isRequested()

bool Tp::Channel::isRequested ( ) const

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

This method requires Channel::FeatureCore to be ready.

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

◆ initiatorContact()

ContactPtr Tp::Channel::initiatorContact ( ) const

Return the contact who initiated this channel.

This method requires Channel::FeatureCore to be ready.

Returns: A pointer to the Contact object representing the contact who initiated the channel, or a null ContactPtr if it can't be retrieved.

◆ requestClose()

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.

See also: requestLeave()

◆ requestLeave()

PendingOperation * Tp::Channel::requestLeave	(	const QString &	message = `QString()`,
		ChannelGroupChangeReason	reason = `ChannelGroupChangeReasonNone`
	)

Start an asynchronous request to leave this channel as gracefully as possible.

If leaving any more gracefully is not possible, this will revert to the same as requestClose(). In particular, this will be the case for channels with no group interface (TP_QT_IFACE_CHANNEL_INTERFACE_GROUP not in the list returned by interfaces()).

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

A message and a reason may be provided along with the request, which will be sent to the server if supported, which is indicated by ChannelGroupFlagMessageDepart and/or ChannelGroupFlagMessageReject.

Attempting to leave again when we have already left, either by our request or forcibly, will be a no-op, with the returned PendingOperation immediately finishing successfully.

Parameters

message	The message, which can be blank if desired.
reason	A reason for leaving.

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

◆ groupFlags()

ChannelGroupFlags Tp::Channel::groupFlags ( ) const

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

Change notification is via the groupFlagsChanged() signal.

This method requires Channel::FeatureCore to be ready.

Returns: The bitfield combination of flags as ChannelGroupFlags.

See also: groupFlagsChanged()

◆ groupCanAddContacts()

bool Tp::Channel::groupCanAddContacts ( ) const

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

Change notification is via the groupCanAddContactsChanged() signal.

This method requires Channel::FeatureCore to be ready.

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

See also: groupFlags(), groupAddContacts()

◆ groupCanAddContactsWithMessage()

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

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

See also: groupFlags(), groupAddContacts()

◆ groupCanAcceptContactsWithMessage()

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

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

See also: groupFlags(), groupAddContacts()

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

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(), groupCanAddContactsWithMessage(), groupCanAcceptContactsWithMessage()

◆ groupCanRescindContacts()

bool Tp::Channel::groupCanRescindContacts ( ) const

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

Change notification is via the groupCanRescindContactsChanged() signal.

This method requires Channel::FeatureCore to be ready.

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

See also: groupFlags(), groupRemoveContacts()

◆ groupCanRescindContactsWithMessage()

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

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

See also: groupFlags(), groupRemoveContacts()

◆ groupCanRemoveContacts()

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.

Change notification is via the groupCanRemoveContactsChanged() signal.

This method requires Channel::FeatureCore to be ready.

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

See also: groupFlags(), groupRemoveContacts()

◆ groupCanRemoveContactsWithMessage()

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

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

See also: groupFlags(), groupRemoveContacts()

◆ groupCanRejectContactsWithMessage()

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

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

See also: groupFlags(), groupRemoveContacts()

◆ groupCanDepartWithMessage()

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: groupFlags(), groupRemoveContacts()

◆ groupRemoveContacts()

PendingOperation * Tp::Channel::groupRemoveContacts	(	const QList< ContactPtr > &	contacts,
		const QString &	message = `QString()`,
		ChannelGroupChangeReason	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 ready.

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(), groupCanRemoveContactsWithMessage(), groupCanRejectContactsWithMessage(), groupCanRescindContacts(), groupCanRescindContacts(), groupCanRescindContactsWithMessage(), groupCanDepartWithMessage()

◆ groupContacts()

Contacts Tp::Channel::groupContacts ( bool includeSelfContact = true ) const

Return the current contacts of the group.

It is possible to omit the contact representing the local user, even if the contact is in the set, by passing false as the parameter includeSelfContact.

Change notification is via the groupMembersChanged() signal.

This method requires Channel::FeatureCore to be ready.

Parameters

includeSelfContact Whether to include the self contact in the returned set.

Returns: A set of pointers to the Contact objects.

See also: groupLocalPendingContacts(), groupRemotePendingContacts()

◆ groupLocalPendingContacts()

Contacts Tp::Channel::groupLocalPendingContacts ( bool includeSelfContact = true ) const

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

It is possible to omit the contact representing the local user, even if the contact is in the set, by passing false as the parameter includeSelfContact.

Change notification is via the groupMembersChanged() signal.

This method requires Channel::FeatureCore to be ready.

Parameters

includeSelfContact Whether to include the self contact in the returned set.

Returns: A set of pointers to the Contact objects.

See also: groupContacts(), groupRemotePendingContacts()

◆ groupRemotePendingContacts()

Contacts Tp::Channel::groupRemotePendingContacts ( bool includeSelfContact = true ) const

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

It is possible to omit the contact representing the local user, even if the contact is in the set, by passing false as the parameter includeSelfContact.

Change notification is via the groupMembersChanged() signal.

This method requires Channel::FeatureCore to be ready.

Parameters

includeSelfContact Whether to include the self contact in the returned set.

Returns: A set of pointers to the Contact objects.

See also: groupContacts(), groupLocalPendingContacts()

◆ groupLocalPendingContactChangeInfo()

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

Parameters

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

Returns: The change info as a GroupMemberChangeDetails object.

◆ groupSelfContactRemoveInfo()

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() returns false is returned.

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

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

This method requires Channel::FeatureCore to be ready.

Returns: The remove info as a GroupMemberChangeDetails object.

◆ groupAreHandleOwnersAvailable()

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 TP_QT_IFACE_CHANNEL_INTERFACE_GROUP
The set of flags returned by groupFlags() contains #GroupFlagProperties and #GroupFlagChannelSpecificHandles

If this function returns 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 ready.

Returns: true if handle owner lookup functionality is available, false otherwise.

◆ groupHandleOwners()

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.

Change notification is via the groupHandleOwnersChanged() signal.

This method requires Channel::FeatureCore to be ready.

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

◆ groupIsSelfContactTracked()

bool Tp::Channel::groupIsSelfContactTracked ( ) const

Return whether the value returned by groupSelfContact() is guaranteed to accurately represent the local user even after nickname changes, etc.

This should always be true for new services implementing the group interface.

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

Returns: true if changes to the self contact are tracked, false otherwise.

◆ groupSelfContact()

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.

Change notification is via the groupSelfContactChanged() signal.

This method requires Channel::FeatureCore to be ready.

Returns: A pointer to the Contact object.

◆ isConference()

bool Tp::Channel::isConference ( ) const

Return whether this channel implements the conference interface (TP_QT_IFACE_CHANNEL_INTERFACE_CONFERENCE is in the list returned by interfaces()).

This method requires Channel::FeatureCore to be ready.

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

◆ conferenceInitialInviteeContacts()

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

Returns: A set of pointers to the Contact objects.

◆ conferenceChannels()

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

Returns: A list of pointers to Channel objects containing all channels in the conference.

See also: conferenceInitialChannels(), conferenceOriginalChannels()

◆ conferenceInitialChannels()

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

Returns: A list of pointers to Channel objects containing all channels that were initially part of the conference.

See also: conferenceChannels(), conferenceOriginalChannels()

◆ conferenceOriginalChannels()

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:

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;
Put that call on hold;
Place another call (with path /call/to/jonny) to +441234567890, and ask to be put through to Jonny Lamb;
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 ready.

Returns: A map of channel specific handles to pointers to Channel objects.

See also: conferenceChannels(), conferenceInitialChannels()

◆ supportsConferenceMerging()

bool Tp::Channel::supportsConferenceMerging ( ) const

Return whether this channel supports conference merging using conferenceMergeChannel().

This method requires Channel::FeatureCore to be ready.

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

See also: conferenceMergeChannel()

◆ conferenceMergeChannel()

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

Request that the given channel be incorporated into this channel.

This method requires Channel::FeatureCore to be ready.

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

See also: supportsConferenceMerging()

◆ supportsConferenceSplitting()

bool Tp::Channel::supportsConferenceSplitting ( ) const

Return whether this channel supports splitting using conferenceSplitChannel().

This method requires Channel::FeatureCore to be ready.

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

See also: conferenceSplitChannel()

◆ conferenceSplitChannel()

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

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

See also: supportsConferenceSplitting()

◆ groupFlagsChanged

void Tp::Channel::groupFlagsChanged	(	Tp::ChannelGroupFlags	flags,
		Tp::ChannelGroupFlags	added,
		Tp::ChannelGroupFlags	removed
	)

signal

Emitted when the value of 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.

◆ groupCanAddContactsChanged

void Tp::Channel::groupCanAddContactsChanged ( bool canAddContacts )

signal

Emitted when the value of groupCanAddContacts() changes.

Parameters

canAddContacts Whether a contact can be added to this channel.

See also: groupCanAddContacts()

◆ groupCanRemoveContactsChanged

void Tp::Channel::groupCanRemoveContactsChanged ( bool canRemoveContacts )

signal

Emitted when the value of groupCanRemoveContacts() changes.

Parameters

canRemoveContacts Whether a contact can be removed from this channel.

See also: groupCanRemoveContacts()

◆ groupCanRescindContactsChanged

void Tp::Channel::groupCanRescindContactsChanged ( bool canRescindContacts )

signal

Emitted when the value of groupCanRescindContacts() changes.

Parameters

canRescindContacts Whether contact invitations can be rescinded.

See also: groupCanRescindContacts()

◆ groupMembersChanged

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.

◆ groupHandleOwnersChanged

void Tp::Channel::groupHandleOwnersChanged	(	const Tp::HandleOwnerMap &	owners,
		const Tp::UIntList &	added,
		const Tp::UIntList &	removed
	)

signal

Emitted when the value returned by groupHandleOwners() changes.

Parameters

owners	The value which would now be returned by groupHandleOwners().
added	Handles which have been added to the mapping as keys, or existing handle keys for which the mapped-to value has changed.
removed	Handles which have been removed from the mapping.

◆ groupSelfContactChanged

void Tp::Channel::groupSelfContactChanged ( )

signal

Emitted when the value returned by groupSelfContact() changes.

◆ conferenceChannelMerged

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

◆ conferenceChannelRemoved

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.

◆ baseInterface()

Client::ChannelInterface * Tp::Channel::baseInterface ( ) const

protected

Return the Client::ChannelInterface interface proxy object for this channel. This method is protected since the convenience methods provided by this class should generally be used instead of calling D-Bus methods directly.

Returns: A pointer to the existing Client::ChannelInterface object for this Channel object.

◆ groupSelfHandleIsLocalPending()

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

Returns: true if local user is in the channel's local-pending set, false otherwise.

◆ groupAddSelfHandle

PendingOperation * Tp::Channel::groupAddSelfHandle ( )

protectedslot

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

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

Member Data Documentation

◆ FeatureCore

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.

◆ FeatureConferenceInitialInviteeContacts

const Feature Tp::Channel::FeatureConferenceInitialInviteeContacts

static

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

See also: conferenceInitialInviteeContacts()

Classes

Signals

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Group interface

Additional Inherited Members

Detailed Description

Usage

Creating a channel object

Making channel ready to use

Constructor & Destructor Documentation

◆ ~Channel()

◆ Channel()

Member Function Documentation

◆ create()

◆ connection()

◆ immutableProperties()

◆ channelType()

◆ targetHandleType()

◆ targetHandle()

◆ targetId()

◆ targetContact()

◆ isRequested()

◆ initiatorContact()

◆ requestClose()

◆ requestLeave()

◆ groupFlags()

◆ groupCanAddContacts()

◆ groupCanAddContactsWithMessage()

◆ groupCanAcceptContactsWithMessage()

◆ groupAddContacts()

◆ groupCanRescindContacts()

◆ groupCanRescindContactsWithMessage()

◆ groupCanRemoveContacts()

◆ groupCanRemoveContactsWithMessage()

◆ groupCanRejectContactsWithMessage()

◆ groupCanDepartWithMessage()

◆ groupRemoveContacts()

◆ groupContacts()

◆ groupLocalPendingContacts()

◆ groupRemotePendingContacts()

◆ groupLocalPendingContactChangeInfo()

◆ groupSelfContactRemoveInfo()

◆ groupAreHandleOwnersAvailable()

◆ groupHandleOwners()

◆ groupIsSelfContactTracked()

◆ groupSelfContact()

◆ isConference()

◆ conferenceInitialInviteeContacts()

◆ conferenceChannels()

◆ conferenceInitialChannels()

◆ conferenceOriginalChannels()

...

◆ supportsConferenceMerging()

◆ conferenceMergeChannel()

◆ supportsConferenceSplitting()

◆ conferenceSplitChannel()

◆ groupFlagsChanged

◆ groupCanAddContactsChanged

◆ groupCanRemoveContactsChanged

◆ groupCanRescindContactsChanged

◆ groupMembersChanged

◆ groupHandleOwnersChanged

◆ groupSelfContactChanged

◆ conferenceChannelMerged

◆ conferenceChannelRemoved

◆ baseInterface()

◆ groupSelfHandleIsLocalPending()

◆ groupAddSelfHandle

Member Data Documentation

◆ FeatureCore

◆ FeatureConferenceInitialInviteeContacts