串口编程常用的API

CloseHandle

BOOL CloseHandle(

　　HANDLE hObject

　　);

　　参数

　　hObject ：代表一个已打开对象handle。

　　返回值

　　TRUE：执行成功；

FALSE：执行失败，可以调用GetLastError()获知失败原因。

函数说明：

关闭一个内核对象。其中包括文件、文件映射、进程、线程、安全和同步对象等。在CreateThread成功之后会返回一个hThread的handle，且内核对象的计数加1，CloseHandle之后，引用计数减1，当变为0时，系统删除内核对象。

若在线程执行完之后，没有调用CloseHandle，在进程执行期间，将会造成内核对象的泄露，相当于句柄泄露，但不同于内存泄露，这势必会对系统的效率带来一定程度上的负面影响。但当进程结束退出后，系统会自动清理这些资源。

 

CreateFile

HANDLE CreateFile(

　　HANDLE lpFileName, //指向文件名的指针

　　DWORD dwDesiredAccess, //访问模式（写/读）

　　DWORD dwShareMode, //共享模式

　　LPSECURITY_ATTRIBUTES lpSecurityAttributes, //指向安全属性的指针

　　DWORD dwCreationDisposition, //如何创建

　　DWORD dwFlagsAndAttributes, //文件属性

　　HANDLE hTemplateFile //用于复制文件句柄

);

参数说明

lpFileName String 要打开的文件的名字

　　dwDesiredAccess Long 如果为 GENERIC_READ 表示允许对设备进行读访问；如果为 GENERIC_WRITE 表示允许对设备进行写访问（可组合使用）；如果为零，表示只允许获取与一个设备有关的信息

　　dwShareMode Long， 零表示不共享； FILE_SHARE_READ 和/或 FILE_SHARE_WRITE 表示允许对文件进行共享访问

　　lpSecurityAttributes SECURITY_ATTRIBUTES， 指向一个SECURITY_ATTRIBUTES结构的指针，定义了文件的安全特性（如果操作系统支持的话）

　　dwCreationDisposition Long，下述常数之一：

　　CREATE_NEW 创建文件；如文件存在则会出错

　　CREATE_ALWAYS 创建文件，会改写前一个文件

　　OPEN_EXISTING 文件必须已经存在。由设备提出要求

　　OPEN_ALWAYS 如文件不存在则创建它

　　TRUNCATE_EXISTING 讲现有文件缩短为零长度

　　dwFlagsAndAttributes Long， 一个或多个下述常数

　　FILE_ATTRIBUTE_ARCHIVE 标记归档属性

　　FILE_ATTRIBUTE_COMPRESSED 将文件标记为已压缩，或者标记为文件在目录中的默认压缩方式

　　FILE_ATTRIBUTE_NORMAL 默认属性

　　FILE_ATTRIBUTE_HIDDEN 隐藏文件或目录

　　FILE_ATTRIBUTE_READONLY 文件为只读

　　FILE_ATTRIBUTE_SYSTEM 文件为系统文件

　　FILE_FLAG_WRITE_THROUGH 操作系统不得推迟对文件的写操作

　　FILE_FLAG_OVERLAPPED 允许对文件进行重叠操作

　　FILE_FLAG_NO_BUFFERING 禁止对文件进行缓冲处理。文件只能写入磁盘卷的扇区块

　　FILE_FLAG_RANDOM_ACCESS 针对随机访问对文件缓冲进行优化

　　FILE_FLAG_SEQUENTIAL_SCAN 针对连续访问对文件缓冲进行优化

　　FILE_FLAG_DELETE_ON_CLOSE 关闭了上一次打开的句柄后，将文件删除。特别适合临时文件

　　也可在Windows NT下组合使用下述常数标记：

　　SECURITY_ANONYMOUS， SECURITY_IDENTIFICATION， SECURITY_IMPERSONATION， SECURITY_DELEGATION， SECURITY_CONTEXT_TRACKING， SECURITY_EFFECTIVE_ONLY

hTemplateFile Long， 如果不为零，则指定一个文件句柄。新文件将从这个文件中复制扩展属性

返回值

如执行成功，则返回文件句柄。

INVALID_HANDLE_VALUE表示出错，会设置GetLastError。即使函数成功，但若文件存在，且指定了CREATE_ALWAYS 或 OPEN_ALWAYS，GetLastError也会设为ERROR_ALREADY_EXISTS

FlushFileBuffers

