NdisAcquireRWLockRead 函式 (ndis.h)

發行項
02/29/2024

NdisAcquireRWLockRead 函式會取得讀取鎖定，讓呼叫端用來讀取存取驅動程式線程之間共用的資源。

語法

void NdisAcquireRWLockRead(
  [in]  PNDIS_RW_LOCK_EX Lock,
  [out] PLOCK_STATE_EX   LockState,
  [in]  UCHAR            Flags
);

參數

[in] Lock

代表鎖定之不透明 NDIS_RW_LOCK_EX 變數的指標。呼叫端可以使用此鎖定來取得非ISR驅動程式線程之間共用之資源的寫入或讀取許可權。

[out] LockState

追蹤鎖定狀態之不透明 LOCK_STATE_EX 變數的指標。此變數存在於呼叫端取得和釋放鎖定之間的間隔。呼叫端必須針對每次嘗試從相同的非ISR驅動程式線程取得鎖定時，使用不同的類型變數 LOCK_STATE_EX 。

[in] Flags

包含鎖定旗標的 ULONG 值。如果呼叫端目前的 IRQL DISPATCH_LEVEL，請將此參數設定為NDIS_RWL_AT_DISPATCH_LEVEL。否則，請將此參數設定為零。如需分派 IRQL 追蹤的詳細資訊，請參閱分派 IRQL 追蹤。

注意如果呼叫端知道目前的 IRQL DISPATCH_LEVEL，請將此參數設定為 NDIS_RWL_AT_DISPATCH_LEVEL。此旗標可讓鎖定更有效率，方法是省略目前 IRQL 的檢查。如果目前的 IRQL 未知，請勿使用 KeGetCurrentIrql 測試目前的 IRQL ，以判斷是否要設定此旗標，因為允許 NdisAcquireRWLockRead 函式測試 IRQL 本身更有效率。

傳回值

無

備註

NDIS 驅動程式會呼叫 NdisAcquireRWLockRead 函式，以取得驅動程式線程之間共用資源的唯讀存取權。

驅動程式必須在驅動程式呼叫 NdisAcquireRWLockRead 函式之前，使用 NdisAllocateRWLock 函式來配置類型NDIS_RW_LOCK_EX變數。

驅動程式呼叫 NdisAllocateRWLock 之後，它可以呼叫 NdisAcquireRWLockWrite 或 NdisAcquireRWLockRead 來取得資源的寫入或讀取許可權。一次只有一個非ISR驅動程式線程可以取得資源的寫入許可權。當一個非ISR線程具有寫入許可權時，其他非ISR線程的所有讀取和寫入存取都必須等到寫入許可權持有者釋放鎖定為止。不過，如果非ISR線程具有讀取許可權，其他非ISR線程可以同時取得讀取許可權。

NDIS_RW_LOCK_EX鎖定不支援從讀取升級為寫入。一旦處理器藉由呼叫 NdisAcquireRWLockRead) 來取得讀取存取 (NDIS_RW_LOCK_EX，相同的處理器便不能呼叫 NdisAcquireRWLockWrite) ，嘗試取得寫入存取權 (，直到釋放先前的讀取存取權為止。

您可以在相同的處理器上以遞歸方式取得 NDIS_RW_LOCK_EX 讀取鎖定。對於 NdisAcquireRWLockRead 的每個呼叫，都必須有對應的 NdisReleaseRWLock 呼叫。只有在 上次呼叫 NdisReleaseRWLock 之後，才會釋放鎖定。

驅動程式無法使用鎖定來保護資源，使其其他函式與 MiniportInterrupt 共用的讀取或寫入存取權 MiniportDisableInterruptEx 函式或兩者。相反地，驅動程式必須呼叫 NdisMSynchronizeWithInterruptEx ，使其 MiniportSynchronizeInterrupt 函式會在其 MiniportInterrupt 或相同的 DIRQL 存取這類共用資源 MiniportDisableInterruptEx 函 式，或兩者皆可執行。

NdisAcquireRWLockRead 一律會將 IRQL 引發至 IRQL = DISPATCH_LEVEL。

規格需求

需求	值
最低支援的用戶端	NDIS 6.20 和更新版本支援。
目標平台	Universal
標頭	ndis.h (包含 Ndis.h)
程式庫	Ndis.lib
IRQL	<= DISPATCH_LEVEL