CcPinRead 函式（ntifs.h）

發行項
12/21/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 如果快取檔案的數據已釘選並成功讀取，FALSE，則傳 回 true。

言論

如果已設定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。