LONG FlushFileBuffers(

         HANDLE lpFileName

);

说明

针对指定的文件句柄，刷新内部文件缓冲区

返回值

Long，非零表示成功，零表示失败。会设置GetLastError

GetCommState

BOOL GetCommState(

  HANDLE hFile, //标识通讯端口的句柄

  LPDCB lpDCB //指向一个设备控制块（DCB结构）的指针

);

在打开通讯设备句柄后，常常需要对串口进行一些初始化配置工作。这需要通过一个DCB结构来进行。DCB结构包含了诸如波特率、数据位数、奇偶校验和停止位数等信息。在查询或配置串口的属性时，都要用DCB结构来作为缓冲区。
　　一般用CreateFile打开串口后，可以调用GetCommState函数来获取串口的初始配置。要修改串口的配置，应该先修改DCB结构，然后再调用SetCommState函数设置串口。
　　DCB结构包含了串口的各项参数设置，下面仅介绍几个该结构常用的变量：

typedef struct _DCB{
   ………
   //波特率，指定通信设备的传输速率。这个成员可以是实际波特率值或者下面的常量值之一：
   DWORD BaudRate;
CBR_110，CBR_300，CBR_600，CBR_1200，CBR_2400，CBR_4800，CBR_9600，CBR_19200， CBR_38400，
CBR_56000， CBR_57600， CBR_115200， CBR_128000， CBR_256000， CBR_14400

DWORD fParity; // 指定奇偶校验使能。若此成员为1，允许奇偶校验检查
   …
BYTE ByteSize; // 通信字节位数，4—8
BYTE Parity; //指定奇偶校验方法。此成员可以有下列值：
EVENPARITY 偶校验     NOPARITY 无校验
MARKPARITY 标记校验   ODDPARITY 奇校验
BYTE StopBits; //指定停止位的位数。此成员可以有下列值：
ONESTOPBIT 1位停止位   TWOSTOPBITS 2位停止位
ONE5STOPBITS   1.5位停止位
   ………
  } DCB;
winbase.h文件中定义了以上用到的常量。如下：
#define NOPARITY            0
#define ODDPARITY           1
#define EVENPARITY          2
#define ONESTOPBIT          0
#define ONE5STOPBITS        1
#define TWOSTOPBITS         2
#define CBR_110             110
#define CBR_300             300
#define CBR_600             600
#define CBR_1200            1200
#define CBR_2400            2400
#define CBR_4800            4800
#define CBR_9600            9600
#define CBR_14400           14400
#define CBR_19200           19200
#define CBR_38400           38400
#define CBR_56000           56000
#define CBR_57600           57600
#define CBR_115200          115200
#define CBR_128000          128000
#define CBR_256000          256000

GetCommTimeouts

BOOL GetCommTimeouts(

HANDLE hFile,

COMMTIMEOUTS lpCommTimeouts

);

查询当前的超时设置

该函数会填充一个COMMTIMEOUTS结构，结构定义如下

typedef struct _COMMTIMEOUTS {

　　DWORD ReadIntervalTimeout; // 读间隔超时

　　DWORD ReadTotalTimeoutMultiplier; // 读时间系数

　　DWORD ReadTotalTimeoutConstant; // 读时间常量

　　DWORD WriteTotalTimeoutMultiplier; // 写时间系数

　　DWORD WriteTotalTimeoutConstant; // 写时间常量

　　} COMMTIMEOUTS,*LPCOMMTIMEOUTS;

COMMTIMEOUTS结构的成员都以毫秒为单位。

GetLastError

LONG GetLastError();

针对之前调用的api函数，用这个函数取得扩展错误信息

返回值Long，由api函数决定

ERROR_INVALID_HANDLE 无效的句柄作为一个参数传递

　　ERROR_CALL_NOT_IMPLEMENTED 在win 95下调用专为win nt设计的win32 api函数

ERROR_INVALID_PARAMETER 函数中有个参数不正确

PurgeComm

BOOL PurgeComm(

HANDLE hFile, //串口句柄

DWORD dwFlags // 需要完成的操作

);

参数dwFlags指定要完成的操作，可以是下列值的组合：

　　PURGE_TXABORT 终止所有正在进行的字符输出操作,完成一个正处于等待状态的重叠i/o操作,他将产生一个事件,指明完成了写操作

　　PURGE_RXABORT 终止所有正在进行的字符输入操作,完成一个正在进行中的重叠i/o操作,并带有已设置得适当事件

　　PURGE_TXCLEAR 这个命令指导设备驱动程序清除输出缓冲区，经常与PURGE_TXABORT 命令标志一起使用

PURGE_RXCLEAR 这个命令用于设备驱动程序清除输入缓冲区，经常与PURGE_RXABORT 命令标志一起使用

ReadFile

BOOL ReadFile(

　　HANDLE hFile, //文件的句柄

　　LPVOID lpBuffer, //用于保存读入数据的一个缓冲区

　　DWORD nNumberOfBytesToRead, //要读入的字符数

　　LPDWORD lpNumberOfBytesRead, //指向实际读取字节数的指针

　　LPOVERLAPPED lpOverlapped //如文件打开时指定了FILE_FLAG_OVERLAPPED，那么必须，用这个参数引用一个特殊的结构。该结构定义了一次异步读取操作。否则，应将这个参数设为NULL

);

从文件指针指向的位置开始将数据读出到一个文件中, 且支持同步和异步操作,

　　如果文件打开方式没有指明FILE_FLAG_OVERLAPPED的话,当程序调用成功时,它将实际读出文件的字节数保存到lpNumberOfBytesRead指明的地址空间中。

　　如果文件要交互使用的话,当函数调用完毕时要记得调整文件指针。

从文件中读出数据。与lread函数相比，这个函数要明显灵活的多。该函数能够操作通信设备、管道、套接字以及邮槽。

参数

HANDLE hFile, 需要写入数据的文件指针,这个指针指向的文件必须是GENERIC_READaccess 访问属性的文件。

LPOVERLAPPED lpOverlapped OVERLAPPED结构体指针,如果文件是以FILE_FLAG_OVERLAPPED方式打开的话,那么这个指针就不能为NULL。

返回值

调用成功,返回非0

　　调用不成功,返回为0

会设置GetLastError。如启动的是一次异步读操作，则函数会返回零值，并将ERROR_IO_PENDING设置成GetLastError的结果。如结果不是零值，但读入的字节数小于nNumberOfBytesToRead参数指定的值，表明早已抵达了文件的结尾。

SetCommState

BOOL SetCommState(

HANDLE hFile,

DCB lpDCB

);

要修改串口的配置，应该先修改DCB结构，在修改串口配置，参数参照GetCommState

SetCommTimeouts

BOOL  SetCommTimeouts(

HANDLE  hFile,

COMMTIMEOUTS lpCommTimeouts

);

手动设置超时时间，单位为毫秒，参数参照GetCommTimeouts

WriteFile

BOOL WriteFile(

　　HANDLE hFile, // 文件句柄

　　LPCVOID lpBuffer, // 数据缓存区指针

　　DWORD nNumberOfBytesToWrite, // 你要写的字节数

　　LPDWORD lpNumberOfBytesWritten, // 用于保存实际写入字节数的存储区域的指针

　　LPOVERLAPPED lpOverlapped // OVERLAPPED结构体指针

);

从文件指针指向的位置开始将数据写入到一个文件中, 且支持同步和异步操作,

　　如果文件打开方式没有指明FILE_FLAG_OVERLAPPED的话,当程序调用成功时,它将实际写入文件的字节数保存到lpNumberOfBytesWriten指明的地址空间中

如果文件要交互使用的话,当函数调用完毕时要记得调整文件指针

HANDLE hFile, 需要写入数据的文件指针,这个指针指向的文件必须是GENERIC_WRITE access 访问属性的文件

LPOVERLAPPED lpOverlapped OVERLAPPED结构体指针,如果文件是以FILE_FLAG_OVERLAPPED方式打开的话,那么这个指针就不能为NULL

OVERLAPPED结构类型声明如下：

　　typedef struct _OVERLAPPED{

　　DWORD Internal;//操作系统保留，指出一个和系统相关的状态

　　DWORD InternalHigh;//指出发送或接收的数据长度

　　DWORD Offset;//文件传送的开始位置

　　DWORD OffsetHigh;//文件传送的字节偏移量的高位字

　　HANDLE hEvent;//指定一个I/O操作完成后触发的事件

}OVERLAPPED;

OVERLAPPED主要是设置异步I/O操作，异步I/O操作是指应用程序可以在后台读或者写数据，而在前台做其他事情。

DBC

typedef struct _DCB {// dcb

　　DWORD DCBlength; // sizeof(DCB)

　　DORD BaudRate; // current baud rate　指定当前的波特率

　　DWORD fBinary: 1; // binary mode, no EOF check　指定是否允许二进制模式WIN95中须为TRUE

　　DWORD fParity: 1; // enable parity checking　指定奇偶校验是否允许

　　DWORD fOutxCtsFlow:1; // CTS output flow control 指定CTS是否用于检测发送控制。当为TRUE时CTS为

　　// OFF，发送将被挂起。（发送清除）

　　DWORD fOutxDsrFlow:1; // DSR output flow control 指定CTS是否用于检测发送控制。

　　//（数据装备好） 当为TRUE是CTS为OFF，发送将被挂起。

　　DWORD fDtrControl:2; // DTR flow control type

　　//DTR_CONTROL_DISABLE值将DTR置为OFF, //DTR_CONTROL_ENABLE值将DTR置为ON, DTR_CONTROL_HANDSHAKE 允许DTR"握手",

　　DWORD fDsrSensitivity:1;

　　// DSR sensitivity 当该值为TRUE时DSR为OFF时接收的字节被忽略

　　DWORD fTXContinueOnXoff:1; // XOFF continues Tx

　　指定当接收缓冲区已满,并且驱动程序已经发送出XoffChar字符时发送是否停止。

　　TRUE时，在接收缓冲区接收到缓冲区已满的字节XoffLim且驱动程序已经发送出XoffChar字 符中止接收字节之后，发送继续进行。

　　FALSE时，在接收缓冲区接收到代表缓冲区已空的字节XonChar且驱动程序已经发送出恢复 发送的XonChar之后，发送继续进行。

　　DWORD fOutX: 1; // XON/XOFF out flow control TRUE时，接收到XoffChar之后便停止发送

　　接收到XonChar之后将重新开始

　　DWORD fInX: 1; // XON/XOFF in flow control

　　TRUE时，接收缓冲区接收到代表缓冲区满的XoffLim之后，XoffChar发送出去

　　接收缓冲区接收到代表缓冲区空的XonLim之后，XonChar发送出去

　　DWORD fErrorChar: 1; // enable error replacement

　　该值为TRUE且fParity为TRUE时，用ErrorChar 成员指定的字符代替奇偶校验错误的接收字符

　　DWORD fNull: 1; // enable null stripping　TRUE时，接收时去掉空（0值）字节

　　DWORD fRtsControl:2; // RTS flow control

　　DWORD fAbortOnError:1; // abort reads/writes on error　TRUE时,有错误发生时中止读和写操作

　　RTS_CONTROL_DISABLE时,RTS置为OFF

　　RTS_CONTROL_ENABLE时, RTS置为ON

　　RTS_CONTROL_HANDSHAKE时,

　　当接收缓冲区小于半满时RTS为ON

　　当接收缓冲区超过四分之三满时RTS为OFF

　　RTS_CONTROL_TOGGLE时,

　　当接收缓冲区仍有剩余字节时RTS为ON ,否则缺省为OFF

　　DWORD fDummy2:17; // reserved　未使用

　　WORD wReserved; // not currently used　未使用,必须为0

　　WORD XonLim; // transmit XON threshold

　　指定在XON字符发送这前接收缓冲区中可允许的最小字节数

　　WORD XoffLim; // transmit XOFF threshold

　　指定在XOFF字符发送这前接收缓冲区中可允许的最小字节数

　　BYTE ByteSize; // number of bits/byte, 4-8　指定端口当前使用的数据位

　　BYTE Parity; // 0-4=no,odd,even,mark,space　指定端口当前使用的奇偶校验方法,可能为:

　　EVENPARITY,MARKPARITY,NOPARITY,ODDPARITY　BYTE StopBits; 0,1,2 = 1, 1.5, 2 指定端口当前使用的停止位数,可能为:

　　ONESTOPBIT,ONE5STOPBITS,TWOSTOPBITS

　　char XonChar; // Tx and Rx XON character　指定用于发送和接收字符XON的值

　　char XoffChar; // Tx and Rx XOFF character　指定用于发送和接收字符XOFF值

　　char ErrorChar; // error replacement character本字符用来代替接收到的奇偶校验发生错误时的值

　　char EofChar; // end of input character　当没有使用二进制模式时,本字符可用来指示数据的结束

　　char EvtChar; // received event character　当接收到此字符时,会产生一个事件

　　WORD wReserved1; // reserved; do not use 未使用

　　} DCB;