ccPinMappedData 函数 (ntifs.h)

项目
02/26/2024

CcPinMappedData 例程固定缓存文件的指定字节范围。

语法

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

参数

[in] FileObject

指向要固定数据范围的缓存文件的文件对象的指针。

[in] FileOffset

指向变量的指针，该变量指定所需数据所在的缓存文件中的起始字节偏移量。

[in] Length

要固定的数据的长度（以字节为单位）。

[in] Flags

指定如何执行固定操作的标志的位掩码。以下一个或多个值的 ORed 组合：

标志	含义
PIN_WAIT	调用方可以进入等待状态，直到数据已固定。
PIN_EXCLUSIVE	BCB) (缓冲区控制块是独占获取的。如果设置了此标志，还必须设置PIN_WAIT。
PIN_NO_READ	仅固定已驻留在内存中的页。如果设置了此标志，还必须设置PIN_WAIT。
PIN_IF_BCB	仅当 BCB 已存在时，才会固定数据。否则，引脚将失败， Bcb 设置为 NULL。

[in, out] Bcb

在第一次调用时，这会返回指向 BCB) (缓冲区控制块的指针。此指针必须作为此缓冲区的所有后续调用的输入提供。

返回值

如果成功固定缓存文件的数据，CcPinMappedData 将返回 TRUE;否则返回 FALSE。

注解

从 CcPinMappedData 成功返回可确保以前在调用 CcMapData 时映射的数据固定在缓存中，并且可以安全地修改指定范围中的数据。如果调用方随后修改由 CcPinMappedData 固定的数据，则它还必须调用 CcSetDirtyPinnedData ，以便最终将修改的数据写入磁盘。

CcPinMappedData 无法在缓存管理器中跨视图边界固定数据。缓存管理器以 256 KB 对齐的视图管理系统中的文件。 (缓存管理器的视图大小由系统定义的常量 VACB_MAPPING_GRANULARITY指定，该常量在 ntifs.h.) 固定区域中设置为 256 KB，不能跨多个 256 KB 视图。因此，可固定的最大区域为 256 KB，从文件中的 256 KB 对齐偏移量开始。

在缓存文件中固定字节范围不能确保页面保留在内存中。只要固定页面，字节范围就保证始终映射到系统缓存虚拟地址空间，但内存管理器可以根据系统的内存需求分页物理页。

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

若要映射缓存文件的数据，请使用 CcMapData 例程。若要缓存文件，请使用 CcInitializeCacheMap。

调用 CcPinMappedData 后无需调用 CcUnpinData ，因为固定引用与 CcMapData 匹配。