.TH "Serial" 3 "19 Jul 2003" "CommonC++" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Serial \- The Serial class is used as the base for all serial I/O services under APE. base class for all serial I/O services. 
.SH SYNOPSIS
.br
.PP
\fC#include <serial.h>\fP
.PP
Inherited by \fBSerialPort\fP, and \fBTTYStream\fP.
.PP
.SS "Public Types"

.in +1c
.ti -1c
.RI "typedef enum Error \fBError\fP"
.br
.ti -1c
.RI "typedef enum Flow \fBFlow\fP"
.br
.ti -1c
.RI "typedef enum Parity \fBParity\fP"
.br
.ti -1c
.RI "typedef enum Pending \fBPending\fP"
.br
.ti -1c
.RI "enum \fBError\fP { \fBerrSuccess\fP =  0, \fBerrOpenNoTty\fP, \fBerrOpenFailed\fP, \fBerrSpeedInvalid\fP, \fBerrFlowInvalid\fP, \fBerrParityInvalid\fP, \fBerrCharsizeInvalid\fP, \fBerrStopbitsInvalid\fP, \fBerrOptionInvalid\fP, \fBerrResourceFailure\fP, \fBerrOutput\fP, \fBerrInput\fP, \fBerrTimeout\fP, \fBerrExtended\fP }"
.br
.ti -1c
.RI "enum \fBFlow\fP { \fBflowNone\fP, \fBflowSoft\fP, \fBflowHard\fP, \fBflowBoth\fP }"
.br
.ti -1c
.RI "enum \fBParity\fP { \fBparityNone\fP, \fBparityOdd\fP, \fBparityEven\fP }"
.br
.ti -1c
.RI "enum \fBPending\fP { \fBpendingInput\fP, \fBpendingOutput\fP, \fBpendingError\fP }"
.br
.in -1c
.SS "Public Methods"

.in +1c
.ti -1c
.RI "virtual \fB~Serial\fP ()"
.br
.RI "\fIThe serial base class may be 'thrown' as a result on an error, and the 'catcher' may then choose to destory the object.\fP"
.ti -1c
.RI "Serial & \fBoperator=\fP (const Serial &from)"
.br
.RI "\fISerial ports may also be duplecated by the assignment operator.\fP"
.ti -1c
.RI "\fBError\fP \fBsetSpeed\fP (unsigned long speed)"
.br
.RI "\fISet serial port speed for both input and output.\fP"
.ti -1c
.RI "\fBError\fP \fBsetCharBits\fP (int bits)"
.br
.RI "\fISet character size.\fP"
.ti -1c
.RI "\fBError\fP \fBsetParity\fP (\fBParity\fP parity)"
.br
.RI "\fISet parity mode.\fP"
.ti -1c
.RI "\fBError\fP \fBsetStopBits\fP (int bits)"
.br
.RI "\fISet number of stop bits.\fP"
.ti -1c
.RI "\fBError\fP \fBsetFlowControl\fP (\fBFlow\fP flow)"
.br
.RI "\fISet flow control.\fP"
.ti -1c
.RI "void \fBtoggleDTR\fP (\fBtimeout_t\fP millisec)"
.br
.RI "\fISet the DTR mode off momentarily.\fP"
.ti -1c
.RI "void \fBsendBreak\fP (void)"
.br
.RI "\fISend the 'break' signal.\fP"
.ti -1c
.RI "\fBError\fP \fBgetErrorNumber\fP (void)"
.br
.RI "\fIOften used by a 'catch' to fetch the last error of a thrown serial.\fP"
.ti -1c
.RI "char * \fBgetErrorString\fP (void)"
.br
.RI "\fIOften used by a 'catch' to fetch the user set error string of a thrown serial.\fP"
.ti -1c
.RI "int \fBgetBufferSize\fP (void)"
.br
.RI "\fIGet the 'buffer' size for buffered operations.\fP"
.ti -1c
.RI "virtual bool \fBisPending\fP (\fBPending\fP pend, \fBtimeout_t\fP timeout=TIMEOUT_INF)"
.br
.RI "\fIGet the status of pending operations.\fP"
.in -1c
.SS "Protected Methods"

