CcMapData 函式 (ntifs.h)

發行項
02/26/2024

CcMapData 例程會將快取檔案的指定位元組範圍對應至記憶體中的緩衝區。

語法

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

參數

[in] FileObject

要對應數據以供讀取存取之檔案之檔案物件的指標。

[in] FileOffset

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

[in] Length

所需數據位元組的長度。

[in] Flags

旗標的位掩碼，指定對應作業的執行方式。這是下列一或多個值的位 OR 組合：

值	意義
MAP_WAIT	呼叫端可以進入等候狀態，直到數據已對應為止。
MAP_NO_READ	只有已駐留在記憶體中的頁面才會對應。

注意在 Windows 2000 和更早版本中，此參數是名為 Wait 的 BOOLEAN 值：

等候

如果呼叫端可以進入等候狀態，直到數據已對應，則設定為 TRUE ，否則為 FALSE 。

[out] Bcb

在第一次呼叫時，這會傳回緩衝區控制區塊的指標， (BCB) 結構。此指標必須提供作為所有後續呼叫的輸入，以供此緩衝區使用。

[out] Buffer

包含對應數據的緩衝區指標。

傳回值

如果快取檔案的數據已成功對應，CcMapData 會傳回 TRUE，否則傳回 FALSE。

備註

CcMapData 會對應快取檔案中的數據以供讀取存取。請注意，呼叫 CcMapData 之後，數據就會對應;但未釘選。這項區別很重要。無法安全地修改對應但未釘選的數據。若要釘選數據，請使用 CcPinMappedData、 CcPinRead 或 CcPreparePinWrite。

每次成功呼叫 CcMapData 時，都必須比對 CcUnpinData 的後續呼叫。

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

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

如果 設定MAP_WAIT 旗標 (或 Wait 為 TRUE) ， 則 CcMapData 保證可以完成對應要求並傳回 TRUE。如果快取檔案的必要頁面已經存在於記憶體中，則會立即對應數據，而且不會發生封鎖。如果有任何必要的頁面未駐留，則呼叫端會處於等候狀態，直到所有必要頁面都已進入駐留狀態，而且數據可以對應。如果未設定 MAP_WAIT 旗標 (或 Wait 為 FALSE) ，且無法立即對應數據， CcMapData 會傳回 FALSE。

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

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

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