Função UcxIoDeviceControl (ucxcontroller.h)
Permite que a UCX (extensão do controlador de host USB) manipule uma solicitação de código de controle de E/S (IOCTL) do modo de usuário.
Sintaxe
BOOLEAN UcxIoDeviceControl(
[in] WDFDEVICE Device,
[in] WDFREQUEST Request,
[in] size_t OutputBufferLength,
[in] size_t InputBufferLength,
[in] ULONG IoControlCode
);
Parâmetros
[in] Device
Um identificador para o objeto de dispositivo da estrutura que o driver cliente recuperou na chamada anterior para WdfDeviceCreate.
[in] Request
Um identificador para um objeto de solicitação de estrutura que representa a solicitação IOCTL no modo de usuário.
[in] OutputBufferLength
O comprimento, em bytes, do buffer de saída da solicitação, se um buffer de saída estiver disponível.
[in] InputBufferLength
O comprimento, em bytes, do buffer de entrada da solicitação, se um buffer de entrada estiver disponível.
[in] IoControlCode
O IOCTL definido pelo driver ou definido pelo sistema associado à solicitação.
Valor de retorno
Se a operação for bem-sucedida, o método retornará TRUE. Caso contrário, retornará FALSE.
Observações
O driver cliente pode chamar esse método para permitir que o UCX lide com IOCTLs listados nesta tabela: User-Mode IOCTLs paraUSB. Se o código IOCTL for IOCTL_USB_DIAGNOSTIC_MODE_OFF ou IOCTL_USB_DIAGNOSTIC_MODE_ON, o UCX concluirá a solicitação com êxito. Para IOCTLS que são usados para recuperar o nome da chave de driver dos controladores de host USB, como IOCTL_USB_GET_ROOT_HUB_NAME ou IOCTL_GET_HCD_DRIVERKEY_NAME, o UCX recupera a cadeia de caracteres Unicode. Se o modo de usuário IOCTL for IOCTL_USB_USER_REQUEST, os comprimentos do buffer de entrada e saída deverão ser iguais e o buffer de saída deverá conter a estrutura USBUSER_REQUEST_HEADER. Para os IOCTLs restantes, o UCX retorna FALSE e o driver cliente pode fornecer sua própria lógica de manipulação.
Exemplos
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;
}
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows 10 |
| da Plataforma de Destino | Windows |
| cabeçalho | ucxcontroller.h (inclua Ucxclass.h) |
| IRQL | <=DISPATCH_LEVEL |