Função USBD_QueryUsbCapability (usbdlib.h)

A rotina de USBD_QueryUsbCapability é chamada por um driver de cliente WDM para determinar se a pilha de driver USB subjacente e o hardware do controlador de host dão suporte a uma funcionalidade específica. Observação para drivers WDF (Windows Driver Framework): Se o driver cliente for um driver baseado em WDF, você deverá chamar o método WdfUsbTargetDeviceQueryUsbCapability em vez de USBD_QueryUsbCapability.

Sintaxe

NTSTATUS USBD_QueryUsbCapability(
  [in]            USBD_HANDLE USBDHandle,
  [in]            const GUID  *CapabilityType,
  [in]            ULONG       OutputBufferLength,
  [in, out]       PUCHAR      OutputBuffer,
  [out, optional] PULONG      ResultLength
);

Parâmetros

[in] USBDHandle

Identificador USBD recuperado pelo driver cliente em uma chamada anterior para a rotina de USBD_CreateHandle .

[in] CapabilityType

Ponteiro para um GUID que representa a capacidade para a qual o driver cliente deseja recuperar informações. Os possíveis valores PGUID são os seguintes:

• GUID_USB_CAPABILITY_CHAINED_MDLS
• GUID_USB_CAPABILITY_STATIC_STREAMS
• GUID_USB_CAPABILITY_SELECTIVE_SUSPEND
• GUID_USB_CAPABILITY_FUNCTION_SUSPEND
• GUID_USB_CAPABILITY_DEVICE_CONNECTION_HIGH_SPEED_COMPATIBLE
• GUID_USB_CAPABILITY_DEVICE_CONNECTION_SUPER_SPEED_COMPATIBLE
• GUID_USB_CAPABILITY_TIME_SYNC

[in] OutputBufferLength

Comprimento, em bytes, do buffer apontado por OutputBuffer.

[in, out] OutputBuffer

Ponteiro para um buffer alocado pelo chamador. Determinadas solicitações de funcionalidade retornam informações adicionais em um buffer de saída. Para essas solicitações, você deve alocar o buffer e fornecer um ponteiro para o buffer no parâmetro OutputBuffer . Atualmente, apenas a solicitação de funcionalidade de fluxos estáticos requer um buffer de saída do tipo USHORT. O buffer é preenchido por USBD_QueryUsbCapability com o número máximo de fluxos com suporte por ponto de extremidade.

Outras solicitações de funcionalidade não exigem um buffer de saída. Para essas solicitações, você deve definir OutputBuffer como NULL e OutputBufferLength como 0.

[out, optional] ResultLength

Ponteiro para uma variável ULONG que recebe o número real de bytes no buffer apontado por OutputBuffer. O chamador pode passar NULL em ResultLength. Se ResultLength não for NULL, o valor recebido será menor ou igual ao valor OutputBufferLength .

Retornar valor

A rotina de USBD_QueryUsbCapability retorna um código de status NT.

Os valores possíveis incluem, mas não se limitam a, os códigos de status listados na tabela a seguir.

Comentários

Windows 8 inclui uma nova pilha de driver USB para dar suporte a dispositivos USB 3.0. A nova pilha de driver USB fornece vários novos recursos definidos, como suporte a fluxo e MDLs encadeados que podem ser usados por um driver cliente.

Um driver cliente pode determinar a versão da pilha de driver USB subjacente chamando a rotina IsInterfaceVersionSupported .

O driver cliente só poderá usar os novos recursos se a pilha de driver USB subjacente e o hardware deem suporte a eles. Por exemplo, para enviar solicitações de E/S para um fluxo específico associado a um ponto de extremidade em massa, a pilha de driver USB subjacente, o ponto de extremidade e o hardware do controlador de host devem dar suporte à funcionalidade de fluxos estáticos. O driver do cliente não deve chamar IsInterfaceVersionSupported e assumir os recursos da pilha de driver. Em vez disso, o driver do cliente deve sempre chamar USBD_QueryUsbCapability para determinar se a pilha de driver USB e o hardware dão suporte a uma funcionalidade específica.

A tabela a seguir descreve os recursos específicos de USB que um driver cliente pode consultar por meio de uma chamada USBD_QueryUsbCapability .

Exemplos

O snippet de código mostra como chamar USBD_QueryUsbCapability para determinar os recursos da pilha de driver USB subjacente.

/*++

Routine Description:
This helper routine queries the underlying USB driver stack
for specific capabilities. This code snippet assumes that 
USBD handle was retrieved by the client driver in a 
previous call to the USBD_CreateHandle routine.

Parameters:

fdo: Pointer to the device object that is the current top
of the stack as reported by IoAttachDeviceToDeviceStack.

Return Value: VOID
--*/

