ApparatusFramework::SerialPort Class Reference

#include <DeviceServices/Win32/current/include/SerialPort.h>

Inheritance diagram for ApparatusFramework::SerialPort:
ApparatusFramework::SerialPortIf

List of all members.

Public Member Functions

 SerialPort ()
virtual ~SerialPort ()
uint32 openPort (int portNr, uint32 baudRate, uint8 byteSize, uint8 parity, uint8 stopBits)
DWORD openPort (LPCTSTR portName, DWORD baudRate, BYTE byteSize, BYTE parity, BYTE stopBits, SerialPortListener *pListener=NULL, DWORD commMask=DEFAULT_COMM_MASK, LPDCB pDcb=NULL, LPCOMMTIMEOUTS pCommTimeouts=NULL)
uint32 closePort ()
uint32 writeByte (uint8 aByte, bool isBlocking=FALSE, uint32 timeout=INFINITE)
uint32 writeByteStream (uint8 *pBuffer, uint16 length, bool isBlocking=FALSE, uint32 timeout=INFINITE)
uint32 readByte (uint8 &aByte, bool isBlocking=FALSE, uint32 timeout=INFINITE)
uint32 readByteStream (uint8 *pBuffer, uint16 &length, bool isBlocking=FALSE, uint32 timeout=INFINITE)
DWORD setDCB (DCB dcb)
DWORD getDCB (DCB &dcb)
void flush ()

Protected Member Functions

UINT runCommThread ()
BOOL read ()
void handleByteReceived ()
void handleOverlappedByteReceived ()
BOOL waitForCommEvent ()
void handleCommEvent ()
void handleOverlappedCommEvent ()
void write ()
void handleBytesWritten ()

Static Protected Member Functions

static THREADRETVAL enterCommThread (LPVOID pParent)

Detailed Description

An instance of class SerialPort represents one serial port in a Win32 system. After opening a port the user can read and write single bytes and byte streams blocking and non-blocking. The data flow in both directions is internally buffered, so that it does not depend on the hardware buffer of the serial port. The class uses the standard Win32 serial communication mechanism. It hides the user from details like file handlers and has got his own communication thread to ensure that the serial communication is independent from the application thread. Opening the port the user configures the serial port (baud rate, parity, ...). The configuration is limited to the most common parameters. If the port has to be configured in detail you have to use the DCB structure from the Win32 serial communication mechanism. A getter an a setter for the DCB structure are part of this class.

Definition at line 192 of file SerialPort.h.


Constructor & Destructor Documentation

ApparatusFramework::SerialPort::SerialPort (  ) 

Constructors, destructors The constructor. It only initializes the members of the Serial Port class.

virtual ApparatusFramework::SerialPort::~SerialPort (  )  [virtual]

If the user has not closed the port before the destructor is called, the remaining work is done in the destructor.


Member Function Documentation

uint32 ApparatusFramework::SerialPort::closePort (  )  [virtual]

Closes the handle for the serial port and does some additional cleanup. This method is called automatically by the destructor but it is recommended to use it explicitly because the destructor cannot react on errors during the cleanup.

Returns:
Returns one of the SERIAL_PORT_... result values.

Implements ApparatusFramework::SerialPortIf.

static THREADRETVAL ApparatusFramework::SerialPort::enterCommThread ( LPVOID  pParent  )  [static, protected]

Communication thread The entry point for the communication thread which listens for events at the serial port.

Parameters:
pParent See Win32 meaning of thread parameters.
Returns:
See Win32 handling of thread return values.
void ApparatusFramework::SerialPort::flush (  )  [inline, virtual]

This function does only flush the input and the output buffer of the SerialPort class but not the hardware buffer of the serial port itself.

Implements ApparatusFramework::SerialPortIf.

Definition at line 333 of file SerialPort.h.

References ApparatusFramework::RingBuffer::flush().

DWORD ApparatusFramework::SerialPort::getDCB ( DCB &  dcb  ) 

This is the getter counterpart for the setter function setDCB(). The same constraints which are true for setDCB have also to be considered for this method.

Parameters:
dcb The current DCB settings of the port represented by the SerialPort class.
Returns:
Returns one of the SERIAL_PORT_... result values.
void ApparatusFramework::SerialPort::handleByteReceived (  )  [protected]

