cpp
WINBASEAPI
_Must_inspect_result_
BOOL
WINAPI
ReadFile(
_In_ HANDLE hFile,
_Out_writes_bytes_to_opt_(nNumberOfBytesToRead, *lpNumberOfBytesRead) __out_data_source(FILE) LPVOID lpBuffer,
_In_ DWORD nNumberOfBytesToRead,
_Out_opt_ LPDWORD lpNumberOfBytesRead,
_Inout_opt_ LPOVERLAPPED lpOverlapped
);
WINBASEAPI
_Must_inspect_result_
来自 Windows 系统的头文件 fileapi.h ,这个文件是 Windows SDK(Software Development Kit)的一部分,用于定义 Windows API 中的文件和设备 I/O(输入/输出)相关的函数,例如 ReadFile、WriteFile 等。这些函数提供了文件、设备(包括串口)的读取、写入、关闭等操作接口,是 Windows 系统 API 的重要组成部分。
如何阅读和理解这些源码?
1. WINBASEAPI、BOOL、WINAPI 等宏定义
-
WINBASEAPI:这是一个宏,用于控制函数的导出方式。对于 Windows API 函数,这个宏通常表示这些函数是通过 DLL(动态链接库)导出的,可以被其他程序调用。 -
BOOL:这是 Windows API 中的布尔类型,通常等价于int,用于表示TRUE(非零)或FALSE(零)。 -
WINAPI:这是一个宏,用于定义调用约定。WINAPI等价于__stdcall,这是 Windows API 使用的标准调用约定,规定了参数的传递和堆栈清理方式。
2. 函数注解
_Must_inspect_result_ 、_In_ 、_Out_ 等是 SAL(Source Annotation Language)注解,用于向开发者和工具描述函数参数的用途、方向和约束条件。它们对编译器的功能无影响,但在代码分析、静态检查时提供帮助。
-
_Must_inspect_result_:提示调用者必须检查ReadFile函数的返回值(即BOOL类型的TRUE或FALSE)。忽略返回值可能导致潜在的错误。 -
_In_:表示这是一个输入参数。HANDLE hFile是输入参数,表示要读取的文件句柄。 -
_Out_:表示这是一个输出参数,函数会通过此参数返回数据。例如LPDWORD lpNumberOfBytesRead是一个输出参数,用于存储实际读取的字节数。 -
_Inout_opt_:表示这是一个可选的输入/输出参数。LPOVERLAPPED lpOverlapped是一个可选的重叠 I/O 结构,用于异步 I/O。
3. 函数 ReadFile 的用途
ReadFile 是一个重要的 Windows API 函数,用于从文件或设备(如串口、管道等)中读取数据。该函数的声明如下:
cpp
BOOL WINAPI ReadFile(
HANDLE hFile, // 文件或设备句柄
LPVOID lpBuffer, // 数据读取缓冲区
DWORD nNumberOfBytesToRead, // 读取的字节数
LPDWORD lpNumberOfBytesRead, // 实际读取的字节数
LPOVERLAPPED lpOverlapped // 异步操作结构
);
4. fileapi.h 是 Windows 系统库的一部分
fileapi.h 是 Windows SDK 中提供的头文件,属于 Windows 系统库的标准文件。它定义了许多文件和设备 I/O 相关的函数,如 ReadFile、WriteFile、DeleteFile 等。此文件位于 Windows SDK 的 include 文件夹中,默认路径可能如下(取决于安装的 Windows SDK 版本):
C:\Program Files (x86)\Windows Kits\10\Include\<version>\um\fileapi.h
这些文件是只读的,不建议修改。Windows API 是通过动态链接库(如 Kernel32.dll)实现的,程序编译时只是包含这些头文件,而实际运行时调用的是 DLL 中的实现代码。
如何使用这些 API
在实际开发中,你可以在 C++ 程序中包含 <windows.h>(或者更具体的 <fileapi.h>),然后直接调用 ReadFile 函数与文件或设备进行交互。例如,从串口读取数据:
cpp
#include <windows.h>
#include <iostream>
int main() {
HANDLE hSerial = CreateFile(
"COM3", // 串口号
GENERIC_READ | GENERIC_WRITE, // 读写权限
0, // 独占访问
NULL, // 默认安全属性
OPEN_EXISTING, // 打开已存在的设备
0, // 同步操作
NULL // 无模板
);
if (hSerial == INVALID_HANDLE_VALUE) {
std::cerr << "无法打开串口,错误代码:" << GetLastError() << std::endl;
return 1;
}
char buffer[128];
DWORD bytesRead;
BOOL result = ReadFile(hSerial, buffer, sizeof(buffer), &bytesRead, NULL);
if (result) {
std::cout << "成功读取 " << bytesRead << " 字节数据:" << buffer << std::endl;
} else {
std::cerr << "读取失败,错误代码:" << GetLastError() << std::endl;
}
CloseHandle(hSerial);
return 0;
}
小结
fileapi.h是 Windows SDK 中的系统库头文件,包含文件和设备 I/O 相关的 API 定义。ReadFile是 Windows API 中的重要函数,用于从文件或设备中读取数据。- SAL 注解帮助开发者理解函数的输入、输出和可选参数,提高代码的可读性和正确性。
- 通过包含
<windows.h>可以使用ReadFile等 API 与系统文件、串口、管道等设备进行交互。
如果现在readfile此函数读文件 花费太长时间,如80~90ms
cpp
COMMTIMEOUTS timeouts = { 0 };
timeouts.ReadIntervalTimeout = 10; // 设置字符间隔超时,减少等待时间
timeouts.ReadTotalTimeoutConstant = 10; // 设置总读取超时常量
timeouts.ReadTotalTimeoutMultiplier = 0; // 每字节的额外超时
SetCommTimeouts(mHandle, &timeouts);