UCommon
ost::Serial Class Reference

The Serial class is used as the base for all serial I/O services under APE. More...

#include <serial.h>

Inheritance diagram for ost::Serial:

Public Types

enum  Error {
  errSuccess = 0 , errOpenNoTty , errOpenFailed , errSpeedInvalid ,
  errFlowInvalid , errParityInvalid , errCharsizeInvalid , errStopbitsInvalid ,
  errOptionInvalid , errResourceFailure , errOutput , errInput ,
  errTimeout , errExtended
}
 
typedef enum Error Error
 
enum  Flow { flowNone , flowSoft , flowHard , flowBoth }
 
typedef enum Flow Flow
 
enum  Parity { parityNone , parityOdd , parityEven }
 
typedef enum Parity Parity
 
enum  Pending { pendingInput , pendingOutput , pendingError }
 
typedef enum Pending Pending
 

Public Member Functions

int getBufferSize (void) const
 Get the "buffer" size for buffered operations.
 
Error getErrorNumber (void) const
 Often used by a "catch" to fetch the last error of a thrown serial.
 
char * getErrorString (void) const
 Often used by a "catch" to fetch the user set error string of a thrown serial.
 
virtual bool isPending (Pending pend, timeout_t timeout=ucommon::Timer::inf)
 Get the status of pending operations.
 
Serialoperator= (const Serial &from)
 Serial ports may also be duplecated by the assignment operator.
 
void sendBreak (void)
 Send the "break" signal.
 
Error setCharBits (int bits)
 Set character size.
 
Error setFlowControl (Flow flow)
 Set flow control.
 
Error setParity (Parity parity)
 Set parity mode.
 
Error setSpeed (unsigned long speed)
 Set serial port speed for both input and output.
 
Error setStopBits (int bits)
 Set number of stop bits.
 
void toggleDTR (timeout_t millisec)
 Set the DTR mode off momentarily.
 
virtual ~Serial ()
 The serial base class may be "thrown" as a result on an error, and the "catcher" may then choose to destory the object.
 

Protected Member Functions

virtual int aRead (char *Data, const int Length)
 Reads from serial device.
 
virtual int aWrite (const char *Data, const int Length)
 Writes to serial device.
 
void close (void)
 Closes the serial device.
 
void endSerial (void)
 Used as the default destructor for ending serial I/O services.
 
void error (char *err)
 This service is used to thow application defined serial errors where the application specific error code is a string.
 
Error error (Error error, char *errstr=NULL)
 This service is used to throw all serial errors which usually occur during the serial constructor.
 
void flushInput (void)
 Used to flush the input waiting queue.
 
void flushOutput (void)
 Used to flush any pending output data.
 
void initConfig (void)
 Used to initialize a newly opened serial file handle.
 
void open (const char *fname)
 Opens the serial device.
 
void restore (void)
 Restore serial device to the original settings at time of open.
 
 Serial ()
 This allows later ttystream class to open and close a serial device.
 
 Serial (const char *name)
 A serial object may be constructed from a named file on the file system.
 
void setError (bool enable)
 This method is used to turn the error handler on or off for "throwing" execptions by manipulating the thrown flag.
 
int setLineInput (char newline=13, char nl1=0)
 Set "line buffering" read mode and specifies the newline character to be used in seperating line records.
 
int setPacketInput (int size, uint8_t btimer=0)
 Set packet read mode and "size" of packet read buffer.
 
void waitOutput (void)
 Used to wait until all output has been sent.
 

Protected Attributes

int bufsize
 
fd_t dev
 

Detailed Description

The Serial class is used as the base for all serial I/O services under APE.

A serial is a system serial port that is used either for line or packet based data input. Serial ports may also be "streamable" in a derived form.

Common C++ serial I/O classes are used to manage serial devices and implement serial device protocols. From the point of view of Common C++, serial devices are supported by the underlying Posix specified "termios" call interface.

The serial I/O base class is used to hold a descriptor to a serial device and to provide an exception handling interface for all serial I/O classes. The base class is also used to specify serial I/O properties such as communication speed, flow control, data size, and parity. The "Serial" base class is not itself directly used in application development, however.

Common C++ Serial I/O is itself divided into two conceptual modes; frame oriented and line oriented I/O. Both frame and line oriented I/O makes use of the ability of the underlying tty driver to buffer data and return "ready" status from when select either a specified number of bytes or newline record has been reached by manipulating termios c_cc fields appropriately. This provides some advantage in that a given thread servicing a serial port can block and wait rather than have to continually poll or read each and every byte as soon as it appears at the serial port.

Author
David Sugar dyfet.nosp@m.@ost.nosp@m.el.co.nosp@m.m

base class for all serial I/O services.

Definition at line 91 of file serial.h.

Member Typedef Documentation

◆ Error

typedef enum Error ost::Serial::Error

Definition at line 110 of file serial.h.

◆ Flow

typedef enum Flow ost::Serial::Flow

Definition at line 118 of file serial.h.

◆ Parity

typedef enum Parity ost::Serial::Parity

Definition at line 125 of file serial.h.

◆ Pending

typedef enum Pending ost::Serial::Pending

Definition at line 132 of file serial.h.

Member Enumeration Documentation

◆ Error

enum ost::Serial::Error

Definition at line 94 of file serial.h.

◆ Flow

enum ost::Serial::Flow

Definition at line 112 of file serial.h.

◆ Parity

enum ost::Serial::Parity

Definition at line 120 of file serial.h.

◆ Pending

enum ost::Serial::Pending

Definition at line 127 of file serial.h.

Constructor & Destructor Documentation

◆ Serial() [1/2]

ost::Serial::Serial ( )
inlineprotected

