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 值：

Wait

如果调用方可以置于等待状态，直到映射数据，则设置为 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。