共用方式為

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 值：

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

請注意，這些狀態值 NT_SUCCESS（status） 等於 TRUE。

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

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

言論

WdfWaitLockAcquire 方法不會傳回，直到取得等候鎖定或逾時期間到期為止。

WdfWaitLockAcquire 呼叫 KeEnterCriticalRegion，再取得等候鎖定。 因此，當方法傳回時，一般核心 API 停用。 WdfWaitLockAcquire 不會改變呼叫者的 IRQL。

如果 逾時 指標 NULL，或逾時值不是零，WdfWaitLockAcquire 必須在 IRQL = PASSIVE_LEVEL呼叫。

如果逾時值為零，則必須在 IRQL < DISPATCH_LEVEL 呼叫 WdfWaitLockAcquire 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）
連結庫 Wdf01000.sys （KMDF）：WUDFx02000.dll （UMDF）
IRQL 請參閱一節。
DDI 合規性規則 DriverCreate（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicitit（kmdf），WdfWaitlock（kmdf），WdfWaitlockRelease（kmdf）

另請參閱

KeEnterCriticalRegion

WdfWaitLockCreate

WdfWaitLockRelease