NLNET::CMessage Class Reference

Message memory stream for network. More...

#include <message.h>

Classes
struct	TFormat
Public Types
enum	TStreamFormat { UseDefault, Binary, String }
enum	TMessageType { OneWay, Request, Response, Except }
Public Member Functions
	CMessage (const std::string &name="", bool inputStream=false, TStreamFormat streamformat=UseDefault, uint32 defaultCapacity=1000)
	CMessage (NLMISC::CMemStream &memstr)
	CMessage (const CMessage &other)
	Copy constructor.
CMessage &	operator= (const CMessage &other)
	Assignment operator.
void	swap (CMessage &other)
	exchange memory data
void	setType (const std::string &name, TMessageType type=OneWay)
	Sets the message type as a string and put it in the buffer if we are in writing mode.
void	changeType (const std::string &name)
uint32	getHeaderSize () const
	Returns the size, in byte of the header that contains the type name of the message or the type number.
void	readType ()
	The message was filled with an CMemStream, Now, we'll get the message type on this buffer.
std::string	readTypeAtCurrentPos () const
	Get the message name (input message only) and advance the current pos.
bool	typeIsSet () const
virtual uint32	length () const
	Returns the length (size) of the message, in bytes.
virtual uint32	lengthS () const
	Returns the serialized length (number of bytes written or read).
uint32	lengthR () const
	Returns the "read" message size (number of bytes to read) (note: see comment about _LengthR).
virtual sint32	getPos () const throw (NLMISC::EStream)
	Get the location of the stream pointer.
std::string	lockSubMessage (uint32 subMsgSize) const
	Set an input message to look like, from a message callback's scope, as if it began at the current pos and ended at the current pos + msgSize, and read the header and return the name of the sub message.
void	unlockSubMessage () const
	Exit from sub message locking, and skip the whole sub message.
bool	hasLockedSubMessage () const
	Return true if a sub message has been locked.
virtual const uint8 *	buffer () const
	If a sub message is locked, return the sub message part.
void	assignFromSubMessage (const CMessage &msgin)
	Similar to operator=, but makes the current message contain only the locked sub message in msgin or the whole msgin if it is not locked.
void	invert ()
	Transforms the message from input to output or from output to input.
void	clear ()
	Clears the message.
std::string	getName () const
	Returns the type name in string if available.
TMessageType	getType () const
	Return the type of the message.
std::string	toString (bool hexFormat=false, bool textFormat=false) const
	Returns a readable string to display it to the screen.
NLMISC::CMemStream	extractStreamFromPos (sint32 pos)
	Return an input stream containing the stream beginning in the message at the specified pos.
void	serialMessage (CMessage &msg)
	Encapsulate/decapsulate another message inside the current message.
Static Public Member Functions
static void	setDefaultStringMode (bool stringmode)
	Set default stream mode.
Protected Member Functions
void	init (const std::string &name, TStreamFormat streamformat)
	Utility method.
void	resetSubMessageInternals () const
	Utility method.
Private Attributes
std::string	_Name
TMessageType	_Type
uint32	_SubMessagePosR
uint32	_LengthR
uint32	_HeaderSize
bool	_TypeSet
Static Private Attributes
static bool	_DefaultStringMode = false

Detailed Description

Message memory stream for network.

Can be serialized to/from (see SerialBuffer()). Can be sent or received over a network, using the NeL network engine. If MESSAGES_PLAIN_TEXT is defined, the messages will be serialized to/from plain text (human-readable), instead of binary.

Author:: Vianney Lecroart; Nevrax France

Date:: 2001

Definition at line 49 of file message.h.

Member Enumeration Documentation

enum NLNET::CMessage::TMessageType

Enumerator:

OneWay
Request
Response
Except

Definition at line 54 of file message.h.

enum NLNET::CMessage::TStreamFormat

Enumerator:

UseDefault
Binary
String

Definition at line 53 of file message.h.

