CSerialPort v1.03 - Serial Port Wrapper By PJ Naughter      下載 : http://www.codeproject.com/system/CSerialPort/CSerialPort_src.zip Introduction Welcome to CSerialPort, a freeware MFC class to wrap access to the Win32 APIs dealing with serial ports. Features Usage History API Reference Planned Enhancements Contacting the Author 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 callback usage models of the serial port. (Callback 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. To see the code in action have a look at the module "app.cpp" in the sample app. A brief example is as follows: try { CSerialPort port; port.Open(1, 1200, CSerialPort::NoParity, 8, CSerialPort::OneStopBit, CSerialPort::XonXoffFlowControl); char sBuf[] = "This should appear on the serial port"; port.Write(sBuf, strlen(sBuf)); port.Flush(); port.Close(); } catch (CSerialException* pEx) { TRACE(_T("Handle Exception, Message:%s\n"), pEx->GetErrorMessage()); pEx->Delete(); } History V1.0 (31st May 1999) Initial public release. V1.01 (3rd 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 (16th June 1999) Fixed a bug whereby CString::ReleaseBuffer was not being called in CSerialException::GetErrorMessage V1.03 (29th September 1999) Fixed a simple copy and paste bug in CSerialPort::SetDTR APIReference 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 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 ~CSerialPort(); Remarks Standard C destructor for the class. It will ensure that the comms port is closed if it is open. CSerialException::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 comms 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 comms port if already open. CSerialPort::Attach void Attach(HANDLE hComm); Parameters hComm The SDK handle of the open comms port. Remarks Allows you to attach a CSerialPort instance to an existing SDK comms port handle. This function is similar in behavior to the CWnd::Attach function provided in MFC. CSerialPort::Detach HANDLE Detach(); Return Value The SDK comms port HANDLE. Remarks Corollary function to Attach. This function is similar in behavior to the CWnd::Detach function provided in MFC. CSerialPort::operator HANDLE operator HANDLE(); Return Value The SDK comms port HANDLE. Remarks Use this operator to get the handle of the underlying comms port. You can use this handle to call the Windows APIs directly. CSerialPort::IsOpen BOOL IsOpen() const Return Value TRUE if the comms 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); 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. Remarks These 3 functions are wrappers for the SDK calls ReadFile and ReadFileEx. The 2nd version of Read is the overlapped version. CSerialPort::Write \ WriteEx DWORD Write(const void* lpBuf, DWORD dwCount); BOOL Write(const void* lpBuf, DWORD dwCount, OVERLAPPED& overlapped); 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. 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 Simple wrapper for the GetCommStatus SDK function call. 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) void WaitEvent(DWORD& dwMask, OVERLAPPED& overlapped) throw( CSerialException ); 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 signaled 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: Value Meaning 0 The I/O was successful. ERROR_HANDLE_EOF The ReadFileEx function tried to read past the end of the file. 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. 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 Please send any comments or bug reports to me via email. For any updates to this article, check my site here. 時間就是金錢 << 發問前請先找找舊文章 >> 發表人 - axsoft 於 2002/07/16 10:39:31