Функция 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), который будет использоваться в запросе. Сведения о кодах элементов управления вводом-выводом для конкретных типов устройств см. в разделах, посвященных типу устройства, в комплекте драйверов 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

Предоставляет указатель на выделенный вызывающим и инициализированный объект события. Диспетчер ввода-вывода устанавливает для события состояние Signaled , когда драйвер нижнего уровня завершает запрошенную операцию. После вызова IoCallDriver драйвер может ожидать объекта события. Параметр Event является необязательным и может иметь значение NULL. Однако если event имеет значение NULL, вызывающий объект должен предоставить процедуру IoCompletion для IRP, чтобы уведомить вызывающего объекта о завершении операции.

[out] IoStatusBlock

Указывает блок состояния ввода-вывода, который необходимо задать при выполнении запроса более низкими драйверами.

Возвращаемое значение

Если операция выполнена успешно, IoBuildDeviceIoControlRequest возвращает указатель на IRP с расположением стека ввода-вывода следующего ниже драйвера, настроенного из указанных параметров. В противном случае подпрограмма возвращает значение NULL.

Драйвер может вызвать IoBuildDeviceIoControlRequest , чтобы настроить IRP для запросов на управление устройствами, которые он синхронно отправляет драйверам более низкого уровня.

После вызова IoBuildDeviceIoControlRequest для создания запроса драйвер должен вызвать IoCallDriver , чтобы отправить запрос следующему драйверу ниже. Если IoCallDriver возвращает STATUS_PENDING, драйвер должен дождаться завершения IRP, вызвав KeWaitForSingleObject для заданного события. Большинству драйверов не нужно задавать подпрограмму IoCompletion для IRP.

IrP, созданные IoBuildDeviceIoControlRequest , должны быть завершены вызовом драйвера IoCompleteRequest. Драйвер, вызывающий IoBuildDeviceIoControlRequest , не должен вызывать IoFreeIrp, так как диспетчер ввода-вывода освобождает эти синхронные IRP после вызова IoCompleteRequest .

IoBuildDeviceIoControlRequest помещает создаваемые им irP в очередь IRP, относяющуюся к текущему потоку. Если поток завершается, диспетчер ввода-вывода отменяет IRP.

Если вызывающий объект предоставляет параметр InputBuffer или OutputBuffer , этот параметр должен указывать на буфер, который находится в системной памяти. Вызывающий объект отвечает за проверку всех значений параметров, копируемых во входной буфер из буфера пользовательского режима. Входной буфер может содержать значения параметров, которые интерпретируются по-разному в зависимости от того, является ли инициатор запроса приложением в пользовательском режиме или драйвером режима ядра. В IRP, возвращаемом IoBuildDeviceIoControlRequest , поле RequestorMode всегда имеет значение KernelMode. Это значение указывает, что запрос и все сведения, содержащиеся в запросе, от доверенного компонента режима ядра.

Если вызывающий объект не может проверить значения параметров, копируемые из буфера пользовательского режима во входной буфер, или если эти значения не следует интерпретировать как поступающие из компонента режима ядра, вызывающий объект должен задать для поля RequestorMode в IRP значение UserMode. Этот параметр информирует драйвер, обрабатывающий запрос управления вводом-выводом, что буфер содержит ненадежные данные в пользовательском режиме.

Фактический метод, с помощью которого содержимое параметров InputBuffer и OutputBuffer хранится в IRP, зависит от значения TransferType для IOCTL. Дополнительные сведения об этом значении см. в разделе Описания буфера для кодов управления вводом-выводом.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 2000.
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
Правила соответствия DDI	HwStorPortProhibitedDIs(storport), IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm), IoAllocateIrpSignalEventInCompletion3(wdm), IoBuildDeviceControlNoFree(wdm), IoBuildDeviceControlWait(wdm), IoBuildDeviceControlWaitTimeout(wdm), IoBuildDeviceIoControlSetEvent(wdm), IrqlIoPassive1(wdm), PowerIrpDDis(wdm), SignalEventInCompletion(wdm)