Cpl::Text::Frame::Decoder Class Reference

This class defines an interface for 'receiving' (decode) a frame. More...

Detailed Description

This class defines an interface for 'receiving' (decode) a frame.

What is a frame? A Frame is sequence of characters that has a unique start-of-character (SOF) and a unique end-of-frame character (EOF). The concept of an escape (ESC) character is also defined to support the content of a frame containing SOF/EOF characters. Below are some examples some framed sequences of characters:

Given:
    SOF:= '.'
    EOF:= ';'
    ESC:= '~'


Raw Stream      Decoded Sequence(s)
-----------     --------------------
".abcde;"       "abcde"
".a;.b;.;"      "a", "b", ""
".a;b.c;"       "a", "c"
".a~;bcd"       "a;bcd"
".~~;"          "~"
".a.bcd;"       "a.bcd"
".a~.bcd;"      "a.bcd"


Notes:
    o The quotes (") in the above example are NOT part of the frame
      and/or character sequences - the quotes are only used to
      illustrate sets of characters.
    o The SOF character does not need to be escaped within a frame
      because once a SOF has been found - the SOF character is NOT
      looked/scanned for until after an EOF character has been
      detected.  Escaping an SOF character within a frame will
      behave as expected, i.e. same behavior/semantics as escaping
      the EOF character.
 

#include <Decoder.h>

Inheritance diagram for Cpl::Text::Frame::Decoder:

Public Member Functions
virtual bool	scan (size_t maxSizeOfFrame, char *frame, size_t &frameSize) noexcept=0
	This method reads from an Input source (which is defined/provided by the concrete implementation) until a valid frame is found or an error occurred.
virtual bool	scan (size_t maxSizeOfFrame, char *frame, size_t &frameSize, bool &isEof) noexcept=0
	This method is similar to the above scan() method, except that it does NOT block till a 'frame' has found, instead it indicates when a 'frame' has been found by setting the 'isEof' flag to true.
virtual bool	oobRead (void *buffer, int numBytes, int &bytesRead) noexcept=0
	This method allows 'out-of-band' reading of the input source.
virtual	~Decoder ()
	Virtual Destructor.

Constructor & Destructor Documentation

~Decoder()

virtual Cpl::Text::Frame::Decoder::~Decoder ( )

inlinevirtual

Virtual Destructor.

Member Function Documentation

oobRead()

virtual bool Cpl::Text::Frame::Decoder::oobRead ( void *  buffer, int  numBytes, int &  bytesRead  )

pure virtualnoexcept

This method allows 'out-of-band' reading of the input source.

If the scanner is in-a-frame the method return false and does nothing.

CAUTION: Most client/consumers of the decoder should never use this method. This method only has meaning/usefulness when the application KNOWS when the input source is NOT in a frame AND that there is 'non-framed' data that can be consumed.

Attempts to read the specified number of bytes from the stream into the supplied buffer. The actual number of bytes read is returned via 'bytesRead'. Returns true if successful, or false if End-of-Stream was encountered or if the input source is in a frame.

Implemented in Cpl::Text::Frame::Decoder_.

scan() [1/2]

virtual bool Cpl::Text::Frame::Decoder::scan ( size_t  maxSizeOfFrame, char *  frame, size_t &  frameSize  )

pure virtualnoexcept

This method reads from an Input source (which is defined/provided by the concrete implementation) until a valid frame is found or an error occurred.

If a valid frame was found, true will be returned and the frame will be stored 'frame'. The length, in bytes, of the frame found is returned via 'frameSize'. False is returned if a error was encountered while reading the Input source.

CAUTION: The returned frame is NOT a null terminated string - it is ONLY a buffer with 'frameSize' number of characters stored in it.

Implemented in Cpl::Text::Frame::Decoder_, and Cpl::Text::Frame::StringDecoder.

scan() [2/2]

virtual bool Cpl::Text::Frame::Decoder::scan ( size_t  maxSizeOfFrame, char *  frame, size_t &  frameSize, bool &  isEof  )

pure virtualnoexcept

This method is similar to the above scan() method, except that it does NOT block till a 'frame' has found, instead it indicates when a 'frame' has been found by setting the 'isEof' flag to true.

False is returned if a error was encountered while reading the Input source.

CAUTION: The returned frame is NOT a null terminated string - it is ONLY a buffer with 'frameSize' number of characters stored in it.

Implemented in Cpl::Text::Frame::Decoder_.

---

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

• Cpl/Text/Frame/Decoder.h