Функция UcxIoDeviceControl (ucxcontroller.h)
Позволяет расширению контроллера узла USB (UCX) обрабатывать запрос кода управления вводом-выводом (IOCTL) из пользовательского режима.
Синтаксис
BOOLEAN UcxIoDeviceControl(
[in] WDFDEVICE Device,
[in] WDFREQUEST Request,
[in] size_t OutputBufferLength,
[in] size_t InputBufferLength,
[in] ULONG IoControlCode
);
Параметры
[in] Device
Дескриптор объекта устройства платформы, который драйвер клиента извлек в предыдущем вызове WdfDeviceCreate.
[in] Request
Дескриптор объекта запроса платформы, который представляет запрос IOCTL в пользовательском режиме.
[in] OutputBufferLength
Длина выходного буфера запроса в байтах, если выходной буфер доступен.
[in] InputBufferLength
Длина входного буфера запроса (в байтах), если входной буфер доступен.
[in] IoControlCode
Определяемый драйвером или системой IOCTL, связанный с запросом.
Возвращаемое значение
Если операция выполнена успешно, метод возвращает значение TRUE. В противном случае возвращается значение FALSE.
Комментарии
Драйвер клиента может вызвать этот метод, чтобы разрешить UCX обрабатывать ioCTLs, перечисленные в таблице User-Mode IOCTLs для USB. Если код IOCTL IOCTL_USB_DIAGNOSTIC_MODE_OFF или IOCTL_USB_DIAGNOSTIC_MODE_ON, UCX успешно завершает запрос. Для IOCTLS, которые используются для получения имени ключа драйвера контроллеров USB-контроллеров, например IOCTL_USB_GET_ROOT_HUB_NAME или IOCTL_GET_HCD_DRIVERKEY_NAME, UCX извлекает строку Юникода. Если IOCTL пользовательского режима IOCTL_USB_USER_REQUEST, длина входного и выходного буферов должна быть одинаковой, а выходной буфер должен содержать структуру USBUSER_REQUEST_HEADER . Для остальных списков IOCTL UCX возвращает значение FALSE, и драйвер клиента может предоставить собственную логику обработки.
Примеры
VOID
Controller_WdfEvtIoDeviceControl(
WDFQUEUE WdfQueue,
WDFREQUEST WdfRequest,
size_t OutputBufferLength,
size_t InputBufferLength,
ULONG IoControlCode
)
/*++
Routine Description:
This routine is a callback function which is called by WDF when a driver
receives an I/O control request from the queue this callback is registered
with.
The controller driver calls UcxIoDeviceControl() to allow UCX to try and
handle the IOCTL. If UCX cannot handle the IOCTL, the controller driver
must handle it, perhaps by failing it.
The default queue only expects to receive IOCTLs from user mode (via the
interface defined by GUID_DEVINTERFACE_USB_HOST_CONTROLLER).
Arguments:
WdfQueue - A handle to the framework I/O queue object.
WdfRequest - A handle to the framework request object that contains the IOCTL.
OutputBufferLength - Length of the IOCTL output buffer, if an output buffer
is available.
InputBufferLength - Length of the IOCTL input buffer, if an input buffer
is available.
IoControlCode - I/O control code associated with the request.
Return Value:
None.
--*/
{
KPROCESSOR_MODE requestorMode;
//
// Allow UCX to try and handle the request
//
if (UcxIoDeviceControl(WdfIoQueueGetDevice(WdfQueue),
WdfRequest,
OutputBufferLength,
InputBufferLength,
IoControlCode)) {
DbgTrace(TL_VERBOSE, Controller, "IoControlCode 0x%x was handled by UCX", IoControlCode);
goto WdfEvtIoDeviceControlEnd;
}
//
// Check that the request is coming from user mode
//
requestorMode = WdfRequestGetRequestorMode(WdfRequest);
if (requestorMode != UserMode) {
DbgTrace(TL_WARNING, Controller, "Invalid RequestorMode %d", requestorMode);
}
//
// UCX could not handle the request, so handle it here
//
switch (IoControlCode) {
default:
DbgTrace(TL_WARNING, Controller, "Unsupported IoControlCode 0x%x", IoControlCode);
WdfRequestComplete(WdfRequest, STATUS_INVALID_DEVICE_REQUEST);
}
WdfEvtIoDeviceControlEnd:
return;
}
Требования
Требование | Значение |
---|---|
Минимальная версия клиента | Windows 10 |
Целевая платформа | Windows |
Header | ucxcontroller.h (включая Ucxclass.h) |
IRQL | <=DISPATCH_LEVEL |