Constructor & Destructor Documentation

NLNET::CMessage::CMessage	(	const std::string &	name = `""`,
		bool	inputStream = `false`,
		TStreamFormat	streamformat = `UseDefault`,
		uint32	defaultCapacity = `1000`
	)

Definition at line 48 of file message.cpp.

References init().

NLNET::CMessage::CMessage ( NLMISC::CMemStream & memstr )

Definition at line 78 of file message.cpp.

References NLMISC::IStream::begin, getPos(), invert(), NLMISC::IStream::isReading(), readType(), and NLMISC::CMemStream::seek().

NLNET::CMessage::CMessage ( const CMessage & other )

Copy constructor.

Definition at line 97 of file message.cpp.

References operator=().

Member Function Documentation

void NLNET::CMessage::assignFromSubMessage ( const CMessage & msgin )

Similar to operator=, but makes the current message contain *only* the locked sub message in msgin or the whole msgin if it is not locked.

Preconditions:

msgin is an input message (isReading())
The current message is blank (new or reset with clear())

Postconditions:

If msgin has been locked using lockSubMessage(), the current message contains only the locked sub message in msgin, otherwise the current message is exactly msgin
The current message is an input message, it is not locked

Definition at line 156 of file message.cpp.

References _LengthR, _TypeSet, buffer(), NLMISC::CMemStream::fill(), getPos(), hasLockedSubMessage(), invert(), NLMISC::IStream::isReading(), nlassert, operator=(), readType(), and NLMISC::CMemStream::seek().

Referenced by NLNET::cbTCReceiveMessage(), operator=(), and NLNET::CStandardGateway::sendModuleMessage().

virtual const uint8* NLNET::CMessage::buffer ( ) const [inline, virtual]

If a sub message is locked, return the sub message part.

Reimplemented from NLMISC::CMemStream.

Definition at line 222 of file message.h.

References NLMISC::CMemStream::_Buffer, _SubMessagePosR, and hasLockedSubMessage().

Referenced by assignFromSubMessage(), extractStreamFromPos(), NLNET::CCallbackClient::receive(), NLNET::TMessageRecord::serial(), and serialMessage().

void NLNET::CMessage::changeType ( const std::string & name )

Definition at line 231 of file message.cpp.

References NLMISC::IStream::begin, getPos(), NLMISC::CMemStream::seek(), and NLMISC::CMemStream::serial().

void NLNET::CMessage::clear ( void ) [virtual]

Clears the message.

Reimplemented from NLMISC::CMemStream.

Definition at line 327 of file message.cpp.

References _LengthR, _SubMessagePosR, _TypeSet, hasLockedSubMessage(), NLMISC::IStream::isReading(), NLNET::LockedSubMessageError, and nlassertex.

Referenced by NLNET::cbTCReceiveMessage(), NLNET::CTransportClass::createLocalRegisteredClassMessage(), NLNET::CPacsClient::initMessage(), and NLNET::CTransportClass::write().

NLMISC::CMemStream NLNET::CMessage::extractStreamFromPos ( sint32 pos )

Return an input stream containing the stream beginning in the message at the specified pos.

Definition at line 411 of file message.cpp.

References buffer(), NLMISC::CMemStream::bufferToFill(), length(), and NLNET::msg.

uint32 NLNET::CMessage::getHeaderSize ( ) const

Returns the size, in byte of the header that contains the type name of the message or the type number.

Definition at line 243 of file message.cpp.

References _HeaderSize, hasLockedSubMessage(), and nlassert.

Referenced by NLNET::getNameOfMessageOrTransportClass().

std::string NLNET::CMessage::getName ( void ) const

Returns the type name in string if available.

Be sure that the message have the name of the message type In a callback driven by message name, getName() does not necessarily return the right name.

Definition at line 340 of file message.cpp.

