NtCopyFileChunk-Funktion (ntifs.h)

Artikel
02/07/2025

Die NtCopyFileChunk Routine kopiert Daten aus der Quelldatei in die Zieldatei.

Syntax

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

Parameter

[in] SourceHandle

Das HANDLE der zu lesenden Quelldatei.

[in] DestHandle

Das HANDLE der Zieldatei. Die Daten aus SourceHandle's Datei werden in DestHandle's Datei kopiert. Vervollständigungsports können für dieses Handle verwendet werden.

[in, optional] Event

Ein optionales Ereignis, das signalisiert werden soll, wenn der Kopiervorgang abgeschlossen ist.

[out] IoStatusBlock

Ein Zeiger auf eine IO_STATUS_BLOCK Struktur, die den endgültigen Abschlussstatus und andere Informationen zum Kopiervorgang empfängt.

[in] Length

Die Länge der zu kopierenden Daten in Byte.

[in] SourceOffset

Der Anfangsbyte-Offset in der Quelldatei, um den Lesevorgang zu starten.

[in] DestOffset

Der Anfangsbyte-Offset innerhalb der Zieldatei, um den Schreibvorgang zu starten.

[in, optional] SourceKey

Ein optionaler Schlüssel, der verwendet werden soll, wenn oplocks der Quelldatei zugeordnet sind.

[in, optional] DestKey

Ein optionaler Schlüssel, der verwendet werden soll, wenn oplocks der Zieldatei zugeordnet sind.

[in] Flags

Optionale Kennzeichnungen. Derzeit gibt es keine gültigen Flagwerte.

Rückgabewert

NtCopyFileChunk gibt STATUS_SUCCESS zurück, wenn die Kopie erfolgreich abgeschlossen wurde, oder einen NTSTATUS-Code wie einen der folgenden:

Code	Bedeutung
STATUS_PENDING	Die Kopie wird ausgeführt. Aufrufer müssen auf das Ereignis oder das Dateiobjekt warten, um den endgültigen Status abzurufen.
STATUS_[ERROR]	Verschiedene Fehler können ähnlich wie NtReadFile- und NtWriteFile-auftreten.

Nach Abschluss des Schreibvorgangs kann der Status des Vorgangs bestimmt werden, indem das Feld StatusIoStatusBlock-untersucht wird.

Einzelheiten zur Behandlung synchroner/asynchroner E/A-Vorgänge finden Sie in Anmerkungen.

Bemerkungen

NtCopyFileChunk kopiert Daten aus einer Quelldatei mithilfe der bereitgestellten Dateiversatze für die angeforderte Länge in eine Zieldatei. Wenn die Länge das Ende der Datei (EOF) in der Quelldatei überschreitet, liest NtCopyFileChunk nur die Daten bis zum EOF der Quelle. Anrufer können die tatsächliche Anzahl von Bytes abrufen, die aus dem IoStatusBlock-geschrieben wurden.

NtCopyFileChunk- enthält zwei E/A-Vorgänge: ein Lesevorgang der Quelldatei und einen Schreibzugriff in die Zieldatei. Während jede E/A intern einen eigenen Abschluss hat, wird das Ereignis des Aufrufers (oder das Zieldateihandle, wenn kein Ereignis bereitgestellt wird) signalisiert, wenn der Kopiervorgang abgeschlossen ist.

Die Quell- und Zieldateien können asynchron oder synchron geöffnet werden. Es wird zwar empfohlen, dass Aufrufer zwischen den beiden Handles konsistent sind, es ist jedoch nicht erforderlich. Abhängig von den bereitgestellten Handles gibt NtCopyFileChunk- an verschiedenen Stellen im Kopiervorgang zurück, wie in der folgenden Tabelle angegeben.

Quellhandle	Zielhandle	Rückgabebedingungen
Asynchron	Asynchron	Nachdem die Lesewarteschlange erfolgreich in die Warteschlange gestellt wurde ODER wenn Fehler vor der Warteschlange vorhanden sind.
Asynchron	Synchron	Nach Abschluss des Schreibvorgangs ODER, wenn fehler vor dem Schreiben vorliegen.
Synchron	Synchron	Nach Abschluss des Schreibvorgangs ODER, wenn fehler vor dem Schreiben vorliegen.
Synchron	Asynchron	Nachdem der Schreibvorgang erfolgreich in die Warteschlange gestellt wurde, oder wenn Fehler vor der Warteschlange des Schreibvorgangs auftreten.

Wenn STATUS_PENDING zurückgegeben wird, muss der aufgerufene Vorgang warten, bis der Vorgang abgeschlossen ist, bevor der E/A-Statusblock auf den endgültigen Status überprüft wird. Wenn STATUS_SUCCESS zurückgegeben wird oder der E/A-Statusblock den Erfolg angibt, sollte der Aufrufer die IoStatusBlock- anzeigen, um zu bestimmen, wie viele Bytes kopiert wurden.

Wenn eine datei für nicht zwischengespeicherte E/A geöffnet wird, muss der Aufrufer sicherstellen, dass die angeforderte Länge sektormäßig an der Datei ausgerichtet ist, die als nicht zwischengespeichert geöffnet wird. Bei beiden sollte die Länge an der größeren Sektorgröße der beiden angepasst werden.

Alle Lese- und Schreibvorgänge aus NtCopyFileChunk haben:

Der Anforderermodus des IRP auf KernelMode-
Eine IRP-Erweiterung vom Typ IopCopyInformationType.

Filter haben keinen direkten Zugriff auf die IRP-Erweiterungen, können aber das Vorhandensein dieser Erweiterung überprüfen und Kopierinformationen aus den Rückrufdaten abrufen, indem sie FltGetCopyInformationFromCallbackDataaufrufen.

Fast IO ist in dieser Kopie nicht verfügbar, da die Kopierinformationen in der IRP-Erweiterung vorhanden sind (und Fast IO keine IRPs erstellt).

NtCopyFileChunk- wird intern von CopyFile- für die meisten Kopierformen verwendet. Zu den aktuellen Ausnahmen gehören Cloudkopien, SMB-Offload und ODX.

Das folgende Beispiel zeigt, wie NtCopyFileChunk-verwendet wird.


// 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; 
    } 
}

Weitere Informationen finden Sie unter Kernelmodusdateikopie und Erkennen von Kopierdateiszenarien.