CcPreparePinWrite 函数 (ntifs.h)
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 的调用。
要求
要求 | 值 |
---|---|
目标平台 | 通用 |
标头 | ntifs.h (包括 Ntifs.h) |
Library | NtosKrnl.lib |
DLL | NtosKrnl.exe |
IRQL | PASSIVE_LEVEL |