Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages   Examples  

ost::Serial Class Reference

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

#include <serial.h>

Inheritance diagram for ost::Serial::

ost::SerialPort ost::TTYStream ost::TTYSession ost::ttystream List of all members.

Public Types

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

Public Methods

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. More...

Serial& operator= (const Serial &from)
 Serial ports may also be duplecated by the assignment operator. More...

Error setSpeed (unsigned long speed)
 Set serial port speed for both input and output. More...

Error setCharBits (int bits)
 Set character size. More...

Error setParity (Parity parity)
 Set parity mode. More...

Error setStopBits (int bits)
 Set number of stop bits. More...

Error setFlowControl (Flow flow)
 Set flow control. More...

void toggleDTR (timeout_t millisec)
 Set the DTR mode off momentarily. More...

void sendBreak (void)
 Send the "break" signal. More...

Error getErrorNumber (void)
 Often used by a "catch" to fetch the last error of a thrown serial. More...

char* getErrorString (void)
 Often used by a "catch" to fetch the user set error string of a thrown serial. More...

int getBufferSize (void)
 Get the "buffer" size for buffered operations. More...

virtual bool isPending (Pending pend, timeout_t timeout=TIMEOUT_INF)
 Get the status of pending operations. More...


Protected Methods

void open (const char *fname)
 Opens the serial device. More...

void close (void)
 Closes the serial device. More...

virtual int aRead (char *Data, const int Length)
 Reads from serial device. More...

virtual int aWrite (const char *Data, const int Length)
 Writes to serial device. More...

Error error (Error error, char *errstr=NULL)
 This service is used to throw all serial errors which usually occur during the serial constructor. More...

void error (char *err)
 This service is used to thow application defined serial errors where the application specific error code is a string. More...

void setError (bool enable)
 This method is used to turn the error handler on or off for "throwing" execptions by manipulating the thrown flag. More...

int setPacketInput (int size, unsigned char btimer=0)
 Set packet read mode and "size" of packet read buffer. More...

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. More...

void restore (void)
 Restore serial device to the original settings at time of open. More...

void flushInput (void)
 Used to flush the input waiting queue. More...

void flushOutput (void)
 Used to flush any pending output data. More...

void waitOutput (void)
 Used to wait until all output has been sent. More...

void endSerial (void)
 Used as the default destructor for ending serial I/O services. More...

void initConfig (void)
 Used to initialize a newly opened serial file handle. More...

 Serial ()
 This allows later ttystream class to open and close a serial device. More...

 Serial (const char *name)
 A serial object may be constructed from a named file on the file system. More...


Protected Attributes

HANDLE dev
int bufsize

Detailed Description

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

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@ostel.com>


Member Typedef Documentation

typedef enum Error ost::Serial::Error
 

typedef enum Flow ost::Serial::Flow
 

typedef enum Parity ost::Serial::Parity
 

typedef enum Pending ost::Serial::Pending
 


Member Enumeration Documentation

enum typedef enum Error ost::Serial::Error
 

Enumeration values:
errSuccess  
errOpenNoTty  
errOpenFailed  
errSpeedInvalid  
errFlowInvalid  
errParityInvalid  
errCharsizeInvalid  
errStopbitsInvalid  
errOptionInvalid  
errResourceFailure  
errOutput  
errInput  
errTimeout  
errExtended  

enum typedef enum Flow ost::Serial::Flow
 

Enumeration values:
flowNone  
flowSoft  
flowHard  
flowBoth  

enum typedef enum Parity ost::Serial::Parity
 

Enumeration values:
parityNone  
parityOdd  
parityEven  

enum typedef enum Pending ost::Serial::Pending
 

Enumeration values:
pendingInput  
pendingOutput  
pendingError  


Constructor & Destructor Documentation

ost::Serial::Serial ( ) [inline, protected]
 

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

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:
name   of file.

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

int ost::Serial::aRead ( char * Data,
const int Length ) [protected, virtual]
 

Reads from serial device.

Parameters:
Data   Point to character buffer to receive data. Buffers MUST be at least Length + 1 bytes in size.
Length   Number of bytes to read.

int ost::Serial::aWrite ( const char * Data,
const int Length ) [protected, virtual]
 

Writes to serial device.

Parameters:
Data   Point to character buffer containing data to write. Buffers MUST
Length   Number of bytes to write.

void ost::Serial::close ( void ) [protected]
 

Closes the serial device.

Reimplemented in ost::ttystream.

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.

void ost::Serial::error ( char * err ) [inline, protected]
 

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

Parameters:
err   string or message to pass.

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:
error   defined serial error id.
errstr   string or message to optionally pass.

void ost::Serial::flushInput ( void ) [protected]
 

Used to flush the input waiting queue.

void ost::Serial::flushOutput ( void ) [protected]
 

Used to flush any pending output data.

int ost::Serial::getBufferSize ( void ) [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.

Error ost::Serial::getErrorNumber ( void ) [inline]
 

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

Returns:
error numbr of last Error.

char * ost::Serial::getErrorString ( void ) [inline]
 

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

Returns:
string for error message.

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.

bool ost::Serial::isPending ( Pending pend,
timeout_t timeout = TIMEOUT_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:
pend   ready check to perform.
timeout   in milliseconds.

Reimplemented in ost::TTYStream.

void ost::Serial::open ( const char * name ) [protected]
 

Opens the serial device.

Parameters:
fname   Pathname of device to open

Reimplemented in ost::ttystream.

Serial & ost::Serial::operator= ( const Serial & from )
 

Serial ports may also be duplecated by the assignment operator.

void ost::Serial::restore ( void ) [protected]
 

Restore serial device to the original settings at time of open.

void ost::Serial::sendBreak ( void )
 

Send the "break" signal.

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

Set character size.

Returns:
0 on success.
Parameters:
bits   character size to use (usually 7 or 8).

void ost::Serial::setError ( bool enable ) [inline, protected]
 

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

Parameters:
enable   true to enable handler.

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

Set flow control.

Returns:
0 on success.
Parameters:
flow   control mode.

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:
newline   newline character.
nl1   EOL2 control character.
Returns:
size of conical input buffer.

int ost::Serial::setPacketInput ( int size,
unsigned char 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:
size   of packet read request.
btimer   optional inter-byte data packet timeout.

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

Set parity mode.

Returns:
0 on success.
Parameters:
parity   mode.

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

Set serial port speed for both input and output.

Returns:
0 on success.
Parameters:
speed   to select. 0 signifies modem "hang up".

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

Set number of stop bits.

Returns:
0 on success.
Parameters:
bits   stop bits.

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

Set the DTR mode off momentarily.

Parameters:
millisec   number of milliseconds.

void ost::Serial::waitOutput ( void ) [protected]
 

Used to wait until all output has been sent.


Member Data Documentation

int ost::Serial::bufsize [protected]
 

HANDLE ost::Serial::dev [protected]
 

bool ost::Serial::linebuf
 

bool ost::Serial::thrown
 


The documentation for this class was generated from the following file:
Generated at Sat May 12 18:59:44 2007 for GNU CommonC++ by doxygen1.2.8.1 written by Dimitri van Heesch, © 1997-2001