NtDeviceIoControlFile-Funktion (ntifs.h)

Artikel
02/29/2024

Die ZwDeviceIoControlFile-Routine sendet einen Steuerungscode 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

Von ZwCreateFile oder ZwOpenFile zurückgegebenes Handle für das Dateiobjekt, das das Gerät darstellt, an das die Steuerelementinformationen übergeben werden sollen, oder von dem die 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 Abschlusskontext (in ApcContext) angibt. Damit E/A auf 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 wird. Dieser Parameter ist optional und kann NULL sein. Er muss NULL sein, wenn der Aufrufer wartet, bis fileHandle auf den Signaled-Zustand 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. 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 Abschlusskontext 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 Abschlusskontext wird als Teil der Abschlussmeldung eingeschlossen, die der E/A-Manager an das zugeordnete E/A-Vervollständigungsobjekt sendet.

Dieser Parameter ist optional und kann NULL sein. Er muss NULL sein, wenn ApcRoutine NULL ist und dem Dateiobjekt kein E/A-Vervollständigungsobjekt zugeordnet ist.

[out] IoStatusBlock

Zeiger auf eine Variable, die den endgültigen Abschluss status und Informationen zum Vorgang empfängt. Bei erfolgreichen Aufrufen, die Daten zurückgeben, wird die Anzahl der Bytes, die in den OutputBuffer geschrieben werden, 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 zur Gerätetechnologie der Dokumentation zu Microsoft Windows Driver Kit (WDK) und Geräteeingabe- und Ausgabesteuerungscodes.

[in, optional] InputBuffer

Zeiger auf einen vom Aufrufer zugewiesenen Eingabepuffer, der gerätespezifische Informationen enthält, die dem Zielgerät übergeben 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 Byte. Wenn InputBuffer NULL ist, legen Sie InputBufferLength auf Null fest.

[out, optional] OutputBuffer

Zeiger auf einen vom Aufrufer zugeordneten 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 Byte bei OutputBuffer. Wenn OutputBuffer NULL 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:

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-Steuerungscodes und Geräteeingabe- und Ausgabesteuerungscodes.

Wenn der Aufrufer die Datei für asynchrone E/A geöffnet hat (ohne dass FILE_SYNCHRONOUS_Xxx-Option zum Erstellen/Öffnen festgelegt ist), wird das angegebene Ereignis, sofern 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, wie 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 systemeigenen Systemdienstroutinen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000
Zielplattform	Universell
Header	ntifs.h (include Ntifs.h, Ntddk.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (siehe Abschnitt "Hinweise")
DDI-Complianceregeln	HwStorPortProhibitedDIs, PowerIrpDDis