共用方式為

WaitForSingleObjectEx 函式 （synchapi.h）

  • 發行項

等候指定的對象處於訊號狀態、I/O 完成例程或異步過程調用 （APC） 排入佇列至線程，或逾時間隔經過。

若要等候多個物件，請使用 waitForMultipleObjectsEx。

語法

DWORD WaitForSingleObjectEx(
  [in] HANDLE hHandle,
  [in] DWORD  dwMilliseconds,
  [in] BOOL   bAlertable
);

參數

[in] hHandle

物件的句柄。 如需可以指定句柄的物件類型清單，請參閱下列一節。

如果等候仍在擱置時關閉此句柄，則未定義函式的行為。

句柄必須具有 SYNCHRONIZE 訪問許可權。 如需詳細資訊，請參閱 標準存取權限。

[in] dwMilliseconds

超時時間間隔，以毫秒為單位。 如果指定了非零值，函式會等候物件收到訊號、I/O 完成例程或 APC 已排入佇列，或間隔經過。 如果 dwMilliseconds 為零，則不符合準則時，函式不會進入等候狀態;它一律會立即傳回。 如果 dwMillisecondsINFINITE，則只有在發出訊號或 I/O 完成例程或 APC 排入佇列時，函式才會傳回。

Windows XP、Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 和 Windows Server 2008 R2：dwMilliseconds 值確實包含花費在低功率狀態的時間。 例如，當計算機處於睡眠狀態時，逾時會持續倒數。

Windows 8 和更新版本、Windows Server 2012 和更新版本：dwMilliseconds 值不包含花費在低功率狀態的時間。 例如，當計算機處於睡眠狀態時，逾時不會持續倒數。

[in] bAlertable

如果此參數 TRUE 且線程處於等候狀態，則當系統將 I/O 完成例程或 APC 排入佇列時，函式會傳回，而線程會執行例程或函式。 否則，函式不會傳回，而且不會執行完成例程或APC函式。

完成例程會在指定的 ReadFileEx 或 WriteFileEx 函式完成 時排入佇列。 只有在 bAlertable TRUE，而且呼叫線程是起始讀取或寫入作業的線程時，等候函式才會傳回 ，而且只會呼叫完成例程。 當您呼叫 queueUserAPC 時，APC 會排入佇列。

傳回值

如果函式成功，傳回值會指出導致函式傳回的事件。 它可以是下列其中一個值。

傳回碼/值 描述
WAIT_ABANDONED
0x00000080L
 指定的對像是一個 Mutex 物件，該物件不是由擁有 Mutex 物件的線程在擁有線程終止之前釋放的。 Mutex 對象的擁有權會授與呼叫線程，且 mutex 會設定為非ignaled。

如果 Mutex 正在保護持續性狀態資訊，您應該檢查其是否一致性。
WAIT_IO_COMPLETION
0x000000C0L
 等候已由一或多個使用者模式結束，異步過程調用 （APC） 排入線程。
WAIT_OBJECT_0
0x00000000L
 指定的物件狀態會發出訊號。
WAIT_TIMEOUT
0x00000102L
 經過的超時時間間隔，且物件的狀態為非對齊。
WAIT_FAILED
（DWORD）0xFFFFFFFF
 函式失敗。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

言論

WaitForSingleObjectEx 函式會判斷是否已符合等候準則。 如果不符合準則，則呼叫線程會進入等候狀態，直到符合等候準則的條件或逾時間隔經過為止。

函式會修改某些同步處理物件類型的狀態。 只有發出訊號狀態導致函式傳回的物件才會進行修改。 例如，號誌物件的計數會減少一個。

WaitForSingleObjectEx 函式可以等候下列物件：

  • 變更通知
  • 主控台輸入
  • 事件
  • 記憶體資源通知
  • Mutex
  • 過程
  • 信號
  • 線
  • 可等候定時器
呼叫直接或間接建立視窗的等候函式和程式代碼時，請小心。 如果線程建立任何視窗，它就必須處理訊息。 訊息廣播會傳送至系統中的所有視窗。 使用沒有超時時間間隔之等候函式的線程可能會導致系統陷入死結。 間接建立視窗的程式代碼範例有 DDE 和 CoInitialize 函式。 因此，如果您有建立視窗的線程，請使用 MsgWaitForMultipleObjects 或 MsgWaitForMultipleObjectsEx，而不是 WaitForSingleObjectEx。

例子

如需範例，請參閱使用完成例程 命名管道伺服器。

要求

要求 價值
最低支援的用戶端 Windows XP [傳統型應用程式 |UWP 應用程式]
支援的最低伺服器 Windows Server 2003 [傳統型應用程式 |UWP 應用程式]
目標平臺 窗戶
標頭 synchapi.h （包括 Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2 上的 Windows.h）
連結庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

同步處理函式

等候函式