Função UcxIoDeviceControl (ucxcontroller.h)

Permite que a UCX (extensão do controlador de host USB) manipule uma solicitação de IOCTL (código de controle de E/S) 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 de 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.

Retornar valor

Se a operação for bem-sucedida, o método retornará TRUE. Caso contrário, retornará FALSE.

Comentários

O driver cliente pode chamar esse método para permitir que o UCX manipule IOCTLs listados nesta tabela: IOCTLs do modo de usuário para USB. 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 as IOCTLs restantes, 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
Cliente mínimo com suporte	Windows 10
Plataforma de Destino	Windows
Cabeçalho	ucxcontroller.h (inclua Ucxclass.h)
IRQL	<=DISPATCH_LEVEL

Confira também

IOCTLs do modo de usuário para USB