MsgWaitForMultipleObjectsEx 函式 (winuser.h)
等候一或所有指定的對象處於訊號狀態、I/O 完成例程或異步過程調用 (APC) 排入線程,或逾時間隔經過。 對象的陣列可以包含使用 dwWakeMask 參數指定的輸入事件物件。
語法
DWORD MsgWaitForMultipleObjectsEx(
[in] DWORD nCount,
[in] const HANDLE *pHandles,
[in] DWORD dwMilliseconds,
[in] DWORD dwWakeMask,
[in] DWORD dwFlags
);
參數
[in] nCount
pHandles 所指向陣列中的物件句柄數目。 物件句柄數目上限 MAXIMUM_WAIT_OBJECTS 減一。 如果此參數的值為零,則函式只會等候輸入事件。
[in] pHandles
物件句柄的陣列。 如需您可以指定句柄的物件類型清單,請參閱本主題稍後的一節。 數位可以包含多個物件類型的句柄。 它可能不會包含相同句柄的多個複本。
如果等候仍在擱置時關閉其中一個句柄,則函式的行為未定義。
句柄必須具有 SYNCHRONIZE 存取權。 如需詳細資訊,請參閱 標準訪問許可權。
[in] dwMilliseconds
逾時間隔,以毫秒為單位。 如果指定了非零值,函式會等到指定的物件收到訊號、I/O 完成例程或 APC 已排入佇列,或間隔經過為止。 如果 dwMilliseconds 為零,則不符合準則時,函式不會進入等候狀態;它一律會立即傳回。 如果 dwMilliseconds 是 INFINITE,則只有在指定的物件收到訊號或 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、Windows 8.1、Windows Server 2012 R2、Windows 10 和 Windows Server 2016:dwMilliseconds 值不包含花費在低電量的時間國家。 例如,當計算機處於睡眠狀態時,逾時不會持續倒數。
[in] dwWakeMask
輸入事件物件句柄將新增至物件句柄數位的輸入類型。 此參數可以是 GetQueueStatus旗標 參數中所列值的任何組合。
[in] dwFlags
等候類型。 此參數可以是下列一或多個值。
值 | 意義 |
---|---|
|
當任一物件發出訊號時,函式會傳回 。 傳回值表示造成函式傳回其狀態的物件。 |
|
當線程處於等候狀態時,如果 APC 已排入 QueueUserAPC 的線程,則此函式也會傳回 。 |
|
函式會傳回如果佇列的輸入存在,即使輸入已 (但未移除) ,但不會使用對另一個函式的呼叫來移除,例如 PeekMessage。 |
|
函式會在 pHandles 陣列中的所有物件都發出訊號並同時收到輸入事件時傳回。 |
傳回值
如果函式成功,傳回值會指出導致函式傳回的事件。 它可以是下列值之一。 (請注意, WAIT_OBJECT_0 定義為 0,WAIT_ABANDONED_0 定義為 0x00000080L.)
傳回碼/值 | Description |
---|---|
|
如果使用 MWMO_WAITALL 旗標,則指定範圍內的傳回值表示所有指定物件的狀態都會發出訊號。 否則,傳回值減 WAIT_OBJECT_0 表示造成函式傳回之物件的 pHandles 陣列索引。 |
|
dwWakeMask 參數中指定的類型新輸入可在線程的輸入佇列中使用。 PeekMessage、GetMessage、GetQueueStatus 和 WaitMessage 等函式會將佇列中的訊息標示為舊訊息。 因此,在您呼叫其中一個函式之後, 後續呼叫 MsgWaitForMultipleObjectsEx 將不會傳回,直到指定型別的新輸入送達為止。
這個值也會在發生需要線程動作的系統事件時傳回,例如前景啟用。 因此,即使沒有適當的輸入,而且 dwWakeMask 設定為 0,MsgWaitForMultipleObjectsEx 仍可傳回。 如果發生這種情況,請呼叫 GetMessage 或 PeekMessage 來處理系統事件,然後再嘗試呼叫 MsgWaitForMultipleObjectsEx 。 |
|
如果使用 MWMO_WAITALL 旗標,則指定範圍內的傳回值表示所有指定物件的狀態都會發出訊號,而且至少有一個物件是已放棄的 mutex 物件。 否則,傳回值減 WAIT_ABANDONED_0 表示造成函式傳回之已放棄 Mutex 物件的 pHandles 陣列索引。 Mutex 對象的擁有權會授與呼叫線程,且 mutex 會設定為非簽署。
如果 mutex 正在保護持續性狀態資訊,您應該檢查其是否一致性。 |
|
等候已由一或多個使用者模式 異步過程調用 結束, (APC) 排入線程。 |
|
經過逾時間隔,但 不符合 dwFlags 和 dwWakeMask 參數所指定的條件。 |
|
函式失敗。 若要取得擴充的錯誤資訊,請呼叫 GetLastError。 |
備註
MsgWaitForMultipleObjectsEx 函式會判斷 dwWakeMask 和 dwFlags 指定的條件是否已符合。 如果條件尚未符合,則呼叫線程會進入等候狀態,直到符合等候準則的條件或逾時間隔經過為止。
當 dwFlags 為零時,此函式會檢查陣列中的句柄,從索引 0 開始,直到發出其中一個物件的訊號為止。 如果多個物件收到訊號,函式會傳回數位中對象已發出訊號的第一個句柄索引。
如果線程呼叫函式來檢查佇列,除非您使用 MWMO_INPUTAVAILABLE 旗標,否則 MsgWaitForMultipleObjectsEx 不會傳回訊息佇列中指定類型的未讀取輸入。 這是因為 PeekMessage、 GetMessage、 GetQueueStatus 和 WaitMessage 等函式會檢查佇列,然後變更佇列的狀態資訊,讓輸入不再被視為新。 除非您使用 MWMO_INPUTAVAILABLE 旗標,否則後續呼叫 MsgWaitForMultipleObjectsEx 將不會傳回,直到指定類型的新輸入送達為止。 如果未使用此旗標,則會在上次線程檢查佇列) 之前收到的現有未讀取輸入 (。
函式會修改某些同步處理物件類型的狀態。 修改只會針對發出訊號狀態導致函式傳回的物件或物件進行修改。 例如,系統會將旗號物件的計數減少一個。 如需詳細資訊,請參閱個別同步處理對象的檔。
MsgWaitForMultipleObjectsEx 函式可以指定 pHandles 陣列中下列任何物件類型的句柄:
- 變更通知
- 主控台輸入
- 事件
- 記憶體資源通知
- Mutex
- 流程
- Semaphore
- 執行緒
- 可等候的定時器
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
最低支援的伺服器 | Windows Server 2003 [僅限桌面應用程式] |
目標平台 | Windows |
標頭 | winuser.h (包含 Windows.h) |
程式庫 | User32.lib |
Dll | User32.dll |
另請參閱
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應