CcPreparePinWrite 函式 (ntifs.h)

發行項
02/26/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	呼叫端負責追蹤已變更的頁面。如果已設定此旗標，則會忽略所有其他旗標。此旗標適用於 Microsoft Windows Server 2003 SP1 和更新版本。

[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 必須呼叫相同的次數。

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

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

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

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

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