All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
PSerialChannel Class Reference

This class defines an I/O channel that communicates via a serial port. More...

`#include <serchan.h>`

Inheritance diagram for PSerialChannel:

## Public Member Functions

PBoolean | Close ()
| Close the channel, shutting down the link to the data source. More...
Configuration functions
PBoolean | SetSpeed (DWORD speed)
| Set the speed (baud rate) of the serial channel. More...
DWORD | GetSpeed () const
| Get the speed (baud rate) of the serial channel. More...
PBoolean | SetDataBits (BYTE data)
| Set the data bits (5, 6, 7 or 8) of the serial port. More...
BYTE | GetDataBits () const
| Get the data bits (5, 6, 7 or 8) of the serial port. More...
PBoolean | SetParity (Parity parity)
| Set the parity of the serial port. More...
Parity | GetParity () const
| Get the parity of the serial port. More...
PBoolean | SetStopBits (BYTE stop)
| Set the stop bits (1 or 2) of the serial port. More...
BYTE | GetStopBits () const
| Get the stop bits (1 or 2) of the serial port. More...
PBoolean | SetInputFlowControl (FlowControl flowControl)
| Set the flow control (handshaking) protocol of the input to the serial port. More...
FlowControl | GetInputFlowControl () const
| Get the flow control (handshaking) protocol of the input to the serial port. More...
PBoolean | SetOutputFlowControl (FlowControl flowControl)
| Set the flow control (handshaking) protocol of the output to the serial port. More...
FlowControl | GetOutputFlowControl () const
| Get the flow control (handshaking) protocol of the output from the serial port. More...
virtual void | SaveSettings (PConfig &cfg)
| Save the current port settings into the configuration file. More...
Status functions
void | SetDTR (PBoolean state=true)
| Set the Data Terminal Ready signal of the serial port. More...
void | ClearDTR ()
| Clear the Data Terminal Ready signal of the serial port. More...
void | SetRTS (PBoolean state=true)
| Set the Request To Send signal of the serial port. More...
void | ClearRTS ()
| Clear the Request To Send signal of the serial port. More...
void | SetBreak (PBoolean state=true)
| Set the break condition of the serial port. More...
void | ClearBreak ()
| Clear the break condition of the serial port. More...
PBoolean | GetCTS ()
| Get the Clear To Send signal of the serial port. More...
PBoolean | GetDSR ()
| Get the Data Set Ready signal of the serial port. More...
PBoolean | GetDCD ()
| Get the Data Carrier Detect signal of the serial port. More...
PBoolean | GetRing ()
| Get the Ring Indicator signal of the serial port. More...
Public Member Functions inherited from PChannel
PBoolean | SetErrorValues (Errors errorCode, int osError, ErrorGroup group=LastGeneralError)
| Set error values to those specified. More...
| PChannel ()
| Create the channel. More...
| ~PChannel ()
| Close down the channel. More...
virtual Comparison | Compare (const PObject &obj) const
| Get the relative rank of the two strings. More...
virtual PINDEX | HashFunction () const
| Calculate a hash value for use in sets and dictionaries. More...
virtual PBoolean | IsOpen () const
| Determine if the channel is currently open. More...
virtual PString | GetName () const
| Get the platform and I/O channel type name of the channel. More...
int | GetHandle () const
| Get the integer operating system handle for the channel. More...
virtual PChannel * | GetBaseReadChannel () const
| Get the base channel of channel indirection using PIndirectChannel. More...
virtual PChannel * | GetBaseWriteChannel () const
| Get the base channel of channel indirection using PIndirectChannel. More...
void | SetReadTimeout (const PTimeInterval &time)
| Set the timeout for read operations. More...
PTimeInterval | GetReadTimeout () const
| Get the timeout for read operations. More...
virtual PBoolean | Read (void *buf, PINDEX len)
| Low level read from the channel. More...
virtual PINDEX | GetLastReadCount () const
| Get the number of bytes read by the last Read() call. More...
virtual int | ReadChar ()
| Read a single 8 bit byte from the channel. More...
PBoolean | ReadBlock (void *buf, PINDEX len)
| Read len bytes into the buffer from the channel. More...
PString | ReadString (PINDEX len)
| Read `len` character into a string from the channel. More...
virtual PBoolean | ReadAsync (void *buf, PINDEX len)
| Begin an asynchronous read from channel. More...
virtual void | OnReadComplete (void *buf, PINDEX len)
| User callback function for when a `ReadAsync()` call has completed or timed out. More...
void | SetWriteTimeout (const PTimeInterval &time)
| Set the timeout for write operations to complete. More...
PTimeInterval | GetWriteTimeout () const
| Get the timeout for write operations to complete. More...
virtual PBoolean | Write (const void *buf, PINDEX len)
| Low level write to the channel. More...
virtual PBoolean | Write (const void *buf, PINDEX len, const void *mark)
| Low level write to the channel with marker. More...
virtual PINDEX | GetLastWriteCount () const
| Get the number of bytes written by the last Write() call. More...
PBoolean | WriteChar (int c)
| Write a single character to the channel. More...
PBoolean | WriteString (const PString &str)
| Write a string to the channel. More...
virtual PBoolean | WriteAsync (const void *buf, PINDEX len)
| Begin an asynchronous write from channel. More...
virtual void | OnWriteComplete (const void *buf, PINDEX len)
| User callback function for when a WriteAsync() call has completed or timed out. More...
virtual PBoolean | Shutdown (ShutdownValue option)
| Close one or both of the data streams associated with a channel. More...
virtual bool | SetLocalEcho (bool localEcho)
| Set local echo mode. More...
virtual bool | FlowControl (const void *flowData)
| Flow Control information Pass data to the channel for flowControl determination. More...
PBoolean | SetBufferSize (PINDEX newSize)
| Set the iostream buffer size for reads and writes. More...
PBoolean | SendCommandString (const PString &command)
| Send a command meta-string. More...
void | AbortCommandString ()
| Abort a command string that is in progress. More...
Errors | GetErrorCode (ErrorGroup group=NumErrorGroups) const
| Get normalised error code. More...
int | GetErrorNumber (ErrorGroup group=NumErrorGroups) const
| Get OS errro code. More...
virtual PString | GetErrorText (ErrorGroup group=NumErrorGroups) const
| Get error message description. More...
virtual PBoolean | Read (const VectorOfSlice &slices)
| Low level scattered read from the channel. More...
virtual PBoolean | Write (const VectorOfSlice &slices)
| Low level scattered write to the channel. More...
Public Member Functions inherited from PObject
virtual | ~PObject ()
virtual PObject * | Clone () const
| Create a copy of the class on the heap. More...
virtual const char * | GetClass (unsigned ancestor=0) const
| Get the current dynamic type of the object instance. More...
PBoolean | IsClass (const char *cls) const
virtual PBoolean | InternalIsDescendant (const char *clsName) const
| Determine if the dynamic type of the current instance is a descendent of the specified class. More...
virtual Comparison | CompareObjectMemoryDirect (const PObject &obj) const
| Determine the byte wise comparison of two objects. More...
bool | operator== (const PObject &obj) const
| Compare the two objects. More...
bool | operator!= (const PObject &obj) const
| Compare the two objects. More...
bool | operator< (const PObject &obj) const
| Compare the two objects. More...
bool | operator> (const PObject &obj) const
| Compare the two objects. More...
bool | operator<= (const PObject &obj) const
| Compare the two objects. More...
bool | operator>= (const PObject &obj) const
| Compare the two objects. More...
virtual void | PrintOn (ostream &strm) const
| Output the contents of the object to the stream. More...
virtual void | ReadFrom (istream &strm)
| Input the contents of the object from the stream. More...

