CSerialPort v1.22

Welcome to CSerialPort, a freeware MFC class to wrap access to the Win32 APIs dealing with serial ports.

Features

• Simple and clean C++ interface.
• Uses C++ exceptions in preference to the normal win32 return value mechanism. This ensures that code which uses CSerialPort is more robust.
• Unicode enabled, supports linking to MFC statically and all code compiles cleanly at warning level 4.
• Supports overlapped, blocking and call-back usage models of the serial port. (Call-back is only supported on NT).

Usage

• To use the class in your code simply include serialport.cpp in your project and #include serialport.h in which ever of your modules needs to make calls to the class.
• As of v1.19 you will need an up to date Platform SDK installed to compile the code if you are using Visual C++ 6 (February 2003 was the last version which was compatible with VC 6).
• To see the code in action have a look at the module "app.cpp" in the sample app.

Copyright

• You are allowed to include the source code in any product (commercial, shareware, freeware or otherwise) when your product is released in binary form.
• You are allowed to modify the source code in any way you want except you cannot modify the copyright details at the top of each module.
• If you want to distribute source code with your application, then you are only allowed to distribute versions released by the author. This is to maintain a single distribution point for the source code.

History

V1.0 (31 May 1999)

• Initial public release.

V1.01 (3 June 1999)

• Fixed problem with code using CancelIo function which does not exist on 95.
• Fixed leaks which can occur in sample app when an exception is thrown

V1.02 (16 June 1999)

• Fixed a bug whereby CString::ReleaseBuffer was not being called in CSerialException::GetErrorMessage

V1.03 (29 September 1999)

• Fixed a simple copy and paste bug in CSerialPort::SetDTR

V1.04 (8 March 2000)

• Links in the documentation now work <g>.

V1.05 (8 May 2000)

• Fixed an unreferenced variable in CSerialPort::GetOverlappedResult in VC 6

V1.06 (12 June 2000)

• Fixed another unreferenced variable problem in CSerialPortApp::InitInstance in VC 6.

3 July 2000

• Minor update to the documentation.

V1.07 (10 December 2000)

• Made class destructor virtual.

V1.08 (15 January 2001)

• Attach method now also allows you to specify whether the serial port is being attached to in overlapped mode
• Removed some ASSERTs which were unnecessary in some of the functions
• Updated the Read method which uses OVERLAPPED IO to also return the bytes read. This allows calls to WriteFile with a zeroed overlapped structure (This is required when dealing with TAPI and serial communications)
• Now includes copyright message in the source code and documentation.

V1.09 (24 March 2001)

• Added a BytesWaiting method

V1.10 (4 April 2001)

• Provided an overridden version of BytesWaiting which specifies a timeout.

V1.11 (23 April 2001)

• Fixed a memory leak in DataWaiting method.

V1.12 (1 May 2002)

• Fixed a problem in Open method which was failing to initialize the DCB structure incorrectly, when calling GetState. Thanks to Ben Newson for this fix.

V1.13 (29 May 2002)

• Fixed an problem where the GetProcAddress for CancelIO was using the wrong calling convention.

V1.14 (7 August 2002)

• Changed the declaration of CSerialPort::WaitEvent to be consistent with the rest of the methods in CSerialPort which can operate in "OVERLAPPED" mode. A note about the usage of this: If the method succeeds then the overlapped operation has completed synchronously and there is no need to do a WaitForSingle/MultipleObjects. If any other unexpected error occurs then a CSerialException will be thrown. See the implementation of the CSerialPort::DataWaiting which has been rewritten to use this new design pattern. Thanks to Serhiy Pavlov for spotting this inconsistency.

V1.15 (20 September 2002)

• Addition of an additional ASSERT in the internal _OnCompletion function.
• Addition of an optional out parameter to the Write method which operates in overlapped mode. Thanks to Kevin Pinkerton for this addition.

5 March 2003

