通过

CcMapData 函数 （ntifs.h）

  • 项目

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。

Buffer 中返回的指针有效，直到调用 ccUnpinData 。 如果在此指针仍然有效时调用 CcPinMappedData，则在调用 CcPinMappedData 后，指针将保持有效（但直到调用 ccUnpinData 为止）。

如果发生任何故障，CcMapData 将引发该特定故障的状态异常。 例如，如果池分配失败，CcMapData 引发 STATUS_INSUFFICIENT_RESOURCES 异常;如果发生 I/O 错误，CcMapData 引发 I/O 错误的状态异常。 因此，若要控制故障是否发生，驱动程序应在 try-finally 语句中包装对 CcMapData 调用， 或 try-finally 语句。

若要缓存文件，请使用 CcInitializeCacheMap。

要求

要求 价值
目标平台 普遍
标头 ntifs.h （include Ntifs.h）
库 NtosKrnl.lib
DLL NtosKrnl.exe
IRQL < DISPATCH_LEVEL

另请参阅

CcInitializeCacheMap

CcPinMappedData

CcPinRead

CcPreparePinWrite

CcUnpinData