VOID QueryUsbDriverStackCaps (PDEVICE_OBJECT fdo)
{
    NTSTATUS ntStatus = STATUS_SUCCESS;   
    PDEVICE_EXTENSION deviceExtension;

    deviceExtension = (PDEVICE_EXTENSION)fdo->DeviceExtension;

    if (!deviceExtension->UsbdHandle)
    {
        return;
    }

    // Check if the underlying USB driver stack
    // supports USB 3.0 devices.

    if (!USBD_IsInterfaceVersionSupported(
        deviceExtension->UsbdHandle,                                       
        USBD_INTERFACE_VERSION_602))
    {
        KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "Old USB stack loaded.\n" ));
    }
    else
    {
        // Call USBD_QueryUsbCapability to determine 
        // function suspend support.     
        KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "New USB stack loaded.\n" ));
        ntStatus = USBD_QueryUsbCapability ( deviceExtension->UsbdHandle,  
            (GUID*)&GUID_USB_CAPABILITY_FUNCTION_SUSPEND,  
            0,  
            NULL,
            NULL);

        if (NT_SUCCESS(ntStatus)) 
        {
            deviceExtension->FunctionSuspendSupported = TRUE;
            KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "Function suspend supported.\n" ));
        } 
        else 
        {
            deviceExtension->FunctionSuspendSupported  = FALSE;
            ntStatus = STATUS_SUCCESS;
            KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "Function suspend not supported.\n" ));
        }
    }

    // Call USBD_QueryUsbCapability to determine 
    // chained MDL support. 

    ntStatus = USBD_QueryUsbCapability(
        deviceExtension->UsbdHandle,
        (GUID*)&GUID_USB_CAPABILITY_CHAINED_MDLS,
        0,
        NULL,
        NULL);

    if (NT_SUCCESS(ntStatus)) 
    {
        deviceExtension->ChainedMDLSupport = TRUE;
        KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "Chained MDLs supported.\n" ));
    } 
    else 
    {
        deviceExtension->ChainedMDLSupport = FALSE;
        ntStatus = STATUS_SUCCESS;
        KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "Chained MDLs not supported.\n" ));
    }

    // Call USBD_QueryUsbCapability to determine 
    // stream support. 

    ntStatus = USBD_QueryUsbCapability (deviceExtension->UsbdHandle, 
        (GUID*)&GUID_USB_CAPABILITY_STATIC_STREAMS, 
        sizeof(ULONG), 
        (PUCHAR) &deviceExtension->MaxSupportedStreams, 
        NULL);  


    if (!NT_SUCCESS(ntStatus)) 
    {
        deviceExtension->MaxSupportedStreams = 0;
        ntStatus = STATUS_SUCCESS;
        KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "Static streams not supported.\n" ));
    }

    // Call USBD_QueryUsbCapability to determine 
    // selective suspend support. 

    ntStatus = USBD_QueryUsbCapability (deviceExtension->UsbdHandle, 
        (GUID*)&GUID_USB_CAPABILITY_SELECTIVE_SUSPEND, 
        0, 
        NULL, 
        NULL);

    if (!NT_SUCCESS(ntStatus)) 
    {
        ntStatus = STATUS_SUCCESS;
        KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "Selective suspend not supported.\n" ));
    }
    else
    {
        KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "Selective suspend supported.\n" ));
    }

    // Call USBD_QueryUsbCapability to determine 
    // device speed. 
    ntStatus = USBD_QueryUsbCapability (deviceExtension->UsbdHandle, 
        (GUID*)&GUID_USB_CAPABILITY_DEVICE_CONNECTION_HIGH_SPEED_COMPATIBLE, 
        0, 
        NULL, 
        NULL);

    if (!NT_SUCCESS(ntStatus)) 
    {
        ntStatus = STATUS_SUCCESS;
        KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "The device is operating at full speed or lower.\n The device can operate at high speed or higher." ));
    }
    else
    {
        KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "The device is operating at high speed or higher.\n" ));
    }

    // Call USBD_QueryUsbCapability to determine 
    // device speed. 
    ntStatus = USBD_QueryUsbCapability (deviceExtension->UsbdHandle, 
        (GUID*)&GUID_USB_CAPABILITY_DEVICE_CONNECTION_SUPER_SPEED_COMPATIBLE, 
        0, 
        NULL, 
        NULL);

    if (!NT_SUCCESS(ntStatus)) 
    {
        ntStatus = STATUS_SUCCESS;
        KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "The device is operating at high speed or lower.\n The device can operate at Superspeed or higher." ));
    }
    else
    {
        KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "The device is operating at SuperSpeed or higher.\n" ));
    }

    return;

}

Requisitos

Confira também

Referência de programação do driver de dispositivo USB