CcPinRead 函数（ntifs.h）

项目
12/21/2024

CcPinRead 例程固定缓存文件的指定字节范围，并将固定的数据读入内存中的缓冲区。

语法

BOOLEAN CcPinRead(
  [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

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

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

[out] Bcb

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

[out] Buffer

指向包含固定数据的缓冲区的指针。

返回值

CcPinRead 如果缓存文件的数据已固定并成功读取，则返回 true TRUE，否则 FALSE。

言论

如果设置了PIN_WAIT标志，则保证 CcPinRead 完成固定请求并返回 TRUE。如果缓存文件所需的页已驻留在内存中，则会立即固定数据，并且不会发生阻塞。如果任何所需的页面不驻留，则调用方将处于等待状态，直到所有必需的页面都已驻留，并且数据可以固定。如果未设置PIN_WAIT标志，但无法立即固定数据，CcPinRead 返回 FALSE，并且其输出参数值毫无意义。

如果调用方随后修改由 CcPinRead读取的数据，则还必须调用 CcSetDirtyPinnedData，以便修改后的数据最终将写入磁盘。

对 CcPinRead 的每个成功调用都必须匹配对 CcUnpinData的后续调用。

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

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

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

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

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