.in +1c
.ti -1c
.RI "void \fBopen\fP (const char *fname)"
.br
.RI "\fIOpens the serial device.\fP"
.ti -1c
.RI "void \fBclose\fP (void)"
.br
.RI "\fICloses the serial device.\fP"
.ti -1c
.RI "virtual int \fBaRead\fP (char *Data, const int Length)"
.br
.RI "\fIReads from serial device.\fP"
.ti -1c
.RI "virtual int \fBaWrite\fP (const char *Data, const int Length)"
.br
.RI "\fIWrites to serial device.\fP"
.ti -1c
.RI "\fBError\fP \fBerror\fP (\fBError\fP error, char *errstr=NULL)"
.br
.RI "\fIThis service is used to throw all serial errors which usually occur during the serial constructor.\fP"
.ti -1c
.RI "void \fBerror\fP (char *errstr)"
.br
.RI "\fIThis service is used to thow application defined serial errors where the application specific error code is a string.\fP"
.ti -1c
.RI "void \fBsetError\fP (bool enable)"
.br
.RI "\fIThis method is used to turn the error handler on or off for 'throwing' execptions by manipulating the thrown flag.\fP"
.ti -1c
.RI "int \fBsetPacketInput\fP (int \fBsize\fP, unsigned char btimer=0)"
.br
.RI "\fISet packet read mode and 'size' of packet read buffer.\fP"
.ti -1c
.RI "int \fBsetLineInput\fP (char newline=13, char nl1=0)"
.br
.RI "\fISet 'line buffering' read mode and specifies the newline character to be used in seperating line records.\fP"
.ti -1c
.RI "void \fBrestore\fP (void)"
.br
.RI "\fIRestore serial device to the original settings at time of open.\fP"
.ti -1c
.RI "void \fBflushInput\fP (void)"
.br
.RI "\fIUsed to flush the input waiting queue.\fP"
.ti -1c
.RI "void \fBflushOutput\fP (void)"
.br
.RI "\fIUsed to flush any pending output data.\fP"
.ti -1c
.RI "void \fBwaitOutput\fP (void)"
.br
.RI "\fIUsed to wait until all output has been sent.\fP"
.ti -1c
.RI "void \fBendSerial\fP (void)"
.br
.RI "\fIUsed as the default destructor for ending serial I/O services.\fP"
.ti -1c
.RI "void \fBinitConfig\fP (void)"
.br
.RI "\fIUsed to initialize a newly opened serial file handle.\fP"
.ti -1c
.RI "\fBSerial\fP ()"
.br
.RI "\fIThis allows later ttystream class to open and close a serial device.\fP"
.ti -1c
.RI "\fBSerial\fP (const char *name)"
.br
.RI "\fIA serial object may be constructed from a named file on the file system.\fP"
.in -1c
.SS "Protected Attributes"

.in +1c
.ti -1c
.RI "\fBHANDLE\fP \fBdev\fP"
.br
.ti -1c
.RI "int \fBbufsize\fP"
.br
.in -1c
.SH "DETAILED DESCRIPTION"
.PP 
The Serial class is used as the base for all serial I/O services under APE. base class for all serial I/O services.
.PP
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.
.PP
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.
.PP
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.
.PP
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.
.PP
\fBAuthor: \fP
.in +1c
David Sugar <dyfet@ostel.com> 
.PP
.SH "MEMBER TYPEDEF DOCUMENTATION"
.PP 
.SS "typedef enum Error Serial::Error"
.PP
.SS "typedef enum Flow Serial::Flow"
.PP
.SS "typedef enum Parity Serial::Parity"
.PP
.SS "typedef enum Pending Serial::Pending"
.PP
.SH "MEMBER ENUMERATION DOCUMENTATION"
.PP 
.SS "enum Serial::Error"
.PP
\fBEnumeration values: \fP
.in +1c
.TP
\fB\fI\fIerrSuccess\fP \fP\fP
.TP
\fB\fI\fIerrOpenNoTty\fP \fP\fP
.TP
\fB\fI\fIerrOpenFailed\fP \fP\fP
.TP
\fB\fI\fIerrSpeedInvalid\fP \fP\fP
.TP
\fB\fI\fIerrFlowInvalid\fP \fP\fP
.TP
\fB\fI\fIerrParityInvalid\fP \fP\fP
.TP
\fB\fI\fIerrCharsizeInvalid\fP \fP\fP
.TP
\fB\fI\fIerrStopbitsInvalid\fP \fP\fP
.TP
\fB\fI\fIerrOptionInvalid\fP \fP\fP
.TP
\fB\fI\fIerrResourceFailure\fP \fP\fP
.TP
\fB\fI\fIerrOutput\fP \fP\fP
.TP
\fB\fI\fIerrInput\fP \fP\fP
.TP
\fB\fI\fIerrTimeout\fP \fP\fP
.TP
\fB\fI\fIerrExtended\fP \fP\fP

