ZwFsControlFile-Funktion (ntifs.h)

Artikel
12/21/2024

Die ZwFsControlFile Routine sendet einen Steuercode direkt an einen angegebenen Dateisystem- oder Dateisystemfiltertreiber, wodurch der entsprechende Treiber die angegebene Aktion ausführt.

Syntax

NTSYSAPI NTSTATUS ZwFsControlFile(
  [in]            HANDLE           FileHandle,
  [in, optional]  HANDLE           Event,
  [in, optional]  PIO_APC_ROUTINE  ApcRoutine,
  [in, optional]  PVOID            ApcContext,
  [out]           PIO_STATUS_BLOCK IoStatusBlock,
  [in]            ULONG            FsControlCode,
  [in, optional]  PVOID            InputBuffer,
  [in]            ULONG            InputBufferLength,
  [out, optional] PVOID            OutputBuffer,
  [in]            ULONG            OutputBufferLength
);

Parameter

[in] FileHandle

Handle zurückgegeben von ZwCreateFile oder ZwOpenFile- für das Dateiobjekt, das die Datei oder das Verzeichnis darstellt, für die die angegebene Aktion ausgeführt werden soll. Das Dateiobjekt muss für asynchrone E/A geöffnet werden, wenn der Aufrufer ein Event, ApcRoutineund einen APC-Kontext (in ApcContext) oder einen Abschlusskontext (in ApcContext) angibt.

[in, optional] Event

Handle für ein vom Aufrufer erstelltes Ereignis. Wenn dieser Parameter angegeben wird, wird der Aufrufer in einen Wartezustand versetzt, bis der angeforderte Vorgang abgeschlossen ist und das angegebene Ereignis auf den Status "Signaled" festgelegt ist. Dieser Parameter ist optional und kann NULL-werden. Es muss NULL- sein, wenn der Aufrufer auf die FileHandle- auf den Zustand "Signaled" festgelegt wird.

[in, optional] ApcRoutine

Adresse einer vom Aufrufer bereitgestellten APC-Routine, die aufgerufen werden soll, wenn der angeforderte Vorgang abgeschlossen ist. Dieser Parameter ist optional und kann NULL-werden. Es muss NULL- sein, wenn dem Dateiobjekt ein E/A-Vervollständigungsobjekt zugeordnet ist.

[in, optional] ApcContext

Zeiger auf einen vom Aufrufer bestimmten Kontextbereich. Dieser Parameterwert wird als APC-Kontext verwendet, wenn der Aufrufer ein APC bereitstellt oder als Abschlusskontext verwendet wird, wenn dem Dateiobjekt ein E/A-Abschlussobjekt zugeordnet wurde. Nach Abschluss des Vorgangs wird entweder der APC-Kontext an das APC übergeben, sofern eins angegeben wurde, oder der Abschlusskontext wird als Teil der Abschlussmeldung eingeschlossen, die der E/A-Manager an das zugeordnete E/A-Abschlussobjekt sendet.

Dieser Parameter ist optional und kann NULL-werden. Es muss NULL- sein, wenn ApcRoutine-NULL- ist und dem Dateiobjekt kein E/A-Vervollständigungsobjekt zugeordnet ist.

[out] IoStatusBlock

Zeigen Sie auf eine IO_STATUS_BLOCK Struktur, die den endgültigen Abschlussstatus und Informationen zum Vorgang empfängt. Bei erfolgreichen Aufrufen, die Daten zurückgeben, wird die Anzahl der Bytes, die in das OutputBuffer- geschrieben wurden, im Information Mitglied dieser Struktur zurückgegeben.

[in] FsControlCode

FSCTL_XXX Code, der angibt, welcher Dateisystemsteuerungsvorgang ausgeführt werden soll. Der Wert dieses Parameters bestimmt die Formate und die erforderlichen Längen des InputBuffer- und OutputBuffer-sowie welche der folgenden Parameterpaare erforderlich sind. Ausführliche Informationen zu den vom System definierten FSCTL_XXX- Codes finden Sie im Abschnitt "Hinweise" des Referenzeintrags für DeviceIoControl- in der Microsoft Windows SDK-Dokumentation.

[in, optional] InputBuffer

Zeigen Sie auf einen vom Aufrufer zugewiesenen Eingabepuffer, der gerätespezifische Informationen enthält, die dem Zieltreiber zugewiesen werden sollen. Wenn FsControlCode- einen Vorgang angibt, der keine Eingabedaten erfordert, ist dieser Zeiger optional und kann NULL-sein.

