Função WdfUsbTargetDeviceCreate (wdfusb.h)

[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.

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.

Retornar valor

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

Para obter uma lista de outros valores retornados que o método WdfUsbTargetDeviceCreate 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

Um driver que usa um destino de E/S USB deve chamar WdfUsbTargetDeviceCreate depois que 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 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 de 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 de estrutura adicionais.

O pai de cada objeto de dispositivo USB é o objeto de driver de estrutura do driver. O driver não pode alterar esse pai e o membro ParentObject ou a estrutura WDF_OBJECT_ATTRIBUTES devem 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

Confira também

EvtDevicePrepareHardware

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceGetNumInterfaces