serialport.gifCSerialPort v1.34

Welcome to CSerialPort / CSerialPort2, two freeware C++ classes to wrap access to the Win32 APIs dealing with serial ports.

 

Features
Usage
Copyright
History
API Reference
Contacting the Author

 

 

 

Features

 

 

 

Usage

 

 

 

Copyright

 

 

 

History

v1.34 (17 December 2017)

v1.33 (16 August 2017)

v1.32 (22 May 2016)

v1.31 (17 December 2015)

v1.30 (26 April 2015)

v1.29 (28 February 2015)

v1.28 (25 January 2013)

v1.27 (4 July 2008)

v1.26 (21 June 2008)

v1.25 (18 May 2008)

v1.24 (30 December 2007)

v1.23 (24 December 2007)

v1.22 (25 January 2007)

v1.21 (5 November 2006)

v1.20 (25 June 2006)

v1.19 (24 June 2006)

v1.18 (5 June 2006)

v1.17 (2 June 2006)

v1.16 (10 April 2006)

5 March 2003

V1.15 (20 September 2002)

V1.14 (7 August 2002)

V1.13 (29 May 2002)

V1.12 (1 May 2002)

V1.11 (23 April 2001)

V1.10 (4 April 2001)

V1.09 (24 March 2001)

V1.08 (15 January 2001)

V1.07 (10 December 2000)

3 July 2000

V1.06 (12 June 2000)

V1.05 (8 May 2000)

V1.04 (8 March 2000)

V1.03 (29 September 1999)

V1.02 (16 June 1999)

V1.01 (3 June 1999)

V1.0 (31 May 1999)

 

 

 

API Reference

The API consists of the classes: CSerialException, CSerialPort and the non exception based CSerialPort2. The CSerialException and CSerialPort classes have the following member functions and variables:

CSerialException::CSerialException
CSerialException::GetErrorMessage
CSerialException::m_dwError
CSerialPort::CSerialPort
CSerialPort::~CSerialPort
CSerialPort::Open
CSerialPort::Close
CSerialPort::Attach
CSerialPort::Detach
CSerialPort::operator HANDLE
CSerialPort::IsOpen
CSerialPort::Dump
CSerialPort::Read
CSerialPort::ReadEx
CSerialPort::Write
CSerialPort::WriteEx
CSerialPort::TransmitChar
CSerialPort::GetOverlappedResult
CSerialPort::CancelIo
CSerialPort::CancelIoEx
CSerialPort::GetConfig
CSerialPort::GetDefaultConfig
CSerialPort::SetConfig
CSerialPort::SetDefaultConfig
CSerialPort::ClearBreak
CSerialPort::SetBreak
CSerialPort::ClearError
CSerialPort::GetStatus
CSerialPort::GetState
CSerialPort::SetState
CSerialPort::Escape
CSerialPort::ClearDTR
CSerialPort::ClearRTS
CSerialPort::SetDTR
CSerialPort::SetRTS
CSerialPort::SetXOFF
CSerialPort::SetXON
CSerialPort::GetProperties
CSerialPort::GetModemStatus
CSerialPort::SetTimeouts
CSerialPort::GetTimeouts
CSerialPort::Set0Timeout
CSerialPort::Set0WriteTimeout
CSerialPort::Set0ReadTimeout
CSerialPort::SetMask
CSerialPort::GetMask
CSerialPort::WaitEvent
CSerialPort::Flush
CSerialPort::Purge
CSerialPort::TerminateOutstandingWrites
CSerialPort::TerminateOutstandingReads
CSerialPort::ClearWriteBuffer
CSerialPort::ClearReadBuffer
CSerialPort::Setup
CSerialPort::BytesWaiting

 

CSerialException::CSerialException

CSerialException(DWORD dwError = 0);

Parameters

dwError   The error that caused the exception.

Remarks

This member function is called when a CSerialException object is created. To throw a CSerialException, call the method CSerialPort::ThrowSerialException. If you call if using the default value for dwError, then internally it will call GetLastError for you.

 

CSerialException::GetErrorMessage

virtual BOOL GetErrorMessage(LPTSTR lpszError, UINT nMaxError, PUINT pnHelpContext = nullptr);
CString GetErrorMessage();

Return Value

1) Nonzero if the function is successful; otherwise 0 if no error message text is available.

2) A CString representation of the error

Parameters

lpszError A pointer to a buffer that will receive an error message.

nMaxError The maximum number of characters the buffer can hold, including the null terminator.

pnHelpContext The address of a UINT that will receive the help context ID. If null, no ID will be returned.

Remarks

Call this member function to provide text about an error that has occurred. Note this method is only available if you enable MFC integration via CSERIALPORT_MFC_EXTENSIONS.

 

CSerialException::m_dwError

Remarks

The error that caused the exception. This error value is a system error code as found in WinError.h.

For a list of Win32 error codes, see Error Codes in the Win32 SDK.

 

CSerialPort::CSerialPort

CSerialPort();

Remarks

Standard C++ constructor for the class. Internally it just sets up the member variables to default values.

 

CSerialPort::~CSerialPort

virtual ~CSerialPort();

Remarks

Standard C++ destructor for the class. It will ensure that the comm port is closed if it is open.

 

CSerialPort::Open

void Open(LPCTSTR pszPort, BOOL bOverlapped = FALSE);
void Open(LPCTSTR
pszPort, DWORD dwBaud = 9600, Parity parity = NoParity, BYTE DataBits = 8, StopBits stopBits = OneStopBit, FlowControl fc = NoFlowControl, BOOL bOverlapped = FALSE);
void Open(int
nPort, DWORD dwBaud = 9600, Parity parity = NoParity, BYTE DataBits = 8, StopBits stopBits = OneStopBit, FlowControl fc = NoFlowControl, BOOL bOverlapped = FALSE);
    throw( CSerialException* / CSerialException& );

Parameters

nPort   The communications port to open.

pszPort The name of the communications port to open. Note you would use this version of the Open method if the serial port does not have a name of type "COM%d".

dwBaud The baud rate to use

parity The parity to use. parity is an enum with the following values:

enum Parity
{
EvenParity,
MarkParity,
NoParity,
OddParity,
SpaceParity
};

Databits The number of data bits to use

stopbits The number of stop bits to use. stopbits is an enum with the following values:

enum StopBits
{
OneStopBit,
OnePointFiveStopBits,
TwoStopBits
};

fc The flow control method to use. fc is an enum with the following values:

enum FlowControl
{
NoFlowControl,
CtsRtsFlowControl,
CtsDtrFlowControl,
DsrRtsFlowControl,
DsrDtrFlowControl,
XonXoffFlowControl
};

bOverlapped TRUE if you want to open in overlapped mode, otherwise FALSE to use blocking calls.

Remarks

Call this member function to open a communications port. Internally the class will use CreateFile to open the comm port (handling the case where the port number if greater than 9) and then uses SetState to set the various RS-232 settings as specified via the function parameters. If an error occurs, a CSerialException will be thrown.

 

CSerialPort::Close

Close();

Remarks

The corollary function to Open. Just closes the comm port if already open.

 

CSerialPort::Attach

void Attach(HANDLE hComm);

Parameters

hComm   The SDK handle of the open comm port.

Remarks

Allows you to attach a CSerialPort instance to an existing SDK comm port handle. This function is similar in behaviour to the CWnd::Attach function provided in MFC.

 

CSerialPort::Detach

HANDLE Detach();

Return Value

The SDK comm port HANDLE.

Remarks

Corollary function to Attach. This function is similar in behaviour to the CWnd::Detach function provided in MFC.

 

CSerialPort::operator HANDLE

operator HANDLE();

Return Value

The SDK comm port HANDLE.

Remarks

Use this operator to get the handle of the underlying comm port. You can use this handle to call the Windows APIs directly.

 

CSerialPort::IsOpen

BOOL IsOpen() const

Return Value

TRUE if the comm port is open otherwise FALSE

 

CSerialPort::Dump

void Dump(CDumpContext& dc) const

Remarks

Standard MFC diagnostic support function

 

CSerialPort::Read \ ReadEx

DWORD Read(void* lpBuffer, DWORD dwNumberOfBytesToRead);
void Read(void*
lpBuffer, DWORD dwCount, OVERLAPPED& overlapped, DWORD* lpNumberOfBytesRead = nullptr);
void ReadEx(void*
lpBuffer, DWORD dwNumberOfBytesToRead, LPOVERLAPPED lpOverlapped, LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine);
    throw( CSerialException*/ CSerialException& );

Return Value

1) The number of bytes read.

2) & 3) No return value

Parameters

lpBuffer  Points to the buffer to read the data into from the serial port

dwNumberOfBytesToRead  Specifies the number of bytes to read from the serial port.

overlapped  reference to an OVERLAPPED structure. This is required if the port was opened in overlapped mode.

lpNumberOfBytesRead If the value is non-null then upon return it will contain the number of bytes read

