NtCopyFileChunk-Funktion (ntifs.h)
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 |