#include <messagesession.h>
Inherits MessageHandler.
Inheritance diagram for MessageSession:
Public Member Functions | |
MessageSession (ClientBase *parent, const JID &jid) | |
virtual | ~MessageSession () |
const JID & | target () const |
const std::string & | threadID () const |
void | registerMessageHandler (MessageHandler *mh) |
void | removeMessageHandler () |
void | send (const std::string &message, const std::string &subject) |
void | registerMessageFilter (MessageFilter *mf) |
void | removeMessageFilter (MessageFilter *mf) |
virtual void | handleMessage (Stanza *stanza) |
Protected Member Functions | |
virtual void | send (Tag *tag) |
Friends | |
class | MessageEventFilter |
class | ChatStateFilter |
class | InBandBytestream |
This is an alternative interface to raw, old-style messaging. The original interface, using the simple MessageHandler-derived interface, is based on an all-or-nothing approach. Once registered with ClientBase, a handler receives all message stanzas sent to this client and has to do any filtering on its own.
MessageSession adds an abstraction to a chat conversation. A MessageSession is responsible for communicating with exactly one (full) JID. It is extensible with so-called MessageFilters, which can provide additional features such as Message Events, Chat State Notifications or In-Band Bytestreams.
You can still use the old MessageHandler in parallel, but messages will not be relayed to both the generic MessageHandler and a MessageSession established for the sender's JID. The MessageSession takes precedence.
Using MessageSessions has the following advantages over the plain old MessageHandler:
void MyClass::myFunc() { JID jid( "abc@example.org/gloox" ); j = new Client( jid, "password" ); [...] j->setAutoMessageSession( true, this ); }
In this example, MyClass needs to be MessageHandler, MessageEventHandler and ChatStateHandler, too. The handlers are registered with the session to receive the respective events.
virtual void MyClass::handleMessageSession( MessageSession *session ) { // this leaks heavily if there was an earlier session m_session = session; m_session->registerMessageHandler( this ); // the following is optional m_messageEventFilter = new MessageEventFilter( m_session ); m_messageEventFilter->registerMessageEventHandler( this ); m_chatStateFilter = new ChatStateFilter( m_session ); m_chatStateFilter->registerChatStateHandler( this ); }
MessageEventHandler::handleMessageEvent() and ChatStateHandler::handleChatState() are called for incoming Message Events and Chat States, respectively.
virtual void MyClass::handleMessageEvent( const JID& from, MessageEventType event ) { // display contact's Message Event } virtual void MyClass::handleChatState( const JID& from, ChatStateType state ) { // display contact's Chat State }
To let the chat partner now that the user is typing a message or has closed the chat window, use raiseMessageEvent() and setChatState(), respectively. For example:
// user is typing a message m_messageEventFilter->raiseMessageEvent( MESSAGE_EVENT_COMPOSING ); // acknowledge receiving of a message m_messageEventFilter->raiseMessageEvent( MESSAGE_EVENT_DELIVERED ); // user is not actively paying attention to the chat m_chatStateFilter->setChatState( CHAT_STATE_INACTIVE ); // user has closed the chat window m_chatStateFilter->setChatState( CHAT_STATE_GONE );
To send a message to the chat partner of the session, use send( const std::string& message, const std::string& subject ). You don't have to care about receipient, thread id, etc., they are added automatically.
m_session->send( "Hello World!", "No Subject" );
To initiate a new chat session, all you have to do is create a new MessageSession and register a MessageHandler with it:
MessageSession* MyClass::newSession( const JID& to ) { MessageSession *session = new MessageSession( m_client, to ); session->registerMessageHandler( this ); return session; }
See InBandBytestreamManager for a detailed description on how to implement In-Band Bytestreams.
Definition at line 139 of file messagesession.h.
MessageSession | ( | ClientBase * | parent, | |
const JID & | jid | |||
) |
Constructs a new MessageSession for the given JID. It is recommended to supply a full JID, in other words, it should have a resource set. No resource can lead to unexpected behavior. A thread ID is generated and sent along with every message sent through this session.
parent | The ClientBase to use for communication. | |
jid | The remote contact's full JID. |
Definition at line 26 of file messagesession.cpp.
~MessageSession | ( | ) | [virtual] |
Virtual destructor.
Definition at line 35 of file messagesession.cpp.
void handleMessage | ( | Stanza * | stanza | ) | [virtual] |
Reimplement this function if you want to be notified about incoming messages.
stanza | The complete Stanza. |
Implements MessageHandler.
Definition at line 41 of file messagesession.cpp.
void registerMessageFilter | ( | MessageFilter * | mf | ) |
Use this function to hook a new MessageFilter into a MessageSession. The filter will be able to read and/or modify a message stanza's content.
mf | The MessageFilter to add. |
Definition at line 91 of file messagesession.cpp.
Referenced by MessageFilter::attachTo().
void registerMessageHandler | ( | MessageHandler * | mh | ) |
Use this function to associate a MessageHandler with this MessageSession. The MessageHandler will receive all messages sent from this MessageSession's remote contact.
mh | The MessageHandler to register. |
Definition at line 81 of file messagesession.cpp.
void removeMessageFilter | ( | MessageFilter * | mf | ) |
Use this function to remove a MessageFilter from the MessageSession.
mf | The MessageFilter to remove. |
Definition at line 96 of file messagesession.cpp.
Referenced by MessageFilter::attachTo(), InBandBytestream::~InBandBytestream(), and MessageFilter::~MessageFilter().
void removeMessageHandler | ( | ) |
This function clears the internal pointer to the MessageHandler and therefore disables message delivery.
Definition at line 86 of file messagesession.cpp.
void send | ( | Tag * | tag | ) | [protected, virtual] |
A wrapper around ClientBase::send(). You should not use this function to send a chat message because the Tag is not prepared accordingly (neither Thread ID nor Message Event requests are added).
tag | A Tag to send. |
Definition at line 76 of file messagesession.cpp.
void send | ( | const std::string & | message, | |
const std::string & | subject | |||
) |
A convenience function to quickly send a message (optionally with subject). This is the preferred way to send a message from a MessageSession.
message | The message to send. | |
subject | The optional subject to send. |
Definition at line 55 of file messagesession.cpp.
Referenced by MessageEventFilter::raiseMessageEvent(), and ChatStateFilter::setChatState().
const JID& target | ( | ) | const [inline] |
Use this function to find out where is this session points at.
Definition at line 169 of file messagesession.h.
Referenced by MessageEventFilter::raiseMessageEvent(), InBandBytestream::sendBlock(), and ChatStateFilter::setChatState().
const std::string& threadID | ( | ) | const [inline] |
By default, a thread ID is sent with every message to identify messages belonging together.
Definition at line 176 of file messagesession.h.