MessageSession Class Reference

`#include <messagesession.h>`

Inheritance diagram for MessageSession:
[legend]

## Public Member Functions

| MessageSession (ClientBase *parent, const JID &jid, bool wantUpgrade=true, int types=0, bool honorTID=true)
virtual | ~MessageSession ()
const JID & | target () const
const std::string & | threadID () const
void | setThreadID (const std::string &thread)
bool | honorThreadID () const
void | registerMessageHandler (MessageHandler *mh)
void | removeMessageHandler ()
virtual void | send (const std::string &message)
virtual void | send (const std::string &message, const std::string &subject, const StanzaExtensionList &sel=StanzaExtensionList())
void | registerMessageFilter (MessageFilter *mf)
void | removeMessageFilter (MessageFilter *mf)
void | disposeMessageFilter (MessageFilter *mf)
int | types () const
void | resetResource ()
virtual void | handleMessage (Message &msg)

## Protected Member Functions

virtual void | send (const Message &msg)

## Detailed Description

An abstraction of a message session between any two entities.

This is an alternative interface to unmanaged 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, or Chat State Notifications.

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:

- automatic creation of MessageSessions
- filtering by JID
- automatic handling of threading (i.e., XMPP message threads)
- simpler sending of messages
- support for MessageFilters.

Usage:
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( "abc@example.org/gloox" );
j = new Client( jid, "password" );
[...]
j->registerMessageSessionHandler( this, 0 );
}
gloox::Client
This class implements a basic Jabber/XMPP Client.
Definition client.h:117
gloox::JID
An abstraction of a JID.
Definition jid.h:31

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 );
}
gloox::ChatStateFilter
This class adds Chat State Notifications (XEP-0085) support to a MessageSession.
Definition chatstatefilter.h:44
gloox::MessageEventFilter
This class adds Message Event (XEP-0022) support to a MessageSession.
Definition messageeventfilter.h:39
gloox::MessageSession::registerMessageHandler
void registerMessageHandler(MessageHandler *mh)
Definition messagesession.h:212
gloox::MessageSession::MessageSession
MessageSession(ClientBase *parent, const JID &jid, bool wantUpgrade=true, int types=0, bool honorTID=true)
Definition messagesession.cpp:24

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
}
gloox::MessageEventType
MessageEventType
Definition gloox.h:1090
gloox::ChatStateType
ChatStateType
Definition gloox.h:1105

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 );
gloox::MessageEventComposing
@ MessageEventComposing
Definition gloox.h:1096
gloox::MessageEventDelivered
@ MessageEventDelivered
Definition gloox.h:1093
gloox::ChatStateGone
@ ChatStateGone
Definition gloox.h:1110
gloox::ChatStateInactive
@ ChatStateInactive
Definition gloox.h:1109

To send a message to the chat partner of the session, use string& subject, const StanzaExtensionList& ). 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;
}

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

Author
  Jakob Schröter js@ca.nosp@m.maya.nosp@m..net

Since
  0.8

Definition at line 145 of file messagesession.h.

## Constructor & Destructor Documentation

## MessageSession()

MessageSession | ( | ClientBase * | parent,
|  | const JID & | jid,
|  | bool | wantUpgrade = true,
|  | int | types = 0,
|  | bool | honorTID = 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.

Parameters

  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 handled by 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.
  types | ORed list of Message::MessageType values this MessageSession shall receive. Defaults to 0 which means any type is received.
  honorTID | Indicates whether thread IDs should be honored when matching incoming messages to MessageSessions. The default (true) is usually fine.

Definition at line 24 of file messagesession.cpp.

## ~MessageSession()

~MessageSession | ( |  | ) |

virtual

Virtual destructor.

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

Definition at line 32 of file messagesession.cpp.

## Member Function Documentation

## disposeMessageFilter()

void disposeMessageFilter | ( | MessageFilter * | mf | ) |

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

Parameters

  mf | The MessageFilter to remove and delete.

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

Definition at line 109 of file messagesession.cpp.

## handleMessage()

void handleMessage | ( | Message & | msg | ) |

virtual

This function can be used to feed a message into the session. Ususally, only ClientBase should call this function.

Parameters

  msg | A Message to feed into the session.

Reimplemented in MUCMessageSession.

Definition at line 37 of file messagesession.cpp.

## honorThreadID()

bool honorThreadID | ( |  | ) | const

inline

Indicates whether thread IDs are honored when matching incoming messages to MessageSessions.

Returns
  Whether thread IDs are honored.

Definition at line 204 of file messagesession.h.

## registerMessageFilter()

void registerMessageFilter | ( | MessageFilter * | mf | ) |

inline

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.

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

Parameters

  mf | The MessageFilter to add.

Definition at line 247 of file messagesession.h.

## registerMessageHandler()

void registerMessageHandler | ( | MessageHandler * | mh | ) |

inline

Use this function to associate a MessageHandler with this MessageSession. The MessageHandler will receive all messages sent from this MessageSession's remote contact.

Parameters

  mh | The MessageHandler to register.

Definition at line 212 of file messagesession.h.

## removeMessageFilter()

void removeMessageFilter | ( | MessageFilter * | mf | ) |

inline

Use this function to remove a MessageFilter from the MessageSession.

Parameters

  mf | The MessageFilter to remove.

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

Definition at line 255 of file messagesession.h.

## removeMessageHandler()

void removeMessageHandler | ( |  | ) |

inline

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

Definition at line 219 of file messagesession.h.

## resetResource()

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. This does not automatically set the wantResourceTracking option. If you need escalation, be sure to set this option in the constructor.

Definition at line 99 of file messagesession.cpp.

## send() [1/3]

void send | ( | const Message & | msg | ) |

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 a thread ID is added nor is the message ran through the message filters).

Parameters

  msg | A Message to send.

Definition at line 89 of file messagesession.cpp.

## send() [2/3]

void send | ( | const std::string & | message | ) |

virtual

A convenience function to quickly send a message.

Parameters

  message | The message to send.

Reimplemented in MUCMessageSession.

Definition at line 62 of file messagesession.cpp.

## send() [3/3]

void send | ( | const std::string & | message,
|  | const std::string & | subject,
|  | const StanzaExtensionList & | sel = StanzaExtensionList() )

virtual

A convenience function to quickly send a message (optionally with subject). This is the preferred way to send a message from a MessageSession.

Parameters

  message | The message to send.
  subject | The optional subject to send.
  sel | An optional list of StanzaExtensions. The extensions will be owned by the message-to-be-sent; do not attempt to re-use or delete them.

Reimplemented in MUCMessageSession.

Definition at line 67 of file messagesession.cpp.

## setThreadID()

void setThreadID | ( | const std::string & | thread | ) |

inline

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

Parameters

  thread | The new thread ID.

Definition at line 197 of file messagesession.h.

## target()

const JID & target | ( |  | ) | const

inline

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

Returns
  The receipient's JID.

Definition at line 183 of file messagesession.h.

## threadID()

const std::string & threadID | ( |  | ) | const

inline

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

Returns
  The thread ID for this session.

Definition at line 190 of file messagesession.h.

## types()

int types | ( |  | ) | const

inline

Returns the message type this MessageSession wants to receive.

Returns
  ORed list of Message::MessageType values this MessageSession wants to receive.

Definition at line 269 of file messagesession.h.

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

- messagesession.h
- messagesession.cpp