lpOverlapped  pointer to the OVERLAPPEDpped structure to use

lpCompletionRoutine  the completion routine to use

Remarks

These 3 functions are wrappers for the SDK calls ReadFile and ReadFileEx. Also please note that depending on the way you have configured timeouts, this function may appear to block while it waits to receive the specified data. To configure timeouts, please check out the Set*Timeout(s) functions.

 

CSerialPort::Write \ WriteEx

DWORD Write(const void* lpBuffer, DWORD dwNumberOfBytesToWrite);
void Write(const void*
lpBuffer, DWORD dwNumberOfBytesToWrite, OVERLAPPED& overlapped, DWORD* lpNumberOfBytesWritten = nullptr);
void WriteEx(const void*
lpBuffer, DWORD dwNumberOfBytesToWrite, LPOVERLAPPED lpOverlapped, LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine);
    throw( CSerialException* / CSerialException& );

Return Value

1) The number of bytes written.

2) & 3) No return value

Parameters

lpBuffer  Points to the buffer containing the data to be written to the serial port

dwNumberOfBytesToWrite  Specifies the number of bytes to write to the serial port.

overlapped  reference to an OVERLAPPED structure. This is required if the port was opened in overlapped mode.

lpNumberOfBytesWritten If the value is non-null then upon return it will contain the number of bytes written

lpOverlapped  pointer to the OVERLAPPEDpped structure to use

lpCompletionRoutine  the completion routine to use

Remarks

These 3 functions are wrappers for the SDK calls WriteFile and WriteFileEx.

 

CSerialPort::TransmitChar

void TransmitChar(char cChar) const
   
throw( CSerialException*/ CSerialException& );

Remarks

Simple wrapper for the TransmitCommChar SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::GetOverlappedResult

void GetOverlappedResult(OVERLAPPED& overlapped, DWORD& dwBytesTransferred, BOOL bWait)
   
throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the GetOverlappedResult SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::CancelIo

void CancelIo()
    throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the CancelIo SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::CancelIoEx

void CancelIoEx(_In_opt_ LPOVERLAPPED lpOverlapped = nullptr)
    throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the CancelIoEx SDK function call. See the Win32 SDK documentation for further details.

 

 

CSerialPort::GetConfig

void GetConfig(COMMCONFIG& config)
   
throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the GetCommConfig SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::GetDefaultConfig

static void GetDefaultConfig(int nPort, COMMCONFIG& config)
   
throw( CSerialException*/ CSerialException& );

static void GetDefaultConfig(LPCTSTR pszPort, COMMCONFIG& config)
   
throw( CSerialException*/ CSerialException& );

Remarks

Simple wrapper for the GetDefaultCommConfig SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::SetConfig

void SetConfig(COMMCONFIG& config)
   
throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the SetCommConfig SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::SetDefaultConfig

static void SetDefaultConfig(int nPort, COMMCONFIG& config)
   
throw( CSerialException* / CSerialException& );

static void SetDefaultConfig(LPCTSTR pszPort, COMMCONFIG& config)
   
throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the SetDefaultCommConfig SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::ClearBreak

void ClearBreak()
    throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the ClearCommBreak SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::SetBreak

void SetBreak()
    throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the SetCommBreak SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::ClearError

void ClearError(DWORD& dwErrors)
   
throw( CSerialException*/ CSerialException& );

Remarks

Simple wrapper for the ClearCommError SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::GetStatus

void GetStatus(COMMSTAT& stat)
   
throw( CSerialException* / CSerialException& );

Remarks

Another way of returning information which the SDK call ClearCommError returns. See the Win32 SDK documentation for further details.

 

CSerialPort::GetState

void GetState(DCB& dcb)
   
throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the GetCommState SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::SetState

void SetState(DCB& dcb)
   
throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the SetCommState SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::Escape

void Escape(DWORD dwFunc)
   
throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the EscapeCommFunction SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::ClearDTR

void ClearDTR()
    throw( CSerialException* / CSerialException& );

Remarks

Calls the Escape function using the constant CLRDTR which lowers the DTR line.

 

CSerialPort::ClearRTS

void ClearRTS()
    throw( CSerialException* / CSerialException& );

Remarks

Calls the Escape function using the constant CLRRTS which lowers the RTS line.

 

CSerialPort::SetDTR

void SetDTR()
    throw( CSerialException* / CSerialException& );

Remarks

Calls the Escape function using the constant SETDTR which raises the DTR line.

 

