NtDeviceIoControlFile-Funktion (ntifs.h)

2025-02-07

Die ZwDeviceIoControlFile Routine sendet einen Steuercode direkt an einen angegebenen Gerätetreiber, wodurch der entsprechende Treiber den angegebenen Vorgang ausführt.

Syntax

__kernel_entry NTSYSCALLAPI NTSTATUS NtDeviceIoControlFile(
  [in]            HANDLE           FileHandle,
  [in, optional]  HANDLE           Event,
  [in, optional]  PIO_APC_ROUTINE  ApcRoutine,
  [in, optional]  PVOID            ApcContext,
  [out]           PIO_STATUS_BLOCK IoStatusBlock,
  [in]            ULONG            IoControlCode,
  [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 das Gerät darstellt, an das die Steuerelementinformationen übergeben werden sollen oder aus denen Informationen zurückgegeben werden sollen. 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. Für E/A für ein zugrunde liegendes Massenspeichergerät muss das Dateiobjekt für den Direkten Zugriff auf das Speichergerät (DASD) geöffnet worden sein.

[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 optionalen, vom Aufrufer bereitgestellten APC-Routine, die aufgerufen werden soll, wenn der angeforderte Vorgang abgeschlossen ist. Dieser Parameter 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 Variable, 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 Member zurückgegeben.

[in] IoControlCode

IOCTL_Xxx Code, der angibt, auf welchem Geräte-E/A-Steuerungsvorgang ausgeführt werden soll, in der Regel vom zugrunde liegenden Gerätetreiber. Der Wert dieses Parameters bestimmt das Format und die erforderliche Länge des InputBuffer- und OutputBuffer-sowie welche der folgenden Parameterpaare erforderlich sind. Ausführliche Informationen zu den systemdefinierten, gerätespezifischen IOCTL_Xxx- Codes finden Sie im abschnitt Gerätetechnologiespezifischen Abschnitt der Dokumentation zum Microsoft Windows Driver Kit (WDK) und von Geräteeingabe- und Ausgabesteuerungscodes.

[in, optional] InputBuffer

Zeigen Sie auf einen vom Aufrufer zugewiesenen Eingabepuffer, der gerätespezifische Informationen enthält, die dem Zielgerät zugewiesen werden sollen. Wenn IoControlCode einen Vorgang angibt, der keine Eingabedaten erfordert, kann dieser Zeiger NULL sein.

[in] InputBufferLength

Größe des Puffers in Bytes bei InputBuffer-. Wenn InputBuffer- NULL ist, legen Sie InputBufferLength- auf Null fest.

[out, optional] OutputBuffer

Zeigen Sie auf einen vom Aufrufer zugewiesenen Ausgabepuffer, in dem Informationen vom Zielgerät zurückgegeben werden. Wenn IoControlCode- einen Vorgang angibt, der keine Ausgabedaten erzeugt, kann dieser Zeiger NULL sein.

[in] OutputBufferLength

Größe des Puffers in Bytes bei OutputBuffer-. Wenn OutputBuffer- NULL ist, legen Sie OutputBufferLength- auf Null fest.

Rückgabewert

ZwDeviceIoControlFile gibt STATUS_SUCCESS zurück, wenn der angeforderte Vorgang erfolgreich vom zugrunde liegenden Treiber ausgeführt wurde. Andernfalls kann der Rückgabewert ein Fehlerstatuscode sein, der von einem zugrunde liegenden Treiber weitergegeben wird. Mögliche Fehlerstatuscodes sind:

Bemerkungen

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

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

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 (sofern 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.

Minifilter sollten FltDeviceIoControlFile- anstelle von ZwDeviceIoControlFile-verwenden.

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

Wenn der Aufruf der ZwDeviceIoControlFile- Funktion im Benutzermodus auftritt, sollten Sie den Namen "NtDeviceIoControlFile" anstelle von "ZwDeviceIoControlFile" 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 (include Ntifs.h, Ntddk.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	PASSIVE_LEVEL (siehe Abschnitt "Hinweise")
DDI-Complianceregeln	HwStorPortProhibitedDIs, PowerIrpDDis