CcPinRead 函式 (ntifs.h)

發行項
02/26/2024

CcPinRead 例程會釘選快取檔案的指定位元組範圍，並將釘選的數據讀入記憶體中的緩衝區。

語法

BOOLEAN CcPinRead(
  [in]  PFILE_OBJECT   FileObject,
  [in]  PLARGE_INTEGER FileOffset,
  [in]  ULONG          Length,
  [in]  ULONG          Flags,
  [out] PVOID          *Bcb,
  [out] PVOID          *Buffer
);

參數

[in] FileObject

要釘選數據範圍之快取檔案對象的檔案對象指標。

[in] FileOffset

變數的指標，指定所需數據所在之快取檔案內的起始位移。

[in] Length

所需數據以位元組為單位的長度。

[in] Flags

旗標的位掩碼，指定如何執行釘選作業。下列一或多個值的 ORed 組合：

值	意義
PIN_WAIT	呼叫端可以進入等候狀態，直到數據已釘選為止。
PIN_EXCLUSIVE	BCB) (緩衝區控制區塊是以獨佔方式取得。如果設定此旗標，也必須設定PIN_WAIT。
PIN_NO_READ	只有已駐留在記憶體中的頁面才會釘選。如果設定此旗標，也必須設定PIN_WAIT。
PIN_IF_BCB	只有在 BCB 已經存在時，才會釘選數據。否則，針腳會失敗，且 Bcb 設定為 NULL。

[out] Bcb

在第一次呼叫時，這會傳回緩衝區控制區塊的指標， (BCB) 。這個指標必須提供為此緩衝區的所有後續呼叫做為輸入。

[out] Buffer

包含已釘選數據的緩衝區指標。

傳回值

如果已釘選並成功讀取快取檔案的數據，CcPinRead 會傳回 TRUE，否則傳回 FALSE。

備註

如果已設定PIN_WAIT旗標， 則 CcPinRead 保證會完成釘選要求並傳回 TRUE。如果快取檔案的必要頁面已經駐留在記憶體中，則會立即釘選數據，而且不會發生封鎖。如果有任何必要的頁面未存在，則呼叫端會處於等候狀態，直到所有必要頁面都已存在且數據可以釘選為止。如果未設定PIN_WAIT旗標，但無法立即釘選數據， CcPinRead 會傳回 FALSE，而且其輸出參數值沒有意義。

如果呼叫端後續修改 CcPinRead 讀取的數據，它也必須呼叫 CcSetDirtyPinnedData ，讓修改的數據最終會寫入磁碟。

每次成功呼叫 CcPinRead 都必須與後續對 CcUnpinData 的呼叫進行比對。

在 Buffer 中傳回的指標有效，直到呼叫 CcUnpinData 為止。如果在這個指標仍然有效時呼叫 CcPinMappedData ，則在呼叫 CcPinMappedData (之後，指標仍然有效，但只有在 呼叫 CcUnpinData) 為止。

CcPinRead 無法在快取管理員中跨檢視界限釘選數據。快取管理員會在 256 KB 對齊的檢視中管理系統中的檔案。 (快取管理員的檢視大小是由系統定義的常數VACB_MAPPING_GRANULARITY所指定，這會在 ntifs.h.) 釘選區域中設定為 256 KB，無法跨越一個以上的 256 KB 檢視。因此，可釘選的最大區域是 256 KB，從檔案中的 256 KB 對齊位移開始。

將位元組範圍釘選在快取的檔案中，並不可確保頁面保留在記憶體中。只要釘選頁面，位元組範圍就保證會持續對應到系統快取虛擬位址空間，但記憶體管理員可以在系統記憶體需求需要時分頁出實體頁面。

如果發生任何失敗， CcPinRead 會針對該特定失敗引發狀態例外狀況。例如，如果發生集區配置失敗， CcPinRead 會引發STATUS_INSUFFICIENT_RESOURCES例外狀況;如果發生 I/O 錯誤， CcPinRead 會引發 I/O 錯誤的狀態例外狀況。因此，若要控制是否發生失敗，驅動程式應該在 try-except 或 try-finally 語句中包裝對 CcPinRead 的呼叫。

若要對應快取檔案的數據，請使用 CcMapData 例程。若要快取檔案，請使用 CcInitializeCacheMap。