WaitForSingleObject 関数 (synchapi.h)

  • [アーティクル]

指定されたオブジェクトがシグナル状態であるか、タイムアウト間隔が経過するまで待機します。

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

構文

DWORD WaitForSingleObject(
  [in] HANDLE hHandle,
  [in] DWORD  dwMilliseconds
);

パラメーター

[in] hHandle

オブジェクトへのハンドル。 ハンドルを指定できるオブジェクトの種類の一覧については、次の「解説」セクションを参照してください。

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

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

[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 値には低電力状態で経過した時間は含まれません。 たとえば、コンピューターがスリープ状態の間、タイムアウトのカウント ダウンは継続されません。

戻り値

関数が成功した場合、戻り値は、関数が返される原因となったイベントを示します。 次のいずれかの値を指定できます。

リターン コード/値 Description
WAIT_ABANDONED
0x00000080L
 指定されたオブジェクトは、所有しているスレッドが終了する前にミューテックス オブジェクトを所有していたスレッドによって解放されなかったミューテックス オブジェクトです。 ミューテックス オブジェクトの所有権は呼び出し元のスレッドに付与され、ミューテックスの状態は非署名に設定されます。

ミューテックスが永続的な状態情報を保護していた場合は、一貫性のためにチェックする必要があります。
WAIT_OBJECT_0
0x000000000L
 指定したオブジェクトの状態が通知されます。
WAIT_TIMEOUT
0x00000102L
 タイムアウト間隔が経過し、オブジェクトの状態が非割り当てです。
WAIT_FAILED
(DWORD)0xFFFFFFFF
 関数が失敗しました。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

WaitForSingleObject 関数は、指定されたオブジェクトの現在の状態を確認します。 オブジェクトの状態が非署名の場合、呼び出し元のスレッドは、オブジェクトが通知されるかタイムアウト間隔が経過するまで待機状態になります。

関数は、一部の種類の同期オブジェクトの状態を変更します。 変更は、シグナル状態によって関数が返されたオブジェクトに対してのみ行われます。 たとえば、セマフォ オブジェクトの数は 1 ずつ減少します。

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

  • 変更通知
  • コンソール入力
  • イベント
  • メモリ リソース通知
  • Mutex
  • Process
  • Semaphore
  • スレッド
  • 待機可能タイマー
直接または間接的にウィンドウを作成する待機関数とコードを呼び出す場合は注意が必要です。 スレッドがウィンドウを作成する場合は、メッセージを処理する必要があります。 メッセージ ブロードキャストは、システム内のすべてのウィンドウに送信されます。 タイムアウト間隔のない待機関数を使用するスレッドによって、システムがデッドロックする可能性があります。 ウィンドウを間接的に作成するコードの例として、DDE と CoInitialize 関数の 2 つがあります。 したがって、ウィンドウを作成するスレッドがある場合は、WaitForSingleObject ではなく、MsgWaitForMultipleObjects または MsgWaitForMultipleObjectsEx を使用します。

例

例については、「 ミューテックス オブジェクトの使用」を参照してください。

要件

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

関連項目

同期関数

待機関数