CcPrepareMdlWrite 函式 (ntifs.h)

發行項
02/26/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

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

[out] IoStatus

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

傳回值

無

備註

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

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

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

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

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