Função WdfUsbTargetDeviceCreateWithParameters (wdfusb.h)
[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.
Valor de retorno
WdfUsbTargetDeviceCreateWithParameters 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 |
|---|---|
|
O parâmetro Config não é o tamanho correto. |
|
Não havia memória suficiente para criar um novo objeto de dispositivo USB da estrutura. |
|
Um parâmetro inválido foi detectado. Consulte a seção Comentários para obter mais informações. |
|
Falha na tentativa de obter informações de configuração USB. |
Para obter uma lista de outros valores retornados que o método WdfUsbTargetDeviceCreateWithParameters pode retornar, consulte Framework Object Creation Errors.
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
O Windows 8 inclui uma nova pilha de driver USB para dar suporte a dispositivos USB 3.0.
Antes que um driver cliente baseado em estrutura possa usar os novos recursos da pilha de driver 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 do contrato na estrutura WDF_USB_DEVICE_CREATE_CONFIG.
Se o driver 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 do 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 do 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 |
|---|---|
| da Plataforma de Destino | Universal |
| versão mínima do KMDF | 1.11 |
| 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), RequestForUrbXrb(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf) |