WdfWaitLockAcquire 函数 (wdfsync.h)

  • 项目

[适用于 KMDF 和 UMDF]

WdfWaitLockAcquire 方法获取指定的等待锁。

语法

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

参数

[in] Lock

框架 wait-lock 对象的句柄，由对 WdfWaitLockCreate 的先前调用获取。

[in, optional] Timeout

指向超时值的可选指针。 超时值以系统时间单位 (100 纳秒间隔) 指定。

如果指针为非 NULL，则框架将取消获取锁的尝试（如果未在指定的超时期限内完成）。 超时值可以是负、正或零，如下所示：

  • 如果超时值为负值，则过期时间相对于当前系统时间。
  • 如果超时值为正值，则到期时间指定为绝对时间 (实际上相对于 1601 年 1 月 1 日) 。
  • 如果超时值为零， 则 WdfWaitLockAcquire 将尝试获取锁，然后立即返回，无论它是否已获取锁。
相对过期时间不受在指定超时期限内可能发生的系统时间的任何更改的影响。 绝对过期时间确实反映了系统时间更改。

框架提供 时间转换函数 ，用于将时间值转换为系统时间单位。

如果调用方提供 NULL 指针，该方法将无限期等待，直到获取锁。

返回值

WdfWaitLockAcquire 可以返回以下 NTSTATUS 值：

返回代码 说明
STATUS_SUCCESS
 调用方已获取等待锁。
STATUS_TIMEOUT
 指定的 超时 间隔在获取锁之前过期。
 

请注意 ，对于 所有这些状态值，NT_SUCCESS (状态) 等于 TRUE 。

如果 Timeout 指针为 NULL，调用方不必检查返回值，因为在这种情况下，WdfWaitLockAcquire 仅在获取锁后返回。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

注解

WdfWaitLockAcquire 方法在获取等待锁或超时期限到期之前不会返回。

WdfWaitLockAcquire 在获取等待锁之前调用 KeEnterCriticalRegion 。 因此，当方法返回时， 将禁用正常的内核 APC 。 WdfWaitLockAcquire 不会更改调用方 IRQL。

如果 Timeout 指针为 NULL，或者超时值不为零，则必须在 IRQL = PASSIVE_LEVEL调用 WdfWaitLockAcquire 。

如果超时值为零，则必须在 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
标头 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