ZwDeviceIoControlFile-Funktion (ntddk.h)

Artikel
02/27/2024

Die ZwDeviceIoControlFile-Routine sendet einen Steuerungscode 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 von dem Informationen zurückgegeben werden sollen. 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. Damit E/A zu einem zugrunde liegenden Massenspeichergerät ausgeführt werden kann, 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 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 optionalen, vom Anrufer bereitgestellten APC-Routine, die aufgerufen werden soll, wenn der angeforderte Vorgang abgeschlossen ist. Dieser Parameter 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 Variable, die die endgültige Vervollständigung status und Informationen zum Vorgang empfängt. Bei erfolgreichen Aufrufen, die Daten zurückgeben, wird die Anzahl der Bytes, die in den 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 von InputBuffer und OutputBuffer sowie welche der folgenden Parameterpaare erforderlich sind. Ausführliche Informationen zu den systemdefinierten, gerätetypspezifischen IOCTL_XXX-Codes finden Sie im Abschnitt Gerätetechnologiespezifische Dokumentation des Microsoft Windows Driver Kit (WDK) und Geräteeingabe- und Ausgabesteuerungscodes in der Microsoft Windows SDK-Dokumentation.

[in, optional] InputBuffer

Zeiger 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 bei InputBuffer in Bytes. Wenn InputBufferNULL ist, legen Sie InputBufferLength auf Null fest.

[out, optional] OutputBuffer

Zeiger 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 bei OutputBuffer in Bytes. Wenn OutputBufferNULL ist, legen Sie OutputBufferLength auf 0 fest.

Rückgabewert

ZwDeviceIoControlFile gibt STATUS_SUCCESS zurück, wenn die zugrunde liegenden Treiber den angeforderten Vorgang erfolgreich ausgeführt haben. Andernfalls kann der Rückgabewert ein Fehler status Code sein, der von einem zugrunde liegenden Treiber weitergegeben wird. Mögliche Fehler status Codes sind:

Hinweise

ZwDeviceIoControlFile 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 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-Werte finden Sie unter Verwenden von E/A-Steuercodes im Kernelmodusarchitekturhandbuch und Geräteeingabe- und Ausgabesteuerungscodes in der Microsoft Windows SDK-Dokumentation.

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.

Minifilter sollten FltDeviceIoControlFile anstelle von ZwDeviceIoControlFile verwenden.

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

Wenn der Aufruf der ZwDeviceIoControlFile-Funktion im Benutzermodus erfolgt, 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, 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
Zielplattform	Universell
Header	ntddk.h (include Ntifs.h, Ntddk.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (siehe Abschnitt Hinweise)
DDI-Complianceregeln	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)