Funzione NtCopyFileChunk (ntifs.h)

Articolo
02/27/2024

La routine NtCopyFileChunk copia i dati dal file di origine nel file di destinazione.

Sintassi

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

Parametri

[in] SourceHandle

Handle del file di origine da leggere.

[in] DestHandle

HANDLE del file di destinazione. I dati del file sourceHandle sono copiati nel file di DestHandle. Le porte di completamento possono essere usate in questo handle.

[in, optional] Event

Evento facoltativo da segnalare al termine dell'operazione di copia.

[out] IoStatusBlock

Puntatore a una struttura IO_STATUS_BLOCK che riceve lo stato di completamento finale e altre informazioni sull'operazione di copia.

[in] Length

Lunghezza dei dati da copiare, in byte.

[in] SourceOffset

Offset dei byte iniziale all'interno del file di origine per avviare l'operazione di lettura.

[in] DestOffset

Offset dei byte iniziale all'interno del file di destinazione per avviare l'operazione di scrittura.

[in, optional] SourceKey

Chiave facoltativa da utilizzare se sono presenti oplock associati al file di origine.

[in, optional] DestKey

Chiave facoltativa da utilizzare se sono presenti oplock associati al file di destinazione.

[in] Flags

Flag facoltativi. Attualmente non sono presenti valori di flag validi.

Valore restituito

NtCopyFileChunk restituisce STATUS_SUCCESS se la copia è stata completata correttamente o un codice NTSTATUS, ad esempio uno dei seguenti:

Codice	Significato
STATUS_PENDING	La copia è in corso. I chiamanti devono attendere l'evento o l'oggetto file per ottenere lo stato finale.
STATUS_[ERROR]	Possono verificarsi diversi errori simili a NtReadFile e NtWriteFile.

Al termine della scrittura, lo stato dell'operazione può essere determinato esaminando il campo Stato di IoStatusBlock.

Per informazioni dettagliate sulla gestione delle operazioni di I/O sincrone/asincrone, vedere La sezione Osservazioni .

Commenti

NtCopyFileChunk copia i dati da un file di origine in un file di destinazione usando gli offset di file forniti per la lunghezza richiesta. Se la lunghezza supera la fine del file (EOF) nel file di origine, NtCopyFileChunk leggerà e copia i dati nella destinazione fino all'EOF dell'origine. I chiamanti possono ottenere il numero effettivo di byte scritti da IoStatusBlock.

NtCopyFileChunk include due operazioni di I/O: una lettura del file di origine e una scrittura nel file di destinazione. Anche se ogni I/O dispone internamente del proprio completamento, l'evento del chiamante (o l'handle del file di destinazione se non viene fornito alcun evento) verrà segnalato al termine dell'operazione di copia.

I file di origine e di destinazione possono essere aperti in modo asincrono o sincrono. Anche se è consigliabile che i chiamanti siano coerenti tra i due handle, non è obbligatorio. A seconda degli handle forniti, NtCopyFileChunk restituirà in punti diversi nell'operazione di copia, come specificato nella tabella seguente.

Handle di origine	Handle di destinazione	Condizioni di restituzione
Asincrono	Asincrono	Dopo che la lettura è stata accodata correttamente oppure se sono presenti errori prima di accodare la lettura.
Asincrono	Sincrono	Al termine della scrittura OPPURE se sono presenti errori prima del completamento della scrittura.
Sincrono	Sincrono	Al termine della scrittura OPPURE se sono presenti errori prima del completamento della scrittura.
Sincrono	Asincrono	Dopo che la scrittura è stata accodata correttamente oppure se sono presenti errori prima di accodare la scrittura.

Se viene restituito STATUS_PENDING, il metodo chiamato deve attendere il completamento dell'operazione prima di esaminare il blocco di stato di I/O per lo stato finale. Se STATUS_SUCCESS viene restituito o il blocco di stato di I/O indica l'esito positivo, il chiamante deve esaminare IoStatusBlock per determinare il numero di byte copiati.

Se uno dei due file viene aperto per operazioni di I/O non memorizzate nella cache, il chiamante deve assicurarsi che la lunghezza richiesta sia allineata al settore con qualsiasi file aperto come non memorizzato nella cache. Se entrambe, la lunghezza deve essere allineata alle dimensioni del settore maggiori dei due.

Tutte le operazioni di lettura e scrittura da NtCopyFileChunk avranno:

La modalità richiedente di IRP impostata su KernelMode
Estensione IRP di tipo IopCopyInformationType.

I filtri non hanno accesso direttamente alle estensioni IRP, ma possono controllare la presenza di questa estensione e ottenere informazioni di copia dai dati di callback chiamando FltGetCopyInformationFromCallbackData.

I/O veloce non è disponibile in questa copia perché le informazioni di copia sono presenti nell'estensione IRP (e Fast I/O non crea IP).

NtCopyFileChunk viene usato internamente da CopyFile per la maggior parte delle forme di copia. Le eccezioni correnti includono copie cloud, offload SMB e ODX.

Nell'esempio seguente viene illustrato come usare 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; 
    } 
}

Per altre informazioni, vedere Copiare e rilevare scenari di file in modalità kernel .