• Updated the documentation for the function CSerialPort::GetStatus.

v1.16 (10 April 2006)

• Updated copyright details.
• Addition of a CSERIALPORT_EXT_CLASS and CSERIALPORT_EXT_API macros which makes the class easier to use in an extension dll.
• Removed derivation of CSerialPort from CObject as it was not really needed.
• Fixed a number of level 4 warnings in the sample app.
• Reworked the overlapped IO methods to expose the LPOVERLAPPED structure to client code.
• Updated the documentation to use the same style as the web site.
• Did a spell check of the HTML documentation.
• Updated the documentation on possible blocking in Read/Ex function. Thanks to D Kerrison for reporting this issue.
• Fixed a minor issue in the sample app when the code is compiled using /Wp64

v1.17 (2 June 2006)

• Removed the bOverlapped as a member variable from the class. There was no real need for this setting, since the SDK functions will perform their own checking of how overlapped operations should
• Fixed a bug in GetOverlappedResult where the code incorrectly checking against the error ERROR_IO_PENDING instead of ERROR_IO_INCOMPLETE. Thanks to Sasho Darmonski for reporting this bug.
• Reviewed all TRACE statements for correctness.

v1.18 (5 June 2006)

• Fixed an issue with the creation of the internal event object. It was incorrectly being created as an auto-reset event object instead of a manual reset event object. Thanks to Sasho Darmonski for reporting this issue.

v1.19 (24 June 2006)

• Fixed some typos in the history list. Thanks to Simon Wong for reporting this.
• Made the class which handles the construction of function pointers at runtime a member variable of CSerialPort
• Made AfxThrowSerialPortException part of the CSerialPort class. Thanks to Simon Wong for reporting this.
• Removed the unnecessary CSerialException destructor. Thanks to Simon Wong for reporting this.
• Fixed a minor error in the TRACE text in CSerialPort::SetDefaultConfig. Again thanks to Simon Wong for reporting this.
• Code now uses new C++ style casts rather than old style C casts where necessary. Again thanks to Simon Wong for reporting this.
• CSerialException::GetErrorMessage now uses the strsafe functions. This does mean that the code now requires the Platform SDK if compiled using VC 6.

v1.20 (25 June 2006)

• Combined the functionality of the CSerialPortData class into the main CSerialPort class.
• Renamed AfxThrowSerialPortException to ThrowSerialPortException and made the method public.

v1.21 (5 November 2006)

• Minor update to stdafx.h of sample app to avoid compiler warnings in VC 2005.
• Reverted the use of the strsafe.h header file. Instead now the code uses the VC 2005 Safe CRT and if this is not available, then we fail back to the standard CRT.

v1.22 (25 January 2007)

• Minor update to remove strsafe.h from stdafx.h of the sample app.
• Updated copyright details.

API Reference

The API consists of the classes: CSerialException and the CSerialPort class. They 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::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::OnCompletion
CSerialPort::BytesWaiting
CSerialPort::DataWaiting

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 global function AfxThrowSerialException. 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 = NULL);
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.

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(int nPort, DWORD dwBaud = 9600, Parity parity = NoParity, BYTE DataBits = 8, StopBits stopbits = OneStopBit, FlowControl fc = NoFlowControl, BOOL bOverlapped = FALSE);
    throw( CSerialException* );

Parameters

nPort   The communications port to open.

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* lpBuf, DWORD dwCount);
BOOL Read(void* lpBuf, DWORD dwCount, OVERLAPPED& overlapped, DWORD* pBytesRead = NULL);
void ReadEx(void* lpBuf, DWORD dwCount);
    throw( CSerialException* );

Return Value

1) The number of bytes read.

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

Parameters

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

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

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

Remarks

These 3 functions are wrappers for the SDK calls ReadFile and ReadFileEx. The 2nd version of Read is the overlapped version. 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* lpBuf, DWORD dwCount);
BOOL Write(const void* lpBuf, DWORD dwCount, OVERLAPPED& overlapped, DWORD* pBytesWritten = NULL);
void WriteEx(const void* lpBuf, DWORD dwCount);
    throw( CSerialException* );