References NLMISC::CMemStream::_Buffer, _LengthR, _Name, _SubMessagePosR, _TypeSet, NLMISC::IStream::begin, getPos(), hasLockedSubMessage(), nlassert, readTypeAtCurrentPos(), and NLMISC::CMemStream::seek().

Referenced by NLNET::CModuleBase::_onProcessModuleMessage(), NLNET::CStandardGateway::dispatchModuleMessage(), NLNET::getNameOfMessageOrTransportClass(), NLNET::CGatewayL3ClientTransport::onDispatchMessage(), NLNET::CGatewayL3ServerTransport::onDispatchMessage(), NLNET::CStandardGateway::onModuleUnplugged(), NLNET::CStandardGateway::onModuleUpdate(), NLNET::CStandardGateway::onProcessModuleMessage(), NLNET::CStandardGateway::onReceiveMessage(), NLNET::CStandardGateway::onReceiveModuleMessage(), NLNET::CCallbackNetBase::processOneMessage(), NLNET::CUnifiedNetwork::send(), NLNET::CStandardGateway::sendModuleMessage(), NLNET::uncbMsgProcessing(), and unlockSubMessage().

virtual sint32 NLNET::CMessage::getPos ( void ) const throw (NLMISC::EStream) [inline, virtual]

Get the location of the stream pointer.

NB: If the stream doesn't support the seek fonctionnality, it throws ESeekNotSupported. Default implementation: { throw ESeekNotSupported; }

Parameters:

	offset	is the wanted offset from the origin.
	origin	is the origin of the seek

Returns:: the new offset regarding from the origin.

See also:: ESeekNotSupported SeekOrigin seek

Reimplemented from NLMISC::CMemStream.

Definition at line 149 of file message.h.

References NLMISC::CMemStream::_Buffer, and _SubMessagePosR.

Referenced by assignFromSubMessage(), changeType(), CMessage(), getName(), getType(), lockSubMessage(), NLNET::CStandardGateway::onReceiveModuleUpdate(), readType(), setType(), and unlockSubMessage().

CMessage::TMessageType NLNET::CMessage::getType ( void ) const

Return the type of the message.

Definition at line 365 of file message.cpp.

References NLMISC::CMemStream::_Buffer, _LengthR, _SubMessagePosR, _Type, _TypeSet, NLMISC::IStream::begin, getPos(), hasLockedSubMessage(), nlassert, readTypeAtCurrentPos(), and NLMISC::CMemStream::seek().

Referenced by NLNET::CModuleBase::_onProcessModuleMessage(), NLNET::CStandardGateway::dispatchModuleMessage(), and NLNET::CModuleBase::invokeModuleOperation().

bool NLNET::CMessage::hasLockedSubMessage ( ) const [inline]

Return true if a sub message has been locked.

Definition at line 215 of file message.h.

References _SubMessagePosR.

Referenced by assignFromSubMessage(), buffer(), clear(), getHeaderSize(), getName(), getType(), invert(), lengthS(), lockSubMessage(), operator=(), NLNET::CStandardGateway::sendModuleMessage(), swap(), and unlockSubMessage().

void NLNET::CMessage::init	(	const std::string &	name,
		TStreamFormat	streamformat
	)			`[protected]`

Utility method.

Definition at line 59 of file message.cpp.

References _DefaultStringMode, NLMISC::CMemStream::setStringMode(), setType(), String, and UseDefault.

Referenced by CMessage().

void NLNET::CMessage::invert ( ) [inline, virtual]

Transforms the message from input to output or from output to input.

Reimplemented from NLMISC::CMemStream.

Definition at line 252 of file message.h.

References NLMISC::CMemStream::_Buffer, _TypeSet, hasLockedSubMessage(), NLMISC::IStream::isReading(), NLNET::LockedSubMessageError, nlassertex, and readType().

Referenced by assignFromSubMessage(), CMessage(), NLNET::CTransportClass::createLocalRegisteredClassMessage(), serialMessage(), and NLNET::CTransportClass::write().

