OVERLAPPED 構造体 (minwinbase.h)

[アーティクル]
02/29/2024

非同期 (または重複) 入力と出力 (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 要求を実行する場合にのみ 0 以外です。それ以外の場合、このメンバーは 0 である必要があります。

詳細については、次を参照してください。解説します。

DUMMYUNIONNAME.DUMMYSTRUCTNAME.OffsetHigh

ユーザーが指定した I/O 要求を開始するファイル位置の上位部分。

詳細については、次を参照してください。解説します。

DUMMYUNIONNAME.Pointer

システムの使用のために予約されています。0 への初期化後にを使用しないでください。

hEvent

操作が完了したときにシステムによってシグナル状態に設定されるイベントのハンドル。ユーザーは、この構造体を重複する関数に渡す前に、 CreateEvent 関数を使用して、このメンバーをゼロまたは有効なイベントハンドルに初期化する必要があります。その後、このイベントを使用して、デバイスの同時 I/O 要求を同期できます。詳細については、次を参照してください。解説します。

ReadFile や WriteFile などの関数は、I/O 操作を開始する前に、このハンドルを非割り当て状態に設定します。操作が完了すると、ハンドルはシグナル状態に設定されます。

GetOverlappedResult や同期待機関数などの関数は、自動リセットイベントを非署名状態にリセットします。したがって、手動リセットイベントを使用する必要があります。自動リセットイベントを使用する場合、操作が完了するのを待ってから、bWait パラメーターを TRUE に設定して GetOverlappedResult を呼び出すと、アプリケーションは応答を停止できます。

注釈

この構造体の未使用のメンバーは、関数呼び出しで構造体が使用される前に、常に 0 に初期化する必要があります。それ以外の場合、関数は失敗し、 ERROR_INVALID_PARAMETERを返す可能性があります。

Offset メンバーと OffsetHigh メンバーは、64 ビットのファイル位置を表します。これは、ファイルまたはファイルのようなデバイスの先頭からのバイトオフセットであり、ユーザーによって指定されます。システムはこれらの値を変更しません。呼び出し元のプロセスでは、オフセットを使用する関数に OVERLAPPED 構造体を渡す前に、このメンバーを設定する必要があります ( ReadFile 関数や WriteFile (および関連する関数など)。

HasOverlappedIoCompleted マクロを使用すると、GetOverlappedResult がアプリケーションにとって面倒な場合に非同期 I/O 操作が完了したかどうかをチェックできます。

CancelIo 関数を使用して、非同期 I/O 操作を取り消すことができます。

一般的な間違いは、前の非同期操作が完了する前に OVERLAPPED 構造体を再利用することです。要求ごとに個別の構造を使用する必要があります。また、データを処理するスレッドごとにイベントオブジェクトを作成する必要もあります。イベントハンドルを配列に格納すると、 WaitForMultipleObjects 関数を使用して、すべてのイベントがシグナル通知されるまで簡単に待機できます。

非同期 I/O 使用の追加情報と潜在的な落とし穴については、「CreateFile、ReadFile、WriteFile、および関連する関数」を参照してください。

一般的な同期の概要と概念的な OVERLAPPED の使用情報については、「同期と重複した入力と出力」および関連トピックを参照してください。

同期および非同期 I/O のファイル I/O 指向の概要については、「同期および非同期 I/O」を参照してください。

例

例については、「重複した I/O を使用した名前付きパイプサーバー」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows XP [デスクトップアプリ \| UWP アプリ]
サポートされている最小のサーバー	Windows Server 2003 [デスクトップアプリのみ \| UWP アプリ]
Header	minwinbase.h (Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2 の Windows.h を含む)