Home · Modules · All Classes · All Namespaces
Public Slots | Signals | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | List of all members
Tp::TextChannel Class Reference

The TextChannel class represents a Telepathy channel of type Text. More...

#include <TelepathyQt/TextChannel>

Inherits Tp::Channel.

Public Slots

void acknowledge (const QList< ReceivedMessage > &messages)
 
void forget (const QList< ReceivedMessage > &messages)
 
PendingSendMessagesend (const QString &text, ChannelTextMessageType type=ChannelTextMessageTypeNormal, MessageSendingFlags flags=0)
 
PendingSendMessagesend (const MessagePartList &parts, MessageSendingFlags flags=0)
 
PendingOperationinviteContacts (const QList< ContactPtr > &contacts, const QString &message=QString())
 
PendingOperationrequestChatState (ChannelChatState state)
 

Signals

void messageSent (const Tp::Message &message, Tp::MessageSendingFlags flags, const QString &sentMessageToken)
 
void messageReceived (const Tp::ReceivedMessage &message)
 
void pendingMessageRemoved (const Tp::ReceivedMessage &message)
 
void chatStateChanged (const Tp::ContactPtr &contact, Tp::ChannelChatState state)
 
- Signals inherited from Tp::Channel
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 ~TextChannel ()
 
bool hasMessagesInterface () const
 
bool hasChatStateInterface () const
 
bool canInviteContacts () const
 
bool supportsMessageType (ChannelTextMessageType messageType) const
 
QList< ChannelTextMessageTypesupportedMessageTypes () const
 
QStringList supportedContentTypes () const
 
MessagePartSupportFlags messagePartSupport () const
 
DeliveryReportingSupportFlags deliveryReportingSupport () const
 
QList< ReceivedMessagemessageQueue () const
 
ChannelChatState chatState (const ContactPtr &contact) const
 
- Public Member Functions inherited from Tp::Channel
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
 
PendingOperationrequestClose ()
 
