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:
| Código de retorno | Descrição |
|---|---|
|
Um parâmetro inválido foi detectado. |
|
Não havia memória suficiente para criar um novo objeto de dispositivo USB. |
|
Falha ao tentar obter informações de configuração de USB. |
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
| Requisito | Valor |
|---|---|
| Plataforma de Destino | Universal |
| Versão mínima do KMDF | 1.0 |
| 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), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |