Ceylan::Middleware::LightWeightMarshaller Class Reference

Encodes et decodes basic data types from a given stream with most basic encoding routines, which deal only with endianness for fixed-size types. More...

#include <CeylanLightWeightMarshaller.h>

Inheritance diagram for Ceylan::Middleware::LightWeightMarshaller:

Inheritance graph
[legend]
Collaboration diagram for Ceylan::Middleware::LightWeightMarshaller:

Collaboration graph
[legend]

List of all members.

Public Types

enum  TextOutputFormat { rawText, html }
 Defines what text output formats for TextDisplayable instances are available. More...

Public Member Functions

 LightWeightMarshaller (System::InputOutputStream &lowerLevelStream, System::Size bufferedSize=0)
 Constructs a new marshaller/demarshaller object.
virtual ~LightWeightMarshaller () throw ()
 Virtual destructor.
virtual Ceylan::Sint8 decodeSint8 ()
 Returns a Ceylan::Sint8 decoded from internal stream.
virtual Ceylan::Uint8 decodeUint8 ()
 Returns a Ceylan::Uint8 decoded from internal stream.
virtual Ceylan::Sint16 decodeSint16 ()
 Returns a Ceylan::Sint16 decoded from internal stream.
virtual Ceylan::Uint16 decodeUint16 ()
 Returns a Ceylan::Uint16 decoded from internal stream.
virtual Ceylan::Sint32 decodeSint32 ()
 Returns a Ceylan::Sint32 decoded from internal stream.
virtual Ceylan::Uint32 decodeUint32 ()
 Returns a Ceylan::Uint32 decoded from internal stream.
virtual Ceylan::Float32 decodeFloat32 ()
 Returns a Ceylan::Float32 decoded from internal stream.
virtual Ceylan::Float64 decodeFloat64 ()
 Returns a Ceylan::Float64 decoded from internal stream.
virtual void decodeString (std::string &result)
 Reads a string from this internal stream, and stores it in the specified string.
virtual void encodeSint8 (Ceylan::Sint8 toEncode)
 Encodes a Ceylan::Sint8 to internal stream.
virtual void encodeUint8 (Ceylan::Uint8 toEncode)
 Encodes a Ceylan::Uint8 to internal stream.
virtual void encodeSint16 (Ceylan::Sint16 toEncode)
 Encodes a Ceylan::Sint16 to internal stream.
virtual void encodeUint16 (Ceylan::Uint16 toEncode)
 Encodes a Ceylan::Uint16 to internal stream.
virtual void encodeSint32 (Ceylan::Sint32 toEncode)
 Encodes a Ceylan::Sint32 to internal stream.
virtual void encodeUint32 (Ceylan::Uint32 toEncode)
 Encodes a Ceylan::Uint32 to internal stream.
virtual void encodeFloat32 (Ceylan::Float32 toEncode)
 Encodes a Ceylan::Uint32 to internal stream.
virtual void encodeFloat64 (Ceylan::Float64 toEncode)
 Encodes a Ceylan::Uint32 to internal stream.
virtual void encodeString (std::string &toEncode)
 Encodes a string to internal stream.
virtual const std::string toString (Ceylan::VerbosityLevels level=Ceylan::high) const
 Returns a user-friendly description of the state of this object.
virtual System::Size retrieveData (System::Size requestedSize=0)
 Requests this marshaller to read either a minimum size or as much data as possible, so that there may be enough data to read at least a full PDU.

Static Public Member Functions

static const std::string ToString (std::list< TextDisplayable * > displayables, Ceylan::VerbosityLevels level=Ceylan::high)
 Returns a user-friendly description of this list of pointers to text displayable instances.
static TextOutputFormat GetOutputFormat ()
 Returns the current overall text format to be used by TextDisplayable instances.
static void SetOutputFormat (TextOutputFormat newOutputFormat)
 Sets the current overall text format to be used by TextDisplayable instances.

Protected Member Functions

System::InputOutputStream & getEffectiveStream ()
 Returns the input stream that should be used for direct encoding/decoding.
bool isBuffered () const

Protected Attributes

System::InputOutputStream * _lowerLevelStream
 The stream that will be used to exchange marshall/demarshall informations.
System::MemoryStream * _bufferStream
 An in-memory buffered stream that may be used to cache read bytes until they form a full structure that has to be read as a whole (like a PDU) or not at all, for example by a protocol endpoint.

Static Protected Attributes

static TextOutputFormat _OutputFormat = rawText
 The text format to be used currently by TextDisplayable instances.