## Construction

enum | Parity { DefaultParity, NoParity, EvenParity, OddParity, MarkParity, SpaceParity }
| Configuration of serial port parity options. More...
enum | FlowControl { DefaultFlowControl, NoFlowControl, XonXoff, RtsCts }
| Configuration of serial port flow control options. More...
| PSerialChannel ()
| Create a new serial channel object, but do not open it. More...
| PSerialChannel (const PString &port, DWORD speed=0, BYTE data=0, Parity parity=DefaultParity, BYTE stop=0, FlowControl inputFlow=DefaultFlowControl, FlowControl outputFlow=DefaultFlowControl)
| Create a serial channal. More...
| PSerialChannel (PConfig &cfg)
| Create a serial channal. More...
| ~PSerialChannel ()
| Close the serial channel on destruction. More...

## Open functions

virtual PBoolean | Open (const PString &port, DWORD speed=0, BYTE data=0, Parity parity=DefaultParity, BYTE stop=0, FlowControl inputFlow=DefaultFlowControl, FlowControl outputFlow=DefaultFlowControl)
| Open a serial channal. More...
virtual PBoolean | Open (PConfig &cfg)
| Open a serial channal. More...
static PStringList | GetPortNames ()
| Get a list of the available serial ports. More...

## Additional Inherited Members

