CcPreparePinWrite 函式（ntifs.h）

發行項
12/21/2024

CcPreparePinWrite 例程會釘選快取檔案的指定位元組範圍以進行寫入存取。

語法

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

參數

[in] FileObject

要寫入數據的快取檔案之檔案物件的指標。

[in] FileOffset

變數的指標，指定要寫入資料之檔案中的起始位移。

[in] Length

所需的數據位元組長度。

[in] Zero

如果緩衝區在傳回時為零，則設定為 TRUE。如果在 Flags 參數中設定PIN_CALLER_TRACKS_DIRTY_DATA旗標，則會忽略此參數。

[in] Flags

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

價值	意義
PIN_WAIT	呼叫端可以放入等候狀態，直到數據已釘選為止。
PIN_EXCLUSIVE	緩衝區控制區塊（BCB）是獨佔取得。
PIN_NO_READ	只有已駐紮在記憶體中的頁面才會釘選。如果已設定此旗標，也必須設定PIN_WAIT。
PIN_IF_BCB	只有在 BCB 已經存在時，才會釘選數據。否則，針腳會失敗，而且不會傳回BCB。
PIN_CALLER_TRACKS_DIRTY_DATA	呼叫端負責追蹤髒頁面。如果設定此旗標，則會忽略所有其他旗標。此旗標可在 windows Server 2003 SP1 和更新版本Microsoft取得。

[out] Bcb

固定緩衝區控制區塊（BCB）的不透明指標。此指標必須做為輸入，才能在此緩衝區的任何後續呼叫上，CcPreparePinWrite 或 CcUnpinData。

[out] Buffer

傳回所需數據的指標，直到緩衝區取消釘選或釋放為止。

傳回值

CcPreparePinWrite 傳回 true 如果已成功釘選快取的檔案，FALSE。

言論

CcPreparePinWrite 在系統快取中釘選指定的檔案頁面。要完全覆寫的頁面可能會對零頁感到滿意。

如果已設定PIN_WAIT旗標，CcPreparePinWrite 保證可以完成準備要求，並傳回 TRUE。如果可以立即準備所有頁面，則不會發生任何封鎖。如果任何必要的頁面都不是常駐頁面，則呼叫端會處於等候狀態，直到所有必要頁面都已進入常駐狀態，而且頁面可以準備好。如果未設定PIN_WAIT旗標，但無法立即準備所有頁面，CcPreparePinWrite 會傳回 FALSE，且其輸出參數值毫無意義。

Microsoft Windows Server 2003 SP1 和更新版本： 檔案系統管理寫入但無法讀取的記錄檔時，通常會使用 PIN_CALLER_TRACKS_DIRTY_DATA 旗標。由於會覆寫現有的檔案數據，且不會讀取，因此快取管理員可能會傳回零頁，而不是從磁碟傳回檔案數據的實際頁面發生錯誤。如果設定此旗標，快取管理員不會追蹤髒頁面。呼叫端負責追蹤任何髒頁面。請注意，CcPreparePinWrite 只有在緩衝區最終會排清到磁碟時，才應該以此方式釘選數據。呼叫 CcFlushCache 將緩衝區排清到磁碟之前，呼叫者必須先呼叫 MmSetAddressRangeModified，以通知記憶體管理員系統快取緩衝區中的指定頁面已變更且應該寫入。

每次成功呼叫 CcPreparePinWrite，都必須符合對 CcUnpinData的後續呼叫。如果 相同數據的 CcPreparePinWrite 多次呼叫，CcUnpinData 必須呼叫相同的次數。

Buffer 中傳回的指標有效，直到呼叫 ccUnpinData 為止。如果呼叫 CcPinMappedData，而此指標仍然有效，則指標在呼叫 CcPinMappedData 之後仍有效（但直到呼叫 CcUnpinData 為止）。

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

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

呼叫 CcPreparePinWrite之後，不需要呼叫 CcSetDirtyPinnedData。如果 CcPreparePinWrite 傳回 true，BCB 已標示為已變更。

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