Telepathy::Client::TextChannel Class Reference
[Channel proxies]

#include <TelepathyQt4/Client/TextChannel>

Inheritance diagram for Telepathy::Client::TextChannel:

Inheritance graph
[legend]
Collaboration diagram for Telepathy::Client::TextChannel:

Collaboration graph
[legend]

List of all members.

Public Types

enum  Feature { FeatureMessageQueue = 1, FeatureMessageCapabilities = 2, FeatureMessageSentSignal = 4, _Padding = 0xFFFFFFFF }

Public Slots

void acknowledge (const QList< ReceivedMessage > &messages)
void forget (const QList< ReceivedMessage > &messages)
PendingSendMessagesend (const QString &text, ChannelTextMessageType type=ChannelTextMessageTypeNormal)
PendingSendMessagesend (const MessagePartList &parts)
PendingOperationinviteContacts (const QList< QSharedPointer< Contact > > &contacts, const QString &message=QString())

Signals

void messageSent (const Telepathy::Client::Message &message, Telepathy::MessageSendingFlags flags, const QString &sentMessageToken)
void messageReceived (const Telepathy::Client::ReceivedMessage &message)
void pendingMessageRemoved (const Telepathy::Client::ReceivedMessage &message)

Public Member Functions

 TextChannel (Connection *connection, const QString &objectPath, const QVariantMap &immutableProperties, QObject *parent=0)
 ~TextChannel ()
bool hasMessagesInterface () const
bool canInviteContacts () const
bool isReady (Channel::Features channelFeatures=0, Features textFeatures=0) const
PendingReadyChannelbecomeReady (Channel::Features channelFeatures=0, Features textFeatures=0)
QStringList supportedContentTypes () const
MessagePartSupportFlags messagePartSupport () const
DeliveryReportingSupportFlags deliveryReportingSupport () const
QList< ReceivedMessagemessageQueue () const

Friends

struct Private


Detailed Description

High-level proxy object for accessing remote Channel objects of the Text channel type.

This subclass of Channel will eventually provide a high-level API for the Text and Messages interface. Until then, it's just a Channel.


Member Enumeration Documentation

Features that can be enabled on a TextChannel using becomeReady().

Enumerator:
FeatureMessageQueue  The messageQueue method can be called, and the messageReceived and pendingMessageRemoved methods can be called
FeatureMessageCapabilities  The supportedContentTypes, messagePartSupport and deliveryReportingSupport methods can be called
FeatureMessageSentSignal  The messageSent signal will be emitted when a message is sent
_Padding 

Reimplemented from Telepathy::Client::Channel.


Constructor & Destructor Documentation

Telepathy::Client::TextChannel::TextChannel ( Connection connection,
const QString &  objectPath,
const QVariantMap &  immutableProperties,
QObject *  parent = 0 
)

Creates a TextChannel associated with the given object on the same service as the given connection.

Parameters:
connection Connection owning this TextChannel, and specifying the service.
objectPath Path to the object on the service.
immutableProperties The immutable D-Bus properties of the channel (as announced in the NewChannels D-Bus signal), used to reduce D-Bus round trips
parent Passed to the parent class constructor.

Telepathy::Client::TextChannel::~TextChannel (  ) 

Class destructor.


Member Function Documentation

void Telepathy::Client::TextChannel::acknowledge ( const QList< ReceivedMessage > &  messages  )  [slot]

Acknowledge that received messages have been displayed to the user.

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 ChannelDispatcher 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 in Telepathy-Qt4 by calling forget() instead.

The messages must have come from this channel, therefore this method does not make sense if FeatureMessageQueue has not been enabled.

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

References forget(), Telepathy::Client::ReceivedMessage::isFromChannel(), Telepathy::Client::ReceivedMessage::pendingId(), Telepathy::Client::Channel::textInterface(), and Telepathy::warning().

PendingReadyChannel * Telepathy::Client::TextChannel::becomeReady ( Channel::Features  channelFeatures = 0,
Features  textFeatures = 0 
)

Gather the necessary information to use the requested features.

Parameters:
channelFeatures Features of the Channel class
textFeatures Features of the TextChannel class
Returns:
A pending operation which will finish when basic Channel functionality, and all the requested features (if any), are ready for use

References FeatureMessageCapabilities, FeatureMessageQueue, FeatureMessageSentSignal, Telepathy::Client::DBusProxy::invalidationMessage(), Telepathy::Client::DBusProxy::invalidationReason(), isReady(), Telepathy::Client::DBusProxy::isValid(), Telepathy::Client::PendingOperation::setFinished(), Telepathy::Client::PendingOperation::setFinishedWithError(), and TELEPATHY_ERROR_INVALID_ARGUMENT.