[in] InputBufferLength

Größe des Puffers in Bytes bei InputBuffer-. Dieser Wert wird ignoriert, wenn InputBuffer-NULL-ist.

[out, optional] OutputBuffer

Zeigen Sie auf einen vom Aufrufer zugewiesenen Ausgabepuffer, in dem Informationen vom Zieltreiber zurückgegeben werden. Wenn FsControlCode- einen Vorgang angibt, der keine Ausgabedaten erzeugt, ist dieser Zeiger optional und kann NULL-werden.

[in] OutputBufferLength

Größe des Puffers in Bytes bei OutputBuffer-. Dieser Wert wird ignoriert, wenn OutputBuffer-NULL-ist.

Rückgabewert

ZwFsControlFile gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Wert zurück, z. B. einen der folgenden:

Bemerkungen

ZwFsControlFile- bietet eine konsistente Ansicht der Eingabe- und Ausgabedaten an das System und an Kernelmodustreiber, während Anwendungen und zugrunde liegende Treiber mit einer treiberabhängigen Methode zum Angeben einer Kommunikationsschnittstelle bereitgestellt werden.

Wenn der Aufrufer die Datei für asynchrone E/A (mit keinem FILE_SYNCHRONOUS_XXX Create/Open Option Set) geöffnet hat, wird das angegebene Ereignis (falls vorhanden) auf den signalierten Zustand festgelegt, wenn der Gerätesteuerungsvorgang abgeschlossen ist. Andernfalls wird das durch FileHandle- angegebene Dateiobjekt auf den signalierten Zustand festgelegt. Wenn eine ApcRoutine- angegeben wurde, wird sie mit dem ApcContext- und IoStatusBlock- Zeiger aufgerufen.

Die folgenden FSCTL-Codes sind derzeit für Kernelmodustreiber dokumentiert:

FSCTL_DELETE_REPARSE_POINT

FSCTL_GET_REPARSE_POINT

FSCTL_OPBATCH_ACK_CLOSE_PENDING

FSCTL_OPLOCK_BREAK_ACK_NO_2

FSCTL_OPLOCK_BREAK_ACKNOWLEDGE

FSCTL_OPLOCK_BREAK_NOTIFY

FSCTL_REQUEST_BATCH_OPLOCK

FSCTL_REQUEST_FILTER_OPLOCK

FSCTL_REQUEST_OPLOCK_LEVEL_1

FSCTL_REQUEST_OPLOCK_LEVEL_2

FSCTL_SET_REPARSE_POINT

Weitere Informationen zu systemdefinierten FSCTL_XXX- Codes finden Sie im Abschnitt "Hinweise" des Referenzeintrags für DeviceIoControl- in der Microsoft Windows SDK-Dokumentation.

Weitere Informationen zu systemdefinierter IOCTL_XXX- codes und zum Definieren treiberspezifischer IOCTL_XXX- oder FSCTL_XXX--Werte finden Sie unter Verwenden von I/O-Steuercodes im Kernelmodusarchitekturhandbuch und Geräteeingabe- und Ausgabesteuerungscodes in der Windows SDK-Dokumentation.

Minifilter sollten FltFsControlFile- anstelle von ZwFsControlFile-verwenden.

Aufrufer von ZwFsControlFile- müssen unter IRQL = PASSIVE_LEVEL und mit speziellen Kernel-APCs ausgeführt werden, dieaktiviert sind.

Hinweis Wenn der Aufruf der ZwFsControlFile- Funktion im Benutzermodus auftritt, sollten Sie den Namen "NtFsControlFile" anstelle von "ZwFsControlFile" verwenden.

Für Aufrufe von Kernelmodustreibern können sich die Versionen **Nt*Xxx*** und **Zw*Xxx*** einer Windows Native System Services-Routine anders verhalten, wie sie Eingabeparameter verarbeiten und interpretieren. Weitere Informationen zur Beziehung zwischen den Versionen **Nt*Xxx*** und **Zw*Xxx*** einer Routine finden Sie unter [Using Nt and Zw Versions of the Native System Services Routines](/windows-hardware/drivers/kernel/using-nt-and-zw-versions-of-the-native-system-services-routines).

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 2000.
Zielplattform-	Universal
Header-	ntifs.h (einschließlich Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	PASSIVE_LEVEL (siehe Abschnitt "Hinweise")
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)