Функция 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
ДеСКРиптор исходного файла для чтения.
[in] DestHandle
ДЕСКРИПтор целевого файла. Данные из файла SourceHandleкопируются в файл DestHandle. Порты завершения можно использовать для этого дескриптора.
[in, optional] Event
Необязательное событие, которое будет сигнализировать при завершении операции копирования.
[out] IoStatusBlock
Указатель на структуру IO_STATUS_BLOCK, которая получает окончательное состояние завершения и другие сведения об операции копирования.
[in] Length
Длина данных для копирования в байтах.
[in] SourceOffset
Начальная смещение байтов в исходном файле, чтобы начать операцию чтения.
[in] DestOffset
Начальная смещение байтов в целевом файле, чтобы начать операцию записи.
[in, optional] SourceKey
Необязательный ключ, используемый при наличии оплоков, связанных с исходным файлом.
[in, optional] DestKey
Необязательный ключ, используемый при наличии оплоков, связанных с целевым файлом.
[in] Flags
Необязательные флаги. В настоящее время нет допустимых значений флага.
Возвращаемое значение
NtCopyFileChunk возвращает STATUS_SUCCESS, если копия успешно завершена, или код NTSTATUS, например один из следующих:
| Код | Значение |
|---|---|
| STATUS_PENDING | Выполняется копирование. Вызывающие серверы должны ждать события или объекта файла, чтобы получить окончательное состояние. |
| STATUS_[ERROR] | Различные ошибки могут возникать аналогично NtReadFile и NtWriteFile. |
После завершения записи можно определить состояние операции, проверив поле состоянияIoStatusBlock.
Дополнительные сведения об обработке синхронных и асинхронных операций ввода-вывода см. в примечаниях.
Замечания
NtCopyFileChunk копирует данные из исходного файла в целевой файл, используя указанные смещения файла для запрошенной длины. Если длина превышает конец файла (EOF) исходного файла, NtCopyFileChunk будет считывать и копировать данные в место назначения до EOF источника. Вызывающие устройства могут получить фактическое количество байтов, записанных из IoStatusBlock.
NtCopyFileChunk включает две операции ввода-вывода: чтение исходного файла и запись в целевой файл. Хотя каждый ввод-вывод внутри имеет собственное завершение, событие вызывающего абонента (или дескриптор целевого файла, если не указано событие) будет сигнализировать после завершения операции копирования.
Исходные и целевые файлы можно открывать асинхронно или синхронно. Хотя рекомендуется, чтобы вызывающие абоненты были согласованы между двумя дескрипторами, это не обязательно. В зависимости от предоставленных дескрипторов NtCopyFileChunk возвращается в разные точки операции копирования, как указано в следующей таблице.
| Дескриптор источника | Дескриптор назначения | Условия возврата |
|---|---|---|
| Асинхронный | Асинхронный | После успешного завершения чтения или при возникновении ошибок перед очередью чтения. |
| Асинхронный | Синхронный | После завершения записи или при возникновении ошибок до завершения записи. |
| Синхронный | Синхронный | После завершения записи или при возникновении ошибок до завершения записи. |
| Синхронный | Асинхронный | После успешной записи или при возникновении ошибок перед очередью записи. |
Если возвращается STATUS_PENDING, вызов должен ожидать завершения операции перед просмотром блока состояния ввода-вывода для конечного состояния. Если STATUS_SUCCESS возвращается или блок состояния ввода-вывода указывает на успех, вызывающий объект должен просмотреть IoStatusBlock, чтобы определить, сколько байтов было скопировано.
Если любой файл открыт для не кэшированных операций ввода-вывода, вызывающий объект должен убедиться, что запрошенная длина соответствует сектору с любым файлом, открытым как не кэшированный. В обоих случаях длина должна быть выровнена с большим размером сектора двух.
Все операции чтения и записи из NtCopyFileChunk будут иметь:
- В режиме запроса IRP задано значение KernelMode
- Расширение IRP типа IopCopyInformationType.
Фильтры не имеют доступа к расширениям IRP напрямую, но могут проверить наличие этого расширения и получить сведения о копировании из данных обратного вызова, вызвав FltGetCopyInformationFromCallbackData.
Быстрый ввод-вывод недоступен в этой копии, так как сведения о копировании присутствуют в расширении IRP (и быстрые операции ввода-вывода не создают irPs).
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 |