串口编程笔记：函数和结构体

串口编程中需要用到的函 数有：
CreateFile
GetCommState
SetCommState
SetupComm
SetCommTimeouts
ReadFile
WriteFile
CloseHandle
此外，需要用到的结构体有：
DCB结构体
COMMTIMEOUTS 结构体

1.  CreateFile函数
该函数用于创建、打开一个文件、通讯资源、磁盘设备或控制台。它返回一个能用于访问对象的句柄 （handle）。它也能打开和返回一个用于访问目录的句柄（handle）。

函数原型：

HANDLE CreateFile(
LPCTSTR lpFileName,
DWORD dwDesiredAccess,
DWORD dwShareMode,
LPSECURITY_ATTRIBUTES lpSecurityAttributes,
DWORD dwCreationDispostion ,
DWORD dwFlagsAndAttributes,
HANDLE hTemplateFile);
参数：
LPCTSTR lpFileName
指向一个对象（文件、通讯资源、磁盘设备、控制台或目录）名字的字符串。对于串口，若访问COM1，则参 数设置成：“COM1”或“////.//COM1”。

DWORD dwDesiredAccess
说 明对对象的访问类型，该参数可以是以下的组合：0、GENERIC_READ和GENERIC_WRITE。对于串口，通常设置成 GENERIC_READ | GENERIC_WRITE。

DWORD dwShareMode
说 明对象如何被共享，参数设置为0表示不共享。对于串口，该参数设置成0。LPSECURITY_ATTRIBUTES lpSecurityAttributes
该参数设置成NULL即可。

DWORD dwCreationDispostion
说明当访问文件存在或不存在时，将会产生什么。该参数必须是如下的某一个值：CREATE_NEW、CREATE_ALWAYS、 OPEN_EXISTING、OPEN_ALWAYS、TRUNCATE_EXISTING。对于串口，该参数设置成OPEN_EXISTING。

DWORD dwFlagsAndAttributes
说 明文件属性和文件的标识。对于串口，用于指定该串口是否进行异步操作，该值为FILE_FLAG_OVERLAPPED，表示使用异步的I/O；该值为 0，表示同步I/O操作。

HANDLE hTemplateFile
该 参数设置成NULL即可。

2.  GetCommState函数
该 函数用当前控制的一个指定通讯设备来填充一个设备控制块（一个DCB结构体）。
函数原型：

BOOL GetCommState(
HANDLE hFile,
LPDCB lpDCB);
参 数：
File
通讯设备的句柄（Handle）。CreateFile函数返回的 句柄。
lpDCB
指 向DCB结构体的指针，被用于存储控制设备的数据。
返 回值：
非零（Nonzero）表示成功，零（Zero）表示失败，调用GetLastError可获取错误信息。

 
3.  SetCommState函数
该 函数用于根据一个设备控制块（一个DCB结构体）中的规范说明来配置一个通讯设备。该函数重新初始化所有的硬件和控制设置，但是不会清空输入或输出队列。
函数原型：

BOOL SetCommState(
HANDLE hFile,
LPDCB lpDCB);
参 数：
File
通讯设备的句柄（Handle）。CreateFile函数返回的 句柄。
lpDCB
指 向DCB结构体的指针，该DCB结构体包含通讯设备的配置信息。
返 回值：
非零（Nonzero）表示成功，零（Zero）表示失败，调用GetLastError可获取错误信息。

 
4.  SetupComm函数
该 函数用于初始化一个指定通讯设备的通讯参数。
函 数原型：

BOOL SetupComm(
HANDLE hFile,
DWORD dwInQueue,
DWORD dwOutQueue);
参数：
hFile
通讯设备的句柄 （Handle）。CreateFile函数返回的句柄。
dwInQueue
说明设备的内部输入缓存所要求的大小，单位是字节。
dwOutQueue
说明设备的内部输出缓存所要求的大小，单位是字节。
返 回值：
非零（Nonzero）表示成功，零（Zero）表示失败，调用GetLastError可获取错误信息。

