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 為零,如果指定的物件未發出訊號,函式就不會進入等候狀態;它一律會立即傳回。 如果 dwMilliseconds 是 INFINITE,則函式只會在發出指定物件的訊號時傳回。
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旗標 參數中所列值的任何組合。
傳回值
如果函式成功,傳回值會指出導致函式傳回的事件。 它可以是下列值之一。 (請注意, WAIT_OBJECT_0 定義為 0, WAIT_ABANDONED_0 定義為 0x00000080L.)
傳回碼/值 | 描述 |
---|---|
|
如果 bWaitAll 為 TRUE,則指定範圍內的傳回值表示所有指定物件的狀態都會發出訊號。 如果 bWaitAll 為 FALSE,傳回值減 去WAIT_OBJECT_0 表示滿足等候之物件的 pHandles 陣列索引。 |
|
dwWakeMask參數中指定的類型新輸入可線上程的輸入佇列中使用。 PeekMessage、GetMessage 和 WaitMessage等函式會將佇列中的訊息標示為舊訊息。 因此,在您呼叫其中一個函式之後, 後續呼叫 MsgWaitForMultipleObjects 將不會傳回,直到指定型別的新輸入到達為止。
這個值也會在發生需要執行緒動作的系統事件時傳回,例如前景啟用。 因此,即使沒有適當的輸入,而且dwWakeMask設定為 0,MsgWaitForMultipleObjects仍可傳回。 如果發生這種情況,請先呼叫 GetMessage 或 PeekMessage 來處理系統事件,然後再嘗試呼叫 MsgWaitForMultipleObjects 。 |
|
如果 bWaitAll 為 TRUE,則指定範圍內的傳回值表示所有指定物件的狀態都會發出訊號,而且至少有一個物件是已放棄的 mutex 物件。 如果 bWaitAll 為 FALSE,則傳回值減 去WAIT_ABANDONED_0 表示已放棄 Mutex 物件的 pHandles 陣列索引,該物件滿足等候。 Mutex 物件的擁有權會授與呼叫執行緒,且 mutex 會設定為非簽署。
如果 mutex 正在保護持續性狀態資訊,您應該檢查其是否一致性。 |
|
逾時間隔已經過,且 不符合 bWaitAll 和 dwWakeMask 參數所指定的條件。 |
|
函式失敗。 若要取得擴充的錯誤資訊,請呼叫 GetLastError。 |
備註
MsgWaitForMultipleObjects函式會判斷是否已符合等候準則。 如果不符合準則,則呼叫執行緒會進入等候狀態,直到符合等候準則的條件或逾時間隔經過為止。
當 bWaitAll為TRUE時,函式不會修改指定物件的狀態,直到所有物件的狀態都設定為已發出訊號為止。 例如,可以發出 Mutex 的訊號,但執行緒在其他物件的狀態也設定為已發出訊號之前,不會取得擁有權。 同時,某些其他執行緒可能會取得 mutex 的擁有權,因此將其狀態設定為非簽署狀態。
當 bWaitAll為TRUE時,只有在所有物件的狀態都設定為已發出訊號且已收到輸入事件時,函式的等候才會完成。 因此,將 bWaitAll 設定為 TRUE 可防止輸入處理,直到 pHandles 陣列中的所有物件狀態都設定為已發出訊號為止。 基於這個理由,如果您將 bWaitAll 設定為 TRUE,您應該在 dwMilliseconds中使用簡短的逾時值。 如果您有線程會建立視窗以等候 pHandles 陣列中的所有物件,包括 dwWakeMask所指定的輸入事件,且沒有逾時間隔,系統將會死結。 這是因為建立視窗的執行緒必須處理訊息。 DDE 會將訊息傳送至系統中的所有視窗。 因此,如果執行緒建立視窗,請勿在該執行緒呼叫MsgWaitForMultipleObjects時,將bWaitAll參數設定為TRUE。
當 bWaitAll為FALSE時,此函式會檢查陣列中的控制碼,從索引 0 開始,直到發出其中一個物件的訊號為止。 如果多個物件收到訊號,函式會傳回陣列中物件已發出訊號的第一個控制碼索引。
如果執行緒呼叫函式來檢查佇列之後,訊息佇列中指定類型的未讀取輸入,MsgWaitForMultipleObjects不會傳回。 這是因為 PeekMessage、 GetMessage、 GetQueueStatus和 WaitMessage 等函式會檢查佇列,然後變更佇列的狀態資訊,讓輸入不再被視為新。 後續對 MsgWaitForMultipleObjects 的呼叫將不會傳回,直到指定類型的新輸入到達為止。 上次執行緒檢查佇列) 之前收到的現有未讀取輸入 (。
函式會修改某些同步處理物件類型的狀態。 修改只會針對發出訊號狀態導致函式傳回的物件或物件進行修改。 例如,旗號物件的計數會減少一個。 如需詳細資訊,請參閱個別同步處理物件的檔。
MsgWaitForMultipleObjects函式可以指定pHandles陣列中下列任何物件類型的控制碼:
- 變更通知
- 主控台輸入
- 事件
- 記憶體資源通知
- Mutex
- 處理序
- Semaphore
- Thread
- 可等候的計時器
規格需求
最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
最低支援的伺服器 | Windows Server 2003 [僅限傳統型應用程式] |
目標平臺 | Windows |
標頭 | winuser.h (包括 Windows.h) |
程式庫 | User32.lib |
DLL | User32.dll |