重叠结构 (minwinbase.h)

项目
08/24/2023

包含用于异步 (或重叠) 输入和输出 (I/O) 的信息。

语法

typedef struct _OVERLAPPED {
  ULONG_PTR Internal;
  ULONG_PTR InternalHigh;
  union {
    struct {
      DWORD Offset;
      DWORD OffsetHigh;
    } DUMMYSTRUCTNAME;
    PVOID Pointer;
  } DUMMYUNIONNAME;
  HANDLE    hEvent;
} OVERLAPPED, *LPOVERLAPPED;

成员

Internal

I/O 请求的状态代码。发出请求时，系统会将此成员设置为 STATUS_PENDING 以指示操作尚未启动。请求完成后，系统会将此成员设置为已完成请求的状态代码。

内部成员最初保留供系统使用，其行为可能会更改。

InternalHigh

为 I/O 请求传输的字节数。如果请求完成且未出错，系统会设置此成员。

InternalHigh 成员最初保留供系统使用，其行为可能会更改。

DUMMYUNIONNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Offset

启动 I/O 请求的文件位置的低顺序部分，由用户指定。

仅当在支持偏移 (也称为文件指针) 机制（如文件）的查找设备上执行 I/O 请求时，此成员才为非零。否则，此成员必须为零。

有关其他信息，请参阅备注。

DUMMYUNIONNAME.DUMMYSTRUCTNAME.OffsetHigh

要启动 I/O 请求的文件位置的高序部分，由用户指定。

仅当在支持偏移 (也称为文件指针) 机制（如文件）的查找设备上执行 I/O 请求时，此成员才为非零。否则，此成员必须为零。

有关其他信息，请参阅备注。

DUMMYUNIONNAME.Pointer

保留供系统使用;初始化后不要使用为零。

hEvent

事件的句柄，该句柄将在操作完成后由系统设置为信号状态。用户必须使用 CreateEvent 函数将此成员初始化为零或有效的事件句柄，然后才能将此结构传递给任何重叠的函数。然后，可以使用此事件同步设备的同步 I/O 请求。有关其他信息，请参阅备注。

ReadFile 和 WriteFile 等函数在开始 I/O 操作之前将此句柄设置为非对齐状态。操作完成后，句柄将设置为信号状态。

GetOverlappedResult 等函数和同步等待函数将自动重置事件重置为非对齐状态。因此，应使用手动重置事件;如果使用自动重置事件，则在等待操作完成，然后使用 bWait 参数设置为 TRUE 的情况下调用 GetOverlappedResult，应用程序可以停止响应。

注解

在函数调用中使用结构之前，应始终将此结构的任何未使用成员初始化为零。否则，函数可能会失败并返回 ERROR_INVALID_PARAMETER。

Offset 和 OffsetHigh 成员共同表示 64 位文件位置。它是与文件或类似文件的设备开头的字节偏移量，由用户指定;系统不会修改这些值。调用进程必须先设置此成员，然后才能将 OVERLAPPED 结构传递给使用偏移量的函数，例如 ReadFile 或 WriteFile (和相关) 函数。

可以使用 HasOverlappedIoCompleted 宏检查如果 GetOverlappedResult 对应用程序而言过于繁琐，异步 I/O 操作是否已完成。

可以使用 CancelIo 函数取消异步 I/O 操作。

一个常见错误是在完成以前的异步操作之前重用 OVERLAPPED 结构。应为每个请求使用单独的结构。还应为处理数据的每个线程创建一个事件对象。如果将事件句柄存储在数组中，则可以使用 WaitForMultipleObjects 函数轻松等待所有事件发出信号。

有关异步 I/O 用法的其他信息和潜在缺陷，请参阅 CreateFile、 ReadFile、 WriteFile 和相关函数。

有关一般同步概述和概念 性重叠 使用情况信息，请参阅同步和重叠输入和输出以及相关主题。

有关同步和异步 I/O 的面向文件 I/O 的概述，请参阅同步和异步 I/O。

示例

有关示例，请参阅使用重叠 I/O 的命名管道服务器。

要求

要求	值
最低受支持的客户端	Windows XP [桌面应用 \| UWP 应用]
最低受支持的服务器	Windows Server 2003 [桌面应用 \| UWP 应用]
标头	minwinbase.h (包括 Windows Server 2003 上的 Windows.h、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2)