Private Member Functions

 LightWeightMarshaller (const LightWeightMarshaller &source)
 Copy constructor made private to ensure that it will be never called.
LightWeightMarshaller & operator= (const LightWeightMarshaller &source)
 Assignment operator made private to ensure that it will be never called.

Detailed Description

Encodes et decodes basic data types from a given stream with most basic encoding routines, which deal only with endianness for fixed-size types.

More precisely, this marshaller allows to encode and decode basic data types such as Ceylan::Uint32 so that they can for example go through a network channel while being correctly understood by both sides of the channel, no matter their respective endiannesses are.

To do so, a pivot format is chosen, and both sides ensure that it is respected: the sender converts its own format to the pivot one, the result goes through the network layer, and the receiver converts it from the pivot format to its own format.

Many formats can be chosen for the pivot, we chose here to rely on the usual sequence of bits transformed into litlle endian format. We preferred little endian (the native encoding for x86) to the big one (the one of PowerPC, Sparc, but also the network order), so that on most cases no conversion has to be performed (x86 actually just writes and reads bytes as they are).

See also:
CeylanTypes.h
Note:
Actually the conversion is directly performed by the underlying input/output stream, hence this marshaller is light-weight insofar as it is just an empty "letter-box" interface.

Definition at line 77 of file CeylanLightWeightMarshaller.h.

Member Enumeration Documentation

enum Ceylan::TextDisplayable::TextOutputFormat [inherited]

Defines what text output formats for TextDisplayable instances are available.

Enumerator:
rawText 
html 

Definition at line 124 of file CeylanTextDisplayable.h.

Constructor & Destructor Documentation

LightWeightMarshaller::LightWeightMarshaller ( System::InputOutputStream &  lowerLevelStream,
System::Size  bufferedSize = 0 
) [explicit]

Constructs a new marshaller/demarshaller object.

Parameters:
lowerLevelStream the stream that will be used by the marshaller to read/write the bitstream to be transformed into higher level constructs, here basic Ceylan datatypes such as Ceylan::Sint16, or strings.
bufferedSize the size in bytes of an internal buffered stream used so that only full PDU can be made available by the marshaller. A null size means no buffer wanted.
Note:
The marshaller does not take ownership of the stream, hence will not deallocate it.

Definition at line 55 of file CeylanLightWeightMarshaller.cc.

LightWeightMarshaller::~LightWeightMarshaller (  )  throw () [virtual]

Virtual destructor.

Definition at line 65 of file CeylanLightWeightMarshaller.cc.

Ceylan::Middleware::LightWeightMarshaller::LightWeightMarshaller ( const LightWeightMarshaller &  source  )  [private]

Copy constructor made private to ensure that it will be never called.

The compiler should complain whenever this undefined constructor is called, implicitly or not.

Member Function Documentation

Ceylan::Float32 LightWeightMarshaller::decodeFloat32 (  )  [virtual]

Returns a Ceylan::Float32 decoded from internal stream.

Exceptions:
DecodeException in case a conversion error occured, or IOException if a transport protocol error occured, including if there are fewer bytes available than expected.

Definition at line 158 of file CeylanLightWeightMarshaller.cc.

References getEffectiveStream(), and Ceylan::System::InputStream::readFloat32().

Ceylan::Float64 LightWeightMarshaller::decodeFloat64 (  )  [virtual]

Returns a Ceylan::Float64 decoded from internal stream.

Exceptions:
DecodeException in case a conversion error occured, or IOException if a transport protocol error occured, including if there are fewer bytes available than expected.

Definition at line 170 of file CeylanLightWeightMarshaller.cc.

References getEffectiveStream(), and Ceylan::System::InputStream::readFloat64().

Ceylan::Sint16 LightWeightMarshaller::decodeSint16 (  )  [virtual]

Returns a Ceylan::Sint16 decoded from internal stream.

Exceptions:
DecodeException in case a conversion error occured, or IOException if a transport protocol error occured, including if there are fewer bytes available than expected.

Definition at line 113 of file CeylanLightWeightMarshaller.cc.

References getEffectiveStream(), and Ceylan::System::InputStream::readSint16().

Ceylan::Sint32 LightWeightMarshaller::decodeSint32 (  )  [virtual]

Returns a Ceylan::Sint32 decoded from internal stream.

Exceptions:
DecodeException in case a conversion error occured, or IOException if a transport protocol error occured, including if there are fewer bytes available than expected.

Definition at line 136 of file CeylanLightWeightMarshaller.cc.

References getEffectiveStream(), and Ceylan::System::InputStream::readSint32().

Ceylan::Sint8 LightWeightMarshaller::decodeSint8 (  )  [virtual]

Returns a Ceylan::Sint8 decoded from internal stream.

Exceptions:
DecodeException in case a conversion error occured, or IOException if a transport protocol error occured, including if there are fewer bytes available than expected.

Definition at line 90 of file CeylanLightWeightMarshaller.cc.

References getEffectiveStream(), and Ceylan::System::InputStream::readSint8().

void LightWeightMarshaller::decodeString ( std::string &  result  )  [virtual]

Reads a string from this internal stream, and stores it in the specified string.

Note:
Read strings can have no more than 65535 characters.
Parameters:
result the string to fill from this stream.
Exceptions:
DecodeException in case a conversion error occured, or IOException if a transport protocol error occured, including if there are fewer bytes available than expected.

Definition at line 181 of file CeylanLightWeightMarshaller.cc.

References getEffectiveStream(), and Ceylan::System::InputStream::readString().

Ceylan::Uint16 LightWeightMarshaller::decodeUint16 (  )  [virtual]

Returns a Ceylan::Uint16 decoded from internal stream.

Exceptions:
DecodeException in case a conversion error occured, or IOException if a transport protocol error occured, including if there are fewer bytes available than expected.

Definition at line 124 of file CeylanLightWeightMarshaller.cc.

References getEffectiveStream(), and Ceylan::System::InputStream::readUint16().

Ceylan::Uint32 LightWeightMarshaller::decodeUint32 (  )  [virtual]

Returns a Ceylan::Uint32 decoded from internal stream.

Exceptions:
DecodeException in case a conversion error occured, or IOException if a transport protocol error occured, including if there are fewer bytes available than expected.

Definition at line 147 of file CeylanLightWeightMarshaller.cc.

References getEffectiveStream(), and Ceylan::System::InputStream::readUint32().

Ceylan::Uint8 LightWeightMarshaller::decodeUint8 (  )  [virtual]

Returns a Ceylan::Uint8 decoded from internal stream.

Exceptions:
DecodeException in case a conversion error occured, or IOException if a transport protocol error occured, including if there are fewer bytes available than expected.

Definition at line 101 of file CeylanLightWeightMarshaller.cc.

References getEffectiveStream(), and Ceylan::System::InputStream::readUint8().

void LightWeightMarshaller::encodeFloat32 ( Ceylan::Float32  toEncode  )  [virtual]

Encodes a Ceylan::Uint32 to internal stream.

Exceptions:
EncodeException in case a conversion error occured, or IOException if a transport protocol error occured.

Definition at line 277 of file CeylanLightWeightMarshaller.cc.

References Ceylan::Middleware::Marshaller::_lowerLevelStream, and Ceylan::System::OutputStream::writeFloat32().

void LightWeightMarshaller::encodeFloat64 ( Ceylan::Float64  toEncode  )  [virtual]

Encodes a Ceylan::Uint32 to internal stream.

Exceptions:
EncodeException in case a conversion error occured, or IOException if a transport protocol error occured.

Definition at line 288 of file CeylanLightWeightMarshaller.cc.

References Ceylan::Middleware::Marshaller::_lowerLevelStream, and Ceylan::System::OutputStream::writeFloat64().

void LightWeightMarshaller::encodeSint16 ( Ceylan::Sint16  toEncode  )  [virtual]

Encodes a Ceylan::Sint16 to internal stream.

Exceptions:
EncodeException in case a conversion error occured, or IOException if a transport protocol error occured.

Definition at line 232 of file CeylanLightWeightMarshaller.cc.

References Ceylan::Middleware::Marshaller::_lowerLevelStream, and Ceylan::System::OutputStream::writeSint16().

void LightWeightMarshaller::encodeSint32 ( Ceylan::Sint32  toEncode  )  [virtual]

Encodes a Ceylan::Sint32 to internal stream.

Exceptions:
EncodeException in case a conversion error occured, or IOException if a transport protocol error occured.

Definition at line 255 of file CeylanLightWeightMarshaller.cc.

References Ceylan::Middleware::Marshaller::_lowerLevelStream, and Ceylan::System::OutputStream::writeSint32().

void LightWeightMarshaller::encodeSint8 ( Ceylan::Sint8  toEncode  )  [virtual]

Encodes a Ceylan::Sint8 to internal stream.

Exceptions:
EncodeException in case a conversion error occured, or IOException if a transport protocol error occured.

Definition at line 209 of file CeylanLightWeightMarshaller.cc.

References Ceylan::Middleware::Marshaller::_lowerLevelStream, and Ceylan::System::OutputStream::writeSint8().

