CcPrepareMdlWrite 函式（ntifs.h）

發行項
12/21/2024

CcPrepareMdlWrite 例程可讓您直接存取快取的檔案記憶體，讓呼叫端可以將數據寫入檔案。

語法

void CcPrepareMdlWrite(
  [in]  PFILE_OBJECT     FileObject,
  [in]  PLARGE_INTEGER   FileOffset,
  [in]  ULONG            Length,
  [out] PMDL             *MdlChain,
  [out] PIO_STATUS_BLOCK IoStatus
);

參數

[in] FileObject

快取檔案之檔案物件的指標。

[in] FileOffset

變數的指標，指定要寫入數據的快取檔案內的起始位移。

[in] Length

要寫入系統快取之數據的位元組長度。

[out] MdlChain

一或多個記憶體描述元的鏈結會列出描述要寫入數據的頁面。

[out] IoStatus

IO_STATUS_BLOCK 結構的指標。如果呼叫 CcPrepareMdlWrite 成功，IoStatus.Status 會設定為 STATUS_SUCCESS。否則，它會設定為適當的NTSTATUS錯誤碼。 IoStatus.Information 會設定為 MDL 鏈結中成功鎖定的實際位元組數目。

傳回值

沒有

言論

CcPrepareMdlWrite 類似於 CcCopyWrite，不同之處在於數據不會複製到快取的檔案。相反地，系統快取中要覆寫的實體頁面會鎖定在記憶體中，CcPrepareMdlWrite 會傳回描述指定位元組範圍的一或多個記憶體描述元清單（MDL）。在呼叫 CcMdlWriteAbort 或 CcMdlWriteAbort 之前，這些頁面會保持鎖定在記憶體中。因此，CcPrepareMdlWrite 的每個呼叫都必須接著呼叫 CcMdlWriteComplete 或 CcMdlWriteAbort。

請注意，MDL 所描述的頁面會鎖定在記憶體中，但不會對應到系統空間中。呼叫者可以呼叫 MmGetSystemAddressForMdlSafe來執行此對應。

請注意，即使呼叫 CcPrepareMdlWrite 失敗，也可能已配置一或多個 MDL。呼叫端可以檢查 IoStatus.Information 的值，以判斷是否已發生此狀況。如果有，呼叫端必須呼叫 CcMdlWriteComplete，以釋放配置的 MDL。

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

若要快取檔案，請使用 CcInitializeCacheMap。