CcPinMappedData 函式（ntifs.h）

發行項
12/21/2024

CcPinMappedData 例程會釘選快取檔案的指定位元組範圍。

語法

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

參數

[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。

[in, out] Bcb

在第一次呼叫時，這會傳回緩衝區控件區塊（BCB）的指標。此指標必須做為此緩衝區所有後續呼叫的輸入。

傳回值

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

言論

從 CcPinMappedData 成功傳回，可確保先前在呼叫 CcMapData 中的數據會釘選在快取中，而且可以安全地修改指定範圍中的數據。如果呼叫端後續修改由 CcPinMappedData釘選的數據，它也必須呼叫 CcSetDirtyPinnedData，讓修改的數據最終會寫入磁碟。

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

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

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

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

呼叫 CcPinMappedData 之後，不需要呼叫 CcUnpinData，因為釘選參考會比對 CcMapData。