CSerialPort::SetRTS

void SetRTS()
    throw( CSerialException* / CSerialException& );

Remarks

Calls the Escape function using the constant SETRTS which raises the RTS line.

 

CSerialPort::SetXOFF

void SetXOFF()
    throw( CSerialException* / CSerialException& );

Remarks

Calls the Escape function using the constant SETXOFF which causes transmission to act as if an XOFF character has been received.

 

CSerialPort::SetXON

void SetXON()
    throw( CSerialException* / CSerialException& );

Remarks

Calls the Escape function using the constant SETXON which causes transmission to act as if an XON character has been received.

 

CSerialPort::GetProperties

void GetProperties(COMMPROP& properties)
   
throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the GetCommProperties SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::GetModemStatus

void GetModemStatus(DWORD& dwModemStatus)
   
throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the GetCommModemStatus SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::SetTimeouts

void SetTimeouts(COMMTIMEOUTS& timeouts)
   
throw( CSerialException* );

Remarks

Simple wrapper for the SetCommTimeouts SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::GetTimeouts

void GetTimeouts(COMMTIMEOUTS& timeouts)
   
throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the GetCommTimeouts SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::Set0Timeout

void Set0Timeout()
    throw( CSerialException* / CSerialException& );

Remarks

Configure both send and receive timeouts to be 0. This cause writes to return immediately and for reads to return with whatever data is waiting in the receive buffer rather than wait for the specified amount of bytes to arrive.

 

CSerialPort::Set0WriteTimeout

void Set0WriteTimeout()
    throw( CSerialException* / CSerialException& );

Remarks

Configures the send timeouts to be 0. This cause writes to return immediately.

 

CSerialPort::Set0ReadTimeout

void Set0ReadTimeout()
    throw( CSerialException* / CSerialException& );

Remarks

Configure the receive timeout to be 0. This cause reads to return with whatever data is waiting in the receive buffer rather than wait for the specified amount of bytes to arrive.

 

CSerialPort::SetMask

void SetMask(DWORD dwMask)
   
throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the SetCommMask SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::GetMask

void GetMask(DWORD& dwMask)
   
throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the GetCommMask SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::WaitEvent

void WaitEvent(DWORD& dwMask)
BOOL WaitEvent(DWORD&
dwMask, OVERLAPPED& overlapped)
   
throw( CSerialException* / CSerialException& );

Return Value

TRUE if the overlapped read completely synchronously, FALSE if the operation is to be completed asynchronously.

Remarks

Simple wrapper for the WaitCommEvent SDK function call. The second version of WaitEvent is the overlapped version which will return immediately and you can wait for the manual reset event member of the OVERLAPPED structure to become signalled in your code. See the Win32 SDK documentation for further details.

 

CSerialPort::Flush

void Flush()
    throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the FlushFileBuffers SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::Purge

void Purge(DWORD dwFlags)
   
throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the PurgeComm SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::TerminateOutstandingWrites

void TerminateOutstandingWrites()
    throw( CSerialException* / CSerialException& );

Remarks

Calls the Purge function using the constant PURGE_TXABORT which terminates all outstanding write operations and returns immediately, even if the write operations have not been completed.

 

CSerialPort::TerminateOutstandingReads

void TerminateOutstandingReads()
    throw( CSerialException* / CSerialException& );

Remarks

Calls the Purge function using the constant PURGE_RXABORT which terminates all outstanding read operations and returns immediately, even if the read operations have not been completed.

 

CSerialPort::ClearWriteBuffer

void ClearWriteBuffer()
    throw( CSerialException* / CSerialException& );

Remarks

Calls the Purge function using the constant PURGE_TXCLEAR which clears the output buffer (if the device driver has one)..

CSerialPort::ClearReadBuffer

void ClearReadBuffer()
    throw( CSerialException* / CSerialException& );

Remarks

Calls the Purge function using the constant PURGE_RXCLEAR which clears the input buffer (if the device driver has one)..

 

CSerialPort::Setup

void Setup(DWORD dwInQueue, DWORD dwOutQueue)
   
throw( CSerialException* / CSerialException& );

Remarks

Simple wrapper for the SetupComm SDK function call. See the Win32 SDK documentation for further details.

 

CSerialPort::BytesWaiting

DWORD BytesWaiting();
    throw( CSerialException* / CSerialException& );

Return Value

The number of bytes waiting to be read from the serial port

Remarks

The function returns the number of bytes waiting to be read from the serial port

 

 

 

Contacting the Author

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
17 December 2017