windows串口通信函数API

windows串口通讯主要函数

先列个目录表

1.CreateFile - 打开串口；
2.SetupComm-初始化一个指定的通信设备的通信参数
3.ReadFile - 读数据；
4.WriteFile - 写数据；
5.CloseHandle - 关闭串口；
6.GetCommState - 取得串口当前状态；
7.SetCommState - 设置串口状态；
8.PurgeComm - 清除串口缓冲区 ；
9.ClearCommError - 清除串口错误或者读取串口现在的状态；
10.SetCommMask - 设置串口通信事件；
11.WaitCommEvent - 用来判断用SetCommMask()函数设置的串口通信事件是否已发生；

1. CreateFile - 打开串口；

HANDLE CreateFile(LPCTSTR lpFileName, 
					DWORD dwDesiredAccess, 
					DWORD dwShareMode, 
					LPSECURITY_ATTRIBUTES lpSecurityAttributes, 
					DWORD dwCreationDistribution, 
					DWORD dwFlagsAndAttributes, 
					HANDLE hTemplateFile); 

• lpFileName：要打开的文件名称。对串口通信来说就是COM1或COM2。
• dwDesiredAccess:读写模式设置。此处应该用GENERIC_READ及GENERIC_WRITE。
• dwShareMode：串口共享模式。此处不允许其他应用程序共享，应为0。
• lpSecurityAttributes：串口的安全属性，应为0，表示该串口不可被子程序继承。
• dwCreationDistribution：创建文件的性质，此处为OPEN_EXISTING.
• dwFlagsAndAttributes：属性及相关标志，这里使用异步方式应该用FILE_FLAG_OVERLAPPED。
• hTemplateFile:此处为0。

操作说明：若文件打开成功，串口即可使用了，该函数返回串口的句柄，以后对串口操作时
即可使用该句柄。

示例：
HANDLE hComm;
hComm = CreateFile(COM5,       //串口名称 
					GENERIC_READ | GENERIC_WRITE, //允许读和写   				 
					0,             //独占方式                               
					NULL,          // 无安全属性，不可被子程序继承                             
					OPEN_EXISTING, //创建文件的性质，打开而不是创建                     
					0,             // Non Overlapped I/O                           
					NULL);         // Null for Comm Devices

2.SetupComm-初始化一个指定的通信设备的通信参数。

原型：
BOOL SetupComm（HANDLE hFile，
				DWORD dwInQueue，
				DWORD dwOutQueue）;

hFile：串口句柄 ，CreateFile函数返回此句柄。
dwInQueue：指定推荐的大小，以 字节为单位，对设备的内部输入缓冲区。
dwOutQueue：指定推荐的大小，以字节为单位，对设备的内部输出缓冲区。
返回非零表示成功。零表示失败。 要获得更多错误信息，调用GetLastError函数

3. ReadFile - 读数据；

原型：
BOOL ReadFile(HANDLE hFile, 
	LPVOID lpBuffer, 
	DWORD nNumberOfBytesToRead, 
	lpNumberOfBytesRead, 
	lpOverlapped); 

-hFile：串口句柄
-lpBuffer：存储被读出数据的首地址
-nNumberOfBytesToRead：准备读出的字节个数
-NumberOfBytesRead：实际读出的字节个数
-lpOverlapped：异步I/O结构，

示例：
DWORD NoBytesRead;
BOOL bResult=ReadFile(hComm, //串口句柄 
						ucRxBuff, //输入缓冲区地址 
						len, //想读入的字符数 
						&NoBytesRead, //实际读出的字节数的变量指针 
						&NULL); //重叠结构指针 

4. WriteFile - 写数据；

原型：
BOOL WriteFile(HANDLE hFile, 
				LPCVOID lpBuffer, 
				DWORD nNumberOfBytesToWrite, 
				LPDWORD lpNumberOfBytesWritten, 
				LPOVERLAPPED lpOverlapped); 

参数说明：
-hFile：串口句柄
-lpBuffer：待写入数据的首地址
-nNumberOfBytesToWrite：待写入数据的字节数长度
-lpNumberOfBytesWritten：函数返回的实际写入串口的数据个数的地址，利用此变量可判断 实际写入的字节数和准备写入的字节数是否相同。
-lpOverlapped:重叠I/O结构的指针

示例：
DWORD  dNoOFBytestoWrite = strlen(data);
DWORD  dNoOfBytesWritten;
BOOL Status = WriteFile(com_port,
						data,
						dNoOFBytestoWrite,
						&dNoOfBytesWritten,
						NULL);

5. CloseHandle - 关闭串口；

原型：
BOOL CloseHandle(HANDLE hObjedt) 

-hObjedt：串口句柄

示例：
CloseHandle(hComm); 

6. GetCommState - 取得串口当前状态；

原型：
BOOL GetCommState(HANDLE hFile, 
					LPDCB lpDCB); 

-hFile：串口句柄
-lpDCB：设备控制块(Device Control Block)结构地址。此结构中含有和设备相关的
参数。此处是与串口相关的参数。由于参数非常多，当需要设置串口参数
时，通常是先取得串口的参数结构，修改部分参数后再将参数结构写入。
在此仅介绍少数的几个常用的参数：
DWORD BaudRate：串口波特率
DWORD fParity：为1的话激活奇偶校验检查
DWORD Parity：校验方式，值0~4分别对应无校验、奇校验、偶校验、校验
置位、校验清零
DWORD ByteSize：一个字节的数据位个数，范围是5~8
DWORD StopBits：停止位个数，0~2分别对应1位、1.5位、2位停止位

示例：
DCB dcbSerialParams = { 0 };
BOOL Status;
dcbSerialParams.DCBlength = sizeof(dcbSerialParams);
Status = GetCommState(com_port, &dcbSerialParams);

7. SetCommState - 设置串口状态；

原型：
BOOL SetCommState(HANDLE hFile, 
					LPDCB lpDCB); 

-hFile:串口句柄
-lpDCB：设备控制块(Device Control Block)结构地址。要更改的串口参数包含在此结构中。

示例：
Status = GetCommState(com_port, &dcbSerialParams);//取得当前串口状态
if (Status == FALSE)
	return FALSE;
dcbSerialParams.BaudRate = rate;//更波特率 
Status = SetCommState(com_port, &dcbSerialParams);//将更改后的参数写入串口

8. PurgeComm - 清除串口缓冲区 ；

原型：
BOOL PurgeComm(HANDLE hFile, 
				DWORD dwFlags ); 

-hFile:串口句柄
-dwFlags：指定串口执行的动作，由以下参数组成：
-PURGE_TXABORT:停止目前所有的传输工作立即返回不管是否完成传输动作。
-PURGE_RXABORT:停止目前所有的读取工作立即返回不管是否完成读取动作。
-PURGE_TXCLEAR:清除发送缓冲区的所有数据。
-PURGE_RXCLEAR:清除接收缓冲区的所有数据。

示例：
PurgeComm(hComm, PURGE_RXCLEAR|PURGE_TXCLEAR|PURGE_RXABORT|PURGE_TXABORT); 
清除串口的所有操作。 

9. ClearCommError - 清除串口错误或者读取串口现在的状态；

原型：
BOOL ClearCommError(HANDLE hFile, 
					LPDWORD lpErrors, 
					LPCOMATAT lpStat ); 

-hFile:串口句柄
-lpErrors：返回错误数值，错误常数如下：
1-CE_BREAK:检测到中断信号。意思是说检测到某个字节数据缺少合法的停止位。
2-CE_FRAME:硬件检测到帧错误。
3-CE_IOE:通信设备发生输入/输出错误。
4-CE_MODE:设置模式错误，或是hFile值错误。
5-CE_OVERRUN:溢出错误，缓冲区容量不足，数据将丢失。
6-CE_RXOVER:溢出错误。
7-CE_RXPARITY:硬件检查到校验位错误。
8-CE_TXFULL:发送缓冲区已满。
-lpStat:指向通信端口状态的结构变量，原型如下：
typedef struct _COMSTAT{
…
…
DWORD cbInQue; //输入缓冲区中的字节数
DWORD cbOutQue;//输出缓冲区中的字节数
}COMSTAT,*LPCOMSTAT;
该结构中对我们很重要的只有上面两个参数，其他的我们可以不用管。

示例：
COMSTAT ComStat; 
DWORD dwError=0; 
ClearCommError(hComm,&dwError,&ComStat); 
/*上式执行完后，ComStat.cbInQue就是串口中当前含有的数据字节个数，我们利用此 
数值就可以用ReadFile()函数去读串口中的数据了。*/

10. SetCommMask - 设置串口通信事件；

BOOL SetCommMask(HANDLE hFile, 
				DWORD dwEvtMask ); 

参数说明：
-hFile：串口句柄
-dwEvtMask：准备监视的串口事件掩码

注：在用api函数撰写串口通信函数时大体上有两种方法，一种是查寻法，另外一种是事件通知法。
这两种方法的区别在于收串口数据时，前一种方法是主动的周期性的查询串口中当前有没有
数据；后一种方法是事先设置好需要监视的串口通信事件，然后依靠单独开设的辅助线程进行
监视该事件是否已发生，如果没有发生的话该线程就一直不停的等待直到该事件发生后，将
该串口事件以消息的方式通知主窗体，然后主窗体收到该消息后依据不同的事件性质进行处理。
比如说当主窗体收到监视线程发来的RX_CHAR(串口中有数据)的消息后，就可以用ReadFile()
函数去读串口。该参数有如下信息掩码位值：
EV_BREAK:收到BREAK信号
EV_CTS:CTS(clear to send)线路发生变化
EV_DSR:DST(Data Set Ready)线路发生变化
EV_ERR:线路状态错误，包括了CE_FRAME/CE_OVERRUN/CE_RXPARITY 3钟错误。
EV_RING:检测到振铃信号。
EV_RLSD:CD(Carrier Detect)线路信号发生变化。
EV_RXCHAR:输入缓冲区中已收到数据。
EV_RXFLAG:使用SetCommState()函数设置的DCB结构中的等待字符已被传入输入缓冲区中。
EV_TXEMPTY:输出缓冲区中的数据已被完全送出。

示例：
SetCommMask(hComm,EV_RXCHAR|EV_TXEMPTY); 
//上面函数执行完毕后将监视串口中有无数据和发送缓冲区中的数据是否全部发送完毕。 

11. WaitCommEvent - 用来判断用SetCommMask()函数设置的串口通信事件是否已发生；

原型：
BOOL WaitCommEvent(HANDLE hFile, 
					LPDWORD lpEvtMask, 
					LPOVERLAPPED lpOverlapped ); 

-hFile：串口句柄
-lpEvtMask:发生的事件变量的地址。
-lpOverlapped：异步结构，用来保存异步操作结果。

示例：
BOOL Status = WaitCommEvent(com_port, &dwEvtMask, NULL);

以上是常用的API
还有其他的以后再说：
12. GetOverlappedResult；
13. WaitForSingleObject；
14. GetCommModemStatus；
15. EscapeCommFunction；
16. BuildCommDCB；
17. SetCommTimeouts 。