#include <messagesession.h>
Inherits MessageHandler.
Inheritance diagram for MessageSession:
Public Member Functions | |
MessageSession (ClientBase *parent, const JID &jid, bool wantUpgrade=true) | |
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, | |||
bool | wantUpgrade = true | |||
) |
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. If you don't know the full JID (this is probably the most common case) but still want replies from the full JID to be matches to this MessageSession, set the wantUpgrade parameter to true (or leave it untouched). | |
wantUpgrade | This flag indicates whether gloox should try to match an incoming message from a full JID to this MessageSession. If unsure, use the default. You probably only want to use a non-default value if this MessageSession is supposed to talk directly to a server or component JID that has no resource. This 'upgrade' will only happen once. |
Definition at line 26 of file messagesession.cpp.
~MessageSession | ( | ) | [virtual] |
Virtual destructor.
Definition at line 35 of file messagesession.cpp.
const JID& target | ( | ) | const [inline] |
Use this function to find out where is this session points at.
Definition at line 175 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 182 of file messagesession.h.
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 91 of file messagesession.cpp.
void removeMessageHandler | ( | ) |
This function clears the internal pointer to the MessageHandler and therefore disables message delivery.
Definition at line 96 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 58 of file messagesession.cpp.
Referenced by MessageEventFilter::raiseMessageEvent(), and ChatStateFilter::setChatState().
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 101 of file messagesession.cpp.
Referenced by MessageFilter::attachTo().
void removeMessageFilter | ( | MessageFilter * | mf | ) |
Use this function to remove a MessageFilter from the MessageSession.
mf | The MessageFilter to remove. |
Definition at line 106 of file messagesession.cpp.
Referenced by MessageFilter::attachTo(), InBandBytestream::~InBandBytestream(), and MessageFilter::~MessageFilter().
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 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 79 of file messagesession.cpp.