.SS "enum Serial::Flow"
.PP
\fBEnumeration values: \fP
.in +1c
.TP
\fB\fI\fIflowNone\fP \fP\fP
.TP
\fB\fI\fIflowSoft\fP \fP\fP
.TP
\fB\fI\fIflowHard\fP \fP\fP
.TP
\fB\fI\fIflowBoth\fP \fP\fP

.SS "enum Serial::Parity"
.PP
\fBEnumeration values: \fP
.in +1c
.TP
\fB\fI\fIparityNone\fP \fP\fP
.TP
\fB\fI\fIparityOdd\fP \fP\fP
.TP
\fB\fI\fIparityEven\fP \fP\fP

.SS "enum Serial::Pending"
.PP
\fBEnumeration values: \fP
.in +1c
.TP
\fB\fI\fIpendingInput\fP \fP\fP
.TP
\fB\fI\fIpendingOutput\fP \fP\fP
.TP
\fB\fI\fIpendingError\fP \fP\fP

.SH "CONSTRUCTOR & DESTRUCTOR DOCUMENTATION"
.PP 
.SS "Serial::Serial ()\fC [inline, protected]\fP"
.PP
This allows later ttystream class to open and close a serial device.
.PP
.SS "Serial::Serial (const char * name)\fC [protected]\fP"
.PP
A serial object may be constructed from a named file on the file system.
.PP
This named device must be 'isatty()'.
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIname\fP\fP
of file. 
.SS "virtual Serial::~Serial ()\fC [inline, virtual]\fP"
.PP
The serial base class may be 'thrown' as a result on an error, and the 'catcher' may then choose to destory the object.
.PP
By assuring the socket base class is a virtual destructor, we can assure the full object is properly terminated. 
.SH "MEMBER FUNCTION DOCUMENTATION"
.PP 
.SS "virtual int Serial::aRead (char * Data, const int Length)\fC [protected, virtual]\fP"
.PP
Reads from serial device.
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIData\fP\fP
Point to character buffer to receive data. Buffers MUST be at least Length + 1 bytes in size. 
.TP
\fB\fILength\fP\fP
\fBNumber\fP of bytes to read. 
.SS "virtual int Serial::aWrite (const char * Data, const int Length)\fC [protected, virtual]\fP"
.PP
Writes to serial device.
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIData\fP\fP
Point to character buffer containing data to write. Buffers MUST 
.TP
\fB\fILength\fP\fP
\fBNumber\fP of bytes to write. 
.SS "void Serial::close (void)\fC [protected]\fP"
.PP
Closes the serial device.
.PP
Reimplemented in \fBttystream\fP.
.SS "void Serial::endSerial (void)\fC [protected]\fP"
.PP
Used as the default destructor for ending serial I/O services.
.PP
It will restore the port to it's original state. 
.SS "void Serial::error (char * errstr)\fC [inline, protected]\fP"
.PP
This service is used to thow application defined serial errors where the application specific error code is a string.
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIerrstr\fP\fP
string or message to pass. 
.SS "\fBError\fP Serial::error (\fBError\fP error, char * errstr = NULL)\fC [protected]\fP"
.PP
This service is used to throw all serial errors which usually occur during the serial constructor.
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIerror\fP\fP
defined serial error id. 
.TP
\fB\fIerrstr\fP\fP
string or message to optionally pass. 
.SS "void Serial::flushInput (void)\fC [protected]\fP"
.PP
Used to flush the input waiting queue.
.PP
.SS "void Serial::flushOutput (void)\fC [protected]\fP"
.PP
Used to flush any pending output data.
.PP
.SS "int Serial::getBufferSize (void)\fC [inline]\fP"
.PP
Get the 'buffer' size for buffered operations.
.PP
This can be used when setting packet or line read modes to determine how many bytes to wait for in a given read call.
.PP
\fBReturns: \fP
.in +1c
number of bytes used for buffering. 
.SS "\fBError\fP Serial::getErrorNumber (void)\fC [inline]\fP"
.PP
Often used by a 'catch' to fetch the last error of a thrown serial.
.PP
\fBReturns: \fP
.in +1c
error numbr of last Error. 
.SS "char* Serial::getErrorString (void)\fC [inline]\fP"
.PP
Often used by a 'catch' to fetch the user set error string of a thrown serial.
.PP
\fBReturns: \fP
.in +1c
string for error message. 
.SS "void Serial::initConfig (void)\fC [protected]\fP"
.PP
Used to initialize a newly opened serial file handle.
.PP
You should set serial properties and DTR manually before first use. 
.SS "virtual bool Serial::isPending (\fBPending\fP pend, \fBtimeout_t\fP timeout = TIMEOUT_INF)\fC [virtual]\fP"
.PP
Get the status of pending operations.
.PP
This can be used to examine if input or output is waiting, or if an error has occured on the serial device.
.PP
\fBReturns: \fP
.in +1c
true if ready, false if timeout. 
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIpend\fP\fP
ready check to perform. 
.TP
\fB\fItimeout\fP\fP
in milliseconds. 
.PP
Reimplemented in \fBTTYStream\fP.
.SS "void Serial::open (const char * fname)\fC [protected]\fP"
.PP
Opens the serial device.
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIfname\fP\fP
Pathname of device to open 
.PP
Reimplemented in \fBttystream\fP.
.SS "Serial& Serial::operator= (const Serial & from)"
.PP
Serial ports may also be duplecated by the assignment operator.
.PP
.SS "void Serial::restore (void)\fC [protected]\fP"
.PP
Restore serial device to the original settings at time of open.
.PP
.SS "void Serial::sendBreak (void)"
.PP
Send the 'break' signal.
.PP
.SS "\fBError\fP Serial::setCharBits (int bits)"
.PP
Set character size.
.PP
\fBReturns: \fP
.in +1c
0 on success. 
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIbits\fP\fP
character size to use (usually 7 or 8). 
.SS "void Serial::setError (bool enable)\fC [inline, protected]\fP"
.PP
This method is used to turn the error handler on or off for 'throwing' execptions by manipulating the thrown flag.
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIenable\fP\fP
true to enable handler. 
.SS "\fBError\fP Serial::setFlowControl (\fBFlow\fP flow)"
.PP
Set flow control.
.PP
\fBReturns: \fP
.in +1c
0 on success. 
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIflow\fP\fP
control mode. 
.SS "int Serial::setLineInput (char newline = 13, char nl1 = 0)\fC [protected]\fP"
.PP
Set 'line buffering' read mode and specifies the newline character to be used in seperating line records.
.PP
isPending can then be used to wait for an entire line of input.
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fInewline\fP\fP
newline character. 
.TP
\fB\fInl1\fP\fP
EOL2 control character. 
.PP
\fBReturns: \fP
.in +1c
size of conical input buffer. 
.SS "int Serial::setPacketInput (int size, unsigned char btimer = 0)\fC [protected]\fP"
.PP
Set packet read mode and 'size' of packet read buffer.
.PP
This sets VMIN to x. VTIM is normally set to '0' so that '\fBisPending()\fP' can wait for an entire packet rather than just the first byte.
.PP
\fBReturns: \fP
.in +1c
actual buffer size set. 
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIsize\fP\fP
of packet read request. 
.TP
\fB\fIbtimer\fP\fP
optional inter-byte data packet timeout. 
.SS "\fBError\fP Serial::setParity (\fBParity\fP parity)"
.PP
Set parity mode.
.PP
\fBReturns: \fP
.in +1c
0 on success. 
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIparity\fP\fP
mode. 
.SS "\fBError\fP Serial::setSpeed (unsigned long speed)"
.PP
Set serial port speed for both input and output.
.PP
\fBReturns: \fP
.in +1c
0 on success. 
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIspeed\fP\fP
to select. 0 signifies modem 'hang up'. 
.SS "\fBError\fP Serial::setStopBits (int bits)"
.PP
Set number of stop bits.
.PP
\fBReturns: \fP
.in +1c
0 on success. 
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIbits\fP\fP
stop bits. 
.SS "void Serial::toggleDTR (\fBtimeout_t\fP millisec)"
.PP
Set the DTR mode off momentarily.
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fImillisec\fP\fP
number of milliseconds. 
.SS "void Serial::waitOutput (void)\fC [protected]\fP"
.PP
Used to wait until all output has been sent.
.PP
.SH "MEMBER DATA DOCUMENTATION"
.PP 
.SS "int Serial::bufsize\fC [protected]\fP"
.PP
.SS "\fBHANDLE\fP Serial::dev\fC [protected]\fP"
.PP


.SH "AUTHOR"
.PP 
Generated automatically by Doxygen for CommonC++ from the source code.