 |
General Reading »
Hardware & System »
Hardware programming
Intermediate
CSerialPort v1.03 - Serial Port WrapperBy PJ NaughterA freeware MFC class for Win32 serial ports. |
VC6, MFC, Dev
|
|
Advanced Search Add to IE Search |
|
|
|
||||||||||||||||
Welcome to CSerialPort, a freeware MFC class to wrap access to the Win32 APIs dealing with serial ports.
CSerialPort is more robust.
#include serialport.h in which ever of your modules needs to make calls to the class.
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(); }
CancelIo function which does not exist on 95.
CString::ReleaseBuffer was not being called in CSerialException::GetErrorMessage. CSerialPort::SetDTR. The API consists of the classes: CSerialException and CSerialPort. They have the following member functions and variables:
CSerialException( DWORD dwError = 0);
dwError - The error that caused the exception.
This member function is called when a CSerialException object is created. To throw a CSerialException, call the global function AfxThrowSerialException. If you call it using the default value for dwError, then internally it will call GetLastError for you.
virtual BOOL GetErrorMessage( LPTSTR lpszError,
UINT nMaxError, PUINT pnHelpContext = NULL );
CString GetErrorMessage();
CString representation of the error. 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. Call this member function to provide text about an error that has occurred.
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();
Standard C++ constructor for the class. Internally it just sets up the member variables to default values.
~CSerialPort();
Standard C++ destructor for the class. It will ensure that the comms port is closed if it is 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 );
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. 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.
Close();
The corollary function to Open. Just closes the comms port if already open.
void Attach(HANDLE hComm);
hComm - The SDK handle of the open comms port.
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.
HANDLE Detach();
The SDK comms port HANDLE.
Corollary function to Attach. This function is similar in behavior to the CWnd::Detach function provided in MFC.
operator HANDLE();
The SDK comms port HANDLE.
Use this operator to get the handle of the underlying comms port. You can use this handle to call the Windows APIs directly.
BOOL IsOpen() const
TRUE if the comms port is open, otherwise FALSE.
void Dump(CDumpContext& dc) const
Standard MFC diagnostic support function.
DWORD Read(void* lpBuf, DWORD dwCount); BOOL Read(void* lpBuf, DWORD dwCount, OVERLAPPED& overlapped); void ReadEx(void* lpBuf, DWORD dwCount); throw( CSerialException );
TRUE if the overlapped read completed synchronously, FALSE if the operation is to be completed asynchronously. 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. These 3 functions are wrappers for the SDK calls ReadFile and ReadFileEx. The 2nd version of Read is the overlapped version.
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 );
TRUE if the overlapped write completed synchronously, FALSE if the operation is to be completed asynchronously. 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. These 3 functions are wrappers for the SDK calls WriteFile and WriteFileEx. The 2nd version of Write is the overlapped version.
void TransmitChar(char cChar) const throw( CSerialException );
Simple wrapper for the TransmitCommChar SDK function call. See the Win32 SDK documentation for further details.
void GetOverlappedResult(OVERLAPPED& overlapped, DWORD& dwBytesTransferred, BOOL bWait) throw( CSerialException );
Simple wrapper for the GetOverlappedResult SDK function call. See the Win32 SDK documentation for further details.
void CancelIo() throw( CSerialException );
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.
void GetConfig(COMMCONFIG& config) throw( CSerialException );
Simple wrapper for the GetCommConfig SDK function call. See the Win32 SDK documentation for further details.
static void GetDefaultConfig(int nPort, COMMCONFIG& config) throw( CSerialException );
Simple wrapper for the GetDefaultCommConfig SDK function call. See the Win32 SDK documentation for further details.
void SetConfig(COMMCONFIG& config) throw( CSerialException );
Simple wrapper for the SetCommConfig SDK function call. See the Win32 SDK documentation for further details.
static void SetDefaultConfig(int nPort, COMMCONFIG& config) throw( CSerialException );
Simple wrapper for the SetDefaultCommConfig SDK function call. See the Win32 SDK documentation for further details.
void ClearBreak() throw( CSerialException );
Simple wrapper for the ClearCommBreak SDK function call. See the Win32 SDK documentation for further details.
void SetBreak() throw( CSerialException );
Simple wrapper for the SetCommBreak SDK function call. See the Win32 SDK documentation for further details.
void ClearError(DWORD& dwErrors) throw( CSerialException );
Simple wrapper for the ClearCommError SDK function call. See the Win32 SDK documentation for further details.
void GetStatus(COMMSTAT& stat) throw( CSerialException );
Simple wrapper for the GetCommStatus SDK function call. See the Win32 SDK documentation for further details.
void GetState(DCB& dcb) throw( CSerialException );
Simple wrapper for the GetCommState SDK function call. See the Win32 SDK documentation for further details.
void SetState(DCB& dcb) throw( CSerialException );
Simple wrapper for the SetCommState SDK function call. See the Win32 SDK documentation for further details.
void Escape(DWORD dwFunc) throw( CSerialException );
Simple wrapper for the EscapeCommFunction SDK function call. See the Win32 SDK documentation for further details.
void ClearDTR() throw( CSerialException );
Calls the Escape function using the constant CLRDTR which lowers the DTR line.
void ClearRTS() throw( CSerialException );
Calls the Escape function using the constant CLRRTS which lowers the RTS line.
void SetDTR() throw( CSerialException );
Calls the Escape function using the constant SETDTR which raises the DTR line.
void SetRTS() throw( CSerialException );
Calls the Escape function using the constant SETRTS which raises the RTS line.
void SetXOFF() throw( CSerialException );
Calls the Escape function using the constant SETXOFF which causes transmission to act as if an XOFF character has been received..
void SetXON() throw( CSerialException );
Calls the Escape function using the constant SETXON which causes transmission to act as if an XON character has been received..
void GetProperties(COMMPROP& properties) throw( CSerialException );
Simple wrapper for the GetCommProperties SDK function call. See the Win32 SDK documentation for further details.
void GetModemStatus(DWORD& dwModemStatus) throw( CSerialException );
Simple wrapper for the GetCommModemStatus SDK function call. See the Win32 SDK documentation for further details.
void SetTimeouts(COMMTIMEOUTS& timeouts) throw( CSerialException );
Simple wrapper for the SetCommTimeouts SDK function call. See the Win32 SDK documentation for further details.
void GetTimeouts(COMMTIMEOUTS& timeouts) throw( CSerialException );
Simple wrapper for the GetCommTimeouts SDK function call. See the Win32 SDK documentation for further details.
void Set0Timeout() throw( CSerialException );
Configures both send and receive timeouts to be 0. This causes 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.
void Set0WriteTimeout() throw( CSerialException );
Configures the send timeouts to be 0. This cause writes to return immediately.
void Set0ReadTimeout() throw( CSerialException );
Configure the receive timeout to be 0. This causes reads to return with whatever data is waiting in the receive buffer rather than wait for the specified amount of bytes to arrive.
void SetMask(DWORD dwMask) throw( CSerialException );
Simple wrapper for the SetCommMask SDK function call. See the Win32 SDK documentation for further details.
void GetMask(DWORD& dwMask) throw( CSerialException );
Simple wrapper for the GetCommMask SDK function call. See the Win32 SDK documentation for further details.
void WaitEvent(DWORD& dwMask) void WaitEvent(DWORD& dwMask, OVERLAPPED& overlapped) throw( CSerialException );
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.
void Flush() throw( CSerialException );
Simple wrapper for the FlushFileBuffers SDK function call. See the Win32 SDK documentation for further details.
void Purge(DWORD dwFlags) throw( CSerialException );
Simple wrapper for the PurgeComm SDK function call. See the Win32 SDK documentation for further details.
void TerminateOutstandingWrites() throw( CSerialException );
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.
void TerminateOutstandingReads() throw( CSerialException );
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.
void ClearWriteBuffer() throw( CSerialException );
Calls the Purge function using the constant PURGE_TXCLEAR which clears the output buffer (if the device driver has one)..
void ClearReadBuffer() throw( CSerialException );
Calls the Purge function using the constant PURGE_RXCLEAR which clears the input buffer (if the device driver has one)..
void Setup(DWORD dwInQueue, DWORD dwOutQueue) throw( CSerialException );
Simple wrapper for the SetupComm SDK function call. See the Win32 SDK documentation for further details.
virtual void OnCompletion(DWORD dwErrorCode, DWORD dwCount, LPOVERLAPPED lpOverlapped); throw( CSerialException );
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. 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 completion. 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.
Please send any comments or bug reports to me via email. For any updates to this article, check my site here.
General 
News 
Question 
Answer 
Joke 
Rant 
Admin
|
PermaLink |
Privacy |
Terms of Use
Last Updated: 3 Mar 2000 Editor: Smitha Vijayan |
Copyright 2000 by PJ Naughter Everything else Copyright © CodeProject, 1999-2009 Web13 | Advertise on the Code Project |
