Ionflux::Tools::Message

Ionflux::Tools::Message Class Reference
[Network interface]

#include <Message.hpp>

Inheritance diagram for Ionflux::Tools::Message:

[legend]Collaboration diagram for Ionflux::Tools::Message:


Public Member Functions
	Message ()
	Constructor.
virtual	~Message ()
	Destructor.
virtual void	clearData ()
	Clear data.
virtual void	clearAll ()
	Clear everything.
virtual void	serialize (std::string &buffer)
	Serialize.
virtual bool	append (const std::string &bytes)
	Append bytes.
virtual void	dump (const std::string &bytes)
	Dump bytes.
virtual void	setMagicWord (const std::string &newMagicWord)
	Set magic word.
virtual void	setProtocolVersion (int newProtocolVersion)
	Set protocol version number.
virtual void	setAcceptableProtocolVersion (int newProtocolVersionLower, int newProtocolVersionUpper)
	Set acceptable protocol version number range.
virtual void	setUID (int newUID)
	Set UID.
virtual void	setType (int newType)
	Set message type.
virtual void	setFlags (unsigned int newFlags)
	Set flags.
virtual void	setUsername (const std::string &newUsername)
	Set username.
virtual void	setUserSecret (const std::string &newUserSecret)
	Set user secret.
virtual void	setSessionSecret (const std::string &newSessionSecret)
	Set session secret.
virtual void	setTarget (MessageDump *newTarget)
	Set target.
virtual void	setMaxSize (unsigned int newMaxSize)
	Set maximum message size.
virtual std::string	getMagicWord ()
	Get magic word.
virtual int	getProtocolVersion ()
	Get protocol version.
virtual int	getUID ()
	Get UID.
virtual int	getType ()
	Get message type.
virtual unsigned int	getFlags ()
	Get flags.
virtual unsigned int	getSize ()
	Get size.
virtual std::string	getUsername ()
	Get username.
virtual void	getUserSecret (std::string &userSecretBuffer)
	Get user secret.
virtual void	getSessionSecret (std::string &sessionSecretBuffer)
	Get session secret.
virtual unsigned int	getNumBytesMissing ()
	Get number of missing bytes.
virtual unsigned int	getMaxSize ()
	Get maximum message size.
Static Public Attributes
static const std::string	DEFAULT_MAGIC_WORD = "IFTM"
	Default magic word.
static const int	DEFAULT_PROTOCOL_VERSION = 0
	Default protocol version.
static const int	UID_NOT_SET = -1
	UID: Not set.
static const int	TYPE_NOT_SET = -1
	Type: Not set.
static const int	FLAG_COMPRESS = 1
	Flag: Compress message.
static const int	HEADER_SIZE = 40
	Message header size (excluding the magic word).
static const unsigned int	DEFAULT_MAX_SIZE = 10485760L
	Default maximum message size.
Protected Member Functions
virtual bool	unpack ()
	Unpack message.
Protected Attributes
std::string	magicWord
	Magic word.
int	protocolVersion
	Protocol version.
int	protocolVersionLower
	Acceptable protocol version range: lower boundary.
int	protocolVersionUpper
	Acceptable protocol version range: upper boundary.
int	uid
	Message UID.
int	type
	Message type.
unsigned int	flags
	Message flags.
unsigned int	size
	Size of serialized message.
std::string	checksum
	Checksum buffer.
std::string	username
	Username (used for authentication).
std::string	userSecret
	User secret (used for authentication).
std::string	sessionSecret
	Session secret (used for authentication).
std::string	serialized
	Serialization buffer.
MessageDump *	target
	Target for completed messages.
unsigned int	maxSize
	Maximum size.

Detailed Description

Message.

A message which can encapsulate and serialize arbitrary data, to be sent over a network supporting byte streams or packets. Facilities are provided for integrity verification, compression and simple message authentication.

To create a serialized message, initialize the message as necessary, then call Message::serialize().

To create messages out of a stream of serialized messages, set a handler with Message::setTarget(), then pass bytes from the stream to Message::dump(). The handler will be called whenever a complete message has arrived and has been parsed successfully.

Simple authentication on a per-message basis will be performed if you set the username, user secret and session secret to non-empty values. All of these fields are optional; however, for authentication to succeed, the fields must be set to the same values for the sender and receiver of a message.

Constructor & Destructor Documentation

Ionflux::Tools::Message::Message ( )

Constructor.
Construct new Message object.

Ionflux::Tools::Message::~Message ( ) [virtual]

Destructor.
Destruct Message object.

Member Function Documentation

