---

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 Serial::

List of all members.

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...
sioerror_t	setSpeed (unsigned long speed)
	Set serial port speed for both input and output. More...
sioerror_t	setCharBits (int bits)
	Set character size. More...
sioerror_t	setParity (sioparity_t parity)
	Set parity mode. More...
sioerror_t	setStopBits (int bits)
	Set number of stop bits. More...
sioerror_t	setFlowControl (sioflow_t 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...
sioerror_t	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 (siopend_t pend, timeout_t timeout=TIMEOUT_INF)
	Get the status of pending operations. More...
Protected Methods
sioerror_t	Error (sioerror_t error, char *errstr=NULL)
	This service is used to throw all serial errors which usually occur during the serial constructor. More...
void	Error (char *errstr)
	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 (const char *name)
	A serial object may be constructed from a named file on the file system. More...
	Serial ()
	This allows later ttystream class to open and close a serial device. More...
Protected Attributes
int	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>

---

Constructor & Destructor Documentation

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.

Serial::Serial (    )  [inline, protected]

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

virtual Serial::~Serial (    )  [inline, 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

void Serial::Error (  char *   errstr )  [inline, protected]

This service is used to thow application defined serial errors where the application specific error code is a string. Parameters: errstr   string or message to pass.

sioerror_t Serial::Error (  sioerror_t   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 Serial::Restore (  void   )  [protected]

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

void 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 Serial::flushInput (  void   )  [protected]

Used to flush the input waiting queue.

void Serial::flushOutput (  void   )  [protected]

Used to flush any pending output data.

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

sioerror_t Serial::getErrorNumber (  void   )  [inline]

Often used by a "catch" to fetch the last error of a thrown serial. Returns: error numbr of last sioerror_t.

char* 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 Serial::initConfig (  void   )  [protected]

Used to initialize a newly opened serial file handle. You should set serial properties and DTR manually before first use.

virtual bool Serial::isPending (  siopend_t   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: ready   check to perform. timeout   in milliseconds. Reimplemented in TTYStream.

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

Serial ports may also be duplecated by the assignment operator.

void Serial::sendBreak (  void   )

Send the "break" signal.

sioerror_t Serial::setCharBits (  int   bits )

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

void 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: true   to enable handler.

sioerror_t Serial::setFlowControl (  sioflow_t   flow )

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

int 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. Returns: size of conical input buffer. Parameters: newline   character.

int 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. optional   inter-byte data packet timeout.

sioerror_t Serial::setParity (  sioparity_t   parity )

Set parity mode. Returns: 0 on success. Parameters: parity   mode.

sioerror_t 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".

sioerror_t Serial::setStopBits (  int   bits )

Set number of stop bits. Returns: 0 on success. Parameters: stop   bits.

void Serial::toggleDTR (  timeout_t   millisec )

Set the DTR mode off momentarily. Parameters: number   of milliseconds.

void Serial::waitOutput (  void   )  [protected]

Used to wait until all output has been sent.

---

Member Data Documentation

int Serial::bufsize [protected]

int Serial::dev [protected]

---

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

• serial.h

---