MsgWaitForMultipleObjects 函式（winuser.h）

等候一或所有指定的對象處於訊號狀態或逾時間隔。物件可以包含輸入事件物件，您可以使用 dwWakeMask 參數來指定。

若要輸入可警示的等候狀態，請使用 MsgWaitForMultipleObjectsEx 函式。

語法

DWORD MsgWaitForMultipleObjects(
  [in] DWORD        nCount,
  [in] const HANDLE *pHandles,
  [in] BOOL         fWaitAll,
  [in] DWORD        dwMilliseconds,
  [in] DWORD        dwWakeMask
);

參數

[in] nCount

pHandles 所指向之陣列中的物件句柄數目。物件句柄數目上限 MAXIMUM_WAIT_OBJECTS 減一。如果此參數的值為零，則函式只會等候輸入事件。

[in] pHandles

物件句柄的陣列。如需可以指定句柄的物件類型清單，請參閱下列一節。數位可以包含不同類型物件的句柄。它可能不會包含相同句柄的多個複本。

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

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

[in] fWaitAll

如果此參數 TRUE，則函式會在 pHandles 陣列中的所有物件狀態設定為訊號且已收到輸入事件時傳回。如果此參數 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 值不包含花費在低功率狀態的時間。例如，當計算機處於睡眠狀態時，逾時不會持續倒數。

[in] dwWakeMask

將輸入事件物件句柄加入物件句柄數位的輸入型別。此參數可以是 GetQueueStatus旗標參數中所列值的任何組合。

傳回值

如果函式成功，傳回值會指出導致函式傳回的事件。它可以是下列其中一個值。（請注意，WAIT_OBJECT_0 定義為 0，WAIT_ABANDONED_0 定義為 0x00000080L。

傳回碼/值	描述
WAIT_OBJECT_0 至（WAIT_OBJECT_0 + nCount– 1）	如果 bWaitAllTRUE，則指定範圍內的傳回值表示發出所有指定物件的狀態。如果 bWaitAllFALSE，則傳回值減 WAIT_OBJECT_0 表示滿足等候之物件的 pHandles 陣列索引。
WAIT_OBJECT_0 + nCount	dwWakeMask 參數中指定的類型新輸入可在線程的輸入佇列中使用。 PeekMessage、GetMessage和 WaitMessage 等函式，將佇列中的訊息標示為舊訊息。因此，在您呼叫其中一個函式之後，MsgWaitForMultipleObjects 的後續呼叫將不會傳回，直到指定型別的新輸入到達為止。這個值也會在發生需要線程動作的系統事件時傳回，例如前景啟用。因此，MsgWaitForMultipleObjects 即使沒有可用的適當輸入，即使 dwWakeMask 設定為 0，還是可以傳回。如果發生這種情況，請呼叫 GetMessage 或 PeekMessage 來處理系統事件，然後再嘗試呼叫 MsgWaitForMultipleObjects。
WAIT_ABANDONED_0 至（WAIT_ABANDONED_0 + nCount– 1）	如果 bWaitAll 為 TRUE，則指定範圍內的傳回值表示所有指定物件的狀態已發出訊號，而且至少有一個物件是已放棄的 Mutex 物件。如果 bWaitAllFALSE，則傳回值減去 WAIT_ABANDONED_0 表示已放棄 mutex 物件的 pHandles 陣列索引，該對象滿足等候。 Mutex 對象的擁有權會授與呼叫線程，且 mutex 會設定為非ignaled。如果 Mutex 正在保護持續性狀態資訊，您應該檢查其是否一致性。
WAIT_TIMEOUT 258L	bWaitAll 和 dwWakeMask 參數所指定的超時時間間隔和條件都未滿足。
WAIT_FAILED （DWORD）0xFFFFFFFF	函式失敗。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

言論

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

當 bWaitAllTRUE時，函式不會修改指定物件的狀態，直到所有物件的狀態都設定為訊號為止。例如，可以發出 mutex 的訊號，但線程在其他物件的狀態也設定為訊號之前，不會取得擁有權。同時，其他一些線程可能會取得 Mutex 的擁有權，藉此將其狀態設定為非對齊狀態。

當 bWaitAllTRUE時，函式的等候只會在所有物件的狀態設定為訊號且已接收輸入事件時完成。因此，將 bWaitAll 設定為 TRUE 會防止處理輸入，直到 pHandles 陣列中的所有物件狀態設定為訊號為止。基於這個理由，如果您將 bWaitAll 設為 TRUE，您應該在 dwMilliseconds中使用簡短的逾時值。如果您有線程會建立視窗來等候 pHandles 陣列中的所有物件，包括 dwWakeMask所指定的輸入事件，且沒有逾時間隔，系統將會死結。這是因為建立窗口的線程必須處理訊息。 DDE 會將訊息傳送至系統中的所有視窗。因此，如果線程建立視窗，請勿在呼叫 MsgWaitForMultipleObjects 時 ，將 bWaitAll 參數設定為 true。

當 bWaitAllFALSE時，此函式會檢查陣列中的句柄，從索引 0 開始，直到其中一個物件收到訊號為止。如果多個物件收到訊號，函式會傳回陣列中對象已發出訊號之第一個句柄的索引。

如果線程呼叫函式來檢查佇列之後，訊息佇列中指定類型的未讀取輸入，則不會傳回 msgWaitForMultipleObjects。這是因為如 PeekMessage、GetMessage、GetQueueStatus和 WaitMessage 檢查佇列，然後變更佇列的狀態資訊，讓輸入不再被視為新的。後續呼叫 MsgWaitForMultipleObjects 在指定型別的新輸入送達之前，將不會傳回。現有的未讀取輸入（在上次檢查佇列的線程之前收到）會被忽略。

函式會修改某些同步處理物件類型的狀態。修改只會針對發出訊號狀態導致函式傳回的物件或物件進行修改。例如，號誌物件的計數會減少一個。如需詳細資訊，請參閱個別同步處理對象的檔。

MsgWaitForMultipleObjects 函式可以指定 pHandles 陣列中下列任一物件類型的句柄：

變更通知
主控台輸入
事件
記憶體資源通知
Mutex
過程
信號
線
可等候定時器

要求

要求	價值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平臺	窗戶
標頭	winuser.h （包括 Windows.h）
連結庫	User32.lib
DLL	User32.dll