多线程串口编程工具CSerialPort v1.pdf

《多线程串口编程工具CSerialPort v1.pdf》由会员分享，可在线阅读，更多相关《多线程串口编程工具CSerialPort v1.pdf（18页珍藏版）》请在淘文阁 - 分享文档赚钱的网站上搜索。

1、CSerialPort v1.22Welcome to CSerialPort,a freeware MFC class to wrap access to the Win32 APIs dealing with serialports.FeaturesUsageCopyrightHistoryAPI ReferencePlanned EnhancementsContacting the Author FeaturesSimple and clean C+interface.Uses C+exceptions in preference to the normal win32 return v

2、alue mechanism.This ensures thatcode 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 onlysupported on NT).UsageTo use the

3、 class in your code simply include serialport.cpp in your project and#include serialport.h inwhich 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 usingVisual C+6(February 2003 was the last version wh

4、ich was compatible with VC 6).To see the code in action have a look at the module app.cpp in the sample app.CopyrightYou are allowed to include the source code in any product(commercial,shareware,freeware orotherwise)when your product is released in binary form.You are allowed to modify the source c

5、ode in any way you want except you cannot modify thecopyright details at the top of each module.If you want to distribute source code with your application,then you are only allowed to distributeversions released by the author.This is to maintain a single distribution point for the source code.2011-

6、3-14CSerialPort v1.22C:/SerialPort.htm1/18 HistoryV1.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 thrownV1.02(16 June 1999)Fixed a bug whereby CString:R

7、eleaseBuffer was not being called inCSerialException:GetErrorMessageV1.03(29 September 1999)Fixed a simple copy and paste bug in CSerialPort:SetDTRV1.04(8 March 2000)Links in the documentation now work.V1.05(8 May 2000)Fixed an unreferenced variable in CSerialPort:GetOverlappedResult in VC 6V1.06(12

8、 June 2000)Fixed another unreferenced variable problem in CSerialPortApp:InitInstance in VC 6.3 July 2000Minor 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

9、 to inoverlapped modeRemoved some ASSERTs which were unnecessary in some of the functionsUpdated the Read method which uses OVERLAPPED IO to also return the bytes read.This allows callsto WriteFile with a zeroed overlapped structure(This is required when dealing with TAPI and serialcommunications)No

10、w includes copyright message in the source code and documentation.V1.09(24 March 2001)Added a BytesWaiting methodV1.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

11、in Open method which was failing to initialize the DCB structure incorrectly,whencalling GetState.Thanks to Ben Newson for this fix.V1.13(29 May 2002)2011-3-14CSerialPort v1.22C:/SerialPort.htm2/18Fixed an problem where the GetProcAddress for CancelIO was using the wrong calling convention.V1.14(7 A

12、ugust 2002)Changed the declaration of CSerialPort:WaitEvent to be consistent with the rest of the methods inCSerialPort which can operate in OVERLAPPED mode.A note about the usage of this:If the methodsucceeds then the overlapped operation has completed synchronously and there is no need to do aWait

13、ForSingle/MultipleObjects.If any other unexpected error occurs then a CSerialException will bethrown.See the implementation of the CSerialPort:DataWaiting which has been rewritten to use thisnew design pattern.Thanks to Serhiy Pavlov for spotting this inconsistency.V1.15(20 September 2002)Addition o

14、f 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 2003Updated the documentation for the function CSerialPort:GetStatus.v1.16(10 April 2006)Updat

15、ed copyright details.Addition of a CSERIALPORT_EXT_CLASS and CSERIALPORT_EXT_API macros which makes the classeasier 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 me

16、thods 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 forreporting this issue.Fixed a minor issue in

17、 the sample app when the code is compiled using/Wp64v1.17(2 June 2006)Removed the bOverlapped as a member variable from the class.There was no real need for thissetting,since the SDK functions will perform their own checking of how overlapped operations shouldFixed a bug in GetOverlappedResult where

18、 the code incorrectly checking against the errorERROR_IO_PENDING instead of ERROR_IO_INCOMPLETE.Thanks to Sasho Darmonski for reportingthis 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 creat

19、ed as anauto-reset event object instead of a manual reset event object.Thanks to Sasho Darmonski forreporting 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 mem

20、ber variable ofCSerialPortMade AfxThrowSerialPortException part of the CSerialPort class.Thanks to Simon Wong for reportingthis.Removed the unnecessary CSerialException destructor.Thanks to Simon Wong for reporting this.Fixed a minor error in the TRACE text in CSerialPort:SetDefaultConfig.Again than

