MsgWaitForMultipleObjectsEx 関数 (winuser.h)

  • [アーティクル]

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

[in] pHandles

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

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

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

[in] dwMilliseconds

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

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

[in] dwFlags

待機の種類。 このパラメーターには、次の 1 つ以上の値を指定できます。

値 意味
0
 関数は、いずれかのオブジェクトがシグナル通知されると を返します。 戻り値は、関数が戻る原因となった状態のオブジェクトを示します。
MWMO_ALERTABLE
0x0002
 この関数は、スレッドが待機状態にある間に、 APC が QueueUserAPC を使用してスレッドにキューに登録されている場合にも を返します。
MWMO_INPUTAVAILABLE
0x0004
 関数は、 PeekMessage などの別の関数の呼び出しを使用して入力が見られた (削除されていない) 場合でも、キューの入力が存在する場合に を返します。
MWMO_WAITALL
0x0001
 関数は、 pHandles 配列内のすべてのオブジェクトがシグナル通知され、入力イベントが同時に受信されると を返します。

戻り値

関数が成功した場合、戻り値は関数が戻る原因となったイベントを示します。 次のいずれかの値を指定できます。 ( WAIT_OBJECT_0 は 0 として定義され、 WAIT_ABANDONED_0 は 0x00000080L として定義されていることに注意してください)。

リターン コード/値 Description
にWAIT_OBJECT_0 (WAIT_OBJECT_0 + nCount - 1)
 MWMO_WAITALL フラグを使用する場合、指定した範囲内の戻り値は、指定されたすべてのオブジェクトの状態がシグナル通知されることを示します。 それ以外の場合、戻り値 から WAIT_OBJECT_0 を引いた値は、関数が返される原因となったオブジェクトの pHandles 配列インデックスを示します。
+ WAIT_OBJECT_0nCount
 dwWakeMask パラメーターで指定された型の新しい入力は、スレッドの入力キューで使用できます。 PeekMessage、GetMessage、GetQueueStatus、WaitMessage などの関数は、キュー内のメッセージを古いメッセージとしてマークします。 したがって、これらの関数のいずれかを呼び出した後、指定した型の新しい入力が到着するまで 、MsgWaitForMultipleObjectsEx への後続の呼び出しは返されません。

この値は、フォアグラウンドのアクティブ化など、スレッドのアクションを必要とするシステム イベントが発生したときにも返されます。 したがって、適切な入力が使用できなくても、dwWakeMask が 0 に設定されている場合でも、MsgWaitForMultipleObjectsEx は を返すことができます。 この場合は、GetMessage または PeekMessage を呼び出してシステム イベントを処理してから、MsgWaitForMultipleObjectsEx の呼び出しを再試行してください。
にWAIT_ABANDONED_0 (WAIT_ABANDONED_0 + nCount - 1)
 MWMO_WAITALL フラグが使用されている場合、指定された範囲内の戻り値は、指定されたすべてのオブジェクトの状態がシグナル通知され、少なくとも 1 つのオブジェクトが破棄されたミューテックス オブジェクトであることを示します。 それ以外の場合、戻り値 から WAIT_ABANDONED_0 を引いた値は、関数が返される原因となった破棄されたミューテックス オブジェクトの pHandles 配列インデックスを示します。 ミューテックス オブジェクトの所有権は呼び出し元のスレッドに付与され、ミューテックスは非署名に設定されます。

ミューテックスが永続的な状態情報を保護していた場合は、整合性のためにチェックする必要があります。
WAIT_IO_COMPLETION
0x000000C0L
 待機は、スレッドにキューに入れた 1 つ以上のユーザー モード 非同期プロシージャ呼び出し (APC) によって終了しました。
WAIT_TIMEOUT
258L
 タイムアウト間隔が経過しましたが、 dwFlags パラメーターと dwWakeMask パラメーターで指定された条件が満たされませんでした。
WAIT_FAILED
(DWORD)0xFFFFFFFF
 関数が失敗しました。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

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

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

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

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

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

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

要件

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

こちらもご覧ください

同期関数

待機関数