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.
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 |
|---|---|
|
O parâmetro Config não é o tamanho correto. |
|
Não havia memória suficiente para criar um novo objeto de dispositivo USB de estrutura. |
|
Um parâmetro inválido foi detectado. Consulte a seção Comentários para obter mais informações. |
|
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) |