21、ks to Simon Wongfor reporting this.Code now uses new C+style casts rather than old style C casts where necessary.Again thanks toSimon Wong for reporting this.2011-3-14CSerialPort v1.22C:/SerialPort.htm3/18CSerialException:GetErrorMessage now uses the strsafe functions.This does mean that the codenow

22、 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 sa

23、mple 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 andif 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

24、 copyright details.API ReferenceThe API consists of the classes:CSerialException and the CSerialPort class.They have the followingmember functions and variables:CSerialException:CSerialExceptionCSerialException:GetErrorMessageCSerialException:m_dwErrorCSerialPort:CSerialPortCSerialPort:CSerialPortCS

25、erialPort:OpenCSerialPort:CloseCSerialPort:AttachCSerialPort:DetachCSerialPort:operator HANDLECSerialPort:IsOpenCSerialPort:DumpCSerialPort:ReadCSerialPort:ReadExCSerialPort:WriteCSerialPort:WriteExCSerialPort:TransmitCharCSerialPort:GetOverlappedResultCSerialPort:CancelIoCSerialPort:GetConfigCSeria

26、lPort:GetDefaultConfigCSerialPort:SetConfigCSerialPort:SetDefaultConfigCSerialPort:ClearBreakCSerialPort:SetBreakCSerialPort:ClearErrorCSerialPort:GetStatusCSerialPort:GetStateCSerialPort:SetStateCSerialPort:Escape2011-3-14CSerialPort v1.22C:/SerialPort.htm4/18CSerialPort:ClearDTRCSerialPort:ClearRT

27、SCSerialPort:SetDTRCSerialPort:SetRTSCSerialPort:SetXOFFCSerialPort:SetXONCSerialPort:GetPropertiesCSerialPort:GetModemStatusCSerialPort:SetTimeoutsCSerialPort:GetTimeoutsCSerialPort:Set0TimeoutCSerialPort:Set0WriteTimeoutCSerialPort:Set0ReadTimeoutCSerialPort:SetMaskCSerialPort:GetMaskCSerialPort:W

28、aitEventCSerialPort:FlushCSerialPort:PurgeCSerialPort:TerminateOutstandingWritesCSerialPort:TerminateOutstandingReadsCSerialPort:ClearWriteBufferCSerialPort:ClearReadBufferCSerialPort:SetupCSerialPort:OnCompletionCSerialPort:BytesWaitingCSerialPort:DataWaiting CSerialException:CSerialExceptionCSeria

29、lException(DWORD dwError=0);ParametersdwError The error that caused the exception.RemarksThis 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,thenintern

30、ally it will call GetLastError for you.CSerialException:GetErrorMessagevirtual BOOL GetErrorMessage(LPTSTR lpszError,UINT nMaxError,PUINT pnHelpContext=NULL);CString GetErrorMessage();Return Value1)Nonzero if the function is successful;otherwise 0 if no error message text is available.2)A CString re

31、presentation of the errorParameterslpszError A pointer to a buffer that will receive an error message.2011-3-14CSerialPort v1.22C:/SerialPort.htm5/18nMaxError The maximum number of characters the buffer can hold,including the NULL terminator.pnHelpContext The address of a UINT that will receive the

32、help context ID.If NULL,no ID will bereturned.RemarksCall this member function to provide text about an error that has occurred.CSerialException:m_dwErrorRemarksThe 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 Erro

33、r Codes in the Win32 SDK.CSerialPort:CSerialPortCSerialPort();RemarksStandard C+constructor for the class.Internally it just sets up the member variables to defaultvalues.CSerialPort:CSerialPortvirtual CSerialPort();RemarksStandard C+destructor for the class.It will ensure that the comm port is clos

34、ed if it is open.CSerialPort:Openvoid Open(int nPort,DWORD dwBaud=9600,Parity parity=NoParity,BYTE DataBits=8,StopBitsstopbits=OneStopBit,FlowControl fc=NoFlowControl,BOOL bOverlapped=FALSE);throw(CSerialException*);ParametersnPort The communications port to open.dwBaud The baud rate to useparity Th

35、e parity to use.parity is an enum with the following values:enum Parity EvenParity,MarkParity,NoParity,OddParity,SpaceParity2011-3-14CSerialPort v1.22C:/SerialPort.htm6/18;Databits The number of data bits to usestopbits The number of stop bits to use.stopbits is an enum with the following values:enu

