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

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

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

ハンドルには、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
この関数は、スレッドが待機状態にある間に、QueueUserAPC を使用して APC がスレッドにキューに登録されている場合も返します。
MWMO_INPUTAVAILABLE
0x0004
PeekMessageなど、別の関数の呼び出しを使用して入力が表示された (削除されていない) 場合でも、関数はキューの入力が存在する場合 返します。
MWMO_WAITALL
0x0001
この関数は、pHandles 配列内のすべてのオブジェクトがシグナル通知され、入力イベントがすべて同時に受信されたときに返されます。

戻り値

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

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

この値は、フォアグラウンドのアクティブ化など、スレッドのアクションを必要とするシステム イベントが発生したときにも返されます。 したがって、適切な入力が使用できなくても、dwWakeMask が 0 に設定されている場合でも、MsgWaitForMultipleObjectsEx 返すことができます。 この場合は、GetMessage 呼び出すか、PeekMessageしてシステム イベントを処理してから、MsgWaitForMultipleObjectsEx 再度呼び出してください。

WAIT_ABANDONED_0 to (WAIT_ABANDONED_0 + nCount - 1)
MWMO_WAITALL フラグが使用されている場合、指定した範囲内の戻り値は、指定されたすべてのオブジェクトの状態が通知され、少なくとも 1 つのオブジェクトが破棄されたミューテックス オブジェクトであることを示します。 それ以外の場合、戻り値から WAIT_ABANDONED_0 を引いた値は、関数が返される原因となった破棄されたミューテックス オブジェクトの配列インデックス pHandles を示します。 ミューテックス オブジェクトの所有権は呼び出し元のスレッドに付与され、ミューテックスは非署名に設定されます。

ミューテックスが永続的な状態情報を保護していた場合は、整合性を確認する必要があります。

WAIT_IO_COMPLETION
0x000000C0L
スレッドにキューに入 (APC) の非同期プロシージャ呼び出し 、1 つ以上のユーザー モードによって待機が終了しました。
WAIT_TIMEOUT
258L
タイムアウト間隔は経過しましたが、dwFlags および dwWakeMask パラメーター 指定された条件が満たされませんでした。
WAIT_FAILED
(DWORD)0xFFFFFFFF
関数が失敗しました。 拡張エラー情報を取得するには、GetLastError呼び出します。

備考

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

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

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

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

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

  • 変更通知
  • コンソール入力
  • 出来事
  • メモリ リソース通知
  • ミューテックス
  • 過程
  • セマフォ
  • 待機可能タイマー

必要条件

要件 価値
サポートされる最小クライアント Windows XP [デスクトップ アプリのみ]
サポートされる最小サーバー Windows Server 2003 [デスクトップ アプリのみ]
ターゲット プラットフォーム の ウィンドウズ
ヘッダー winuser.h (Windows.h を含む)
ライブラリ User32.lib
DLL User32.dll

関連項目

同期関数の

待機関数の