Public Types inherited from PChannel
enum | PXBlockType { PXReadBlock, PXWriteBlock, PXAcceptBlock, PXConnectBlock }
enum | ShutdownValue { ShutdownRead = 0, ShutdownWrite = 1, ShutdownReadAndWrite = 2 }
enum | Errors { NoError, NotFound, FileExists, DiskFull, AccessDenied, DeviceInUse, BadParameter, NoMemory, NotOpen, Timeout, Interrupted, BufferTooSmall, Miscellaneous, ProtocolFailure, NumNormalisedErrors }
| Normalised error codes. More...
enum | ErrorGroup { LastReadError, LastWriteError, LastGeneralError, NumErrorGroups }
| Error groups. More...
typedef std::vector< Slice > | VectorOfSlice
Public Types inherited from PObject
enum | Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
| Result of the comparison operation performed by the `Compare()` function. More...
Static Public Member Functions inherited from PChannel
static PBoolean | ConvertOSError (int libcReturnValue, Errors &lastError, int &osError)
| Convert an operating system error into platform independent error. More...
static PString | GetErrorText (Errors lastError, int osError=0)
| Get error message description. More...
Static Public Member Functions inherited from PObject
static const char * | Class ()
| Get the name of the class as a C string. More...
static Comparison | InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
| Internal function caled from CompareObjectMemoryDirect() More...
Protected Member Functions inherited from PChannel
| PChannel (const PChannel &)
PChannel & | operator= (const PChannel &)
virtual PBoolean | ConvertOSError (int libcReturnValue, ErrorGroup group=LastGeneralError)
| Convert an operating system error into platform independent error. More...
int | ReadCharWithTimeout (PTimeInterval &timeout)
| Read a character with specified timeout. More...
PBoolean | ReceiveCommandString (int nextChar, const PString &reply, PINDEX &pos, PINDEX start)
PBoolean | PXSetIOBlock (PXBlockType type, const PTimeInterval &timeout)
int | PXClose ()
Protected Member Functions inherited from PObject
| PObject ()
| Constructor for PObject, made protected so cannot ever create one on its own. More...
Protected Attributes inherited from PChannel
int | os_handle
| The operating system file handle return by standard open() function. More...
Errors | lastErrorCode [NumErrorGroups+1]
| The platform independant error code. More...
int | lastErrorNumber [NumErrorGroups+1]
| The operating system error number (eg as returned by errno). More...
PINDEX | lastReadCount
| Number of byte last read by the Read() function. More...
PINDEX | lastWriteCount
| Number of byte last written by the Write() function. More...
PTimeInterval | readTimeout
| Timeout for read operations. More...
PTimeInterval | writeTimeout
| Timeout for write operations. More...
PString | channelName
PMutex | px_threadMutex
PXBlockType | px_lastBlockType
PThread * | px_readThread
PThread * | px_writeThread
PMutex | px_writeMutex
PThread * | px_selectThread [3]
PMutex | px_selectMutex [3]

## Detailed Description

This class defines an I/O channel that communicates via a serial port.

This is usually an RS-232 port.

## Member Enumeration Documentation

enum PSerialChannel::FlowControl

Configuration of serial port flow control options.

Enumerator
DefaultFlowControl | Use the default flow control, ie do not change it.
NoFlowControl | Set the port for no flow control.
XonXoff | Set the port for software or XON/XOFF flow control.
RtsCts | Set the port for hardware or RTS/CTS flow control.

enum PSerialChannel::Parity

Configuration of serial port parity options.

Enumerator
DefaultParity | Use the default parity, ie do not change it.
NoParity | Set the port for no parity bit.
EvenParity | Set the port to generate parity and make it even.
OddParity | Set the port to generate parity and make it odd.
MarkParity | Set the port parity bit to mark only.
SpaceParity | Set the port parity bit to space only.

