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