IoBuildDeviceIoControlRequest

The IoBuildDeviceIoControlRequest function allocates and initializes an IRP to send an IOCTL request to a target device object.

Syntax


NTSTATUS IoBuildDeviceIoControlRequest(
  [out] PIO_STACK_LOCATION IrpStackLocation,
  [in]  PDEVICE_OBJECT   DeviceObject,
  [in]  ULONG            IoControlCode,
  [in]  PVOID            InputBuffer,
  [in]  ULONG            InputBufferLength,
  [in]  PVOID            OutputBuffer,
  [in]  ULONG            OutputBufferLength,
  [in]  KPROCESSOR_MODE  RequestorMode,
  [out] PSTATUS_BLOCK    IoStatusBlock
);

Parameters

Parameter Description
IrpStackLocation A pointer to an IO_STACK_LOCATION structure that will be filled with the request parameters.
DeviceObject A pointer to the DEVICE_OBJECT for the target device.
IoControlCode The IOCTL code for the request. This value specifies the operation to be performed on the target device.
InputBuffer An optional pointer to a buffer containing input data for the operation. If no input data is required, this parameter should be NULL.
InputBufferLength The size, in bytes, of the buffer pointed to by InputBuffer. If InputBuffer is NULL, this parameter must be zero.
OutputBuffer An optional pointer to a buffer that will receive output data from the operation. If no output data is expected, this parameter should be NULL.
OutputBufferLength The size, in bytes, of the buffer pointed to by OutputBuffer. If OutputBuffer is NULL, this parameter must be zero.
RequestorMode Specifies the KPROCESSOR_MODE of the caller (KernelMode or UserMode).
IoStatusBlock A pointer to an IO_STATUS_BLOCK structure that will receive the final status of the operation and the number of bytes transferred.

Return Value

The IoBuildDeviceIoControlRequest function returns STATUS_SUCCESS if the IRP and stack location were successfully initialized. Otherwise, it may return an appropriate NTSTATUS error code.

Remarks

This function is typically called by higher-level drivers to send an IOCTL to a lower-level driver. The caller is responsible for allocating the IRP itself and calling IoSetNextIrpStackLocation before calling this function.

The caller must also call IoCallDriver to send the initialized IRP to the target device.

After the operation completes, the caller is responsible for freeing the IRP using IoFreeIrp.

See Also