bool Ionflux::Tools::Message::append ( const std::string & bytes ) [virtual]

Append bytes.
Pass a string of bytes to be processed as part of a serialized message.

Parameters:

bytes The bytes to be appended.

Returns:
true if the bytes could be processed as part of a valid message, false if an error occured.

See also:
serialize(), dump()

void Ionflux::Tools::Message::clearAll ( ) [virtual]

Clear everything.
Clears all internal state, including otherwise persistent properties.

See also:
clearData()

void Ionflux::Tools::Message::clearData ( ) [virtual]

Clear data.
Clears internal data of this message. Persistent properties, such as the magic word, protocol version and user/session data will not be reset.

See also:
clearAll()

void Ionflux::Tools::Message::dump ( const std::string & bytes ) [virtual]

Dump bytes.
Pass a string of bytes to be processed as part of a serialized message.

Note:
If you need information on whether the dumped bytes are part of a valid message, you should use append() instead.

Parameters:

bytes The bytes to be dumped.

See also:
serialize(), append()

unsigned int Ionflux::Tools::Message::getFlags ( ) [virtual]

Get flags.

Returns:
Flags.

std::string Ionflux::Tools::Message::getMagicWord ( ) [virtual]

Get magic word.

Returns:
The magic word.

unsigned int Ionflux::Tools::Message::getMaxSize ( ) [virtual]

Get maximum message size.

Returns:
Maximum allowed size of serialized message, in bytes.

unsigned int Ionflux::Tools::Message::getNumBytesMissing ( ) [virtual]

Get number of missing bytes.
Get the number of serialized bytes required to complete the message. Use dump() to append additional bytes to the message. If the message is complete or invalid, this function returns 0.

Note:
Even if you supply the correct amount of bytes, the message might still not be complete due to invalid or corrupted data or an invalid protocol version. You should rely on the callback facility provided by setTarget() to determine whether a message is actually complete and valid.

Returns:
Number of bytes missing.

See also:
setTarget()

int Ionflux::Tools::Message::getProtocolVersion ( ) [virtual]

Get protocol version.

Returns:
Protocol version.

void Ionflux::Tools::Message::getSessionSecret ( std::string & sessionSecretBuffer ) [virtual]

Get session secret.
Copies the session secret to a specified buffer.

Parameters:

sessionSecretBuffer Where to store the session secret.

unsigned int Ionflux::Tools::Message::getSize ( ) [virtual]

Get size.

Returns:
Size of serialized message data.

int Ionflux::Tools::Message::getType ( ) [virtual]

Get message type.

Returns:
Message type ID.

int Ionflux::Tools::Message::getUID ( ) [virtual]

Get UID.

Returns:
Message UID.

std::string Ionflux::Tools::Message::getUsername ( ) [virtual]

Get username.

Returns:
Username.

void Ionflux::Tools::Message::getUserSecret ( std::string & userSecretBuffer ) [virtual]

Get user secret.
Copies the user secret to a specified buffer.

Parameters:

userSecretBuffer Where to store the user secret.

void Ionflux::Tools::Message::serialize ( std::string & buffer ) [virtual]

Serialize.
Serialize the message. The result will be ready to be sent over a network and may be re-assembled into a message object using dump().

Parameters:

buffer Where to store the serialized message.

See also:
dump(), append()

void Ionflux::Tools::Message::setAcceptableProtocolVersion ( int newProtocolVersionLower,

int newProtocolVersionUpper

) [virtual]

Set acceptable protocol version number range.
Sets the upper and lower limit of acceptable protocol version numbers for creating messages from a stream of serialized messages. If messages arrive that have version numbers outside the specified range, they will be ignored. Messages with acceptable version numbers will be parsed and passed to the handler on completion.

Parameters:

newProtocolVersionLower Lower boundary of acceptable version number range.

newProtocolVersionUpper Upper boundary of acceptable version number range.

See also:
setProtocolVersion(), dump(), setTarget()

void Ionflux::Tools::Message::setFlags ( unsigned int newFlags ) [virtual]

Set flags.
Set additional flags to be sent along with the message. It is possible to combine several flags using the "|" (OR) operator.
Note: Set Message::FLAG_COMPRESS to compress message data using bzip2.

Parameters:

newFlags Flags.

void Ionflux::Tools::Message::setMagicWord ( const std::string & newMagicWord ) [virtual]

Set magic word.
Sets the magic word. This should be a short string (2-4 bytes) specific to your protocol. It will be used to determine ad-hoc whether incoming data might be part of a valid message.

Parameters:

newMagicWord The magic word.