Return Value

1) The number of bytes written.

2) TRUE if the overlapped write completely synchronously, FALSE if the operation is to be completed asynchronously.

Parameters

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

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

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

Remarks

These 3 functions are wrappers for the SDK calls WriteFile and WriteFileEx. The 2nd version of Write is the overlapped version.

CSerialPort::TransmitChar

void TransmitChar(char cChar) const
    throw( 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* );

Remarks

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

CSerialPort::CancelIo

void CancelIo()
    throw( CSerialException* );

Remarks

Simple wrapper for the CancelIo SDK function call. See the Win32 SDK documentation for further details. Please note that this function is only available on NT 4 or Windows 98 or later. In version 1.0 of CSerialPort, this would cause code developed with it to fail to load on Windows 95 with an error about a missing export. This problem has been rectified in v1.01 of CSerialPort.

CSerialPort::GetConfig

void GetConfig(COMMCONFIG& config)
    throw( 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* );

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* );

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* );

Remarks

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

CSerialPort::ClearBreak

void ClearBreak()
    throw( CSerialException* );

Remarks

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

CSerialPort::SetBreak

void SetBreak()
    throw( 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* );

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* );

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* );

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* );

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* );

Remarks

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

CSerialPort::ClearDTR

void ClearDTR()
    throw( CSerialException* );

Remarks

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

CSerialPort::ClearRTS

void ClearRTS()
    throw( CSerialException* );

Remarks

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

CSerialPort::SetDTR

void SetDTR()
    throw( CSerialException* );

Remarks

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

CSerialPort::SetRTS

void SetRTS()
    throw( CSerialException* );

Remarks

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

CSerialPort::SetXOFF

void SetXOFF()
    throw( 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* );

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* );

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* );

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* );

Remarks

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

CSerialPort::Set0Timeout

void Set0Timeout()
    throw( 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* );

Remarks

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

CSerialPort::Set0ReadTimeout

void Set0ReadTimeout()
    throw( 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* );

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* );

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* );

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* );

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* );

Remarks

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

CSerialPort::TerminateOutstandingWrites

void TerminateOutstandingWrites()
    throw( 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* );

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* );

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* );

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* );

Remarks

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

CSerialPort::OnCompletion

virtual void OnCompletion(DWORD dwErrorCode, DWORD dwCount, LPOVERLAPPED lpOverlapped);
    throw( CSerialException* );

Parameters

dwErrorCode  

Specifies the I/O completion status. This parameter may be one of the following values:

dwCount Specifies the number of bytes transferred. If an error occurs, this parameter is zero

lpOverlapped Points to the OVERLAPPED structure specified by the asynchronous I/O function.

Remarks

This function is called as the completion routine for any asynchronous calls to WriteEx or ReadEx. In your derived class from CSerialPort, you can override this function to perform your own specific code in reaction to an asynchronous call completing. Don't forget to call the parent version namely this function "CSerialPort::OnCompletion" as it handles the cleanup of the memory allocated for the lpOverlapped parameter.

CSerialPort::BytesWaiting

DWORD BytesWaiting();
    throw( 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

CSerialPort::DataWaiting

BOOL DataWaiting(DWORD dwTimeout);
    throw( CSerialException* );

Parameters

dwTimeout Specifies The timeout to wait in milliseconds to determine if data has arrived.

Return Value

TRUE if data has arrived in the specified timeout interval, otherwise FALSE.

Remarks

The function waits for the specified interval to see if data has arrived on the serial port.

Planned Enhancements

• Provide a better sample app. At the moment, it's very much a test program which tests all of the functions.
• If you have any other suggested improvements, please let me know so that I can incorporate them into the next release.

Contacting the Author

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
25 January 2006