NtCopyFileChunk 函数 （ntifs.h）
NtCopyFileChunk 例程将数据从源文件复制到目标文件中。
语法
__kernel_entry NTSYSCALLAPI NTSTATUS NtCopyFileChunk(
[in] HANDLE SourceHandle,
[in] HANDLE DestHandle,
[in, optional] HANDLE Event,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] ULONG Length,
[in] PLARGE_INTEGER SourceOffset,
[in] PLARGE_INTEGER DestOffset,
[in, optional] PULONG SourceKey,
[in, optional] PULONG DestKey,
[in] ULONG Flags
);
参数
[in] SourceHandle
要读取的源文件的 HANDLE。
[in] DestHandle
目标文件的 HANDLE。 sourceHandle 文件中的数据将复制到 DestHandle's 文件中。 可以在此句柄上使用完成端口。
[in, optional] Event
复制作完成后要发出信号的可选事件。
[out] IoStatusBlock
指向 IO_STATUS_BLOCK 结构的指针，该结构接收最终完成状态以及有关复制作的其他信息。
[in] Length
要复制的数据的长度（以字节为单位）。
[in] SourceOffset
源文件中的起始字节偏移量，用于开始读取作。
[in] DestOffset
要开始写入作的目标文件中的起始字节偏移量。
[in, optional] SourceKey
如果存在与源文件关联的 oplock，则要使用的可选键。
[in, optional] DestKey
如果存在与目标文件关联的 oplock，则要使用的可选键。
[in] Flags
可选标志。 目前没有有效的标志值。
返回值
如果复制成功完成，NtCopyFileChunk 返回STATUS_SUCCESS，或者返回 NTSTATUS 代码，例如以下代码之一：
| 法典 | 意义 |
|---|---|
| STATUS_PENDING | 副本正在进行中。 调用方必须等待事件或文件对象才能获取最终状态。 |
| STATUS_[错误] | 可能会发生各种错误，类似于 NtReadFile 和 NtWriteFile。 |
写入完成后，可以通过检查 IoStatusBlock的 状态 字段来确定作的状态。
有关处理同步/异步 I/O 的详细信息，请参阅 备注。
言论
NtCopyFileChunk 使用所请求长度提供的文件偏移量将数据从源文件复制到目标文件中。 如果长度超过源文件上的文件结尾（EOF），则 NtCopyFileChunk 将仅读取数据并将其复制到目标，直到源的 EOF。 调用方可以从 IoStatusBlock中获取实际写入的字节数。
NtCopyFileChunk 包括两个 I/O作：读取源文件和写入目标文件。 虽然每个 I/O 在内部都有其自己的完成，但复制作完成后，调用方的事件（或目标文件句柄）将发出信号。
源文件和目标文件可以异步或同步打开。 虽然建议调用方在两个句柄之间保持一致，但不是必需的。 根据提供的句柄，NtCopyFileChunk 将在下表中指定的复制作的不同点返回。
| 源句柄 | 目标句柄 | 返回条件 |
|---|---|---|
| 异步 | 异步 | 读取成功排队后，如果排队读取之前出错，则为读取排队。 |
| 异步 | 同步 | 写入完成后，如果写入完成之前有错误，则为 OR。 |
| 同步 | 同步 | 写入完成后，如果写入完成之前有错误，则为 OR。 |
| 同步 | 异步 | 写入成功排队后，如果在对写入进行排队之前出错，则为 OR 排队。 |
如果返回STATUS_PENDING，则调用者必须等待作完成，然后才能查看最终状态的 I/O 状态块。 如果返回STATUS_SUCCESS或 I/O 状态块指示成功，则调用方应查看 IoStatusBlock 以确定复制的字节数。
如果为非缓存 I/O 打开任一文件，则调用方必须确保请求的长度与以非缓存方式打开的文件保持扇区一致。 如果两者，长度应与两者更大的扇区大小保持一致。
从 NtCopyFileChunk 执行的所有读取和写入作都将具有：
- IRP 的请求程序模式设置为 KernelMode
- IopCopyInformationType类型的 IRP 扩展。
筛选器不能直接访问 IRP 扩展，但可以通过调用 FltGetCopyInformationFromCallbackData来检查此扩展是否存在并从回调数据获取复制信息。
此副本中不提供快速 IO，因为 IRP 扩展中存在复制信息（而快速 IO 不会创建 IRP）。
NtCopyFileChunk 由 CopyFile 用于大多数形式的复制。 当前异常包括云副本、SMB 卸载和 ODX。
以下示例演示如何使用 NtCopyFileChunk。
// Input parameters to NtCopyFileChunk. Opening
// the file handles is done using NtCreateFile
// and creating the event is done with CreateEvent.
// This is not shown in this code sample.
HANDLE sourceHandle;
HANDLE destHandle;
HANDLE event;
IO_STATUS_BLOCK ioStatusBlock;
ULONG length;
LARGE_INTEGER sourceOffset;
LARGE_INTEGER destOffset;
// Copy the data
status = NtCopyFileChunk( sourceHandle,
destHandle,
event,
&ioStatusBlock,
length,
&sourceOffset,
&destOffset,
NULL,
NULL,
0 );
// Wait for the copy to complete
if (status == STATUS_PENDING) {
status = NtWaitForSingleObject( event, FALSE, NULL );
if (NT_SUCCESS(status)) {
status = ioStatusBlock.Status;
}
}
有关详细信息，请参阅 内核模式文件复制和检测复制文件方案。
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | Windows 11 版本 22H2 |
| 标头 | ntifs.h |
| 库 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |