ZwDeviceIoControlFile-Funktion (ntifs.h)

Artikel
12/21/2024

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

Syntax

NTSYSAPI NTSTATUS ZwDeviceIoControlFile(
  [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, das von ZwCreateFile oder ZwOpenFile- für das Dateiobjekt zurückgegeben wird, 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-werden. Es muss NULL- sein, wenn der Aufrufer auf die FileHandle- auf den Zustand "Signaled" 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-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 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 welcher 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ätetechnischen der Dokumentation zum Microsoft Windows Driver Kit (WDK) und Geräteeingabe- und Ausgabesteuerungscodes 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 Zielgerät zugewiesen werden sollen. Wenn IoControlCode- einen Vorgang angibt, der keine Eingabedaten erfordert, kann dieser Zeiger NULL-werden.

[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-werden.

[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 systemdefiniertem IOCTL_XXX- codes und zum Definieren treiberspezifischer IOCTL_XXX- oder FSCTL_XXX--Werten finden Sie unter Verwenden von I/O-Steuercodes im Kernelmodusarchitekturhandbuch und Geräteeingabe- und Ausgabesteuerungscodes in der Microsoft Windows SDK-Dokumentation.

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.

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.

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