---
name: "Serial"
section: "3cc"
platform: "linux"
package: "libcommoncpp2-dev"
version: "1.0.13-5"
release: "Debian 3.1 (Sarge)"
platforms: ["linux"]
url: "https://new.carta.tech/Serial"
---

# Serial(3cc)

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

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

## SYNOPSIS

`#include <serial.h>`

Inherited by **SerialPort**, and **TTYStream**.

### 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.* Serial & **operator=** (const Serial &from)\
 *Serial ports may also be duplecated by the assignment operator.* **Error** **setSpeed** (unsigned long speed)\
 *Set serial port speed for both input and output.* **Error** **setCharBits** (int bits)\
 *Set character size.* **Error** **setParity** (**Parity** parity)\
 *Set parity mode.* **Error** **setStopBits** (int bits)\
 *Set number of stop bits.* **Error** **setFlowControl** (**Flow** flow)\
 *Set flow control.* void **toggleDTR** (**timeout\_t** millisec)\
 *Set the DTR mode off momentarily.* void **sendBreak** (void)\
 *Send the 'break' signal.* **Error** **getErrorNumber** (void)\
 *Often used by a 'catch' to fetch the last error of a thrown serial.* char \* **getErrorString** (void)\
 *Often used by a 'catch' to fetch the user set error string of a thrown serial.* int **getBufferSize** (void)\
 *Get the 'buffer' size for buffered operations.* virtual bool **isPending** (**Pending** pend, **timeout\_t** timeout=TIMEOUT\_INF)\
 *Get the status of pending operations.*

### Protected Methods

void **open** (const char \*fname)\
 *Opens the serial device.* void **close** (void)\
 *Closes the serial device.* 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.* **Error** **error** (**Error** error, char \*errstr=NULL)\
 *This service is used to throw all serial errors which usually occur during the serial constructor.* void **error** (char \*errstr)\
 *This service is used to thow application defined serial errors where the application specific error code is a string.* 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 **setPacketInput** (int **size**, unsigned char btimer=0)\
 *Set packet read mode and 'size' of packet read buffer.* 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.* void **restore** (void)\
 *Restore serial device to the original settings at time of open.* void **flushInput** (void)\
 *Used to flush the input waiting queue.* void **flushOutput** (void)\
 *Used to flush any pending output data.* void **waitOutput** (void)\
 *Used to wait until all output has been sent.* void **endSerial** (void)\
 *Used as the default destructor for ending serial I/O services.* void **initConfig** (void)\
 *Used to initialize a newly opened serial file handle.* **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.*

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

### typedef enum Flow Serial::Flow

### typedef enum Parity Serial::Parity

### typedef enum Pending Serial::Pending

## MEMBER ENUMERATION DOCUMENTATION

### enum Serial::Error

**Enumeration values:**

- *errSuccess*

  - *errOpenNoTty*

  - *errOpenFailed*

  - *errSpeedInvalid*

  - *errFlowInvalid*

  - *errParityInvalid*

  - *errCharsizeInvalid*

  - *errStopbitsInvalid*

  - *errOptionInvalid*

  - *errResourceFailure*

  - *errOutput*

  - *errInput*

  - *errTimeout*

  - *errExtended*

  ### enum Serial::Flow

**Enumeration values:**

- *flowNone*

  - *flowSoft*

  - *flowHard*

  - *flowBoth*

  ### enum Serial::Parity

**Enumeration values:**

- *parityNone*

  - *parityOdd*

  - *parityEven*

  ### enum Serial::Pending

**Enumeration values:**

- *pendingInput*

  - *pendingOutput*

  - *pendingError*

  ## CONSTRUCTOR & DESTRUCTOR DOCUMENTATION

### Serial::Serial ()` [inline, protected]`

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

### 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.*

### 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

### virtual int 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.*

### virtual int 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 Serial::close (void)` [protected]`

*Closes the serial device.*

*Reimplemented in* **ttystream***.*

### 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::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.*

### Error 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 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.*

### Error 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\* 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 (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* **TTYStream***.*

### void Serial::open (const char \* fname)` [protected]`

*Opens the serial device.*

**Parameters:**

- *fname*

  *Pathname of device to open*

*Reimplemented in* **ttystream***.*

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

*Serial ports may also be duplecated by the assignment operator.*

### void Serial::restore (void)` [protected]`

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

### void Serial::sendBreak (void)

*Send the 'break' signal.*

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

*Set character size.*

**Returns:**  *0 on success.*

**Parameters:**

- *bits*

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

- *enable*

  *true to enable handler.*

### Error Serial::setFlowControl (Flow 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.*

**Parameters:**

- *newline*

  *newline character.*

- *nl1*

  *EOL2 control character.*

**Returns:**  *size of conical input buffer.*

### 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.*

- *btimer*

  *optional inter-byte data packet timeout.*

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

*Set parity mode.*

**Returns:**  *0 on success.*

**Parameters:**

- *parity*

  *mode.*

### Error 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 Serial::setStopBits (int bits)

*Set number of stop bits.*

**Returns:**  *0 on success.*

**Parameters:**

- *bits*

  *stop bits.*

### void Serial::toggleDTR (timeout\_t millisec)

*Set the DTR mode off momentarily.*

**Parameters:**

- *millisec*

  *number of milliseconds.*

### void Serial::waitOutput (void)` [protected]`

*Used to wait until all output has been sent.*

## MEMBER DATA DOCUMENTATION

### int Serial::bufsize` [protected]`

### HANDLE Serial::dev` [protected]`

## AUTHOR

*Generated automatically by Doxygen for CommonC++ from the source code.*