CcPinMappedData 函式 (ntifs.h)

發行項
02/29/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，否則為 FALSE。

備註

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

CcPinMappedData 無法跨快取管理員中的檢視界限釘選數據。快取管理員會在 256 KB 對齊的檢視中管理系統中的檔案。 (快取管理員的檢視大小是由系統定義的常數 VACB_MAPPING_GRANULARITY所指定，其設定為 ntifs.h.) Pinned 區域中的 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 相符。