5.  SetCommTimeouts函数

该函数为基于一个指定的通讯设备上的所有读和写操作设置超时（time- out）参数。

函数原型：

BOOL SetCommTimeouts(
HANDLE hFile,
LPCOMMTIMEOUTS lpCommTimeouts);
参数：
hFile
通讯设备的句柄 （Handle）。CreateFile函数返回的句柄。
lpCommTimeouts
指向一个COMMTIMEOUTS结构体的指针，该结构体包含新的超时（time-out）值。
返回值：
非零（Nonzero）表示成功，零 （Zero）表示失败，调用GetLastError可获取错误信息。

6.  ReadFile函数
该函 数从一个文件读取数据，读操作从文件指针所指定的位置开始。读操作完成后，根据实际读取的字节数调整文件指针。
函数原型：

BOOL ReadFile(
HANDLE hFile,
LPVOID lpBuffer,
DWORD nNumberOfBytesToRead,
LPDWORD lpNumberOfBytesRead,
LPOVERLAPPED lpOverlapped);
参数：
hFile
被读文件的句柄 （Handle）。文件句柄必须被以GENERIC_READ访问模式创建。这个参数不能是一个socket句柄。
lpBuffer
指针，指向用于存储读取到的数据的 缓冲区。
nNumberOfBytesToRead
从文件读的字节数。
lpNumberOfBytesRead
指向读取到的字节数的指针。ReadFile在做任何操作前或出错时，会将读的字节数设置为0。
lpOverlapped
可设置为NULL。
返回值：
非零表示成功。零表示失败。可调用 GetLastError得到错误信息。
当如下情形中的一个为真时，ReadFile返回：当被请求读取的字节数已经读取时，或当一个错误出现 时。
如果函数返回值是非零且读取字节数是零，那么在读操作时文件指针越界了，指针超过了文件结尾处。

7.  WriteFile函数
该 函数写数据到一个文件。WriteFile从文件指针指定的位置开始写数据到文件。在写操作完成后，根据实际写入的字节数调整文件指针。
函数原型：

BOOL WriteFile(
HANDLE hFile,
LPCVOID lpBuffer,
DWORD nNumberOfBytesToWrite,
LPDWORD lpNumberOfBytesWritten,
LPOVERLAPPED lpOverlapped);
参数：
hFile
被写文件的句柄 （Handle）。文件句柄必须已经被以GENERIC_WRITE访问模式创建。
lpBuffer
指针，指向包含写入数据的缓冲区。
nNumberOfBytesToWrite
写入 到文件的字节数。
参数设置为0表示一个无效的写操作。一个无效的写操作不会写任何字节，但是会导致时间标记的改变。WriteFile函数不会截 短或扩展文件。如果想截短或扩展一个文件，需使用SetEndOfFile函数。
lpNumberOfBytesWritten
指向 调用这个函数所写入的字节数的指针。WriteFile在做任何操作前或出错时，会将写入的字节数设置为0。
lpOverlapped
可设置为NULL。
返回值：
非零表示成功。零表示失败。可调用 GetLastError得到错误信息。
当如下情形中的一个为真时，ReadFile返回：当被请求读的字节数已经读取时，或当一个错误出现时。
如 果函数返回值是非零且读取字节数是零，那么在读操作时文件指针越界了，指针超过了文件结尾处。

8.  CloseHandle函数
该 函数关闭一个打开的对象句柄（handle）。
函 数原型：

BOOL CloseHandle(
HANDLE hObject);
参数：
hObject
一个打开的对象的句柄（Handle）。
返 回值：
非零表示成功。零表示失败。可调用GetLastError得到错误信息。
备注：
该函数关闭以下对象的句 柄：Communications device、Database、Event、File、File-Mapping Object、Mutex、Process、Socket、Thread和Database enumeration context。 

9.  DCB结构体

可以用于配置串口，主要是用到DCB的以下成员：

DWORD BaudRate;     /* Baudrate at which running          */
BYTE ByteSize;         /* Number of bits/byte, 4-8           */
BYTE Parity;            /* 0-4=None,Odd,Even,Mark,Space  */
BYTE StopBits;         /* 0,1,2 = 1, 1.5, 2                       */
上述成员的含义：

DWORD BaudRate
波特率，如：
CBR_110、CBR_300、CBR_600、CBR_1200、 CBR_2400、CBR_4800、CBR_9600、CBR_14400、CBR_38400、CBR_56000、CBR_57600、 CBR_115200、CBR_128000、CBR_256000。
BYTE ByteSize
数据位，说明发送和接收字节中比特的个数。如：5、6、7、8。
BYTE Parity
奇偶校验， 如：NOPARITY（无校验）、ODDPARITY（奇校验）、EVENPARITY（偶校验）、MARKPARITY（标记）、 SPACEPARITY（空格）。
BYTE StopBits
停止位，如：ONESTOPBIT（1）、ONE5STOPBITS（1.5）、 TWOSTOPBITS（2）。

 

10.  COMMTIMEOUTS结构体
该 结构体在SetCommTimeouts和GetCommTimeouts函数中使用，分别被用于设定和查询基于一个通讯设备的超时参数。这个参数决定了 基于这个通讯设备的ReadFile和WriteFile函数操作的反应。
结构体原型：

typedef struct _COMMTIMEOUTS {
DWORD ReadIntervalTimeout;
DWORD ReadTotalTimeoutMultiplier;
DWORD ReadTotalTimeoutConstant;
DWORD WriteTotalTimeoutMultiplier;
DWORD WriteTotalTimeoutConstant;
} COMMTIMEOUTS,*LPCOMMTIMEOUTS;
参数：
ReadIntervalTimeout
说 明通讯中两个字符在先后到达时刻之间的最大可接受间隔时间，单位是毫秒。在ReadFile操作中，当第一个字符被接收时开始计时，如果第二字符到达时的 间隔时间超过这个最大可接受时间，那么ReadFile操作完成，并返回缓冲区的数据。该参数设置成0表示这个间隔超时无效。
ReadTotalTimeoutMultiplier
说 明乘数，单位是毫秒，用于计算读（read）操作总的超时时间。对于每个读（read）操作，该参数乘以被请求读的字节个数。
ReadTotalTimeoutConstant
说 明常数，单位是毫秒，用于计算读（read）操作总的超时时间。对于每个读（read）操作，这个参数被加到 ReadTotalTimeoutMultiplier与被请求的字节数的乘积上。

ReadTotalTimeoutMultiplier和 ReadTotalTimeoutConstant参数都设置为0时，表示总超时时间对于读操作无效。
WriteTotalTimeoutMultiplier
说 明乘数，单位是毫秒，用于计算写（write）操作总的超时时间。对于每个写（write）操作，该参数乘以写的字节数。
WriteTotalTimeoutConstant
说 明常数，单位是毫秒，用于计算写（write）操作总的超时时间。对于每个写（write）操作，这个参数被加到 WriteTotalTimeoutMultiplier与写的字节数的乘积上。

WriteTotalTimeoutMultiplier和 WriteTotalTimeoutConstant参数都设置为0时，表示总的超时间对于写操作无效。
备注：
如 果程序中设置ReadIntervalTimeout和ReadTotalTimeoutMultiplier为MAXDWORD，并且设置 ReadTotalTimeoutConstant为一个在0和MAXDWORD之间的数，那么当ReadFile函数被调用时，会发生以下情形：

如果输入缓冲区中有字符，那么ReadFile立即返回缓冲区中的字符。
如 果输入缓冲区中没有字符，那么ReadFile将等待直到有字符到达，然后立即返回缓冲区中的字符。
如果在 ReadTotalTimeoutConstant指定的时间内没任何字符到达，那么ReadFile超时。

DWORD fParity; // 指定奇偶校验使能。若此成员为1，允许奇偶校验检查