void LightWeightMarshaller::encodeString ( std::string &  toEncode  )  [virtual]

Encodes a string to internal stream.

Note:
Written strings can have no more than 65535 characters.
Parameters:
result the string to fill from this stream.
Exceptions:
EncodeException in case a conversion error occured, or IOException if a transport protocol error occured.

Definition at line 299 of file CeylanLightWeightMarshaller.cc.

References Ceylan::Middleware::Marshaller::_lowerLevelStream, and Ceylan::System::OutputStream::writeString().

void LightWeightMarshaller::encodeUint16 ( Ceylan::Uint16  toEncode  )  [virtual]

Encodes a Ceylan::Uint16 to internal stream.

Exceptions:
EncodeException in case a conversion error occured, or IOException if a transport protocol error occured.

Definition at line 243 of file CeylanLightWeightMarshaller.cc.

References Ceylan::Middleware::Marshaller::_lowerLevelStream, and Ceylan::System::OutputStream::writeUint16().

void LightWeightMarshaller::encodeUint32 ( Ceylan::Uint32  toEncode  )  [virtual]

Encodes a Ceylan::Uint32 to internal stream.

Exceptions:
EncodeException in case a conversion error occured, or IOException if a transport protocol error occured.

Definition at line 266 of file CeylanLightWeightMarshaller.cc.

References Ceylan::Middleware::Marshaller::_lowerLevelStream, and Ceylan::System::OutputStream::writeUint32().

void LightWeightMarshaller::encodeUint8 ( Ceylan::Uint8  toEncode  )  [virtual]

Encodes a Ceylan::Uint8 to internal stream.

Exceptions:
EncodeException in case a conversion error occured, or IOException if a transport protocol error occured.

Definition at line 220 of file CeylanLightWeightMarshaller.cc.

References Ceylan::Middleware::Marshaller::_lowerLevelStream, and Ceylan::System::OutputStream::writeUint8().

System::InputOutputStream& Ceylan::Middleware::LightWeightMarshaller::getEffectiveStream (  )  [inline, protected]

Returns the input stream that should be used for direct encoding/decoding.

For buffered stream, it is the buffer, for the rest it is directly the lower-level stream.

Definition at line 409 of file CeylanLightWeightMarshaller.h.

Referenced by decodeFloat32(), decodeFloat64(), decodeSint16(), decodeSint32(), decodeSint8(), decodeString(), decodeUint16(), decodeUint32(), and decodeUint8().

TextDisplayable::TextOutputFormat TextDisplayable::GetOutputFormat (  )  [static, inherited]

Returns the current overall text format to be used by TextDisplayable instances.

Definition at line 63 of file CeylanTextDisplayable.cc.

References Ceylan::TextDisplayable::_OutputFormat.

Referenced by Ceylan::formatStringList(), Ceylan::formatStringMap(), Ceylan::XML::XMLMarkup::toString(), Ceylan::Maths::Linear::Vector3::toString(), Ceylan::Maths::Linear::Vector2::toString(), Ceylan::Maths::Linear::Tripoint::toString(), Ceylan::Module::toString(), Ceylan::Maths::Linear::Matrix3::toString(), Ceylan::Maths::Linear::Matrix2::toString(), Ceylan::Maths::Linear::HomogeneousMatrix3::toString(), and Ceylan::Maths::Linear::Bipoint::toString().

bool Ceylan::Middleware::Marshaller::isBuffered (  )  const [inline, protected, inherited]

Definition at line 275 of file CeylanMarshaller.h.

Referenced by Ceylan::Middleware::Marshaller::retrieveData(), and Ceylan::Middleware::Marshaller::~Marshaller().

LightWeightMarshaller& Ceylan::Middleware::LightWeightMarshaller::operator= ( const LightWeightMarshaller &  source  )  [private]

Assignment operator made private to ensure that it will be never called.

The compiler should complain whenever this undefined operator is called, implicitly or not.

System::Size Marshaller::retrieveData ( System::Size  requestedSize = 0  )  [virtual, inherited]

Requests this marshaller to read either a minimum size or as much data as possible, so that there may be enough data to read at least a full PDU.

Parameters:
requestedSize the contiguous size that is needed by the caller to store the bytes it is waiting for. If this needed size is greater than the buffer size, the condition will never be met and a DecodeException is thrown. If the needed size is smaller than the buffer size but bigger than the remaining size of next free chunk, as normally previous PDU should have been decoded, at the expense of an automatic move in buffer, the beginning of the PDU to decode will be set back to the beginning of the buffer so that the full PDU will be able to fit in buffer.
If the requested size is null, then this marshaller will try to read from its encapsulated lower level stream the full remaining free size between the current index of its internal buffer and the end of that buffer.

