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 要求時，這個成員才非零，其支援位移的概念 (也稱為檔案指標機制) ，例如檔案。否則，這個成員必須是零。

如需詳細資訊，請參閱。

DUMMYUNIONNAME.DUMMYSTRUCTNAME.OffsetHigh

要啟動 I/O 要求之檔案位置的高序部分，如使用者所指定。

只有在搜尋裝置上執行 I/O 要求時，這個成員才非零，其支援位移的概念 (也稱為檔案指標機制) ，例如檔案。否則，這個成員必須是零。

如需詳細資訊，請參閱。

DUMMYUNIONNAME.Pointer

保留供系統使用;在初始化為零之後，請勿使用。

hEvent

事件的句柄，當作業完成時，系統將會設定為訊號狀態的事件。用戶必須先使用 CreateEvent 函式將此成員初始化為零或有效的事件句柄，再將此結構傳遞至任何重疊的函式。此事件接著可用來同步處理裝置的同時 I/O 要求。如需詳細資訊，請參閱。

ReadFile 和 WriteFile 等函式會在開始 I/O 作業之前，將此句柄設定為非ignaled 狀態。當作業完成時，句柄會設定為已發出訊號的狀態。

GetOverlappedResult 和同步處理等候函式等函式會將自動重設事件重設為非簽署狀態。因此，您應該使用手動重設事件;如果您使用自動重設事件，則如果您等候作業完成，然後呼叫 GetOverlappedResult 並將 bWait 參數設定為 TRUE，則應用程式可以停止回應。

備註

在函數調用中使用結構之前，此結構的任何未使用成員都應該一律初始化為零。否則，函式可能會失敗並傳回 ERROR_INVALID_PARAMETER。

Offset 和 OffsetHigh 成員一起代表 64 位檔案位置。它是檔案或類似檔案裝置開頭的位元組位移，而且是由使用者指定;系統不會修改這些值。呼叫進程必須先設定這個成員，才能將 OVERLAPPED 結構傳遞至使用位移的函式，例如 ReadFile 或 WriteFile (和相關) 函式。

您可以使用 HasOverlappedIoCompleted 宏，檢查如果 GetOverlappedResult 對您的應用程式而言太麻煩，異步 I/O 作業是否已完成。

您可以使用 CancelIo 函式來取消異步 I/O 作業。

常見的錯誤是先重複使用重疊結構，再完成先前的異步操作。您應該針對每個要求使用不同的結構。您也應該為每個處理數據的線程建立事件物件。如果您將事件句柄儲存在數位中，您可以輕鬆地等候所有事件使用 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 Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2)