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 日) 相對。
  • 如果逾時值為零， WdfWaitLockAcquire 會嘗試取得鎖定，然後立即傳回，不論它是否已取得鎖定。
相對到期時間不會受到在指定逾時期間內可能發生之系統時間的任何變更所影響。 絕對到期時間確實會反映系統時間變更。

架構提供 時間轉換函式 ，可將時間值轉換成系統時間單位。

如果呼叫端提供 NULL 指標，方法會無限期等候，直到取得鎖定為止。

傳回值

WdfWaitLockAcquire 可以傳回下列 NTSTATUS 值：

傳回碼 Description
STATUS_SUCCESS
 呼叫端已取得等候鎖定。
STATUS_TIMEOUT
 指定的 逾 時間隔在取得鎖定之前過期。
 

請注意， NT_SUCCESS ( 狀態) 所有這些狀態值都等於 TRUE 。

如果 Timeout 指標為 NULL，則呼叫端不需要檢查傳回值，因為在此情況下 ，WdfWaitLockAcquire 只會在取得鎖定之後傳回。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

備註

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);

規格需求

需求 值
目標平台 Universal
最低 KMDF 版本 1.0
最低UMDF版本 2.0
標頭 wdfsync.h (包含 Wdf.h)
程式庫 Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL 請參閱一節。
DDI 合規性規則 DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf) 、 WdfWaitlock (kmdf) 、 WdfWaitlockRelease (kmdf)

另請參閱

KeEnterCriticalRegion

WdfWaitLockCreate

WdfWaitLockRelease