PendingOperationrequestLeave (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
 
PendingOperationconferenceMergeChannel (const ChannelPtr &channel)
 
bool supportsConferenceSplitting () const
 
PendingOperationconferenceSplitChannel ()
 
ChannelGroupFlags groupFlags () const
 
bool groupCanAddContacts () const
 
bool groupCanAddContactsWithMessage () const
 
bool groupCanAcceptContactsWithMessage () const
 
PendingOperationgroupAddContacts (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
 
PendingOperationgroupRemoveContacts (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
 
- 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 PendingReadybecomeReady (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 TextChannelPtr create (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties)
 
- Static Public Member Functions inherited from Tp::Channel
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 FeatureMessageQueue
 
static const Feature FeatureMessageCapabilities
 
static const Feature FeatureMessageSentSignal
 
static const Feature FeatureChatState
 
- Static Public Attributes inherited from Tp::Channel
static const Feature FeatureCore
 
static const Feature FeatureConferenceInitialInviteeContacts
 

Protected Member Functions

 TextChannel (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties, const Feature &coreFeature=TextChannel::FeatureCore)
 
- Protected Member Functions inherited from Tp::Channel
 Channel (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties, const Feature &coreFeature)
 
Client::ChannelInterfacebaseInterface () const
 
bool groupSelfHandleIsLocalPending () 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
ReadinessHelperreadinessHelper () const
 
- Protected Member Functions inherited from Tp::OptionalInterfaceFactory< Channel >
void setInterfaces (const QStringList &interfaces)
 

Additional Inherited Members

- Public Types inherited from Tp::OptionalInterfaceFactory< Channel >
enum  InterfaceSupportedChecking
 
- Protected Slots inherited from Tp::Channel
PendingOperationgroupAddSelfHandle ()
 

Detailed Description

The TextChannel class represents a Telepathy channel of type Text.

For more details, please refer to Telepathy specification.

See Asynchronous Object Model, Shared Pointer Usage

Constructor & Destructor Documentation

◆ ~TextChannel()

Tp::TextChannel::~TextChannel ( )
virtual

Class destructor.

◆ TextChannel()

Tp::TextChannel::TextChannel ( const ConnectionPtr &  connection,
const QString &  objectPath,
const QVariantMap &  immutableProperties,
const Feature coreFeature = TextChannel::FeatureCore 
)
protected

Construct a new TextChannel object.

Parameters
connectionConnection owning this channel, and specifying the service.
objectPathThe channel object path.
immutablePropertiesThe channel immutable properties.
coreFeatureThe core feature of the channel type, if any. The corresponding introspectable should depend on TextChannel::FeatureCore.

Member Function Documentation

◆ create()

TextChannelPtr Tp::TextChannel::create ( const ConnectionPtr &  connection,
const QString &  objectPath,
const QVariantMap &  immutableProperties 
)
static

Create a new TextChannel object.

Parameters
connectionConnection owning this channel, and specifying the service.
objectPathThe channel object path.
immutablePropertiesThe channel immutable properties.
Returns
A TextChannelPtr object pointing to the newly created TextChannel object.

◆ hasMessagesInterface()

bool Tp::TextChannel::hasMessagesInterface ( ) const

Return whether this channel supports the Messages interface.

If the interface is not supported, some advanced functionality will be unavailable.

This method requires TextChannel::FeatureCore to be ready.

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

◆ hasChatStateInterface()

bool Tp::TextChannel::hasChatStateInterface ( ) const

Return whether this channel supports the ChatState interface.

If the interface is not supported, requestChatState() will fail and all contacts' chat states will appear to be ChannelChatStateInactive.

This method requires TextChannel::FeatureCore to be ready.

Returns
true if the ChatState interface is supported, false otherwise.
See also
requestChatState(), chatStateChanged()

◆ canInviteContacts()

bool Tp::TextChannel::canInviteContacts ( ) const

Return whether contacts can be invited into this channel using inviteContacts() (which is equivalent to Channel::groupAddContacts()).

Whether this is the case depends on the underlying protocol, the type of channel, and the user's privileges (in some chatrooms, only a privileged user can invite other contacts).

This is an alias for Channel::groupCanAddContacts(), to indicate its meaning more clearly for Text channels.

This method requires Channel::FeatureCore to be ready.

Returns
true if contacts can be invited, false otherwise.
See also
inviteContacts(), Channel::groupCanAddContacts(), Channel::groupAddContacts()

◆ supportsMessageType()

bool Tp::TextChannel::supportsMessageType ( ChannelTextMessageType  messageType) const

Return whether the provided message type is supported.

This method requires TextChannel::FeatureMessageCapabilities to be ready.

Parameters
messageTypeThe message type to check.
Returns
true if supported, false otherwise

◆ supportedMessageTypes()

QList< ChannelTextMessageType > Tp::TextChannel::supportedMessageTypes ( ) const

Return the message types supported by this channel.

This method requires TextChannel::FeatureMessageCapabilities to be ready.

Returns
The list of supported message types

◆ supportedContentTypes()

QStringList Tp::TextChannel::supportedContentTypes ( ) const

Return a list of supported MIME content types for messages on this channel.

For a simple text channel this will be a list containing one item, "text/plain".

This list may contain the special value "*<!--x-->/<!--x-->*", which indicates that any content type is supported.

This method requires TextChannel::FeatureMessageCapabilities to be ready.

Returns
The list of MIME content types.

◆ messagePartSupport()

MessagePartSupportFlags Tp::TextChannel::messagePartSupport ( ) const

Return a set of flags indicating support for multi-part messages on this channel.

This is zero on simple text channels, or greater than zero if there is partial or full support for multi-part messages.

This method requires TextChannel::FeatureMessageCapabilities to be ready.

Returns
The flags as MessagePartSupportFlags.

◆ deliveryReportingSupport()

DeliveryReportingSupportFlags Tp::TextChannel::deliveryReportingSupport ( ) const

Return a set of flags indicating support for delivery reporting on this channel.

This is zero if there are no particular guarantees, or greater than zero if delivery reports can be expected under certain circumstances.

This method requires TextChannel::FeatureMessageCapabilities to be ready.

Returns
The flags as DeliveryReportingSupportFlags.

◆ messageQueue()

QList< ReceivedMessage > Tp::TextChannel::messageQueue ( ) const

Return a list of messages received in this channel.

Messages are added to this list when they are received from the instant messaging service; the messageReceived() signal is emitted.

There is a small delay between the message being received over D-Bus and becoming available to users of this C++ API, since a small amount of additional information needs to be fetched. However, the relative ordering of all the messages in a channel is preserved.

Messages are removed from this list when they are acknowledged with the acknowledge() or forget() methods. On channels where hasMessagesInterface() returns true, they will also be removed when acknowledged by a different client. In either case, the pendingMessageRemoved() signal is emitted.

This method requires TextChannel::FeatureMessageQueue to be ready.

Returns
A list of ReceivedMessage objects.
See also
messageReceived()

◆ chatState()

ChannelChatState Tp::TextChannel::chatState ( const ContactPtr &  contact) const

Return the current chat state for contact.

If hasChatStateInterface() returns false, this method will always return ChannelChatStateInactive.

This method requires TextChannel::FeatureChatState to be ready.

Returns
The contact chat state as ChannelChatState.

◆ acknowledge

void Tp::TextChannel::acknowledge ( const QList< ReceivedMessage > &  messages)
slot

Acknowledge that received messages have been displayed to the user.

Note that this method should only be called by the main handler of a channel, usually meaning the user interface process that displays the channel to the user (when a channel dispatcher is used, the handler must acknowledge messages, and other approvers or observers must not acknowledge messages).

Processes other than the main handler of a channel can free memory used by the library by calling forget() instead.

This method requires TextChannel::FeatureMessageQueue to be ready.

Parameters
messagesA list of received messages that have now been displayed.
See also
forget(), messageQueue(), messageReceived(), pendingMessageRemoved()

◆ forget

void Tp::TextChannel::forget ( const QList< ReceivedMessage > &  messages)
slot

Remove messages from the message queue without acknowledging them.

Note that this method frees memory used by the library, but does not free the corresponding memory in the CM process. It should be used by clients that are not the main handler for a channel; the main handler for a channel should use acknowledge() instead.

This method requires TextChannel::FeatureMessageQueue to be ready.

Parameters
messagesA list of received messages that have now been processed.
See also
acknowledge(), messageQueue(), messageReceived(), pendingMessageRemoved()

◆ send [1/2]

PendingSendMessage * Tp::TextChannel::send ( const QString &  text,
ChannelTextMessageType  type = ChannelTextMessageTypeNormal,
MessageSendingFlags  flags = 0 
)
slot

Request that a message be sent on this channel.

When the message has been submitted for delivery, this method will return and the messageSent() signal will be emitted.

If the message cannot be submitted for delivery, the returned pending operation will fail and no signal is emitted.

This method requires TextChannel::FeatureCore to be ready.

Parameters
textThe message body.
typeThe message type.
flagsFlags affecting how the message is sent. Note that the channel may ignore some or all flags, depending on deliveryReportingSupport(); the flags that were handled by the CM are provided in messageSent().
Returns
A PendingOperation which will emit PendingOperation::finished when the message has been submitted for delivery.
See also
messageSent()

◆ send [2/2]

PendingSendMessage * Tp::TextChannel::send ( const MessagePartList parts,
MessageSendingFlags  flags = 0 
)
slot

Request that a message be sent on this channel.

When the message has been submitted for delivery, this method will return and the messageSent() signal will be emitted.

If the message cannot be submitted for delivery, the returned pending operation will fail and no signal is emitted.

This method requires TextChannel::FeatureCore to be ready.

Parameters
partsThe message parts.
flagsFlags affecting how the message is sent. Note that the channel may ignore some or all flags, depending on deliveryReportingSupport(); the flags that were handled by the CM are provided in messageSent().
Returns
A PendingOperation which will emit PendingOperation::finished when the message has been submitted for delivery.
See also
messageSent()

◆ inviteContacts

PendingOperation* Tp::TextChannel::inviteContacts ( const QList< ContactPtr > &  contacts,
const QString &  message = QString() 
)
inlineslot

◆ requestChatState

PendingOperation * Tp::TextChannel::requestChatState ( ChannelChatState  state)
slot

Set the local chat state and notify other members of the channel that it has changed.

Note that only the primary handler of the channel should set its chat state.

This method requires TextChannel::FeatureCore to be ready.

Parameters
stateThe new state.
See also
chatStateChanged()

◆ messageSent

void Tp::TextChannel::messageSent ( const Tp::Message message,
Tp::MessageSendingFlags  flags,
const QString &  sentMessageToken 
)
signal

Emitted when a message is sent, if the TextChannel::FeatureMessageSentSignal has been enabled.

This signal is emitted regardless of whether the message is sent by this client, or another client using the same channel via D-Bus.

Parameters
messageA message. This may differ slightly from what the client requested to send, for instance if it has been altered due to limitations of the instant messaging protocol used.
flagsMessageSendingFlags that were in effect when the message was sent. Clients can use these in conjunction with deliveryReportingSupport() to determine whether delivery reporting can be expected.
sentMessageTokenEither an empty QString, or an opaque token used to match the message to any delivery reports.

◆ messageReceived

void Tp::TextChannel::messageReceived ( const Tp::ReceivedMessage message)
signal

Emitted when a message is added to messageQueue(), if the TextChannel::FeatureMessageQueue Feature has been enabled.

This occurs slightly later than the message being received over D-Bus; see messageQueue() for details.

Parameters
messageThe message received.
See also
messageQueue(), acknowledge(), forget()

◆ pendingMessageRemoved

void Tp::TextChannel::pendingMessageRemoved ( const Tp::ReceivedMessage message)
signal

Emitted when a message is removed from messageQueue(), if the TextChannel::FeatureMessageQueue Feature has been enabled. See messageQueue() for the circumstances in which this happens.

Parameters
messageThe message removed.
See also
messageQueue(), acknowledge(), forget()

◆ chatStateChanged

void Tp::TextChannel::chatStateChanged ( const Tp::ContactPtr &  contact,
Tp::ChannelChatState  state 
)
signal

Emitted when the state of a member of the channel has changed, if the TextChannel::FeatureChatState feature has been enabled.

Local state changes are also emitted here.

Parameters
contactThe contact whose chat state changed.
stateThe new chat state for contact.
See also
chatState()

Member Data Documentation

◆ FeatureCore

const Feature Tp::TextChannel::FeatureCore
static

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

This is currently the same as Channel::FeatureCore, but may change to include more.

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

◆ FeatureMessageQueue

const Feature Tp::TextChannel::FeatureMessageQueue
static

Feature used in order to access the message queue info.

See message queue methods' documentation for more details.

See also
messageQueue(), messageReceived(), pendingMessageRemoved(), forget(), acknowledge()

◆ FeatureMessageCapabilities

const Feature Tp::TextChannel::FeatureMessageCapabilities
static

Feature used in order to access message capabilities info.

See message capabilities methods' documentation for more details.

See also
supportedContentTypes(), messagePartSupport(), deliveryReportingSupport()

◆ FeatureMessageSentSignal

const Feature Tp::TextChannel::FeatureMessageSentSignal
static

Feature used in order to receive notification when a message is sent.

See also
messageSent()

◆ FeatureChatState

const Feature Tp::TextChannel::FeatureChatState
static

Feature used in order to keep track of chat state changes.

See chat state methods' documentation for more details.

See also
chatState(), chatStateChanged()