This allows later ttystream class to open and close a serial device.

Definition at line 275 of file serial.h.

◆ Serial() [2/2]

ost::Serial::Serial ( const char * name)
protected

A serial object may be constructed from a named file on the file system.

This named device must be "isatty()".

Parameters
nameof file.

◆ ~Serial()

virtual ost::Serial::~Serial ( )
virtual

The serial base class may be "thrown" as a result on an error, and the "catcher" may then choose to destory the object.

By assuring the socket base class is a virtual destructor, we can assure the full object is properly terminated.

Member Function Documentation

◆ aRead()

virtual int ost::Serial::aRead ( char * Data,
const int Length )
protectedvirtual

Reads from serial device.

Parameters
DataPoint to character buffer to receive data. Buffers MUST be at least Length + 1 bytes in size.
LengthNumber of bytes to read.

◆ aWrite()

virtual int ost::Serial::aWrite ( const char * Data,
const int Length )
protectedvirtual

Writes to serial device.

Parameters
DataPoint to character buffer containing data to write. Buffers MUST
LengthNumber of bytes to write.

◆ endSerial()

void ost::Serial::endSerial ( void )
protected

Used as the default destructor for ending serial I/O services.

It will restore the port to it's original state.

◆ error() [1/2]

void ost::Serial::error ( char * err)
inlineprotected

This service is used to thow application defined serial errors where the application specific error code is a string.

Parameters
errstring or message to pass.

Definition at line 200 of file serial.h.

Here is the call graph for this function:

◆ error() [2/2]

Error ost::Serial::error ( Error error,
char * errstr = NULL )
protected

This service is used to throw all serial errors which usually occur during the serial constructor.

Parameters
errordefined serial error id.
errstrstring or message to optionally pass.

◆ getBufferSize()

int ost::Serial::getBufferSize ( void ) const
inline

Get the "buffer" size for buffered operations.

This can be used when setting packet or line read modes to determine how many bytes to wait for in a given read call.

Returns
number of bytes used for buffering.

Definition at line 383 of file serial.h.

◆ getErrorNumber()

Error ost::Serial::getErrorNumber ( void ) const
inline

Often used by a "catch" to fetch the last error of a thrown serial.

Returns
error numbr of last Error.

Definition at line 362 of file serial.h.

◆ getErrorString()

char * ost::Serial::getErrorString ( void ) const
inline

Often used by a "catch" to fetch the user set error string of a thrown serial.

Returns
string for error message.

Definition at line 372 of file serial.h.

◆ initConfig()

void ost::Serial::initConfig ( void )
protected

Used to initialize a newly opened serial file handle.

You should set serial properties and DTR manually before first use.

◆ isPending()

virtual bool ost::Serial::isPending ( Pending pend,
timeout_t timeout = ucommon::Timer::inf )
virtual

Get the status of pending operations.

This can be used to examine if input or output is waiting, or if an error has occured on the serial device.

Returns
true if ready, false if timeout.
Parameters
pendready check to perform.
timeoutin milliseconds.

Reimplemented in ost::TTYStream.

◆ open()

void ost::Serial::open ( const char * fname)
protected

Opens the serial device.

Parameters
fnamePathname of device to open

◆ setCharBits()

Error ost::Serial::setCharBits ( int bits)

Set character size.

Returns
0 on success.
Parameters
bitscharacter size to use (usually 7 or 8).

◆ setError()

void ost::Serial::setError ( bool enable)
inlineprotected

This method is used to turn the error handler on or off for "throwing" execptions by manipulating the thrown flag.

Parameters
enabletrue to enable handler.

Definition at line 211 of file serial.h.

◆ setFlowControl()

Error ost::Serial::setFlowControl ( Flow flow)

Set flow control.

Returns
0 on success.
Parameters
flowcontrol mode.

◆ setLineInput()

int ost::Serial::setLineInput ( char newline = 13,
char nl1 = 0 )
protected

Set "line buffering" read mode and specifies the newline character to be used in seperating line records.

isPending can then be used to wait for an entire line of input.

Parameters
newlinenewline character.
nl1EOL2 control character.
Returns
size of conical input buffer.

◆ setPacketInput()

int ost::Serial::setPacketInput ( int size,
uint8_t btimer = 0 )
protected

Set packet read mode and "size" of packet read buffer.

This sets VMIN to x. VTIM is normally set to "0" so that "isPending()" can wait for an entire packet rather than just the first byte.

Returns
actual buffer size set.
Parameters
sizeof packet read request.
btimeroptional inter-byte data packet timeout.

◆ setParity()

Error ost::Serial::setParity ( Parity parity)

Set parity mode.

Returns
0 on success.
Parameters
paritymode.

◆ setSpeed()

Error ost::Serial::setSpeed ( unsigned long speed)

Set serial port speed for both input and output.

Returns
0 on success.
Parameters
speedto select. 0 signifies modem "hang up".

◆ setStopBits()

Error ost::Serial::setStopBits ( int bits)

Set number of stop bits.

Returns
0 on success.
Parameters
bitsstop bits.

◆ toggleDTR()

void ost::Serial::toggleDTR ( timeout_t millisec)

Set the DTR mode off momentarily.

Parameters
millisecnumber of milliseconds.

Field Documentation

◆ bufsize

int ost::Serial::bufsize
protected

Definition at line 153 of file serial.h.

◆ dev

fd_t ost::Serial::dev
protected

Definition at line 152 of file serial.h.

◆ linebuf

bool ost::Serial::linebuf

Definition at line 140 of file serial.h.

◆ thrown

bool ost::Serial::thrown

Definition at line 139 of file serial.h.


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