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

#include <TelepathyQt/TextChannel>

Public Slots
void	acknowledge (const QList< ReceivedMessage > &messages)

void	forget (const QList< ReceivedMessage > &messages)

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

PendingSendMessage *	send (const MessagePartList &parts, MessageSendingFlags flags=0)

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

PendingOperation *	requestChatState (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< ChannelTextMessageType >	supportedMessageTypes () const

QStringList	supportedContentTypes () const

MessagePartSupportFlags	messagePartSupport () const

DeliveryReportingSupportFlags	deliveryReportingSupport () const

QList< ReceivedMessage >	messageQueue () 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

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

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

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 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::ChannelInterface *	baseInterface () 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
ReadinessHelper *	readinessHelper () 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
PendingOperation *	groupAddSelfHandle ()

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

Tp::TextChannel::~TextChannel ( )

virtual

Class destructor.

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

protected

Construct a new TextChannel 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, if any. The corresponding introspectable should depend on TextChannel::FeatureCore.

Member Function Documentation

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

static

Create a new TextChannel object.

Parameters

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

Returns: A TextChannelPtr object pointing to the newly created TextChannel object.

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.

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

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

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

Return whether the provided message type is supported.

This method requires TextChannel::FeatureMessageCapabilities to be ready.

Parameters

messageType The message type to check.

Returns: true if supported, false otherwise

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

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 "*/*", which indicates that any content type is supported.

This method requires TextChannel::FeatureMessageCapabilities to be ready.

Returns: The list of MIME content types.

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.

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.

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

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.

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

messages A list of received messages that have now been displayed.

See Also: forget(), messageQueue(), messageReceived(), pendingMessageRemoved()

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

messages A list of received messages that have now been processed.

See Also: acknowledge(), messageQueue(), messageReceived(), pendingMessageRemoved()

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

text	The message body.
type	The message type.
flags	Flags 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()

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

parts	The message parts.
flags	Flags 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()

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

inlineslot

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

state The new state.

See Also: chatStateChanged()

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

message	A 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.
flags	MessageSendingFlags 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.
sentMessageToken	Either an empty QString, or an opaque token used to match the message to any delivery reports.

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

message The message received.

See Also: messageQueue(), acknowledge(), forget()

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

message The message removed.

See Also: messageQueue(), acknowledge(), forget()

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

contact	The contact whose chat state changed.
state	The new chat state for contact.

See Also: chatState()

Member Data Documentation

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.

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

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

const Feature Tp::TextChannel::FeatureMessageSentSignal

static

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

See Also: messageSent()

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

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation