【C++】关于使用系统库fileapi.h的readfile，及’读‘时间耗时太长的解决方案

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 函数，用于从文件或设备（如串口、管道等）中读取数据。该函数的声明如下：

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 函数与文件或设备进行交互。例如，从串口读取数据：

#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

 COMMTIMEOUTS timeouts = { 0 };
timeouts.ReadIntervalTimeout = 10;         // 设置字符间隔超时，减少等待时间
timeouts.ReadTotalTimeoutConstant = 10;    // 设置总读取超时常量
timeouts.ReadTotalTimeoutMultiplier = 0;   // 每字节的额外超时
SetCommTimeouts(mHandle, &timeouts);