IoBuildDeviceIoControlRequest

PIRP
IoBuildDeviceIoControlRequest(
IN ULONG IoControlCode,
IN PDEVICE_OBJECT DeviceObject,
IN PVOID InputBuffer, /* optional */
IN ULONG InputBufferLength,
IN OUT PVOID OutputBuffer, /* optional */
IN ULONG OutputBufferLength,
IN BOOLEAN InternalDeviceIoControl,
IN PKEVENT Event,
OUT PIO_STATUS_BLOCK IoStatusBlock
);

IoBuildDeviceIoControlRequest allocates and sets up an IRP for a device control request, optionally with an I/O buffer if the I/O control code requires the caller to supply an input or output buffer.

Parameters

IoControlCode: Specifies the IOCTL_XXX to be set up. For more information about device-type-specific I/O codes, see Part II of this manual.
DeviceObject: Points to the next-lower driver’s device object, representing the target device.
InputBuffer: Points to an input buffer to be passed to the lower driver or NULL if the request does not pass input data to lower driver(s).
InputBufferLength: Specifies the length in bytes of the input buffer. If InputBuffer is NULL, this value must be zero.
OutputBuffer: Points to an output buffer in which the lower driver is to return data or NULL if the request does not require lower driver(s) to return data.
OutputBufferLength: Specifies the length in bytes of the output buffer. If OutputBuffer is NULL, this value must be zero.
InternalDeviceIoControl: If InternalDeviceControl is TRUE the target driver’s Dispatch routine for IRP_MJ_INTERNAL_DEVICE_CONTROL or IRP_MJ_SCSI is called; otherwise, the Dispatch routine for IRP_MJ_DEVICE_CONTROL is called.
Event: Points to an initialized event object for which the caller provides the storage. The event is set to the Signaled state when lower driver(s) have completed the requested operation. The caller can wait on the event object for the completion of the IRP allocated by this routine.
IoStatusBlock: Specifies an I/O status block to be set when the request is completed by lower drivers.

Return Value

IoBuildDeviceIoControlRequest returns a pointer to an IRP with the next-lower driver’s I/O stack location partially set up from the supplied parameters. The returned pointer is NULL if an IRP cannot be allocated.

Comments

An intermediate or highest-level driver can call IoBuildDeviceIoControlRequest to set up IRPs for requests sent to lower-level drivers. The next-lower driver’s I/O stack location is set up with the given IoControlCode at Parameters.DeviceIoControl.IoControlCode. Because the caller can wait on the completion of this driver-allocated IRP by calling KeWaitForSingleObject on the given Event, the caller need not set an IoCompletion routine in the IRP before calling IoCallDriver. When the next-lower driver completes this IRP, the I/O Manager releases it.

Callers of IoBuildDeviceIoControlRequest must be running at IRQL PASSIVE_LEVEL.