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.)

傳回碼/值 描述
WAIT_OBJECT_0 (WAIT_OBJECT_0 + nCount– 1)
如果 bWaitAll 為 TRUE，則指定範圍內的傳回值表示所有指定物件的狀態都會發出訊號。 如果 bWaitAll 為 FALSE，傳回值減 去WAIT_OBJECT_0 表示滿足等候之物件的 pHandles 陣列索引。
+ WAIT_OBJECT_0nCount
 dwWakeMask參數中指定的類型新輸入可線上程的輸入佇列中使用。 PeekMessage、GetMessage 和 WaitMessage等函式會將佇列中的訊息標示為舊訊息。 因此，在您呼叫其中一個函式之後， 後續呼叫 MsgWaitForMultipleObjects 將不會傳回，直到指定型別的新輸入到達為止。

這個值也會在發生需要執行緒動作的系統事件時傳回，例如前景啟用。 因此，即使沒有適當的輸入，而且dwWakeMask設定為 0，MsgWaitForMultipleObjects仍可傳回。 如果發生這種情況，請先呼叫 GetMessage 或 PeekMessage 來處理系統事件，然後再嘗試呼叫 MsgWaitForMultipleObjects 。
WAIT_ABANDONED_0 (WAIT_ABANDONED_0 + nCount – 1)
如果 bWaitAll 為 TRUE，則指定範圍內的傳回值表示所有指定物件的狀態都會發出訊號，而且至少有一個物件是已放棄的 mutex 物件。 如果 bWaitAll 為 FALSE，則傳回值減 去WAIT_ABANDONED_0 表示已放棄 Mutex 物件的 pHandles 陣列索引，該物件滿足等候。 Mutex 物件的擁有權會授與呼叫執行緒，且 mutex 會設定為非簽署。

如果 mutex 正在保護持續性狀態資訊，您應該檢查其是否一致性。
WAIT_TIMEOUT
258L
 逾時間隔已經過，且 不符合 bWaitAll 和 dwWakeMask 參數所指定的條件。
WAIT_FAILED
(DWORD) 0xFFFFFFFF
 函式失敗。 若要取得擴充的錯誤資訊，請呼叫 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

另請參閱

MsgWaitForMultipleObjectsEx

同步處理函式

Wait 函式