Função NtCopyFileChunk (ntifs.h)

Artigo
02/07/2025

A rotina de NtCopyFileChunk copia dados do arquivo de origem para o arquivo de destino.

Sintaxe

__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
);

Parâmetros

[in] SourceHandle

O HANDLE do arquivo de origem a ser lido.

[in] DestHandle

O HANDLE do arquivo de destino. Os dados do arquivo do SourceHandlesão copiados para arquivo dede DestHandle. As portas de conclusão podem ser usadas nesse identificador.

[in, optional] Event

Um evento opcional a ser sinalizado quando a operação de cópia for concluída.

[out] IoStatusBlock

Um ponteiro para uma estrutura IO_STATUS_BLOCK que recebe o status de conclusão final e outras informações sobre a operação de cópia.

[in] Length

O comprimento dos dados a serem copiados, em bytes.

[in] SourceOffset

O deslocamento de bytes inicial no arquivo de origem para iniciar a operação de leitura.

[in] DestOffset

O deslocamento de bytes inicial no arquivo de destino para iniciar a operação de gravação.

[in, optional] SourceKey

Uma chave opcional a ser usada se houver oplocks associados ao arquivo de origem.

[in, optional] DestKey

Uma chave opcional a ser usada se houver oplocks associados ao arquivo de destino.

[in] Flags

Sinalizadores opcionais. Atualmente, não há valores de sinalizador válidos.

Valor de retorno

NtCopyFileChunk retornará STATUS_SUCCESS se a cópia for concluída com êxito ou um código NTSTATUS, como um dos seguintes:

Código	Significado
STATUS_PENDING	A cópia está em andamento. Os chamadores devem aguardar o evento ou o objeto de arquivo para obter o status final.
STATUS_[ERROR]	Vários erros podem ocorrer de forma semelhante a NtReadFile e NtWriteFile.

Depois que a gravação concluir o status da operação pode ser determinada examinando o campo Status de IoStatusBlock.

Consulte Comentários para obter detalhes sobre o tratamento de E/S síncrona/assíncrona.

Observações

NtCopyFileChunk copia dados de um arquivo de origem para um arquivo de destino usando os deslocamentos de arquivo fornecidos para o comprimento solicitado. Se o comprimento ultrapassar o fim do arquivo (EOF) no arquivo de origem, NtCopyFileChunk somente lerá e copiará os dados para o destino até o EOF da origem. Os chamadores podem obter o número real de bytes gravados no IoStatusBlock.

NtCopyFileChunk inclui duas operações de E/S: uma leitura do arquivo de origem e uma gravação no arquivo de destino. Embora cada E/S internamente tenha sua própria conclusão, o evento do chamador (ou identificador de arquivo de destino, se nenhum evento for fornecido) será sinalizado quando a operação de cópia for concluída.

Os arquivos de origem e de destino podem ser abertos de forma assíncrona ou síncrona. Embora seja recomendável que os chamadores sejam consistentes entre os dois identificadores, isso não é necessário. Dependendo dos identificadores fornecidos, NtCopyFileChunk retornará em diferentes pontos na operação de cópia, conforme especificado na tabela a seguir.

Identificador de origem	Identificador de destino	Condições de retorno
Assíncrono	Assíncrono	Depois que a leitura tiver sido enfileirada com êxito ou se houver erros antes de enfileirar a leitura.
Assíncrono	Síncrono	Após a conclusão da gravação ou se houver erros antes da conclusão da gravação.
Síncrono	Síncrono	Após a conclusão da gravação ou se houver erros antes da conclusão da gravação.
Síncrono	Assíncrono	Depois que a gravação tiver sido enfileirada com êxito ou se houver erros antes de enfileirar a gravação.

Se STATUS_PENDING for retornado, o chamado deverá aguardar a conclusão da operação antes de examinar o bloco de status de E/S para o status final. Se STATUS_SUCCESS for retornado ou o bloco de status de E/S indicar êxito, o chamador deverá examinar o IoStatusBlock para determinar quantos bytes foram copiados.

Se um dos arquivos for aberto para E/S não armazenada em cache, o chamador deverá garantir que o comprimento solicitado esteja alinhado ao setor com qualquer arquivo aberto como não armazenado em cache. Se ambos, o comprimento deverá ser alinhado com o tamanho maior do setor dos dois.

Todas as operações de leitura e gravação de NtCopyFileChunk terão:

O modo solicitante do IRP definido como kernelMode
Uma extensão IRP do tipo IopCopyInformationType.

Os filtros não têm acesso diretamente às extensões IRP, mas podem verificar a presença dessa extensão e obter informações de cópia dos dados de retorno de chamada chamando FltGetCopyInformationFromCallbackData.

A E/S rápida não está disponível nesta cópia porque as informações de cópia estão presentes na extensão IRP (e a E/S rápida não cria IRPs).

NtCopyFileChunk é usado internamente por CopyFile para a maioria das formas de cópia. As exceções atuais incluem cópias de nuvem, descarregamento SMB e ODX.

O exemplo a seguir mostra como usar 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; 
    } 
}

Consulte cópia de arquivo no modo Kernel e detectando cenários de arquivo de cópia para obter mais informações.