NtCopyFileChunk-Funktion (ntifs.h)

  • Artikel

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

Der HANDLE der zu lesenden Quelldatei.

[in] DestHandle

Der HANDLE der Zieldatei. Die Daten aus der SourceHandle-Datei werden in die Datei von DestHandle 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 die endgültige Vervollständigung status und andere Informationen zum Kopiervorgang empfängt.

[in] Length

Die Länge der zu kopierenden Daten in Bytes.

[in] SourceOffset

Der Startbyteoffset in der Quelldatei, um den Lesevorgang zu starten.

[in] DestOffset

Der Startbyteoffset in der Zieldatei, um den Schreibvorgang zu starten.

[in, optional] SourceKey

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

[in, optional] DestKey

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

[in] Flags

Optionale Flags. 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 Dateiobjekt warten, um die endgültige status zu erhalten.
STATUS_[FEHLER] Verschiedene Fehler können ähnlich wie NtReadFile und NtWriteFile auftreten.

Sobald der Schreibvorgang abgeschlossen ist, kann die status des Vorgangs bestimmt werden, indem Sie das Feld Status von IoStatusBlock untersuchen.

Ausführliche Informationen zum Umgang mit synchronen/asynchronen E/A-Vorgängen finden Sie unter Hinweise.

Hinweise

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

NtCopyFileChunk umfasst zwei E/A-Vorgänge: ein Lesen der Quelldatei und einen Schreibvorgang in die Zieldatei. Während jede E/A intern über eine eigene Vervollständigung verfügt, wird das Ereignis des Aufrufers (oder das Zieldateihandle, wenn kein Ereignis angegeben 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 wird NtCopyFileChunk an verschiedenen Stellen des Kopiervorgangs zurückgegeben, wie in der folgenden Tabelle angegeben.

Quellhandle Zielhandle Rückgabebedingungen
Asynchron Asynchron Sobald der Lesevorgang erfolgreich in die Warteschlange eingereiht wurde, oder wenn vor dem Anstehen des Lesevorgangs Fehler aufgetreten sind.
Asynchron Synchron Sobald der Schreibvorgang abgeschlossen ist, ODER, wenn vor dem Abschluss des Schreibvorgangs Fehler auftreten.
Synchron Synchron Sobald der Schreibvorgang abgeschlossen ist, ODER, wenn vor dem Abschluss des Schreibvorgangs Fehler auftreten.
Synchron Asynchron Sobald der Schreibvorgang erfolgreich in die Warteschlange eingereiht wurde, oder, wenn vor dem Instehen des Schreibvorgangs Fehler auftreten.

Wenn STATUS_PENDING zurückgegeben wird, muss der aufgerufene warten, bis der Vorgang abgeschlossen ist, bevor der E/A-status-Block für den endgültigen status. Wenn STATUS_SUCCESS zurückgegeben wird oder der E/A-status-Block erfolgreich ist, sollte sich der Aufrufer den IoStatusBlock ansehen, um zu bestimmen, wie viele Bytes kopiert wurden.

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

Alle Lese- und Schreibvorgänge von NtCopyFileChunk verfügen über Folgendes:

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

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

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

NtCopyFileChunk wird intern von CopyFile für die meisten Kopierformen verwendet. Zu den aktuellen Ausnahmen zählen Cloudkopien, SMB-Auslagerung und ODX.

Das folgende Beispiel zeigt die Verwendung von 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; 
    } 
}

Weitere Informationen finden Sie unter Kopieren im Kernelmodus und Erkennen von Kopierdateiszenarien .

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 11, Version 22H2
Kopfzeile ntifs.h
Bibliothek NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL

Weitere Informationen

FltGetCopyInformationFromCallbackData

IO_STATUS_BLOCK

NtCreateFile