virtual uint32 NLNET::CMessage::length ( ) const [inline, virtual]

Returns the length (size) of the message, in bytes.

If isReading(), it is the number of bytes that can be read, otherwise it is the number of bytes that have been written. Overloaded because uses a specific version of lengthR().

Reimplemented from NLMISC::CMemStream.

Definition at line 120 of file message.h.

References NLMISC::IStream::isReading(), lengthR(), and lengthS().

Referenced by extractStreamFromPos(), NLNET::CStandardGateway::onReceiveModuleUpdate(), NLNET::CCallbackNetBase::processOneMessage(), NLNET::CCallbackServer::send(), NLNET::CCallbackClient::send(), NLNET::TMessageRecord::serial(), serialMessage(), and setType().

uint32 NLNET::CMessage::lengthR ( ) const [inline]

Returns the "read" message size (number of bytes to read) (note: see comment about _LengthR).

Reimplemented from NLMISC::CMemStream.

Definition at line 144 of file message.h.

References _LengthR.

Referenced by length(), and lockSubMessage().

virtual uint32 NLNET::CMessage::lengthS ( ) const [inline, virtual]

Returns the serialized length (number of bytes written or read).

Reimplemented from NLMISC::CMemStream.

Definition at line 132 of file message.h.

References NLMISC::CMemStream::_Buffer, _SubMessagePosR, and hasLockedSubMessage().

Referenced by length().

std::string NLNET::CMessage::lockSubMessage ( uint32 subMsgSize ) const [inline]

Set an input message to look like, from a message callback's scope, as if it began at the current pos and ended at the current pos + msgSize, and read the header and return the name of the sub message.

This method provides a way to pass a big message containing a set of sub messages to their message callback, without copying each sub message to a new message. If you need to perform some actions that are not allowed with a locked message (see postconditions), use assignFromSubMessage(): the locked sub message in M1 can be copied to a new message M2 with 'M2.assignFromSubMessage( M1 )'.

Preconditions:

The message is an input message (isReading())
msgEndPos <= length()
getPos() >= getHeaderSize()

Postconditions:

The sub message is ready to be read from
length() returns the size of the sub message
getName() return the name of the sub message
Unless you call unlockSubMessage(), the following actions will assert or raise an exception: Serializing more than the sub message size, clear(), operator=() (from/to), invert().

Definition at line 181 of file message.h.

References _LengthR, _SubMessagePosR, getPos(), hasLockedSubMessage(), NLMISC::IStream::isReading(), lengthR(), nlassert, nlassertex, and NLMISC::IStream::unconst().

Referenced by NLNET::CGatewayL5Transport::onDispatchMessage().

CMessage & NLNET::CMessage::operator= ( const CMessage & other )

Assignment operator.

Reimplemented from NLMISC::CMemStream.

Definition at line 107 of file message.cpp.

References _HeaderSize, _LengthR, _Name, _SubMessagePosR, _Type, _TypeSet, assignFromSubMessage(), hasLockedSubMessage(), NLMISC::IStream::isReading(), NLNET::LockedSubMessageError, and nlassertex.

Referenced by assignFromSubMessage(), and CMessage().

void NLNET::CMessage::readType ( )

The message was filled with an CMemStream, Now, we'll get the message type on this buffer.

This method updates _LengthR with the actual size of the buffer (it calls resetLengthR()).

Definition at line 254 of file message.cpp.

References _HeaderSize, NLMISC::CMemStream::_StringMode, NLMISC::IStream::begin, getPos(), NLMISC::IStream::isReading(), NLNET::CMessage::TFormat::MessageType, nlassert, resetSubMessageInternals(), NLMISC::CMemStream::seek(), NLMISC::CMemStream::serial(), setType(), and NLNET::CMessage::TFormat::StringMode.

Referenced by assignFromSubMessage(), CMessage(), invert(), NLNET::CCallbackServer::receive(), NLNET::CCallbackClient::receive(), and serialMessage().

