NtFsControlFile-Funktion (ntifs.h)

Artikel
12/21/2024

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

Syntax

__kernel_entry NTSYSCALLAPI NTSTATUS NtFsControlFile(
  [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 NtCreateFile oder NtOpenFile- 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 sein. Er muss NULL sein, wenn der Aufrufer auf die FileHandle- auf den Signalstatus 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 sein. 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 sein. 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, 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 sein.

[in] OutputBufferLength

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

Rückgabewert

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

Bemerkungen

NtFsControlFile- 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.

Nachfolgend sind einige der FSCTL-Codes aufgeführt, die für Kernelmodustreiber dokumentiert sind:

Weitere Informationen zu systemdefinierten FSCTL_XXX Codes finden Sie im Abschnitt "Hinweise" des Referenzeintrags für DeviceIoControl.

Weitere Informationen zu vom System definierten IOCTL_XXX--Codes und zum Definieren treiberspezifischer IOCTL_XXX- oder FSCTL_XXX--Werte finden Sie unter Using I/O Control Codes and Device Input and Output Control Codes.

Minifilter sollten FltFsControlFile- anstelle von NtFsControlFile-verwenden.

Aufrufer von NtFsControlFile- müssen unter IRQL = PASSIVE_LEVEL und mit speziellen Kernel-APCs ausgeführt werden, die aktiviert sind**.

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

Bei Aufrufen von Kernelmodustreibern können sich die NtXXX- und ZwXXX- Versionen einer Windows Native System Services-Routine anders verhalten, wie sie Eingabeparameter behandeln und interpretieren. Weitere Informationen zur Beziehung zwischen den NtXXX und ZwXXX Versionen einer Routine finden Sie unter 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, PowerIrpDDis