ZwFsControlFile-Funktion (ntifs.h)

Artikel
07/11/2023

Die ZwFsControlFile-Routine sendet einen Steuerungscode 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, das von ZwCreateFile oder ZwOpenFile für das Dateiobjekt zurückgegeben wird, 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 worden sein, wenn der Aufrufer einen Event-, ApcRoutine- und APC-Kontext (in ApcContext) oder einen Vervollständigungskontext (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 Signalzustand festgelegt ist. Dieser Parameter ist optional und kann NULL sein. Er muss NULL sein, wenn der Aufrufer wartet, bis fileHandle auf den Signalzustand festgelegt wird.

[in, optional] ApcRoutine

Adresse einer vom Anrufer bereitgestellten APC-Routine, die aufgerufen werden soll, wenn der angeforderte Vorgang abgeschlossen ist. Dieser Parameter ist optional und kann NULL sein. Er 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 einen APC bereitstellt, oder als Vervollständigungskontext verwendet, wenn dem Dateiobjekt ein E/A-Vervollständigungsobjekt zugeordnet wurde. Wenn der Vorgang abgeschlossen ist, wird entweder der APC-Kontext an den APC übergeben, sofern einer angegeben wurde, oder der Vervollständigungskontext wird als Teil der Vervollständigungsmeldung eingeschlossen, die der E/A-Manager an das zugehörige E/A-Vervollständigungsobjekt sendet.

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

[out] IoStatusBlock

Zeiger auf eine IO_STATUS_BLOCK-Struktur, die die endgültige Vervollständigung status und Informationen zum Vorgang empfängt. Bei erfolgreichen Aufrufen, die Daten zurückgeben, wird die Anzahl der in den OutputBuffer geschriebenen Bytes im Member Information 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 erforderlichen Längen von InputBuffer und OutputBuffer sowie welche der folgenden Parameterpaare erforderlich sind. Ausführliche Informationen zu den systemdefinierten FSCTL_XXX-Codes finden Sie im Abschnitt "Hinweise" des Referenzeintrags für DeviceIoControl in der Microsoft Windows SDK-Dokumentation.

[in, optional] InputBuffer

Zeiger auf einen vom Aufrufer zugewiesenen Eingabepuffer, der gerätespezifische Informationen enthält, die dem Zieltreiber zugewiesen werden sollen. Wenn FsControlCode einen Vorgang angibt, für den keine Eingabedaten erforderlich sind, ist dieser Zeiger optional und kann NULL sein.

[in] InputBufferLength

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

[out, optional] OutputBuffer

Zeiger 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 sein.

[in] OutputBufferLength

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

Rückgabewert

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

Hinweise

ZwFsControlFile bietet eine konsistente Ansicht der Eingabe- und Ausgabedaten für das System und für 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 geöffnet hat (ohne dass FILE_SYNCHRONOUS_XXX create/open-Option festgelegt ist), wird das angegebene Ereignis, falls vorhanden, auf den signalierten Zustand festgelegt, wenn der Gerätesteuerungsvorgang abgeschlossen ist. Andernfalls wird das von FileHandle angegebene Dateiobjekt auf den signalierten Zustand festgelegt. Wenn eine ApcRoutine angegeben wurde, wird sie mit den Zeigern ApcContext und IoStatusBlock 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 systemdefiniertem IOCTL_XXX-Codes und zum Definieren treiberspezifischer IOCTL_XXX - oder FSCTL_XXX-Werte finden Sie unter Verwenden von E/A-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 aktivierten speziellen Kernel-APCs ausgeführt werden.

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

Bei Aufrufen von Kernelmodustreibern können sich die Versionen **Nt*Xxx*** und **Zw*Xxx*** einer Windows Native System Services-Routine anders verhalten, wenn sie Eingabeparameter verarbeiten und interpretieren. Weitere Informationen zur Beziehung zwischen den Versionen **Nt*Xxx*** und **Zw*Xxx*** einer Routine finden Sie unter Verwenden von Nt- und Zw-Versionen der Systemdienstroutinen(/windows-hardware/drivers/kernel/using-nt-and-zw-versions-of-the-native-system-services-routines).

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000.
Zielplattform	Universell
Header	ntifs.h (include Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (siehe Abschnitt Hinweise)
DDI-Complianceregeln	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)