CcPreparePinWrite 函数 (ntifs.h)

项目
08/07/2023

CcPreparePinWrite 例程固定缓存文件的指定字节范围，以便进行写入访问。

语法

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

参数

[in] FileObject

指向要向其写入数据的缓存文件的文件对象的指针。

[in] FileOffset

指向变量的指针，该变量指定要写入数据的文件中的起始字节偏移量。

[in] Length

所需数据的长度（以字节为单位）。

[in] Zero

如果缓冲区在返回时为零，则设置为 TRUE 。如果在 Flags 参数中设置了PIN_CALLER_TRACKS_DIRTY_DATA标志，则忽略此参数。

[in] Flags

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

值	含义
PIN_WAIT	调用方可以置于等待状态，直到数据已固定。
PIN_EXCLUSIVE	BCB) (缓冲区控制块以独占方式获取。
PIN_NO_READ	仅固定已驻留在内存中的页。如果设置了此标志，还必须设置PIN_WAIT。
PIN_IF_BCB	仅当 BCB 已存在时，才会固定数据。否则，引脚将失败，并且不会返回 BCB。
PIN_CALLER_TRACKS_DIRTY_DATA	调用方负责跟踪脏页。如果设置了此标志，则忽略所有其他标志。此标志在 Microsoft Windows Server 2003 SP1 及更高版本上可用。

[out] Bcb

指向固定缓冲区控制块 (BCB) 的不透明指针。此指针必须作为此缓冲区对 CcPreparePinWrite 或 CcUnpinData 的任何后续调用的输入提供。

[out] Buffer

返回指向所需数据的指针，在取消固定或释放缓冲区之前有效。

返回值

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

注解

CcPreparePinWrite 固定系统缓存中的指定文件页。要完全覆盖的页可能满足于为零的页。

如果设置了 PIN_WAIT 标志，则保证 CcPreparePinWrite 完成准备请求并返回 TRUE。如果可以立即准备所有页面，则不会发生阻塞。如果任何所需的页面不是驻留页，调用方将处于等待状态，直到所有必需的页面都已驻留，并且页面可以准备好。如果未设置PIN_WAIT标志，但不能立即准备所有页面， 则 CcPreparePinWrite 将返回 FALSE，并且其输出参数值毫无意义。

Microsoft Windows Server 2003 SP1 及更高版本： PIN_CALLER_TRACKS_DIRTY_DATA 标志通常用于文件系统管理写入但不是从中读取的日志文件的情况。由于现有文件数据将被覆盖且不会读取，因此缓存管理器可能会返回零页，而不是在磁盘文件数据的实际页中出错。如果设置了此标志，缓存管理器不会跟踪脏页。调用方负责跟踪任何脏页面。请注意，仅当缓冲区最终将刷新到磁盘时， CcPreparePinWrite 才应以这种方式固定数据。在调用 CcFlushCache 将缓冲区刷新到磁盘之前，调用方必须先调用 MmSetAddressRangeModified，以通知内存管理器系统缓存缓冲区中的指定页已脏并且应写入。

每次成功调用 CcPreparePinWrite 都必须与对 CcUnpinData 的后续调用相匹配。如果对同一数据多次调用 CcPreparePinWrite ，则必须调用 CcUnpinData 的次数相同。

Buffer 中返回的指针在调用 CcUnpinData 之前有效。如果当此指针仍然有效时调用 CcPinMappedData ，则指针在调用 CcPinMappedData (后保持有效，但直到 ) 调用 CcUnpinData 为止。

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

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

调用 CcPreparePinWrite 后，无需调用 CcSetDirtyPinnedData。如果 CcPreparePinWrite 返回 TRUE，则 BCB 已标记为脏。

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