std::string NLNET::CMessage::readTypeAtCurrentPos ( ) const

Get the message name (input message only) and advance the current pos.

Definition at line 288 of file message.cpp.

References NLMISC::CMemStream::_StringMode, _Type, NLMISC::IStream::current, NLMISC::IStream::isReading(), NLNET::CMessage::TFormat::LongFormat, NLNET::CMessage::TFormat::MessageType, nlassert, nlerror, nlRead, NLMISC::CMemStream::seek(), NLMISC::CMemStream::serial(), and NLNET::CMessage::TFormat::StringMode.

Referenced by getName(), and getType().

void NLNET::CMessage::resetSubMessageInternals ( ) const [inline, protected]

Utility method.

Definition at line 303 of file message.h.

References NLMISC::CMemStream::_Buffer, _LengthR, and _SubMessagePosR.

Referenced by readType(), and unlockSubMessage().

void NLNET::CMessage::serialMessage ( CMessage & msg )

Encapsulate/decapsulate another message inside the current message.

Definition at line 423 of file message.cpp.

References buffer(), NLMISC::CMemStream::bufferToFill(), invert(), NLMISC::IStream::isReading(), length(), readType(), NLMISC::CMemStream::seek(), NLMISC::CMemStream::serial(), and NLMISC::CMemStream::serialBuffer().

static void NLNET::CMessage::setDefaultStringMode ( bool stringmode ) [inline, static]

Set default stream mode.

Definition at line 289 of file message.h.

References _DefaultStringMode.

Referenced by NLNET::IService::main().

void NLNET::CMessage::setType	(	const std::string &	name,
		TMessageType	type = `OneWay`
	)

Sets the message type as a string and put it in the buffer if we are in writing mode.

Definition at line 179 of file message.cpp.

References _HeaderSize, _Name, NLMISC::CMemStream::_StringMode, _Type, _TypeSet, FormatLong, getPos(), NLMISC::IStream::isReading(), length(), NLNET::CMessage::TFormat::LongFormat, NLNET::CMessage::TFormat::MessageType, nlassert, NLMISC::CMemStream::serial(), and NLNET::CMessage::TFormat::StringMode.

Referenced by NLNET::CModuleBase::_onProcessModuleMessage(), NLNET::CTransportClass::createLocalRegisteredClassMessage(), NLNET::CStandardGateway::dispatchModuleMessage(), init(), NLNET::CPacsClient::initMessage(), readType(), and NLNET::CTransportClass::write().

void NLNET::CMessage::swap ( CMessage & other )

exchange memory data

Reimplemented from NLMISC::CMemStream.

Definition at line 130 of file message.cpp.

References _HeaderSize, _LengthR, _Name, _SubMessagePosR, _Type, _TypeSet, hasLockedSubMessage(), and nlassert.

std::string NLNET::CMessage::toString	(	bool	hexFormat = `false`,
		bool	textFormat = `false`
	)			const

Returns a readable string to display it to the screen.

It's only for debugging purpose! Don't use it for anything else than to debugging, the string format could change in the future.

Parameters:

	hexFormat	If true, display all bytes in hexadecimal
	textFormat	If true, display all bytes as chars (above 31, otherwise '.')

Definition at line 396 of file message.cpp.

References _Name.

Referenced by NLNET::CCallbackNetBase::processOneMessage(), and NLNET::CNetManager::send().

bool NLNET::CMessage::typeIsSet ( ) const

Definition at line 321 of file message.cpp.

References _TypeSet.

Referenced by NLNET::CCallbackServer::send(), and NLNET::CCallbackClient::send().

void NLNET::CMessage::unlockSubMessage ( ) const [inline]

Exit from sub message locking, and skip the whole sub message.

Preconditions:

The message is an input message (isReading()) and has been locked using lockSubMessage()
The reading pos is within or at the end of the previous sub message (if any) (see nlassertex)

Postconditions: