Public Member Functions | Protected Member Functions | List of all members
MessageSession Class Reference

#include <messagesession.h>

Inheritance diagram for MessageSession:
Inheritance graph
Collaboration diagram for MessageSession:
Collaboration graph

Public Member Functions

 MessageSession (ClientBase *parent, const JID &jid, bool wantUpgrade=true, int types=0)
virtual ~MessageSession ()
const JIDtarget () const
const std::string & threadID () const
void setThreadID (const std::string &thread)
void registerMessageHandler (MessageHandler *mh)
void removeMessageHandler ()
virtual void send (const std::string &message, const std::string &subject="")
void registerMessageFilter (MessageFilter *mf)
void removeMessageFilter (MessageFilter *mf)
void disposeMessageFilter (MessageFilter *mf)
int types () const
void resetResource ()

Protected Member Functions

virtual void send (Tag *tag)

Detailed Description

An abstraction of a message session between any two entities.

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:

Derive an object from MessageSessionHandler and reimplement handleMessageSession() to store your shiny new sessions somewhere, or to create a new chat window, or whatever. Register your object with a ClientBase instance using registerMessageSessionHandler(). In code:

void MyClass::myFunc()
JID jid( "" );
j = new Client( jid, "password" );

MyClass is a MessageSessionHandler here.

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 )
// for this example only, we delete any earlier session
if( m_session )
j->disposeMessageSession( m_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( MessageEventComposing );
// acknowledge receiving of a message
m_messageEventFilter->raiseMessageEvent( MessageEventDelivered );
// user is not actively paying attention to the chat
m_chatStateFilter->setChatState( ChatStateInactive );
// user has closed the chat window
m_chatStateFilter->setChatState( ChatStateGone );

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.

You should never delete a MessageSession manually. Use ClientBase::disposeMessageSession() instead.
Jakob Schroeter

Definition at line 146 of file messagesession.h.

Constructor & Destructor Documentation

MessageSession ( ClientBase parent,
const JID jid,
bool  wantUpgrade = true,
int  types = 0 

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.

parentThe ClientBase to use for communication.
jidThe 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 handled by this MessageSession, set the wantUpgrade parameter to true (or leave it untouched).
wantUpgradeThis 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.
typesORed list of StanzaSubType values this MessageSession shall receive. Only the StanzaMessage* types are valid. Defaults to 0 which means any type is received.

Definition at line 26 of file messagesession.cpp.

~MessageSession ( )

Virtual destructor.

You should never delete a MessageSession manually. Use ClientBase::disposeMessageSession() instead.

Definition at line 34 of file messagesession.cpp.

Member Function Documentation

void disposeMessageFilter ( MessageFilter mf)

Use this function to remove and delete a MessageFilter from the MessageSession.

mfThe MessageFilter to remove and delete.
To just remove (and not delete) the MessageFilter use removeMessageFilter().

Definition at line 137 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.

The MessageSession will become the owner of the filter, it will be deleted by MessageSession's destructor. To get rid of the filter before that, use disposeMessageFilter().
mfThe MessageFilter to add.

Definition at line 127 of file messagesession.cpp.

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.

mhThe MessageHandler to register.

Definition at line 117 of file messagesession.cpp.

void removeMessageFilter ( MessageFilter mf)

Use this function to remove a MessageFilter from the MessageSession.

mfThe MessageFilter to remove.
To remove and delete the MessageFilter in one step use disposeMessageFilter().

Definition at line 132 of file messagesession.cpp.

void removeMessageHandler ( )

This function clears the internal pointer to the MessageHandler and therefore disables message delivery.

Definition at line 122 of file messagesession.cpp.

void resetResource ( )

This function resets the session's target JID to its bare form such that subsequently sent messages will be sent to that bare JID. The server will determine the best resource to deliver to. Useful if the target resource changed presence to e.g. away or offline.


Definition at line 106 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.

messageThe message to send.
subjectThe optional subject to send.

Definition at line 68 of file messagesession.cpp.

void send ( Tag tag)

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

tagA Tag to send.

Definition at line 92 of file messagesession.cpp.

void setThreadID ( const std::string &  thread)

Use this function to set the session's thread ID if e.g. a specific thread is continued. It shpuld not normally be needed to set the thread ID manually.

threadThe new thread ID.

Definition at line 196 of file messagesession.h.

const JID& target ( ) const

Use this function to find out where this session points at.

The receipient's JID.

Definition at line 182 of file messagesession.h.

const std::string& threadID ( ) const

By default, a thread ID is sent with every message to identify messages belonging together.

The thread ID for this session.

Definition at line 189 of file messagesession.h.

int types ( ) const

Returns the message type this MessageSession wants to receive.

ORed list of StanzaSubType values this MessageSession wants to receive. Only the StanzaMessage* types are valid.

Definition at line 249 of file messagesession.h.

The documentation for this class was generated from the following files: