Vault  4.1
Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes
VMessage Class Reference

VMessage is an abstract base class that implements the basic messaging capabilities; the concrete subclass must implement the send() and receive() functions, which know how to read and write the particular message protocol format (the wire protocol). More...

#include <vmessage.h>

Inheritance diagram for VMessage:
VBinaryIOStream VIOStream

List of all members.

Public Member Functions

virtual void recycleForSend (VMessageID messageID)
 Readies the message to be re-used with the existing message data intact, for posting to a session or client.
virtual void recycleForReceive ()
 Readies the message to be re-used to read another message from a stream, as if it had just been instantiated, but without pre/re-allocating the data buffer space.
void setMessageID (VMessageID messageID)
 Sets the message ID, which is used when sending.
VMessageID getMessageID () const
 Returns the message ID.
virtual void send (const VString &sessionLabel, VBinaryIOStream &out)=0
 Sends the message to the output stream, using the appropriate wire protocol message format; for example, it might write the message data content length, the message ID, and then the message data.
virtual void receive (const VString &sessionLabel, VBinaryIOStream &in)=0
 Receives the message from the input stream, using the appropriate wire protocol format; for example, it might read the message data content length, the message ID, and then the message data.
void copyMessageData (VMessage &targetMessage) const
 Copies this message's data to the target message's data buffer.
VMessageLength getMessageDataLength () const
 Returns the message data length (does not include the length of the message ID nor the message length indicator itself).
Vu8getBuffer () const
 Returns a pointer to the raw message data buffer -- should only be used for debugging and logging purposes.
Vs64 getBufferSize () const
 Returns the total size of the memory buffer space consumed by this message; this is mainly for use in logging and debugging.

Static Public Attributes

static const VString kMessageLoggerName
static const int kMessageContentRecordingLevel = VLoggerLevel::INFO
 VLoggerLevel::INFO -- human-readable single-line form of message content (e.g., bento text format)
static const int kMessageHeaderLevel = VLoggerLevel::DEBUG
 VLoggerLevel::DEBUG -- message meta data such as ID, length, key, etc.
static const int kMessageContentFieldsLevel = VLoggerLevel::DEBUG + 1
 VLoggerLevel::DEBUG + 1 -- human-readable multi-line form of message content (e.g., non-bento message fields)
static const int kMessageTrafficDetailsLevel = VLoggerLevel::DEBUG + 2
 VLoggerLevel::DEBUG + 2 -- lower level details about message traffic.
static const int kMessageHandlerDispatchLevel = VLoggerLevel::DEBUG + 3
 VLoggerLevel::DEBUG + 3 -- start and end of every message handler.
static const int kMessageHandlerDetailLevel = VLoggerLevel::DEBUG + 4
 VLoggerLevel::DEBUG + 4 -- start and end of every message handler task, plus details of broadcast posting.
static const int kMessageContentHexDumpLevel = VLoggerLevel::DEBUG + 5
 VLoggerLevel::DEBUG + 5 -- hex dump of message content.
static const int kMessageQueueOpsLevel = VLoggerLevel::DEBUG + 6
 VLoggerLevel::DEBUG + 6 -- low-level operations of message i/o queues.
static const int kMessageTraceDetailLevel = VLoggerLevel::TRACE
 VLoggerLevel::TRACE -- extremely low-level message processing details.
static const int kMessageHandlerLifecycleLevel = VLoggerLevel::TRACE
 VLoggerLevel::TRACE -- message handler constructor and destructor.

Protected Member Functions

 VMessage ()
 Constructs an empty message with no message ID defined, suitable for use with receive().
 VMessage (VMessageID messageID, Vs64 initialBufferSize=1024)
 Constructs a message with a message ID, suitable for use with send(), optionally writing message data first.
virtual ~VMessage ()
 Virtual destructor.

Protected Attributes

VMemoryStream mMessageDataBuffer
 The buffer that holds the message data. Mutable because copyMessageData needs to touch it and restore it.

Detailed Description

VMessage is an abstract base class that implements the basic messaging capabilities; the concrete subclass must implement the send() and receive() functions, which know how to read and write the particular message protocol format (the wire protocol).

Definition at line 52 of file vmessage.h.


Constructor & Destructor Documentation

VMessage::VMessage ( ) [protected]

Constructs an empty message with no message ID defined, suitable for use with receive().

You can also set the message ID afterwards with setMessageID().

Definition at line 26 of file vmessage.cpp.

VMessage::VMessage ( VMessageID  messageID,
Vs64  initialBufferSize = 1024 
) [protected]

Constructs a message with a message ID, suitable for use with send(), optionally writing message data first.

Parameters:
messageIDthe message ID
initialBufferSizeif specified, the size of data buffer to preallocate

Definition at line 33 of file vmessage.cpp.


Member Function Documentation

void VMessage::recycleForSend ( VMessageID  messageID) [virtual]

Readies the message to be re-used with the existing message data intact, for posting to a session or client.

The new message ID is applied, and some internal bookkeeping may be performed, but the message data is left alone to be sent, as if it had just been formed. This is designed for use when you receive a message, and then decide to post it or send it without modification (except optionally changing the message ID).

Parameters:
messageIDthe message ID to set for the message

Definition at line 40 of file vmessage.cpp.

References VIOStream::seek0().

void VMessage::recycleForReceive ( ) [virtual]

Readies the message to be re-used to read another message from a stream, as if it had just been instantiated, but without pre/re-allocating the data buffer space.

This can be effective if you have an input loop that reads many messages using a single VMessage on the stack.

Definition at line 45 of file vmessage.cpp.

References CONST_S64, mMessageDataBuffer, and VMemoryStream::setEOF().

void VMessage::setMessageID ( VMessageID  messageID) [inline]

Sets the message ID, which is used when sending.

Parameters:
messageIDthe message ID

Definition at line 77 of file vmessage.h.

virtual void VMessage::send ( const VString sessionLabel,
VBinaryIOStream out 
) [pure virtual]

Sends the message to the output stream, using the appropriate wire protocol message format; for example, it might write the message data content length, the message ID, and then the message data.

The message data content is stored in the mMessageDataBuffer and it is typically just copied to the output stream using streamCopy(). The data length can be obtained by calling this->getMessageDataLength().

Parameters:
sessionLabela label to use in log output, to identify the session
outthe stream to write to
virtual void VMessage::receive ( const VString sessionLabel,
VBinaryIOStream in 
) [pure virtual]

Receives the message from the input stream, using the appropriate wire protocol format; for example, it might read the message data content length, the message ID, and then the message data.

The message data should be read into the mMessageDataBuffer, typically by calling streamCopy() after you have read the length value.

Parameters:
sessionLabela label to use in log output, to identify the session
inthe stream to read from
void VMessage::copyMessageData ( VMessage targetMessage) const

Copies this message's data to the target message's data buffer.

The target's ID and other meta information (such as broadcast info) is not altered. This message's i/o offset is restored upon return, so its internal state is essentially untouched. The target message's offset is honored and altered, so you could use this function to append data to the target message at its current i/o offset. I've declared mMessageDataBuffer mutable so that this function can be properly declared const and still call non-const functions of mMessageDataBuffer (it saves and restores the buffer's state).

Definition at line 50 of file vmessage.cpp.

References VMemoryStream::getEOFOffset(), VMemoryStream::getIOOffset(), mMessageDataBuffer, VMemoryStream::seek(), VStream::seek0(), and VStream::streamCopy().

VMessageLength VMessage::getMessageDataLength ( ) const

Returns the message data length (does not include the length of the message ID nor the message length indicator itself).

Returns:
the message data length

Definition at line 58 of file vmessage.cpp.

References VMemoryStream::getEOFOffset(), and mMessageDataBuffer.

Vu8 * VMessage::getBuffer ( ) const

Returns a pointer to the raw message data buffer -- should only be used for debugging and logging purposes.

The length of the valid data in the buffer is getMessageDataLength(). The returned pointer is only guaranteed to be valid as long as the message itself exists and is not written to (writing may require the buffer to be reallocated).

Returns:
a pointer to the raw message data buffer

Definition at line 62 of file vmessage.cpp.

References VMemoryStream::getBuffer(), and mMessageDataBuffer.

Vs64 VMessage::getBufferSize ( ) const

Returns the total size of the memory buffer space consumed by this message; this is mainly for use in logging and debugging.

Returns:
the message data length

Definition at line 66 of file vmessage.cpp.

References VMemoryStream::getBufferSize(), and mMessageDataBuffer.


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

Copyright ©1997-2014 Trygve Isaacson. All rights reserved. This documentation was generated with Doxygen.