Returns:
the number of bytes available in the buffer for reading. This is not necessarily the exact number of bytes that were just read, insofar as there may already be some data in the buffer before this method was called.
The caller can use the returned information to figure out if it waits for more data or if there is already enough to be decoded in place.

Note:
Using this method only makes sense if the marshaller has an internal buffer.
Exceptions:
DecodeException if the operation failed, including if there is no buffer available, or if there is not enough space in the buffer to fulfill requested size or to read more data.

Definition at line 125 of file CeylanMarshaller.cc.

References Ceylan::Middleware::Marshaller::_bufferStream, Ceylan::Middleware::Marshaller::_lowerLevelStream, dataUtils::e, Ceylan::System::MemoryStream::getAddressOfNextFreeChunk(), Ceylan::System::MemoryStream::getBlockLength(), Ceylan::System::MemoryStream::getSize(), Ceylan::System::MemoryStream::getSizeOfNextFreeChunk(), Ceylan::System::MemoryStream::increaseFilledBlockOf(), Ceylan::Middleware::Marshaller::isBuffered(), Ceylan::System::MemoryStream::moveFilledBlockToBufferStart(), Ceylan::System::InputStream::read(), Ceylan::Exception::toString(), Ceylan::Middleware::Marshaller::toString(), and Ceylan::toString().

void TextDisplayable::SetOutputFormat ( TextOutputFormat  newOutputFormat  )  [static, inherited]

Sets the current overall text format to be used by TextDisplayable instances.

Parameters:
newOutputFormat the new output format.

Definition at line 72 of file CeylanTextDisplayable.cc.

References Ceylan::TextDisplayable::_OutputFormat.

Referenced by Ceylan::Log::LogHolder::LogHolder().

const std::string TextDisplayable::ToString ( std::list< TextDisplayable * >  displayables,
Ceylan::VerbosityLevels  level = Ceylan::high 
) [static, inherited]

Returns a user-friendly description of this list of pointers to text displayable instances.

Parameters:
displayables a list of pointers to TextDisplayable instances/
level the requested verbosity level.
Note:
Text output format is determined from overall settings.
See also:
toString, Ceylan::VerbosityLevels

Definition at line 45 of file CeylanTextDisplayable.cc.

References Ceylan::formatStringList().

const string LightWeightMarshaller::toString ( Ceylan::VerbosityLevels  level = Ceylan::high  )  const [virtual]

Returns a user-friendly description of the state of this object.

Parameters:
level the requested verbosity level.
Note:
Text output format is determined from overall settings.
See also:
TextDisplayable

Reimplemented from Ceylan::Middleware::Marshaller.

Definition at line 310 of file CeylanLightWeightMarshaller.cc.

Member Data Documentation

System::MemoryStream* Ceylan::Middleware::Marshaller::_bufferStream [protected, inherited]

An in-memory buffered stream that may be used to cache read bytes until they form a full structure that has to be read as a whole (like a PDU) or not at all, for example by a protocol endpoint.

Definition at line 291 of file CeylanMarshaller.h.

Referenced by Ceylan::Middleware::Marshaller::Marshaller(), Ceylan::Middleware::Marshaller::retrieveData(), Ceylan::Middleware::Marshaller::toString(), and Ceylan::Middleware::Marshaller::~Marshaller().

System::InputOutputStream* Ceylan::Middleware::Marshaller::_lowerLevelStream [protected, inherited]

The stream that will be used to exchange marshall/demarshall informations.

Definition at line 271 of file CeylanMarshaller.h.

Referenced by encodeFloat32(), encodeFloat64(), encodeSint16(), encodeSint32(), encodeSint8(), encodeString(), encodeUint16(), encodeUint32(), encodeUint8(), Ceylan::Middleware::Marshaller::retrieveData(), and Ceylan::Middleware::Marshaller::toString().

TextDisplayable::TextOutputFormat TextDisplayable::_OutputFormat = rawText [static, protected, inherited]

The text format to be used currently by TextDisplayable instances.

Note:
Defaults to raw text.

Definition at line 158 of file CeylanTextDisplayable.h.

Referenced by Ceylan::TextDisplayable::GetOutputFormat(), and Ceylan::TextDisplayable::SetOutputFormat().

The documentation for this class was generated from the following files:
Generated on Thu Jun 4 20:40:35 2009 for Ceylan by  doxygen 1.5.8