Função WdfUsbTargetDeviceCreateWithParameters (wdfusb.h)

  • Artigo

[Aplica-se a KMDF e UMDF]

O método WdfUsbTargetDeviceCreateWithParameters cria um objeto de dispositivo USB de estrutura para um objeto de dispositivo de estrutura especificado e abre o dispositivo USB para operações de E/S. O método também especifica informações de configuração para o objeto de dispositivo USB da estrutura.

Sintaxe

NTSTATUS WdfUsbTargetDeviceCreateWithParameters(
  [in]           WDFDEVICE                     Device,
  [in]           PWDF_USB_DEVICE_CREATE_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES        Attributes,
  [out]          WDFUSBDEVICE                  *UsbDevice
);

Parâmetros

[in] Device

Um identificador para um objeto de dispositivo de estrutura.

[in] Config

Um ponteiro para uma estrutura WDF_USB_DEVICE_CREATE_CONFIG que contém informações de configuração para o objeto de dispositivo USB da estrutura.

[in, optional] Attributes

Um ponteiro para uma estrutura de WDF_OBJECT_ATTRIBUTES fornecida pelo chamador que contém atributos para o novo objeto de dispositivo USB da estrutura. (O membro ParentObject da estrutura deve ser NULL.) Esse parâmetro é opcional e pode ser WDF_NO_OBJECT_ATTRIBUTES.

[out] UsbDevice

Um ponteiro para um local que recebe um identificador para o novo objeto de dispositivo USB da estrutura.

Retornar valor

WdfUsbTargetDeviceCreateWithParameters retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método pode retornar um dos seguintes valores:

Código de retorno Descrição
STATUS_INFO_LENGTH_MISMATCH
 O parâmetro Config não é o tamanho correto.
STATUS_INSUFFICIENT_RESOURCES
 Não havia memória suficiente para criar um novo objeto de dispositivo USB de estrutura.
STATUS_INVALID_PARAMETER
 Um parâmetro inválido foi detectado. Consulte a seção Comentários para obter mais informações.
STATUS_UNSUCCESSFUL
 Falha ao tentar obter informações de configuração de USB.
 

Para obter uma lista de outros valores retornados que o método WdfUsbTargetDeviceCreateWithParameters pode retornar, consulte Erros de criação de objeto de estrutura.

Esse método também pode retornar outros valores NTSTATUS.

Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Comentários

Windows 8 inclui uma nova pilha de driver USB para dar suporte a dispositivos USB 3.0.

Antes que um driver de cliente baseado em estrutura possa usar os novos recursos da pilha de drivers USB para Windows 8, o driver deve registrar-se com a pilha de driver USB subjacente que é carregada pelo Windows para o dispositivo. Para registrar o driver cliente, chame WdfUsbTargetDeviceCreateWithParameters e especifique uma versão de contrato na estrutura WDF_USB_DEVICE_CREATE_CONFIG .

Se o driver do cliente se destina a compilar, executar e usar as melhorias e os novos recursos no Windows 8, a versão do contrato do cliente será USBD_CLIENT_CONTRACT_VERSION_602.

Normalmente, os drivers chamam WdfUsbTargetDeviceCreateWithParameters de dentro de uma função de retorno de chamada EvtDevicePrepareHardware . Os drivers também podem chamar WdfUsbTargetDeviceCreateWithParameters de dentro de uma função de retorno de chamada EvtDriverDeviceAdd .

Para obter informações sobre como os drivers de cliente USB WDM interagem com a pilha de driver USB 3.0, consulte Práticas recomendadas: usando URBs.

Se o driver chamar WdfUsbTargetDeviceCreateWithParameters para criar um objeto de dispositivo USB de estrutura, o driver deverá criar URBs apenas chamando WdfUsbTargetDeviceCreateUrb ou WdfUsbTargetDeviceCreateIsochUrb.

Se você chamar esse método de um driver UMDF, deverá especificar a diretiva UmdfDispatcher no arquivo INF do driver. Caso contrário, esse método poderá retornar STATUS_INVALID_PARAMETER. Para obter mais informações sobre essa diretiva, consulte Especificando diretivas WDF em arquivos INF.

Exemplos

O exemplo de código a seguir faz parte de uma função de retorno de chamada EvtDevicePrepareHardware que chama WdfUsbTargetDeviceCreateWithParameters. O exemplo armazena o identificador para o objeto de dispositivo USB da estrutura no espaço de contexto definido pelo driver.

NTSTATUS
MyEvtDevicePrepareHardware(
    IN WDFDEVICE  Device,
    IN WDFCMRESLIST  ResourceList,
    IN WDFCMRESLIST  ResourceListTranslated
    )
{
    NTSTATUS  status;
    PMY_DEVICE_CONTEXT  pMyDeviceContext;
    WDF_USB_DEVICE_CREATE_CONFIG  Config;

    pMyDeviceContext = GetDeviceContext(Device);

    // If object handle is not NULL, MyEvtDevicePrepareHardware
    // was called previously and the handle is still valid.
    if (pMyDeviceContext->UsbDevice != NULL) {
        return STATUS_SUCCESS;
    }

    WDF_USB_DEVICE_CREATE_CONFIG_INIT(
                                      &Config,
                                      USBD_CLIENT_CONTRACT_VERSION_602
                                      );

    status = WdfUsbTargetDeviceCreateWithParameters(
                                      Device,
                                      &Config,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &pMyDeviceContext->UsbDevice
                                      );
    if (!NT_SUCCESS(status)) {
        return status;
    }
...
}

Requisitos

Requisito Valor
Plataforma de Destino Universal
Versão mínima do KMDF 1.11
Versão mínima do UMDF 2,0
Cabeçalho wdfusb.h (include Wdfusb.h)
Biblioteca Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
Regras de conformidade da DDI DriverCreate(kmdf), RequestForUrbXrb(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf)

Confira também

USBD_CreateHandle

WDF_USB_DEVICE_CREATE_CONFIG

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreate