WaitForMultipleObjects 函式 （synchapi.h）
等候一或所有指定的對象處於訊號狀態或逾時間隔。
若要輸入可警示的等候狀態，請使用 WaitForMultipleObjectsEx 函式。
語法
DWORD WaitForMultipleObjects(
[in] DWORD nCount,
[in] const HANDLE *lpHandles,
[in] BOOL bWaitAll,
[in] DWORD dwMilliseconds
);
參數
[in] nCount
lpHandles 所指向之陣列中的物件句柄數目。 物件句柄數目上限為 MAXIMUM_WAIT_OBJECTS。 此參數不可為零。
[in] lpHandles
物件句柄的陣列。 如需可以指定句柄的物件類型清單，請參閱下列一節。 數位可以包含不同類型物件的句柄。 它可能不會包含相同句柄的多個複本。
如果其中一個句柄在等候仍在擱置時關閉，則函式的行為未定義。
句柄必須具有 SYNCHRONIZE 訪問許可權。 如需詳細資訊，請參閱 標準存取權限。
[in] bWaitAll
如果此參數 TRUE，當 lpHandles 陣列中的所有物件狀態發出訊號時，函式會傳回 。 如果 FALSE，當任一物件的狀態設定為訊號時，函式會傳回 。 在後者的情況下，傳回值會指出導致函式傳回其狀態的物件。
[in] dwMilliseconds
超時時間間隔，以毫秒為單位。 如果指定了非零值，函式會等到指定的物件收到訊號或間隔經過為止。 如果 dwMilliseconds 為零，則如果指定的物件未收到訊號，函式就不會進入等候狀態;它一律會立即傳回。 如果 dwMillisecondsINFINITE，則函式只會在發出指定物件的訊號時傳回。
Windows XP、Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 和 Windows Server 2008 R2：dwMilliseconds 值確實包含花費在低功率狀態的時間。 例如，當計算機處於睡眠狀態時，逾時會持續倒數。
Windows 8 和更新版本、Windows Server 2012 和更新版本：dwMilliseconds 值不包含花費在低功率狀態的時間。 例如，當計算機處於睡眠狀態時，逾時不會持續倒數。
傳回值
如果函式成功，傳回值會指出導致函式傳回的事件。 它可以是下列其中一個值。 （請注意，WAIT_OBJECT_0 定義為 0，WAIT_ABANDONED_0 定義為 0x00000080L。
| 傳回碼/值 | 描述 |
|---|---|
|
如果 bWaitAllTRUE，則指定範圍內的傳回值表示發出所有指定物件的狀態。
如果 bWaitAllFALSE，則傳回值減 WAIT_OBJECT_0 表示滿足等候之物件的 lpHandles 陣列索引。 如果在呼叫期間收到多個對象的訊號，這是訊號對象的陣列索引，且所有訊號物件的索引值最小。 |
|
如果 如果 bWaitAllFALSE，則傳回值減去 WAIT_ABANDONED_0 表示已放棄 mutex 物件的 lpHandles 陣列索引，該索引符合等候。 Mutex 對象的擁有權會授與呼叫線程，且 mutex 會設定為非ignaled。 如果 Mutex 正在保護持續性狀態資訊，您應該檢查其是否一致性。 |
|
不符合 bWaitAll 參數所指定的逾時間隔和條件。 |
|
函式失敗。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。 |
言論
WaitForMultipleObjects 函式會判斷是否已符合等候準則。 如果不符合準則，則呼叫線程會進入等候狀態，直到符合等候準則的條件或逾時間隔經過為止。
當 bWaitAllTRUE時，函式的等候作業只會在所有物件的狀態設定為訊號時完成。 函式不會修改指定物件的狀態，直到所有物件的狀態都設定為訊號為止。 例如，可以發出 Mutex 的訊號，但線程不會取得擁有權，直到其他物件的狀態也設定為訊號為止。 同時，其他一些線程可能會取得 Mutex 的擁有權，藉此將其狀態設定為非對齊狀態。
當 bWaitAllFALSE時，此函式會檢查陣列中的句柄，從索引 0 開始，直到其中一個物件收到訊號為止。 如果多個物件收到訊號，函式會傳回陣列中對象已發出訊號之第一個句柄的索引。
函式會修改某些同步處理物件類型的狀態。 修改只會針對發出訊號狀態導致函式傳回的物件或物件進行修改。 例如，號誌物件的計數會減少一個。 如需詳細資訊，請參閱個別同步處理對象的檔。
若要等候超過 MAXIMUM_WAIT_OBJECTS 句柄，請使用下列其中一種方法：
- 建立線程以等候 MAXIMUM_WAIT_OBJECTS 句柄，然後等候該線程加上其他句柄。 使用這項技術將句柄分成 MAXIMUM_WAIT_OBJECTS群組。
- 呼叫 registerWaitForSingleObject 或 SetThreadpoolWait 等候每個句柄。 線程集區會在句柄上有效率地等候，並在對象發出訊號或逾時間隔到期后指派背景工作線程。
- 變更通知
- 主控台輸入
- 事件
- 記憶體資源通知
- Mutex
- 過程
- 信號
- 線
- 可等候定時器
例子
如需範例，請參閱 等候多個物件。
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows XP [傳統型應用程式 |UWP 應用程式] |
| 支援的最低伺服器 | Windows Server 2003 [傳統型應用程式 |UWP 應用程式] |
| 目標平臺 | 窗戶 |
| 標頭 | synchapi.h （包括 Windows.h） |
| 連結庫 | Kernel32.lib |
| DLL | Kernel32.dll |