共用方式為

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 為零，則不符合準則時，函式不會進入等候狀態;它一律會立即傳回。 如果 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、Windows 8.1、Windows Server 2012 R2、Windows 10 和 Windows Server 2016：dwMilliseconds 值不包含花費在低功率狀態的時間。 例如，當計算機處於睡眠狀態時，逾時不會持續倒數。

[in] dwWakeMask

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

[in] dwFlags

等候類型。 此參數可以是下列其中一或多個值。

價值 意義
0
 當任何物件發出訊號時，函式會傳回 。 傳回值表示導致函式傳回其狀態的物件。
MWMO_ALERTABLE
0x0002
 如果 APC 已排入 QueueUserAPC 的線程，當線程處於等候狀態時，函式也會傳回 。
MWMO_INPUTAVAILABLE
0x0004
 函式會傳回佇列的輸入是否存在，即使已使用對另一個函式的呼叫來看見輸入（但未移除），例如 PeekMessage。
MWMO_WAITALL
0x0001
 當 pHandles 陣列中的所有物件都發出訊號並同時收到輸入事件時，函式會傳回 。

傳回值

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

傳回碼/值 描述
WAIT_OBJECT_0 至 （WAIT_OBJECT_0 + nCount - 1）
 如果使用 MWMO_WAITALL 旗標，指定範圍內的傳回值會指出所有指定物件的狀態已發出訊號。 否則，傳回值減去 WAIT_OBJECT_0 表示造成函式傳回之物件的 pHandles 陣列索引。
WAIT_OBJECT_0 + nCount
 dwWakeMask 參數中指定的類型新輸入可在線程的輸入佇列中使用。 PeekMessage、GetMessage、GetQueueStatus等函式，以及 WaitMessage 將佇列中的訊息標示為舊訊息。 因此，在您呼叫其中一個函式之後，MsgWaitForMultipleObjectsEx 的後續呼叫將不會傳回，直到指定型別的新輸入到達為止。

這個值也會在發生需要線程動作的系統事件時傳回，例如前景啟用。 因此，MsgWaitForMultipleObjectsEx 即使沒有可用的適當輸入，即使 dwWakeMask 設定為 0，還是可以傳回 。 如果發生這種情況，請呼叫 GetMessage 或 PeekMessage 來處理系統事件，然後再嘗試呼叫 MsgWaitForMultipleObjectsEx。
WAIT_ABANDONED_0 至 （WAIT_ABANDONED_0 + nCount - 1）
 如果使用 MWMO_WAITALL 旗標，指定範圍內的傳回值會指出所有指定物件的狀態已發出訊號，而且至少有一個物件是已放棄的 Mutex 物件。 否則，傳回值減去 WAIT_ABANDONED_0 表示造成函式傳回之已放棄 mutex 物件的 pHandles 陣列索引。 Mutex 對象的擁有權會授與呼叫線程，且 mutex 會設定為非ignaled。

如果 Mutex 正在保護持續性狀態資訊，您應該檢查其是否一致性。
WAIT_IO_COMPLETION
0x000000C0L
 等候已由一或多個使用者模式結束，異步過程調用 （APC） 排入線程。
WAIT_TIMEOUT
258L
 逾時間隔經過，但不符合 dwFlags 和 dwWakeMask 參數所指定的條件。
WAIT_FAILED
（DWORD）0xFFFFFFFF
 函式失敗。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

言論

MsgWaitForMultipleObjectsEx 函式會判斷是否已符合 dwWakeMask 和 dwFlags 所指定的條件。 如果條件尚未符合，則呼叫線程會進入等候狀態，直到符合等候準則的條件或逾時間隔經過為止。

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

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

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

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

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

要求

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

另請參閱

同步處理函式

等候函式