Handles a received byte. If an error occurred during reception, the communication errors are reset and the serial port buffer cleared. A received byte is forwarded to the input buffer.

void ApparatusFramework::SerialPort::handleBytesWritten (  )  [protected]

Checks the number of bytes written and reports to the user.

void ApparatusFramework::SerialPort::handleCommEvent (  )  [protected]

The only communication event which is handled specially, is the one indicating a communication error. There, the error has to be cleared. The other communication events are just reported to the user.

void ApparatusFramework::SerialPort::handleOverlappedByteReceived (  )  [protected]

A call to read can result in an overlapped read operation. As soon as as the serial port receives a byte, it creates a corresponding communication event. On this event the handleOverlappedByteReceived() method is called to fetch the byte. Afterwards it is handled the same way as in read() with a call to handleByteReceived().

void ApparatusFramework::SerialPort::handleOverlappedCommEvent (  )  [protected]

If an overlapped wait for communication events is ends with an incoming communication event, this method is called to fetch the event. The actual handling is done by handleCommEvent().

DWORD ApparatusFramework::SerialPort::openPort ( LPCTSTR  portName,
DWORD  baudRate,
BYTE  byteSize,
BYTE  parity,
BYTE  stopBits,
SerialPortListener pListener = NULL,
DWORD  commMask = DEFAULT_COMM_MASK,
LPDCB  pDcb = NULL,
LPCOMMTIMEOUTS  pCommTimeouts = NULL 
)

Attempts to open a serial port. If the parameters of this method are not sufficient to configure the port, the user can call setDCB() to set the DCB structure (Win32 serial comm. mechanism) directly. The same SerialPort class cannot open two different ports. The user should take care of closing the port before the destructor of this class is called.

