次のいずれかが成立すると、制御を返します。

•指定されたオブジェクトがシグナル状態になった。

•タイムアウト時間が経過した。

アラート可能な待機状態に入るには、WaitForMultipleObjectsEx 関数を使います。複数のオブジェクトを待機するには、WaitForMultipleObjects 関数を使います。

DWORD WaitForSingleObject(
  HANDLE hHandle,        // オブジェクトのハンドル
  DWORD dwMilliseconds   // タイムアウト時間
);

パラメータ

hHandle

オブジェクトのハンドルを指定します。ハンドルを指定できるオブジェクトのタイプについては、この関数の「解説」を参照してください。

ハンドルが待機状態で未処理になっているときに、そのハンドルを閉じた場合、この関数の動作は未定義です。

Windows NT/2000：このハンドルに、SYNCHRONIZE アクセス権を割り当てておかなければなりません。詳細については、MSDN ライブラリの「」を参照してください。

dwMilliseconds

タイムアウト時間を、ミリ秒（ms）単位で指定します。タイムアウト時間が経過すると、オブジェクトが非シグナル状態であっても、制御を返します。0 を指定すると、この関数は指定されたオブジェクトの状態を調べ、即座に制御を返します。INFINITE を指定すると、オブジェクトがシグナル状態になるまで待機し続けます。

戻り値

関数が成功すると、関数が制御を返した原因が返ります。次の値のいずれかになります。

関数が失敗すると、WAIT_FAILED が返ります。拡張エラー情報を取得するには、 関数を使います。

解説

WaitForSingleObject 関数は、指定されたオブジェクトの現在の状態をチェックします。そのオブジェクトが非シグナル状態である場合、呼び出し側スレッドは待機状態に入ります。オブジェクトがシグナル状態になるかタイムアウト時間が経過するのを待機している間、そのスレッドはプロセッサ時間を消費しません。

この関数は、特定のタイプの同期オブジェクトの状態を変更します。指定されたオブジェクトがシグナル状態になり、それが原因で関数が制御を返した場合にのみ、そのオブジェクトに変更を加えます。たとえば、セマフォオブジェクトのカウントを 1 つ減らします。

この関数は、次のオブジェクトを待機することができます。

•変更の通知

•コンソール入力

•イベント

•ジョブ

•ミューテックス

•プロセス

•セマフォ

•スレッド

•待機可能なタイマ

詳細については、MSDN ライブラリの「」を参照してください。

この待機関数と、ウィンドウを直接的または間接的に作成するコードを組み合わせて使う場合は、注意が必要です。1 つのスレッドがウィンドウを作成した場合、そのスレッドはそのウィンドウに関係するメッセージを処理しなければなりません。また、メッセージのブロードキャスト（同報送信）が発生した場合、システム内のすべてのウィンドウへそのメッセージが送信されます。タイムアウト時間として INFINITE を指定して待機関数を呼び出していた場合、このような現象が発生すると、システムはデッドロック状態に陥ることがあります。ウィンドウを間接的に作成する 2 つの例として、DDE と COM の CoInitialize があります。そのため、ウィンドウを作成するスレッドでは、WaitForSingleObject 関数ではなく、MsgWaitForMultipleObjects または MsgWaitForMultipleObjectsEx 関数を使ってください。

対応情報

Windows NT/2000：Windows NT 3.1 以降
Windows 95/98：Windows 95 以降
ヘッダー：Winbase.h 内で宣言、Windows.h をインクルード
インポートライブラリ：Kernel32.lib を使用

参照

MsgWaitForMultipleObjects, MsgWaitForMultipleObjectsEx, WaitForMultipleObjects, WaitForSingleObjectEx