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 | 仅映射已驻留在内存中的页。 |
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。
要求
要求 | 值 |
---|---|
目标平台 | 通用 |
标头 | ntifs.h (包括 Ntifs.h) |
Library | NtosKrnl.lib |
DLL | NtosKrnl.exe |
IRQL | < DISPATCH_LEVEL |