Parameters:
portName The name of the port which should be opened. An example is "COM2".
baudRate Specifies the baud rate at which the serial port operates.
byteSize Number of bits in the bytes transmitted and received
parity Specifies the parity scheme to be used.
stopBits Specifies the number of stop bits to be used.
commMask Specifies a set of events to be monitored. (Default is no event apart from EV_RXCHAR (Win32 API)
pDcb The Win32 specific DCB structure containing the serial port settings. If the other parameters of openPort() are not sufficient to configure the serial port, this structure has to be filled with the missing settings. Default value: NULL.
pCommTimeouts The time-out parameters for all read and write operations
pListener Reference to a class with receives the notifications (e.g. byte received) or communication errors. Default value: NULL.
Returns:
Returns one of the SERIAL_PORT_... result values.
uint32 ApparatusFramework::SerialPort::openPort ( int  portNr,
uint32  baudRate,
uint8  byteSize,
uint8  parity,
uint8  stopBits 
) [virtual]

Open and close ports The SerialPort class owns two overloaded openPort methods. Only this one can be accessed through the platform independent interface SerialPortIf. Whereas the second version of openPort expects Win32 specific values for certain of its parameters, this one uses the values defined in SerialPortIf.h instead.

Parameters:
portNr Number of the port which should be opened. The method constructs a string "COMx" where x is the number and uses it with the Win32 serial communication mechanism. At the moment only the ports COM1 to COMx are available.
baudRate Specifies the baud rate at which the serial port operates. Use the predefined values from the header file SerialPortIf.h.
byteSize Number of bits in the bytes transmitted and received
parity Specifies the parity scheme to be used. Use the predefined values from the header file SerialPortIf.h.
stopBits Stop bits in the serial communication protocol. Use the predefined values from the header file SerialPortIf.h.
Returns:
Returns one of the SERIAL_PORT_... result values.

Implements ApparatusFramework::SerialPortIf.

BOOL ApparatusFramework::SerialPort::read (  )  [protected]

Internal read and write operations. The method starts an overlapped read to the serial port for one byte. If there is already a byte available, it is handled directly by handleByteReceived(). Otherwise, it is handled by the communication thread as soon as the corresponding communication event occurs.

Returns:
TRUE if the read operation is still ongoing because the serial port buffer has been empty (represents an isReading state).
uint32 ApparatusFramework::SerialPort::readByte ( uint8 aByte,
bool  isBlocking = FALSE,
uint32  timeout = INFINITE 
) [virtual]

Read operations Reads a single byte from the serial port. The non-blocking read fails if there is not enough data in the input buffer. The blocking read fails if the given timeout expires.

Parameters:
aByte One byte of data which is has been read from the serial port.
isBlocking TRUE if blocking read, FALSE if non-blocking
timeout A blocking read operation uses this timeout, so that the caller of this method cannot be blocked forever.
Returns:
Returns one of the SERIAL_PORT_... result values.

Implements ApparatusFramework::SerialPortIf.

uint32 ApparatusFramework::SerialPort::readByteStream ( uint8 pBuffer,
uint16 length,
bool  isBlocking = FALSE,
uint32  timeout = INFINITE 
) [virtual]

reads a stream of bytes from the serial port. The non-blocking read fails if there is not enough data in the input buffer. The blocking read fails if the given timeout expires.

Parameters:
pBuffer Start address of the buffer to which the data from the serial port has to be written.
length Number of bytes to be read from the serial port.
isBlocking TRUE if blocking read, FALSE if non-blocking
timeout A blocking read operation uses this timeout, so that the caller of this method cannot be blocked forever.
Returns:
Returns one of the SERIAL_PORT_... result values.

Implements ApparatusFramework::SerialPortIf.

UINT ApparatusFramework::SerialPort::runCommThread (  )  [protected]

The method which represents the communication thread. The communication thread handles incoming data or communication events from the serial port and the transport of data in the output buffer to the serial port.

Returns:
At the moment the return value is always 0.
DWORD ApparatusFramework::SerialPort::setDCB ( DCB  dcb  ) 

Miscellaneous The class uses the Win32 serial communication mechanism. There, the DCB structure defines the control setting for a serial communications devices. The most common settings like baudRate or parity are parameters of openPort(). If it is necessary to change other settings the user can change the contents of the DCB structure directly with setDCB(). IMPORTANT: This has to be done directly after the call to openPort().If the change takes place while the port is receiving or transmitting the results are unpredictable.

Parameters:
dcb The new DCB structure for the port represented by the SerialPort class. The structure has to be set completely. If the user wants to change only a few items of this structure, the current settings have to be retrieved with get DCB first.
Returns:
Returns one of the SERIAL_PORT_... result values.
BOOL ApparatusFramework::SerialPort::waitForCommEvent (  )  [protected]

Starts an overlapped wait for communication events from the serial port. If there is already an event available it is handled with handleCommEvent().

Returns:
TRUE if there was no communication event available (represents an isWaiting state).
void ApparatusFramework::SerialPort::write (  )  [protected]

Uses the Win32 communication mechanism to write the current contents of the output buffer to the serial port.

uint32 ApparatusFramework::SerialPort::writeByte ( uint8  aByte,
bool  isBlocking = FALSE,
uint32  timeout = INFINITE 
) [virtual]

Write operations Writes a single byte to the serial port. The method fails if there is not enough space in the output buffer.

Parameters:
aByte One byte of data which has to be written to the serial port.
isBlocking TRUE if blocking write, FALSE if non-blocking
timeout A blocking write operation uses this timeout, so that the caller of this method cannot be blocked forever.
Returns:
Returns one of the SERIAL_PORT_... result values.

Implements ApparatusFramework::SerialPortIf.

uint32 ApparatusFramework::SerialPort::writeByteStream ( uint8 pBuffer,
uint16  length,
bool  isBlocking = FALSE,
uint32  timeout = INFINITE 
) [virtual]

Writes a certain number of bytes to the serial port. The method fails if there is not enough space in the output buffer.

Parameters:
pBuffer Start address of the buffer from which the data has to be written to the serial port.
length Number of bytes to be written to the serial port.
isBlocking TRUE if blocking write, FALSE if non-blocking
timeout A blocking write operation uses this timeout, so that the caller of this method cannot be blocked forever.
Returns:
Returns one of the SERIAL_PORT_... result values.

Implements ApparatusFramework::SerialPortIf.

© 2004-2010 bbv Software Services AG / Apparatus Services