36、m StopBitsOneStopBit,OnePointFiveStopBits,TwoStopBits;fc The flow control method to use.fc is an enum with the following values:enum FlowControlNoFlowControl,CtsRtsFlowControl,CtsDtrFlowControl,DsrRtsFlowControl,DsrDtrFlowControl,XonXoffFlowControl;bOverlapped TRUE if you want to open in overlapped

37、mode,otherwise FALSE to use blocking calls.RemarksCall this member function to open a communications port.Internally the class will use CreateFile to openthe comm port(handling the case where the port number if greater than 9)and then uses SetState toset the various RS-232 settings as specified via

38、the function parameters.If an error occurs,aCSerialException will be thrown.CSerialPort:CloseClose();RemarksThe corollary function to Open.Just closes the comm port if already open.CSerialPort:Attachvoid Attach(HANDLE hComm);ParametershComm The SDK handle of the open comm port.RemarksAllows you to a

39、ttach a CSerialPort instance to an existing SDK comm port handle.This function is similarin behaviour to the CWnd:Attach function provided in MFC.CSerialPort:Detach2011-3-14CSerialPort v1.22C:/SerialPort.htm7/18HANDLE Detach();Return ValueThe SDK comm port HANDLE.RemarksCorollary function to Attach.

40、This function is similar in behaviour to the CWnd:Detach function providedin MFC.CSerialPort:operator HANDLEoperator HANDLE();Return ValueThe SDK comm port HANDLE.RemarksUse this operator to get the handle of the underlying comm port.You can use this handle to call theWindows APIs directly.CSerialPo

41、rt:IsOpenBOOL IsOpen()constReturn ValueTRUE if the comm port is open otherwise FALSE CSerialPort:Dumpvoid Dump(CDumpContext&dc)constRemarksStandard MFC diagnostic support function CSerialPort:Read ReadExDWORD Read(void*lpBuf,DWORD dwCount);BOOL Read(void*lpBuf,DWORD dwCount,OVERLAPPED&overlapped,DWO

42、RD*pBytesRead=NULL);void ReadEx(void*lpBuf,DWORD dwCount);throw(CSerialException*);Return Value1)The number of bytes read.2)TRUE if the overlapped read completely synchronously,FALSE if the operation is to be completedasynchronously.2011-3-14CSerialPort v1.22C:/SerialPort.htm8/18ParameterslpBuf Poin

43、ts to the buffer to read the data into from the serial portdwCount 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 overlappedmode.pBytesRead If the value is non-null then upon return it will contain

44、 the number of bytes readRemarksThese 3 functions are wrappers for the SDK calls ReadFile and ReadFileEx.The 2nd version of Read isthe overlapped version.Also please note that depending on the way you have configured timeouts,thisfunction may appear to block while it waits to receive the specified d

45、ata.To configure timeouts,pleasecheck out the Set*Timeout(s)functions.CSerialPort:Write WriteExDWORD 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*);R

46、eturn Value1)The number of bytes written.2)TRUE if the overlapped write completely synchronously,FALSE if the operation is to be completedasynchronously.ParameterslpBuf Points to the buffer containing the data to be written to the serial portdwCount Specifies the number of bytes to write to the seri

47、al port.overlapped reference to an OVERLAPPED structure.This is required if the port was opened in overlappedmode.pBytesWritten If the value is non-null then upon return it will contain the number of bytes writtenRemarksThese 3 functions are wrappers for the SDK calls WriteFile and WriteFileEx.The 2

48、nd version of Write isthe overlapped version.CSerialPort:TransmitCharvoid TransmitChar(char cChar)const throw(CSerialException*);RemarksSimple wrapper for the TransmitCommChar SDK function call.See the Win32 SDK documentation forfurther details.2011-3-14CSerialPort v1.22C:/SerialPort.htm9/18 CSerial

49、Port:GetOverlappedResultvoid GetOverlappedResult(OVERLAPPED&overlapped,DWORD&dwBytesTransferred,BOOL bWait)throw(CSerialException*);RemarksSimple wrapper for the GetOverlappedResult SDK function call.See the Win32 SDK documentation forfurther details.CSerialPort:CancelIovoid CancelIo()throw(CSerialE

50、xception*);RemarksSimple 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 ofCSerialPort,this would cause code developed with it to fail to load on Windows 95 w