bool Telepathy::Client::TextChannel::canInviteContacts (  )  const

Return whether contacts can be invited into this channel using inviteContacts (which is equivalent to 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 groupCanAddContacts, to indicate its meaning more clearly for Text channels.

The result of calling this method is undefined until basic Group functionality has been enabled by calling becomeReady and waiting for the pending operation to complete.

Returns:
The same thing as groupCanAddContacts

References Telepathy::Client::Channel::groupCanAddContacts().

DeliveryReportingSupportFlags Telepathy::Client::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.

The result of calling this method is undefined until the FeatureMessageCapabilities Feature has been enabled, by calling becomeReady and waiting for the pending operation to complete.

Returns:
A set of DeliveryReportingSupportFlags

void Telepathy::Client::TextChannel::forget ( const QList< ReceivedMessage > &  messages  )  [slot]

Remove messages from messageQueue without acknowledging them.

This method frees memory inside the Telepathy-Qt4 TextChannel proxy, but does not free the corresponding memory in the Connection Manager 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.

The messages must have come from this channel, therefore this method does not make sense if FeatureMessageQueue has not been enabled.

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

References Telepathy::Client::ReceivedMessage::isFromChannel(), pendingMessageRemoved(), and Telepathy::warning().

Referenced by acknowledge().

bool Telepathy::Client::TextChannel::hasMessagesInterface (  )  const

Return whether this channel supports the Telepathy Messages interface. If it does not, some advanced functionality will be unavailable.

The result of calling this method is undefined until basic Channel functionality has been enabled by calling becomeReady and waiting for the pending operation to complete.

Returns:
true if the Messages interface is supported

References Telepathy::Client::Channel::interfaces(), and TELEPATHY_INTERFACE_CHANNEL_INTERFACE_MESSAGES.

Referenced by send().

PendingOperation* Telepathy::Client::TextChannel::inviteContacts ( const QList< QSharedPointer< Contact > > &  contacts,
const QString &  message = QString() 
) [inline, slot]

bool Telepathy::Client::TextChannel::isReady ( Channel::Features  channelFeatures = 0,
Features  textFeatures = 0 
) const

Return whether the desired features are ready for use.

Parameters:
channelFeatures Features of the Channel class
textFeatures Features of the TextChannel class
Returns:
true if basic Channel functionality, and all the requested features (if any), are ready for use

References Telepathy::debug().

Referenced by becomeReady().

MessagePartSupportFlags Telepathy::Client::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.

The result of calling this method is undefined until the FeatureMessageCapabilities Feature has been enabled, by calling becomeReady and waiting for the pending operation to complete.

Returns:
A set of MessagePartSupportFlags

QList< ReceivedMessage > Telepathy::Client::TextChannel::messageQueue (  )  const

Return a list of messages received in this channel. This list is empty unless the FeatureMessageQueue Feature has been enabled.

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.

Returns:
The unacknowledged messages in this channel, excluding any that have been forgotten with forget().

void Telepathy::Client::TextChannel::messageReceived ( const Telepathy::Client::ReceivedMessage message  )  [signal]

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

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

void Telepathy::Client::TextChannel::messageSent ( const Telepathy::Client::Message message,
Telepathy::MessageSendingFlags  flags,
const QString &  sentMessageToken 
) [signal]

Emitted when a message is sent, if the FeatureMessageSentSignal Feature 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 Telepathy::Client::TextChannel::pendingMessageRemoved ( const Telepathy::Client::ReceivedMessage message  )  [signal]

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

Referenced by forget().

PendingSendMessage * Telepathy::Client::TextChannel::send ( const MessagePartList parts  )  [slot]

PendingSendMessage * Telepathy::Client::TextChannel::send ( const QString &  text,
ChannelTextMessageType  type = ChannelTextMessageTypeNormal 
) [slot]

QStringList Telepathy::Client::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.

The result of calling this method is undefined until the FeatureMessageCapabilities Feature has been enabled, by calling becomeReady and waiting for the pending operation to complete

Returns:
A list of MIME content types


Friends And Related Function Documentation

friend struct Private [friend]

Reimplemented from Telepathy::Client::Channel.


Generated on Thu Mar 5 18:52:13 2009 for TelepathyQt4-0.1.1 by  doxygen 1.5.8