IoBuildDeviceIoControlRequest-Funktion (wdm.h)

Artikel
08/08/2023

Die IoBuildDeviceIoControlRequest-Routine ordnet eine IRP für eine synchron verarbeitete Gerätesteuerungsanforderung zu und richtet sie ein.

Syntax

__drv_aliasesMem PIRP IoBuildDeviceIoControlRequest(
  [in]            ULONG            IoControlCode,
  [in]            PDEVICE_OBJECT   DeviceObject,
  [in, optional]  PVOID            InputBuffer,
  [in]            ULONG            InputBufferLength,
  [out, optional] PVOID            OutputBuffer,
  [in]            ULONG            OutputBufferLength,
  [in]            BOOLEAN          InternalDeviceIoControl,
  [in, optional]  PKEVENT          Event,
  [out]           PIO_STATUS_BLOCK IoStatusBlock
);

Parameter

[in] IoControlCode

Stellt den I/O-Kontrollcode (IOCTL) bereit, der in der Anforderung verwendet werden soll. Informationen zu gerätetypspezifischen E/A-Steuerungscodes finden Sie in den abschnitten gerätetypspezifischen Abschnitten im Windows Driver Kit (WDK).

[in] DeviceObject

Stellt einen Zeiger auf die DEVICE_OBJECT-Struktur für das Geräteobjekt des nächstniedrigen Treibers bereit, das das Zielgerät darstellt.

[in, optional] InputBuffer

Stellt einen Zeiger auf einen Eingabepuffer bereit, der an den unteren Treiber übergeben werden soll, oder NULL , wenn die Anforderung keine Eingabedaten an niedrigere Treiber übergibt.

[in] InputBufferLength

Gibt die Länge des Eingabepuffers in Byte an. Wenn InputBufferNULL ist, muss InputBufferLength null sein.

[out, optional] OutputBuffer

Stellt einen Zeiger auf einen Ausgabepuffer bereit, in dem der untere Treiber Daten zurückgeben soll, oder NULL , wenn für die Anforderung keine niedrigeren Treiber zum Zurückgeben von Daten erforderlich sind.

[in] OutputBufferLength

Stellt die Länge des Ausgabepuffers in Byte bereit. Wenn OutputBufferNULL ist, muss OutputBufferLength null sein.

[in] InternalDeviceIoControl

Bei TRUE legt die Routine den Hauptfunktionscode des IRP auf IRP_MJ_INTERNAL_DEVICE_CONTROL fest. Andernfalls legt die Routine den Hauptfunktionscode des IRP auf IRP_MJ_DEVICE_CONTROL fest.

[in, optional] Event

Stellt einen Zeiger auf ein vom Aufrufer zugeordnetes und initialisiertes Ereignisobjekt bereit. Der E/A-Manager legt das Ereignis auf den Signalzustand fest, wenn ein Treiber auf niedrigerer Ebene den angeforderten Vorgang abschließt. Nach dem Aufruf von IoCallDriver kann der Treiber auf das Ereignisobjekt warten. Der Event-Parameter ist optional und kann auf NULL festgelegt werden. Wenn event jedoch NULL ist, muss der Aufrufer eine IoCompletion-Routine angeben, damit der IRP den Aufrufer benachrichtigt, wenn der Vorgang abgeschlossen ist.

[out] IoStatusBlock

Gibt einen E/A-status-Block an, der festgelegt werden soll, wenn die Anforderung von niedrigeren Treibern abgeschlossen wird.

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt IoBuildDeviceIoControlRequest einen Zeiger auf ein IRP zurück, wobei der E/A-Stapelspeicherort des nächstniedrigen Treibers aus den angegebenen Parametern eingerichtet ist. Andernfalls gibt die Routine NULL zurück.

Hinweise

Ein Treiber kann IoBuildDeviceIoControlRequest aufrufen, um IRPs für Gerätesteuerungsanforderungen einzurichten, die er synchron an Treiber niedrigerer Ebene sendet.

Nachdem IoBuildDeviceIoControlRequest aufgerufen wurde , um eine Anforderung zu erstellen, muss der Treiber IoCallDriver aufrufen, um die Anforderung an den nächstniedrigen Treiber zu senden. Wenn IoCallDriver STATUS_PENDING zurückgibt, muss der Treiber auf den Abschluss des IRP warten, indem Er KeWaitForSingleObject für das angegebene Ereignis aufruft. Die meisten Treiber müssen keine IoCompletion-Routine für die IRP festlegen.

IRPs, die von IoBuildDeviceIoControlRequest erstellt werden, müssen durch den Aufruf eines Treibers an IoCompleteRequest abgeschlossen werden. Ein Treiber, der IoBuildDeviceIoControlRequest aufruft, darf IoFreeIrp nicht aufrufen, da der E/A-Manager diese synchronen IRPs nach dem Aufruf von IoCompleteRequest freigibt.

IoBuildDeviceIoControlRequest stellt die erstellten IRPs in eine Warteschlange für eine IRP-Warteschlange bereit, die für den aktuellen Thread spezifisch ist. Wenn der Thread beendet wird, bricht der E/A-Manager die IRP ab.

Wenn der Aufrufer einen InputBuffer - oder OutputBuffer-Parameter bereitstellt, muss dieser Parameter auf einen Puffer verweisen, der sich im Systemspeicher befindet. Der Aufrufer ist für die Überprüfung aller Parameterwerte verantwortlich, die er aus einem Benutzermoduspuffer in den Eingabepuffer kopiert. Der Eingabepuffer kann Parameterwerte enthalten, die unterschiedlich interpretiert werden, je nachdem, ob der Absender der Anforderung eine Benutzermodusanwendung oder ein Kernelmodustreiber ist. In der IRP, die IoBuildDeviceIoControlRequest zurückgibt, ist das Feld RequestorMode immer auf KernelMode festgelegt. Dieser Wert gibt an, dass die Anforderung und alle in der Anforderung enthaltenen Informationen aus einer vertrauenswürdigen Kernelmoduskomponente stammen.

Wenn der Aufrufer parameterwerte nicht überprüfen kann, die er aus einem Benutzermoduspuffer in den Eingabepuffer kopiert, oder wenn diese Werte nicht als aus einer Kernelmoduskomponente interpretiert werden dürfen, sollte der Aufrufer das Feld RequestorMode im IRP auf UserMode festlegen. Diese Einstellung informiert den Treiber, der die E/A-Steuerungsanforderung verarbeitet, dass der Puffer nicht vertrauenswürdige Daten im Benutzermodus enthält.

Die tatsächliche Methode, mit der der Inhalt der Parameter InputBuffer und OutputBuffer im IRP gespeichert wird, hängt vom TransferType-Wert für die IOCTL ab. Weitere Informationen zu diesem Wert finden Sie unter Pufferbeschreibungen für E/A-Steuerungscodes.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 2000.
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm), IoAllocateIrpSignalEventInCompletion3(wdm), IoBuildDeviceControlNoFree(wdm), IoBuildDeviceControlWait(wdm), IoBuildDeviceControlWaitTimeout(wdm), IoBuildDeviceIoControlSetEvent(wdm), IrqlPassIoive1(wdm), PowerIrpDDis(wdm), SignalEventInCompletion(wdm)