NtFsControlFile-Funktion (ntifs.h)

Artikel
02/29/2024

Die NtFsControlFile-Routine sendet einen Steuerungscode 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, das von NtCreateFile oder NtOpenFile 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 ApcRoutine NULL 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, 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 InputBuffer NULL 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 OutputBuffer NULL ist.

Rückgabewert

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

Hinweise

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

Im Folgenden 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 systemdefiniertem IOCTL_XXX-Codes und zum Definieren treiberspezifischer IOCTL_XXX - oder FSCTL_XXX-Werte finden Sie unter Verwenden von E/A-Steuercodes und Geräteeingabe- und Ausgabesteuerungscodes.

Minifilter sollten FltFsControlFile anstelle von NtFsControlFile verwenden.

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

Wenn der Aufruf der NtFsControlFile-Funktion im Benutzermodus erfolgt, 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, da sie Eingabeparameter verarbeiten und interpretieren. Weitere Informationen zur Beziehung zwischen den Nt XXX- und ZwXXX-Versionen einer Routine finden Sie unter Verwenden von Nt- und Zw-Versionen der Systemdienstroutinen.

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	HwStorPortProhibitedDIs, PowerIrpDDis