WdfWaitLockAcquire 関数 (wdfsync.h)

  • [アーティクル]

[KMDF と UMDF に適用]

WdfWaitLockAcquire メソッドは、指定された待機ロックを取得します。

構文

NTSTATUS WdfWaitLockAcquire(
  [in]           WDFWAITLOCK Lock,
  [in, optional] PLONGLONG   Timeout
);

パラメーター

[in] Lock

WdfWaitLockCreate の以前の呼び出しによって取得されたフレームワーク待機ロック オブジェクトへのハンドル。

[in, optional] Timeout

タイムアウト値への省略可能なポインター。 タイムアウト値は、システム時間単位 (100 ナノ秒間隔) で指定されます。

ポインターが NULL 以外の場合、フレームワークは、指定されたタイムアウト期間内にロックが完了しなかった場合、ロックの取得の試行を取り消します。 タイムアウト値は、次のように負、正、またはゼロにすることができます。

  • タイムアウト値が負の場合、有効期限は現在のシステム時刻に対して相対的です。
  • タイムアウト値が正の場合、有効期限は絶対時間として指定されます (実際には 1601 年 1 月 1 日を基準とします)。
  • タイムアウト値が 0 の場合、 WdfWaitLockAcquire はロックの取得を試み、ロックを取得したかどうかに関係なく、直ちにを返します。
相対有効期限は、指定されたタイムアウト期間内に発生する可能性のあるシステム時間の変更の影響を受けません。 絶対有効期限は、システム時刻の変更を反映します。

フレームワークには、時間値をシステム時間単位に変換する時間 変換関数 が用意されています。

呼び出し元が NULL ポインターを提供する場合、メソッドはロックを取得するまで無期限に待機します。

戻り値

WdfWaitLockAcquire は、次の NTSTATUS 値を返すことができます。

リターン コード 説明
STATUS_SUCCESS
 呼び出し元が待機ロックを取得しました。
STATUS_TIMEOUT
 指定された タイムアウト 間隔は、ロックが取得される前に期限切れになりました。
 

NT_SUCCESS(status) は、これらのすべての状態値に対して TRUE に等しいことに注意してください。

タイムアウト ポインターが NULL の場合、呼び出し元は戻り値をチェックする必要はありません。その場合、WdfWaitLockAcquire はロックを取得した後にのみを返します。

ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。

注釈

WdfWaitLockAcquire メソッドは、待機ロックを取得するまで、またはタイムアウト期間が切れるまで戻りません。

WdfWaitLockAcquire は、待機ロックを取得する前に KeEnterCriticalRegion を呼び出します。 その結果、 メソッドが戻ると、通常の カーネル APC は 無効になります。 WdfWaitLockAcquire は、呼び出し元の IRQL を変更しません。

タイムアウト ポインターが NULL の場合、またはタイムアウト値が 0 でない場合は、IRQL = PASSIVE_LEVELで WdfWaitLockAcquire を呼び出す必要があります。

タイムアウト値が 0 の場合は、IRQL < DISPATCH_LEVELで WdfWaitLockAcquire を呼び出す必要があります。 これはヘッダー ファイル (wdfsync.h) と不一致です。これは、このメソッドをDISPATCH_LEVELで呼び出すことができることを示しています。

待機ロックの詳細については、「 Framework-Based ドライバーの同期手法」を参照してください。

例

次のコード例では、待機ロックを取得し、デバイス オブジェクトをオブジェクト コレクションに追加して、待機ロックを解放します。

WdfWaitLockAcquire(
                   FilterDeviceCollectionLock,
                   NULL
                   );
status = WdfCollectionAdd(
                          FilterDeviceCollection,
                          deviceHandle
                          );
if (!NT_SUCCESS(status)) {
    addFailed = TRUE;
}
WdfWaitLockRelease(FilterDeviceCollectionLock);

要件

要件 値
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.0
最小 UMDF バージョン 2.0
Header wdfsync.h (Wdf.h を含む)
Library Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL 「解説」を参照してください。
DDI コンプライアンス規則 DriverCreate(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、 WdfWaitlock(kmdf)、 WdfWaitlockRelease(kmdf)

こちらもご覧ください

KeEnterCriticalRegion

WdfWaitLockCreate

WdfWaitLockRelease