Функция 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) для использования в запросе. Сведения о кодах управления ввода-вывода для конкретного типа устройства см. в разделах, посвященных типу устройства, в комплекте драйверов Windows (WDK).
[in] DeviceObject
Предоставляет указатель на структуру DEVICE_OBJECT для объекта устройства следующего уровня драйвера, представляющего целевое устройство.
[in, optional] InputBuffer
Предоставляет указатель на входной буфер, передаваемый в нижний драйвер, или NULL, если запрос не передает входные данные в более низкие драйверы.
[in] InputBufferLength
Предоставляет длину в байтах входного буфера. Если InputBufferNULL, 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драйвер может ожидать объекта события. Параметр события является необязательным и может иметь значение NULL. Однако если событие имеет значение NULL, вызывающий объект должен предоставить процедуру IoCompletion для IRP, чтобы уведомить вызывающего абонента о завершении операции.
[out] IoStatusBlock
Указывает блок состояния ввода-вывода, который необходимо задать при завершении запроса более низкими драйверами.
Возвращаемое значение
Если операция выполнена успешно, IoBuildDeviceIoControlRequest возвращает указатель на IRP с расположением стека ввода-вывода следующего уровня драйвера, настроенным из указанных параметров. В противном случае подпрограмма возвращает NULL.
Замечания
Драйвер может вызывать IoBuildDeviceIoControlRequest для настройки irPs для запросов управления устройствами, которые он синхронно отправляет драйверам нижнего уровня.
После вызова IoBuildDeviceIoControlRequest для создания запроса драйвер должен вызвать IoCallDriver, чтобы отправить запрос следующему драйверу. Если IoCallDriver возвращает STATUS_PENDING, драйвер должен ждать завершения IRP путем вызова KeWaitForSingleObject для заданного события . Большинству драйверов не нужно задавать подпрограмму IoCompletion для IRP.
IrPs, созданные IoBuildDeviceIoControlRequest, должны быть завершены вызовом драйвера к IoCompleteRequest. Драйвер, вызывающий IoBuildDeviceIoControlRequest, не должен вызывать IoFreeIrp, так как диспетчер ввода-вывода освобождает эти синхронные irPs после вызова IoCompleteRequest.
IoBuildDeviceIoControlRequest очереди irPs, создаваемые в очереди IRP, относящуюся к текущему потоку. Если поток завершает работу, диспетчер ввода-вывода отменяет IRP.
Если вызывающий объект предоставляет параметр InputBuffer или OutputBuffer, этот параметр должен указывать на буфер, который находится в системной памяти. Вызывающий объект отвечает за проверку всех значений параметров, скопированных в входной буфер из буфера пользовательского режима. Входной буфер может содержать значения параметров, которые интерпретируются по-разному в зависимости от того, является ли источник запроса приложением пользовательского режима или драйвером режима ядра. В IRP, который возвращает IoBuildDeviceIoControlReque st, поле RequestorMode всегда имеет значение KernelMode. Это значение указывает, что запрос и любая информация, содержащаяся в запросе, находится из доверенного компонента режима ядра.
Если вызывающий объект не может проверить значения параметров, скопированные из буфера пользовательского режима в входной буфер, или если эти значения не должны интерпретироваться как поступающие из компонента режима ядра, вызывающий объект должен задать поле RequestorMode в IRP значение UserMode. Этот параметр сообщает драйверу, который обрабатывает запрос элемента управления ввода-вывода, что буфер содержит ненадежные данные пользовательского режима.
Фактический метод, с помощью которого содержимое InputBuffer и параметры OutputBuffer хранятся в IRP, зависят от значения TransferType для IOCTL. Дополнительные сведения об этом значении см. в описания буферов для кодов управления ввода-вывода.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Доступно начиная с Windows 2000. |
| целевая платформа | Всеобщий |
| заголовка | wdm.h (include 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) |