Функция 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

HANDLE целевого файла. Данные из файла 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 будет только считывать и копировать данные в место назначения вплоть до конечной точки источника. Вызывающие абоненты могут получить фактическое количество байтов, записанных из IoStatusBlock.

NtCopyFileChunk включает две операции ввода-вывода: чтение исходного файла и запись в целевой файл. Хотя каждый ввод-вывод внутренне имеет собственное завершение, событие вызывающего объекта (или дескриптор целевого файла, если событие не указано) будет сигнализировать о завершении операции копирования.

Исходные и целевые файлы можно открывать асинхронно или синхронно. Хотя рекомендуется, чтобы вызывающие стороны были согласованы между двумя дескрипторами, это не обязательно. В зависимости от предоставленных дескрипторов NtCopyFileChunk будет возвращать в разные точки операции копирования, как указано в следующей таблице.

Исходный дескриптор Дескриптор назначения Условия возврата
Асинхронный Асинхронный После успешного постановки чтения в очередь или при возникновении ошибок перед постановкой чтения в очередь.
Асинхронный Синхронная После завершения записи ИЛИ при наличии ошибок перед завершением записи.
Синхронная Синхронная После завершения записи ИЛИ при наличии ошибок перед завершением записи.
Синхронная Асинхронный После успешного постановки записи в очередь или при возникновении ошибок перед постановкой записи в очередь.

Если возвращается STATUS_PENDING, вызываемый объект должен дождаться завершения операции, прежде чем просмотреть окончательное состояние блока состояния ввода-вывода. Если возвращается STATUS_SUCCESS или блок состояния ввода-вывода указывает на успешное выполнение, вызывающий объект должен просмотреть IoStatusBlock , чтобы определить, сколько байтов было скопировано.

Если любой из файлов открыт для операций ввода-вывода без кэширования, вызывающий объект должен убедиться, что запрошенная длина совпадает с тем, какой файл открыт как не кэшированный. В обоих случаях длина должна быть выровнена с большим размером сектора.

Все операции чтения и записи из NtCopyFileChunk будут иметь:

  • Для режима запрашивающей стороны IRP задано значение KernelMode
  • Расширение IRP типа IopCopyInformationType.

Фильтры не имеют доступа к расширениям IRP напрямую, но могут проверка наличие этого расширения и получать сведения о копировании из данных обратного вызова путем вызова FltGetCopyInformationFromCallbackData.

Быстрые операции ввода-вывода недоступны в этой копии, так как сведения о копировании присутствуют в расширении IRP (а быстрый ввод не создает 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

См. также раздел

FltGetCopyInformationFromCallbackData

IO_STATUS_BLOCK

NtCreateFile