## Constructor & Destructor Documentation

PSerialChannel::PSerialChannel | ( |  | ) |

Create a new serial channel object, but do not open it.

PSerialChannel::PSerialChannel | ( | const PString & | port,
|  | DWORD | speed = `0`,
|  | BYTE | data = `0`,
|  | Parity | parity = `DefaultParity`,
|  | BYTE | stop = `0`,
|  | FlowControl | inputFlow = `DefaultFlowControl`,
|  | FlowControl | outputFlow = `DefaultFlowControl`
| ) |  |

Create a serial channal.

The channel is opened it on the specified port and with the specified attributes.

Parameters

  port | The name of the serial port to connect to. This is a platform dependent string and woiuld rarely be a literal. The static function `GetPortNames()` can be used to find the platforms serial ports.
  speed | Serial port speed or baud rate. The actual values possible here are platform dependent, but the standard value of 300, 1200, 2400, 4800, 9600, 19200, 38400 always be legal.
  data | Number of data bits for serial port. The actual values possible here are platform dependent, but 7 and 8 should always be legal.
  parity | Parity for serial port. The actual values possible here are platform dependent, but `NoParity`, `OddParity` and `EvenParity` should always be legal.
  stop | Number of stop bits for serial port. The actual values possible here are platform dependent, but 1 and 2 should always be legal.
  inputFlow | Flow control for data from the remote system into this conputer.
  outputFlow | Flow control for data from this conputer out to remote system.

PSerialChannel::PSerialChannel | ( | PConfig & | cfg | ) |

Create a serial channal.

The channel is opened using attributes obtained from standard variables in the configuration file. Note that it assumed that the correct configuration file section is already set.

Parameters

  cfg | Configuration file to read serial port attributes from.

PSerialChannel::~PSerialChannel | ( |  | ) |

Close the serial channel on destruction.

## Member Function Documentation

void PSerialChannel::ClearBreak | ( |  | ) |

Clear the break condition of the serial port.

This is equivalent to `SetBreak(false)`.

void PSerialChannel::ClearDTR | ( |  | ) |

Clear the Data Terminal Ready signal of the serial port.

This is equivalent to `SetDTR(false)`.

void PSerialChannel::ClearRTS | ( |  | ) |

Clear the Request To Send signal of the serial port.

This is equivalent to `SetRTS(false)`.

PBoolean PSerialChannel::Close | ( |  | ) |

virtual

Close the channel, shutting down the link to the data source.

Returns
  true if the channel successfully closed.

Reimplemented from PChannel.

Reimplemented in PModem.

PBoolean PSerialChannel::GetCTS | ( |  | ) |

Get the Clear To Send signal of the serial port.

Returns
  true if the CTS signal is asserted.

BYTE PSerialChannel::GetDataBits | ( |  | ) | const

Get the data bits (5, 6, 7 or 8) of the serial port.

Returns
  current setting.

PBoolean PSerialChannel::GetDCD | ( |  | ) |

Get the Data Carrier Detect signal of the serial port.

Returns
  true if the DCD signal is asserted.

PBoolean PSerialChannel::GetDSR | ( |  | ) |

Get the Data Set Ready signal of the serial port.

Returns
  true if the DSR signal is asserted.

FlowControl PSerialChannel::GetInputFlowControl | ( |  | ) | const

Get the flow control (handshaking) protocol of the input to the serial port.

Returns
  current setting.

FlowControl PSerialChannel::GetOutputFlowControl | ( |  | ) | const

Get the flow control (handshaking) protocol of the output from the serial port.

Returns
  current setting.

Parity PSerialChannel::GetParity | ( |  | ) | const

Get the parity of the serial port.

Returns
  current setting.

static PStringList PSerialChannel::GetPortNames | ( |  | ) |

static

Get a list of the available serial ports.

This returns a set of platform dependent strings which describe the serial ports of the computer. For example under unix it may be "ttyS0", under MS-DOS or NT it would be "COM1" and for the Macintosh it could be "Modem".

Returns
  list of strings for possible serial ports.

PBoolean PSerialChannel::GetRing | ( |  | ) |

Get the Ring Indicator signal of the serial port.

Returns
  true if the RI signal is asserted.

DWORD PSerialChannel::GetSpeed | ( |  | ) | const

Get the speed (baud rate) of the serial channel.

Returns
  current setting.

BYTE PSerialChannel::GetStopBits | ( |  | ) | const

Get the stop bits (1 or 2) of the serial port.

Returns
  current setting.

virtual PBoolean PSerialChannel::Open | ( | const PString & | port,
|  | DWORD | speed = `0`,
|  | BYTE | data = `0`,
|  | Parity | parity = `DefaultParity`,
|  | BYTE | stop = `0`,
|  | FlowControl | inputFlow = `DefaultFlowControl`,
|  | FlowControl | outputFlow = `DefaultFlowControl`
| ) |  |

virtual

Open a serial channal.

The channel is opened it on the specified port and with the specified attributes.

Parameters

  port | The name of the serial port to connect to. This is a platform dependent string and woiuld rarely be a literal. The static function `GetPortNames()` can be used to find the platforms serial ports.
  speed | Serial port speed or baud rate. The actual values possible here are platform dependent, but the standard value of 300, 1200, 2400, 4800, 9600, 19200, 38400 always be legal.
  data | Number of data bits for serial port. The actual values possible here are platform dependent, but 7 and 8 should always be legal.
  parity | Parity for serial port. The actual values possible here are platform dependent, but `NoParity`, `OddParity` and `EvenParity` should always be legal.
  stop | Number of stop bits for serial port. The actual values possible here are platform dependent, but 1 and 2 should always be legal.
  inputFlow | Flow control for data from the remote system into this conputer.
  outputFlow | Flow control for data from this conputer out to remote system.

Reimplemented in PModem.

virtual PBoolean PSerialChannel::Open | ( | PConfig & | cfg | ) |

virtual

Open a serial channal.

The channel is opened using attributes obtained from standard variables in the configuration file. Note that it assumed that the correct configuration file section is already set.

Parameters

  cfg | Configuration file to read serial port attributes from.

Reimplemented in PModem.

virtual void PSerialChannel::SaveSettings | ( | PConfig & | cfg | ) |

virtual

Save the current port settings into the configuration file.

Note that it assumed that the correct configuration file section is already set.

Parameters

  cfg | Configuration file to save setting into.

Reimplemented in PModem.

void PSerialChannel::SetBreak | ( | PBoolean | state = `true` | ) |

Set the break condition of the serial port.

Parameters

  state | New state of the serial port break condition.

PBoolean PSerialChannel::SetDataBits | ( | BYTE | data | ) |

Set the data bits (5, 6, 7 or 8) of the serial port.

Returns
  true if the change was successfully made.

Parameters

  data | New number of data bits for serial channel.

void PSerialChannel::SetDTR | ( | PBoolean | state = `true` | ) |

Set the Data Terminal Ready signal of the serial port.

Parameters

  state | New state of the DTR signal.

PBoolean PSerialChannel::SetInputFlowControl | ( | FlowControl | flowControl | ) |

Set the flow control (handshaking) protocol of the input to the serial port.

Returns
  true if the change was successfully made.

Parameters

  flowControl | New flow control for serial channel input.

PBoolean PSerialChannel::SetOutputFlowControl | ( | FlowControl | flowControl | ) |

Set the flow control (handshaking) protocol of the output to the serial port.

Returns
  true if the change was successfully made.

Parameters

  flowControl | New flow control for serial channel output.

PBoolean PSerialChannel::SetParity | ( | Parity | parity | ) |

Set the parity of the serial port.

Returns
  true if the change was successfully made.

Parameters

  parity | New parity option for serial channel.

void PSerialChannel::SetRTS | ( | PBoolean | state = `true` | ) |

Set the Request To Send signal of the serial port.

Parameters

  state | New state of the RTS signal.

PBoolean PSerialChannel::SetSpeed | ( | DWORD | speed | ) |

Set the speed (baud rate) of the serial channel.

Returns
  true if the change was successfully made.

Parameters

  speed | New speed for serial channel.

PBoolean PSerialChannel::SetStopBits | ( | BYTE | stop | ) |

Set the stop bits (1 or 2) of the serial port.

Returns
  true if the change was successfully made.

Parameters

  stop | New number of stop bits for serial channel.

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

- serchan.h