IoBuildDeviceIoControlRequest 函数 (wdm.h)

项目
08/08/2023

IoBuildDeviceIoControlRequest 例程为同步处理的设备控制请求分配和设置 IRP。

语法

__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
);

参数

[in] IoControlCode

(IOCTL) 请求中提供 I/O 控制代码。有关设备类型特定的 I/O 控制代码的信息，请参阅 Windows 驱动程序工具包 (WDK) 中的特定于设备类型的部分。

[in] DeviceObject

提供指向下一个较低驱动程序的设备对象的 DEVICE_OBJECT 结构的指针，该对象表示目标设备。

[in, optional] InputBuffer

提供指向要传递给较低驱动程序的输入缓冲区的指针;如果请求未将输入数据传递给较低驱动程序，则提供 NULL 。

[in] InputBufferLength

提供输入缓冲区的长度（以字节为单位）。如果 InputBuffer 为 NULL， 则 InputBufferLength 必须为零。

[out, optional] OutputBuffer

提供指向输出缓冲区的指针，该输出缓冲区的较低驱动程序将返回数据;如果请求不需要较低级驱动程序返回数据，则为 NULL 。

[in] OutputBufferLength

提供输出缓冲区的长度（以字节为单位）。如果 OutputBuffer 为 NULL，OutputBufferLength 必须为零。

[in] InternalDeviceIoControl

如果 为 TRUE，则例程将 IRP 的主要函数代码设置为 IRP_MJ_INTERNAL_DEVICE_CONTROL。否则，例程会将 IRP 的主函数代码设置为 IRP_MJ_DEVICE_CONTROL。

[in, optional] Event

提供指向调用方分配和初始化的事件对象的指针。当较低级别的驱动程序完成请求的操作时，I/O 管理器将事件设置为“已信号”状态。调用 IoCallDriver 后，驱动程序可以等待事件对象。 Event 参数是可选的，可以设置为 NULL。但是，如果 Event 为 NULL，则调用方必须为 IRP 提供 IoCompletion 例程，以便在操作完成时通知调用方。

[out] IoStatusBlock

指定要在请求由较低级驱动程序完成时设置的 I/O 状态块。

返回值

如果操作成功， IoBuildDeviceIoControlRequest 将返回指向 IRP 的指针，该指针通过提供的参数设置下一个较低驱动程序的 I/O 堆栈位置。否则，例程返回 NULL。

注解

驱动程序可以调用 IoBuildDeviceIoControlRequest ，为同步发送到较低级别驱动程序的设备控制请求设置 IRP。

调用 IoBuildDeviceIoControlRequest 创建请求后，驱动程序必须调用 IoCallDriver 以将请求发送到下一个较低的驱动程序。如果 IoCallDriver 返回STATUS_PENDING，则驱动程序必须通过在给定事件上调用 KeWaitForSingleObject 来等待 IRP 完成。大多数驱动程序不需要为 IRP 设置 IoCompletion 例程。

由 IoBuildDeviceIoControlRequest 创建的 IRP 必须由驱动程序调用 IoCompleteRequest 来完成。调用 IoBuildDeviceIoControlRequest 的驱动程序不得调用 IoFreeIrp，因为 I/O 管理器在调用 IoCompleteRequest 后释放这些同步 IRP。

IoBuildDeviceIoControlRequest 将创建的 IRP 队列排队到特定于当前线程的 IRP 队列。如果线程退出，I/O 管理器将取消 IRP。

如果调用方提供 InputBuffer 或 OutputBuffer 参数，则此参数必须指向驻留在系统内存中的缓冲区。调用方负责验证从用户模式缓冲区复制到输入缓冲区的任何参数值。输入缓冲区可能包含不同解释的参数值，具体取决于请求的发起方是用户模式应用程序还是内核模式驱动程序。在 IoBuildDeviceIoControlRequest 返回的 IRP 中， RequestorMode 字段始终设置为 KernelMode。此值指示请求以及请求中包含的任何信息来自受信任的内核模式组件。

如果调用方无法验证它从用户模式缓冲区复制到输入缓冲区的参数值，或者如果不能将这些值解释为来自内核模式组件，则调用方应将 IRP 中的 RequestorMode 字段设置为 UserMode。此设置通知处理 I/O 控制请求的驱动程序缓冲区包含不受信任的用户模式数据。

在 IRP 中存储 InputBuffer 和 OutputBuffer 参数内容的实际方法取决于 IOCTL 的 TransferType 值。有关此值的详细信息，请参阅 I/O 控制代码的缓冲区说明。

要求

要求	值
最低受支持的客户端	从 Windows 2000 开始可用。
目标平台	通用
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
DDI 符合性规则	HwStorPortProhibitedDDI (storport) ， IoAllocateIrpSignalEventInCompletion (wdm) ， IoAllocateIrpSignalEventInCompletion2 (wdm) ， IoAllocateIrpSignalEventInCompletion3 (wdm) ， IoBuildDeviceControlNoFree (wdm) 、 IoBuildDeviceControlWait (wdm) 、 IoBuildDeviceControlWaitTimeout (wdm) 、 IoBuildDeviceIoControlSetEvent (wdm) 、 IrqlIoPassive1 (wdm) ， PowerIrpDDis (wdm) 、 SignalEventInCompletion (wdm)