Função WdfUsbTargetDeviceCreate (wdfusb.h)

Artigo
02/07/2025

[Aplica-se a KMDF e UMDF]

O método WdfUsbTargetDeviceCreate 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.

Observação Se você estiver criando seu driver usando KMDF 1.11 ou UMDF 2.0 ou posterior, recomendamos que você chame WdfUsbTargetDeviceCreateWithParameters em vez de WdfUsbTargetDeviceCreate .

Sintaxe

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

Parâmetros

[in] Device

Um identificador para um objeto de dispositivo de 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. (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.

Valor de retorno

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

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi detectado.
STATUS_INSUFFICIENT_RESOURCES	Não havia memória suficiente para criar um novo objeto de dispositivo USB.
STATUS_UNSUCCESSFUL	Falha na tentativa de obter informações de configuração USB.

Para obter uma lista de outros valores retornados que o método WdfUsbTargetDeviceCreate pode retornar, consulte Erros de Criação de Objeto da Estrutura.

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

Uma verificação de bug ocorre se o driver fornece um identificador de objeto inválido.

Observações

Um driver que usa um destino de E/S USB deve chamar WdfUsbTargetDeviceCreate após seu dispositivo entrar em seu estado de trabalho (D0). Normalmente, um driver chama WdfUsbTargetDeviceCreate de dentro de sua função de retorno de chamada EvtDevicePrepareHardware. (O driver não pode chamar WdfUsbTargetDeviceCreate de dentro de sua função de retorno de chamada do EvtDriverDeviceAdd.)

WdfUsbTargetDeviceCreate obtém o descritor de dispositivo USB e o primeiro descritor de configuração USB do dispositivo e os armazena. Ele também cria um objeto de interface USB da estrutura para cada interface na primeira configuração do dispositivo. Para determinar o número de interfaces compatíveis com a configuração, o driver pode chamar WdfUsbTargetDeviceGetNumInterfaces.

Depois de chamar WdfUsbTargetDeviceCreate, o driver pode chamar métodos de objeto de dispositivo USB estrutura adicionais.

O pai de cada objeto de dispositivo USB é o objeto de driver da estrutura do driver. O driver não pode alterar esse pai e o membro ParentObject ou a estrutura WDF_OBJECT_ATTRIBUTES deve ser NULL.

Para obter mais informações sobre o método WdfUsbTargetDeviceCreate e destinos de E/S USB, consulte destinos de E/S USB.

Exemplos

O exemplo de código a seguir faz parte de uma função de retorno de chamada EvtDevicePrepareHardware que chama WdfUsbTargetDeviceCreate. O exemplo armazena o identificador do objeto de dispositivo USB 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;

    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;
    }
 status = WdfUsbTargetDeviceCreate(
                                      Device,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &pMyDeviceContext->UsbDevice
                                      );
    if (!NT_SUCCESS(status)) {
        return status;
    }
...
}

Requisitos

Requisito	Valor
da Plataforma de Destino	Universal
versão mínima do KMDF	1.0
versão mínima do UMDF	2.0
cabeçalho	wdfusb.h (inclua Wdfusb.h)
biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
regras de conformidade de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbDeviceCreate(kmdf), UsbDevic, UsbDeviceCreateTarget(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Consulte também

EvtDevicePrepareHardware

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceGetNumInterfaces

Compartilhar via