MsgWaitForMultipleObjects 関数 (winuser.h)

  • [アーティクル]

指定したオブジェクトの 1 つ以上がシグナル状態であるか、タイムアウト間隔が経過するまで待機します。 オブジェクトには、 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 マイナス 1 です。 このパラメーターの値が 0 の場合、関数は入力イベントのみを待機します。

[in] pHandles

オブジェクト ハンドルの配列。 ハンドルを指定できるオブジェクトの種類の一覧については、次の「解説」セクションを参照してください。 配列には、さまざまな型のオブジェクトのハンドルを含めることができます。 同じハンドルの複数のコピーが含まれていない場合があります。

待機がまだ保留中の間にこれらのハンドルの 1 つが閉じている場合、関数の動作は未定義です。

ハンドルには SYNCHRONIZE アクセス権が必要です。 詳細については、「 Standard Access Rights」を参照してください。

[in] fWaitAll

このパラメーターが TRUE の場合、 関数は、pHandles 配列内のすべてのオブジェクトの状態が signaled に設定され、入力イベントが受信されたときにを返します。 このパラメーターが FALSE の場合、いずれかのオブジェクトの状態が signaled に設定されているか、入力イベントが受信されたときに、関数は を返します。 この場合、戻り値は、関数が戻る原因となった状態のオブジェクトを示します。

[in] dwMilliseconds

タイムアウト間隔 (ミリ秒単位)。 0 以外の値を指定した場合、関数は、指定したオブジェクトがシグナル通知されるか、間隔が経過するまで待機します。 dwMilliseconds が 0 の場合、指定したオブジェクトがシグナル通知されない場合、関数は待機状態になりません。常にすぐに返されます。 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

入力イベント オブジェクト ハンドルがオブジェクト ハンドルの配列に追加される入力型。 このパラメーターには、 GetQueueStatusflags パラメーターに記載されている値の任意の組み合わせを指定できます。

戻り値

関数が成功した場合、戻り値は関数が戻る原因となったイベントを示します。 次のいずれかの値を指定できます。 ( 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 の場合、指定した範囲内の戻り値は、指定されたすべてのオブジェクトの状態がシグナル通知され、少なくとも 1 つのオブジェクトが破棄されたミューテックス オブジェクトであることを示します。 bWaitAll が FALSE の場合、戻り値から WAIT_ABANDONED_0 を引いた値は、待機を満たす破棄されたミューテックス オブジェクトの pHandles 配列インデックスを示します。 ミューテックス オブジェクトの所有権は呼び出し元のスレッドに付与され、ミューテックスは非署名に設定されます。

ミューテックスが永続的な状態情報を保護していた場合は、整合性を確認する必要があります。
WAIT_TIMEOUT
258L
 タイムアウト間隔が経過し、 bWaitAll パラメーターと dwWakeMask パラメーターで指定された条件が満たされませんでした。
WAIT_FAILED
(DWORD)0xFFFFFFFF
 関数が失敗しました。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

MsgWaitForMultipleObjects 関数は、待機条件が満たされているかどうかを判断します。 条件が満たされていない場合、呼び出し元のスレッドは、待機条件の条件が満たされるかタイムアウト間隔が経過するまで待機状態になります。

bWaitAll が TRUE の場合、関数は、すべてのオブジェクトの状態が signaled に設定されるまで、指定されたオブジェクトの状態を変更しません。 たとえば、ミューテックスはシグナル処理できますが、他のオブジェクトの状態も signaled に設定されるまで、スレッドは所有権を取得しません。 それまでは、他のスレッドがミューテックスの所有権を取得し、その状態を非署名に設定する場合があります。

bWaitAll が TRUE の場合、関数の待機は、すべてのオブジェクトの状態が signaled に設定され、入力イベントが受信された場合にのみ完了します。 したがって、 bWaitAllを TRUE に設定すると、 pHandles 配列内のすべてのオブジェクトの状態が signaled に設定されるまで、入力が処理されなくなります。 このため、 bWaitAll を TRUE に設定した場合は、 dwMilliseconds で短いタイムアウト値を使用する必要があります。 タイムアウト間隔なしで dwWakeMask で指定された入力イベントを含む、pHandles 配列内のすべてのオブジェクトを待機しているウィンドウを作成するスレッドがある場合、システムはデッドロックします。 これは、ウィンドウを作成するスレッドがメッセージを処理する必要があるためです。 DDE は、システム内のすべてのウィンドウにメッセージを送信します。 したがって、スレッドがウィンドウを作成する場合は、そのスレッドから行われた MsgWaitForMultipleObjects の呼び出しで bWaitAll パラメーターを TRUE に設定しないでください。

bWaitAll が FALSE の場合、この関数は、オブジェクトの 1 つがシグナル通知されるまで、インデックス 0 から始まる順序で配列内のハンドルをチェックします。 複数のオブジェクトがシグナル化された場合、関数はオブジェクトがシグナル化された配列内の最初のハンドルのインデックスを返します。

スレッドがキューをチェックする関数を呼び出した後、メッセージ キューに指定された型の未読入力がある場合、MsgWaitForMultipleObjects は返されません。 これは、 PeekMessage、 GetMessage、 GetQueueStatus、 WaitMessage などの関数がキューをチェックし、入力が新しいと見なされないようにキューの状態情報を変更するためです。 MsgWaitForMultipleObjects への後続の呼び出しは、指定した型の新しい入力が到着するまで戻りません。 既存の未読入力 (スレッドがキューを最後にチェックした前に受信) は無視されます。

関数は、一部の種類の同期オブジェクトの状態を変更します。 変更は、シグナル状態によって関数が返されたオブジェクトに対してのみ行われます。 たとえば、セマフォ オブジェクトの数は 1 ずつ減ります。 詳細については、個々の同期オブジェクトのドキュメントを参照してください。

MsgWaitForMultipleObjects 関数は、pHandles 配列内の次のいずれかのオブジェクト型のハンドルを指定できます。

  • 変更通知
  • コンソール入力
  • Event
  • メモリ リソース通知
  • Mutex
  • Process
  • Semaphore
  • スレッド
  • 待機可能タイマー

要件

   
サポートされている最小のクライアント Windows XP [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2003 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー winuser.h (Windows.h を含む)
Library User32.lib
[DLL] User32.dll

関連項目

MsgWaitForMultipleObjectsEx

同期関数

待機関数