CSerialPort /CSerialPort2 v1.43 A set of C++ classes for Win32 serial ports

Welcome to CSerialPort / CSerialPort2, a set of freeware C++ classes to support access to the Win32 APIs dealing with serial ports.

Features

• Simple and clean C++ interface.
• The CSerialPort class uses C++ exceptions to indicate errors while CSerialPort2 exposes return values similiar to the Windows SDK API calls which it encapsulates.
• Unicode enabled and all code compiles cleanly at warning level 4 and is /analyze clean.
• Supports overlapped, blocking and call-back usage models of the serial port.

The enclosed zip file contains the CSerialPort source code and a simple test program which exercises all class API's.

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.

Updates

v1.43 (17 February 2022)

• Updated copyright details.
• Updated the code to use C++ uniform initialization for all variable declarations

v1.42 (12 April 2020)

• Updated copyright details.
• Fixed more Clang-Tidy static code analysis warnings in the code.

v1.41 (7 November 2019)

• Updated initialization of various structs to use C++ 11 list initialization

v1.40 (10 September 2019)

• Replaced enum with enum class throughout the code
• Fixed a number of compiler warnings when the code is compiled with VS 2019 Preview

v1.39 (21 April 2019)

• Updated the sample app to clean compile on VC 2019
• Removed the code path supported by the non defunct CSERIALPORT_MFC_EXTENSIONS define

v1.38 (29 January 2019)

• Updated copyright details.
• Fixed a bug in the two CSerialPort::Open methods where they were incorrectly defined as having a return value of BOOL instead of the correct return value of void. Thanks to Boris Usievich for reporting this bug.

v1.37 (21 December 2018)

• Fixed issues in CSerialPort2::Open where sometimes the function would return FALSE, but would leave the serial port in an open state. Thanks to "Guan" for reporting this issue.

v1.36 (16 September 2018)

• Fixed a number of compiler warnings when using VS 2017 15.8.4

v1.35 (1 July 2018)

• Updated copyright details.
• Fixed a number of C++ core guidelines compiler warnings. These changes mean that the code will now only compile on VC 2017 or later.

18 April 2018

• For those interested Sandi Wolfe has translated the CSerialPort / CSerialPort2 release notes into Russian, which is available at http://www.opensourceinitiative.net/edu/serialport.

v1.34 (17 December 2017)

• Replaced NULL throughout the codebase with nullptr. This means that the minimum requirement for the framework is now VC 2010.
• Updated the code to compile cleanly when _ATL_NO_AUTOMATIC_NAMESPACE is defined.
• Provided a CSerialPort::CancelIoEx method which encapsulates the CancelIoEx API. Thanks to Victor Derks for this suggestion.
• Fixed code in CSerialPort::GetDefaultConfig as it does not have a return value. Thanks to Victor Derks for reporting this bug.
• Fixed code in CSerialPort::SetDefaultConfig as it does not have a return value. Thanks to Victor Derks for reporting this bug.
• The sal header file is now included before the fallback SAL macros are defined in SerialPort.h. Thanks to Victor Derks for reporting this issue.
• Reworked the code to now be a header only implementation.
• Provided a new CSerialPort2 class which is a non exception based version of CSerialPort

• Provided methods in CSerialPort & CSerialPort2 which encapsulate the GetOverlappedResultEx API.
• Provided a new Open method in CSerialPort & CSerialPort2 which just opens the port without explicit configuration.
• Provided a new Open method in CSerialPort & CSerialPort2 which encapsulates the OpenCommPort API.

v1.33 (16 August 2017)

• Updated copyright details.
• Updated declarations of CSerialException::GetErrorMessage to be consistent with CException base class implementations
• Fixed up the SAL annotations on CSerialPort::GetConfig. Thanks to Wang Jinhai for reporting this issue.

v1.32 (22 May 2016)

• Updated copyright details.
• Fixed some typos in SerialPort.h, SerialPort.cpp and SerialPort.htm where CSERIALPORT_MFC_EXTENSTIONS was being used instead of CSERIALPORT_MFC_EXTENSIONS. Thanks to Nicholas Buse for reporting this issue.

v1.31 (17 December 2015)

• Verified the code compiles cleanly on VC 2015.

v1.30 (26 April 2015)

• Removed unnecessary inclusion of WinError.h
• Removed the CSerialPort::DataWaiting method as it depends on the port being open in overlapped mode. Instead client code can simply call CSerialPort::WaitEvent directly themselves. Removing this method also means that the CSerialPort::m_hEvent handle has not also been removed.
• The CSerialPort::WriteEx method has been reworked to expose all the parameters of the underlying WriteFileEx API. This rework also fixes a memory leak in WriteEx which can sometimes occur. This reworks also means that the CSerialPort::_OnCompletion and CSerialPort::_OnCompletion methods have been removed. Thanks to Yufeng Huang for reporting this issue.
• The CSerialPort::ReadEx method has been reworked to expose all the parameters of the underlying ReadFileEx API. This rework also fixes a memory leak in ReadEx which can sometimes occur. This reworks also means that the CSerialPort::_OnCompletion and CSerialPort::_OnCompletion methods have been removed. Thanks to Yufeng Huang for reporting this issue.

v1.29 (28 February 2015)

• Updated sample project settings to more modern default values.
• Updated copyright details.
• Reworked the CSerialPort and CSerialPortException classes to optionally compile without MFC. By default the classes now do not use MFC by default but if you define CSERIALPORT_MFC_EXTENSIONS the classes will revert back to the MFC behaviour.
• Remove logic to use GetProcAddress to access CancelIO functionality.
• Updated the code to clean compile on VC 2013
• Added SAL annotations to all the code
• Addition of a GetDefaultConfig method which takes a string
• Addition of a SetDefaultConfig method which takes a string

v1.28 (25 January 2013)

• Updated copyright details.
• Updated sample app and class to compile cleanly on VC 2010 and later.

v1.27 (4 July 2008)

• Provided a version of the Open method which takes a string instead of a numeric port number value. This allows the code to support some virtual serial port packages which do not use device names of the form "COM%d". Thanks to David Balazic for suggesting this addition.

v1.26 (21 June 2008)

• Code now compiles cleanly using Code Analysis (/analyze)
• Updated code to compile correctly using _ATL_CSTRING_EXPLICIT_CONSTRUCTORS define
• The code now only supports VC 2005 or later.
• CSerialPort::Read, Write, GetOverlappedResult & WaitEvent now throw an exception irrespective of whether the last error is ERROR_IO_PENDING or not
• Replaced all calls to ZeroMemory with memset

v1.25 (18 May 2008)

• Updated copyright details.
• Changed the actual values for Parity enum so that they are consistent with the Parity define values in the Windows SDK header file WinBase.h. This avoids the potential issue where you use the CSerialPort enum parity values in a call to the raw Win32 API calls. Thanks to Robert Krueger for reporting this issue.

v1.24 (30 December 2007)

• Updated the sample app to clean compile on VC 2008
• CSerialException::GetErrorMessage now uses Checked::tcsncpy_s if compiled using VC 2005 or later.

v1.23 (24 December 2007)

• CSerialException::GetErrorMessage now uses the FORMAT_MESSAGE_IGNORE_INSERTS flag. For more information please see Raymond Chen's blog at http://blogs.msdn.com/oldnewthing/archive/2007/11/28/6564257.aspx. Thanks to Alexey Kuznetsov for reporting this issue.
• Simplified the code in CSerialException::GetErrorMessage somewhat.
• Optimized the CSerialException constructor code.
• Code now uses newer C++ style casts instead of C style casts.
• Reviewed and updated all the TRACE logging in the module
• Replaced all calls to ZeroMemory with memset

v1.22 (25 January 2007)

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

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.

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

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

5 March 2003

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

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.

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/Multiple]Object. 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.13 (29 May 2002)

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

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.11 (23 April 2001)

• Fixed a memory leak in DataWaiting method.

V1.10 (4 April 2001)

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

V1.09 (24 March 2001)

• Added a BytesWaiting method

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 ASSERT's 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 0'ized overlapped structure (This is required when dealing with TAPI and serial communications)
• Now includes copyright message in the source code and documentation.

V1.07 (10 December 2000)

• Made class destructor virtual.

3 July 2000

• Minor update to the documentation.

V1.06 (12 June 2000)

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

V1.05 (8 May 2000)

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

V1.04 (8 March 2000)

• Links in the documentation now work <g>.

V1.03 (29 September 1999)

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

V1.02 (16 June 1999)

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

V1.01 (3 June 1999)

• Fixed problem with code using CancelIo function which does not exist on Windows 95. This caused any modules developed with CSerialPort to fail to load on Windows 95.
• Fixed leaks which can occur in sample app when an exception is thrown.

V1.0 (31 May 1999)

• Initial public release.