Función NtCopyFileChunk (ntifs.h)

Artículo
01/13/2024

La rutina NtCopyFileChunk copia datos del archivo de origen en el archivo de destino.

Sintaxis

__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

Identificador del archivo de origen que se va a leer.

[in] DestHandle

Identificador del archivo de destino. Los datos del archivo sourceHandle se copian en el archivo de DestHandle. Los puertos de finalización se pueden usar en este identificador.

[in, optional] Event

Evento opcional que se indicará cuando se complete la operación de copia.

[out] IoStatusBlock

Puntero a una estructura de IO_STATUS_BLOCK que recibe el estado de finalización final y otra información sobre la operación de copia.

[in] Length

Longitud de los datos que se van a copiar, en bytes.

[in] SourceOffset

Desplazamiento de bytes inicial dentro del archivo de origen para iniciar la operación de lectura.

[in] DestOffset

Desplazamiento de bytes inicial dentro del archivo de destino para iniciar la operación de escritura.

[in, optional] SourceKey

Una clave opcional que se va a usar si hay interbloqueos asociados al archivo de origen.

[in, optional] DestKey

Una clave opcional que se va a usar si hay interbloqueos asociados al archivo de destino.

[in] Flags

Marcas opcionales. Actualmente no hay valores de marca válidos.

Valor devuelto

NtCopyFileChunk devuelve STATUS_SUCCESS si la copia se ha completado correctamente o un código NTSTATUS, como uno de los siguientes:

Código	Significado
STATUS_PENDING	La copia está en curso. Los autores de llamadas deben esperar al evento o al objeto de archivo para obtener el estado final.
STATUS_[ERROR]	Se pueden producir varios errores similares a NtReadFile y NtWriteFile.

Una vez que la escritura completa el estado de la operación se puede determinar examinando el campo Estado de IoStatusBlock.

Consulte Comentarios para obtener más información sobre el control de E/S sincrónica/asincrónica.

Comentarios

NtCopyFileChunk copia los datos de un archivo de origen en un archivo de destino mediante los desplazamientos de archivo proporcionados para la longitud solicitada. Si la longitud supera el final del archivo (EOF) en el archivo de origen, NtCopyFileChunk solo leerá y copiará los datos en el destino hasta el EOF del origen. Los autores de llamadas pueden obtener el número real de bytes escritos desde IoStatusBlock.

NtCopyFileChunk incluye dos operaciones de E/S: una lectura del archivo de origen y una escritura en el archivo de destino. Aunque cada E/S internamente tiene su propia finalización, el evento del autor de la llamada (o el identificador de archivo de destino si no se proporciona ningún evento) se indicará cuando se complete la operación de copia.

Los archivos de origen y destino se pueden abrir de forma asincrónica o sincrónica. Aunque se recomienda que los autores de llamadas sean coherentes entre los dos identificadores, no es necesario. En función de los identificadores proporcionados, NtCopyFileChunk devolverá en distintos puntos de la operación de copia, tal como se especifica en la tabla siguiente.

Identificador de origen	Identificador de destino	Condiciones de retorno
Asincrónica	Asincrónica	Una vez que la lectura se ha puesto en cola correctamente O si hay errores antes de poner en cola la lectura.
Asincrónica	Sincrónico	Una vez finalizada la escritura, O si hay errores antes de la finalización de la escritura.
Sincrónico	Sincrónico	Una vez finalizada la escritura, O si hay errores antes de la finalización de la escritura.
Sincrónica	Asincrónica	Una vez que la escritura se ha puesto en cola correctamente O si hay errores antes de poner en cola la escritura.

Si se devuelve STATUS_PENDING, el llamado debe esperar a que se complete la operación antes de examinar el bloque de estado de E/S para el estado final. Si se devuelve STATUS_SUCCESS o el bloque de estado de E/S indica que el autor de la llamada debe examinar ioStatusBlock para determinar cuántos bytes se copiaron.

Si se abre cualquiera de los archivos para E/S no almacenados en caché, el autor de la llamada debe asegurarse de que la longitud solicitada esté alineada con el sector con el que se abra el archivo como no almacenado en caché. Si ambas, la longitud debe alinearse con el tamaño de sector mayor de los dos.

Todas las operaciones de lectura y escritura de NtCopyFileChunk tendrán:

El modo de solicitante del IRP establecido en KernelMode
Extensión IRP de tipo IopCopyInformationType.

Los filtros no tienen acceso directamente a las extensiones IRP, pero pueden comprobar la presencia de esta extensión y obtener información de copia de los datos de devolución de llamada llamando a FltGetCopyInformationFromCallbackData.

La E/S rápida no está disponible en esta copia porque la información de copia está presente en la extensión IRP (y la E/S rápida no crea IRP).

CopyFileChunk lo usa internamente CopyFile para la mayoría de los formularios de copia. Las excepciones actuales incluyen copias en la nube, descarga de SMB y ODX.

En el ejemplo siguiente se muestra cómo 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 Escenarios de copia de archivos en modo kernel y detección de escenarios de archivos de copia para obtener más información.