void Ionflux::Tools::Message::setMaxSize ( unsigned int newMaxSize ) [virtual]

Set maximum message size.
Set the maximum allowed size for a single message, in bytes.

Parameters:

newMaxSize Maximum message size (bytes).

void Ionflux::Tools::Message::setProtocolVersion ( int newProtocolVersion ) [virtual]

Set protocol version number.
Sets the protocol version number. Incoming data will be accepted only if the protocol version number is contained within the range of acceptable protocol version numbers.

Parameters:

newProtocolVersion Protocol version.

See also:
setAcceptableProtocolVersion()

void Ionflux::Tools::Message::setSessionSecret ( const std::string & newSessionSecret ) [virtual]

Set session secret.
Set the session secret to be used for message authentication.
Note: As the name implies, you should not reuse this secret across sessions or connections. The best candidate for a session secret is a random string of a fixed length, generated on a new connection and passed to the peer in one of the first few messages.

Parameters:

newSessionSecret Session secret.

void Ionflux::Tools::Message::setTarget ( MessageDump * newTarget ) [virtual]

Set target.
Set the target that should be noified on completion of a message.

Parameters:

newTarget Message target.

void Ionflux::Tools::Message::setType ( int newType ) [virtual]

Set message type.
Set the numerical type ID of the message. This makes sense only if your protocol distingusihes several different message types. You may also use this for error message codes.

Parameters:

newType Message type ID.

void Ionflux::Tools::Message::setUID ( int newUID ) [virtual]

Set UID.
Set the UID of his message. This should be a number unique to a session or connection.

Parameters:

newUID Message UID.

void Ionflux::Tools::Message::setUsername ( const std::string & newUsername ) [virtual]

Set username.
Set the username to be used for message authentication.

Parameters:

newUsername Username.

void Ionflux::Tools::Message::setUserSecret ( const std::string & newUserSecret ) [virtual]

Set user secret.
Set the user secret to be used for message authentication.

Parameters:

newUserSecret User secret.

bool Ionflux::Tools::Message::unpack ( ) [protected, virtual]

Unpack message.
Unpack a message from the data stored in the serialization buffer.

Returns:
true on success, false if the message could not be unpacked.

Member Data Documentation

std::string Ionflux::Tools::Message::checksum [protected]

Checksum buffer.

const std::string Ionflux::Tools::Message::DEFAULT_MAGIC_WORD = "IFTM" [static]

Default magic word.

const unsigned int Ionflux::Tools::Message::DEFAULT_MAX_SIZE = 10485760L [static]

Default maximum message size.

const int Ionflux::Tools::Message::DEFAULT_PROTOCOL_VERSION = 0 [static]

Default protocol version.

const int Ionflux::Tools::Message::FLAG_COMPRESS = 1 [static]

Flag: Compress message.

unsigned int Ionflux::Tools::Message::flags [protected]

Message flags.

const int Ionflux::Tools::Message::HEADER_SIZE = 40 [static]

Message header size (excluding the magic word).

std::string Ionflux::Tools::Message::magicWord [protected]

Magic word.

unsigned int Ionflux::Tools::Message::maxSize [protected]

Maximum size.

int Ionflux::Tools::Message::protocolVersion [protected]

Protocol version.

int Ionflux::Tools::Message::protocolVersionLower [protected]

Acceptable protocol version range: lower boundary.

int Ionflux::Tools::Message::protocolVersionUpper [protected]

Acceptable protocol version range: upper boundary.

std::string Ionflux::Tools::Message::serialized [protected]

Serialization buffer.

std::string Ionflux::Tools::Message::sessionSecret [protected]

Session secret (used for authentication).

unsigned int Ionflux::Tools::Message::size [protected]

Size of serialized message.

MessageDump* Ionflux::Tools::Message::target [protected]

Target for completed messages.

int Ionflux::Tools::Message::type [protected]

Message type.

const int Ionflux::Tools::Message::TYPE_NOT_SET = -1 [static]

Type: Not set.

int Ionflux::Tools::Message::uid [protected]

Message UID.

const int Ionflux::Tools::Message::UID_NOT_SET = -1 [static]

UID: Not set.

std::string Ionflux::Tools::Message::username [protected]

Username (used for authentication).

std::string Ionflux::Tools::Message::userSecret [protected]

User secret (used for authentication).

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

Generated on Tue Mar 14 21:08:47 2006 for Ionflux Tools Class Library (iftools) by

1.4.6

Ionflux::Tools::Message Class Reference [Network interface]

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

Ionflux::Tools::Message Class Reference
[Network interface]