ioBuildDeviceIoControlRequest 函数 (wdm.h)

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 (IOCTL) I/O 控制代码。 有关特定于设备的 I/O 控制代码的信息,请参阅 Windows 驱动程序工具包 (WDK) 中的设备类型特定部分。

[in] DeviceObject

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

[in, optional] InputBuffer

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

[in] InputBufferLength

提供输入缓冲区的长度(以字节为单位)。 如果 InputBufferNULL则 InputBufferLength 必须为零。

[out, optional] OutputBuffer

提供指向输出缓冲区的指针,其中较低驱动程序返回数据,如果请求不需要较低的驱动程序返回数据,则为 NULL

[in] OutputBufferLength

提供输出缓冲区的长度(以字节为单位)。 如果 OutputBufferNULL则 OutputBufferLength 必须为零。

[in] InternalDeviceIoControl

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

[in, optional] Event

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

[out] IoStatusBlock

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

返回值

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

注解

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

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

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

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

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

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

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

要求

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

另请参阅

IO_STACK_LOCATION

IRP

IoAllocateIrp

IoBuildAsynchronousFsdRequest

IoBuildSynchronousFsdRequest

IoCallDriver

IoCompleteRequest

KeInitializeEvent

KeWaitForSingleObject