Função USBD_CreateHandle (usbdlib.h)
A rotina USBD_CreateHandle é chamada por um driver cliente USB WDM para obter um identificador USBD. A rotina registra o driver cliente com a pilha de driver USB subjacente.
Observação para drivers WDF (Windows Driver Framework): Se o driver cliente for um driver baseado em WDF, você não precisará do identificador USBD. O driver cliente é registrado em sua chamada para o método WdfUsbTargetDeviceCreateWithParameters .
Sintaxe
NTSTATUS USBD_CreateHandle(
[in] PDEVICE_OBJECT DeviceObject,
[in] PDEVICE_OBJECT TargetDeviceObject,
[in] ULONG USBDClientContractVersion,
[in] ULONG PoolTag,
[out] USBD_HANDLE *USBDHandle
);
Parâmetros
[in] DeviceObject
Ponteiro para o objeto de dispositivo para o driver cliente.
[in] TargetDeviceObject
Ponteiro para o próximo objeto de dispositivo inferior na pilha do dispositivo. O driver cliente recebe um ponteiro para esse objeto de dispositivo em uma chamada anterior para IoAttachDeviceToDeviceStack.
[in] USBDClientContractVersion
A versão do contrato à qual o driver cliente dá suporte. USBDClientContractVersion deve ser USBD_CLIENT_CONTRACT_VERSION_602. Para obter mais informações, consulte Comentários.
[in] PoolTag
A marca de pool usada para alocações de memória.
[out] USBDHandle
Identificador opaco que indica que o driver cliente foi registrado com a pilha de driver USB. Para obter mais informações, consulte Comentários.
Retornar valor
A rotina retorna um código NTSTATUS. Os valores possíveis incluem, mas não se limitam a, esses valores na tabela a seguir.
| Código de retorno | Descrição |
|---|---|
|
A chamada de rotina foi bem-sucedida. |
|
O chamador não está em execução no valor IRQL PASSIVE_LEVEL. |
|
O chamador passou um dos seguintes valores de parâmetro inválidos:
|
Comentários
Registro de versão
Windows 8 inclui uma nova pilha de driver USB para dar suporte a dispositivos USB 3.0. A nova pilha de driver USB fornece vários novos recursos, como suporte a fluxo, MDLs encadeados e assim por diante. Antes que o driver cliente possa usar qualquer uma dessas funcionalidades USB, você deve registrar o driver cliente com a pilha de driver USB e obter um identificador USBD. O identificador é necessário para chamar rotinas que usam ou configuram os novos recursos. Para obter um identificador USBD, chame USBD_CreateHandle.O driver cliente deve chamar USBD_CreateHandle independentemente de o dispositivo estar anexado a um controlador de host USB 3.0, 2.0 ou 1.1. Se o dispositivo estiver anexado a um controlador de host USB 3.0, o Windows carregará a pilha de driver USB 3.0. Caso contrário, a pilha de driver USB 2.0 será carregada. Em ambos os casos, o driver cliente não precisa saber a versão compatível com a pilha de driver USB subjacente. USBD_CreateHandle avalia a versão da pilha de driver e aloca recursos adequadamente.
O driver cliente deve especificar USBD_CLIENT_CONTRACT_VERSION_602 no parâmetro USBDClientContractVersion e seguir o conjunto de regras descrito em Práticas Recomendadas: Usando URBs.
Chamando USBD_CreateHandle
A rotina USBD_CreateHandle deve ser chamada por um driver de cliente WDM (Modelo de Driver do Windows) antes que o driver envie quaisquer outras solicitações, por meio de URBs ou IOCTLs, para a pilha de driver USB. Normalmente, o driver cliente obtém o identificador USBD em sua rotina AddDevice.Um driver de cliente do WDF (Windows Driver Frameworks) não precisa chamar USBD_CreateHandle porque a estrutura chama essa rotina em nome do driver cliente durante a fase de inicialização do dispositivo. Em vez disso, o driver cliente pode especificar sua versão de contrato de cliente na estrutura WDF_USB_DEVICE_CREATE_CONFIG e passá-la na chamada para WdfUsbTargetDeviceCreateWithParameters.
Conclusão da chamada USBD_CreateHandle
Se a chamada USBD_CreateHandle for bem-sucedida, um identificador USBD válido será obtido no parâmetro USBDHandle . O driver cliente deve usar o identificador USBD nas solicitações futuras do driver cliente para a pilha de driver USB.Se a chamada USBD_CreateHandle falhar, o driver cliente poderá falhar na rotina AddDevice.
Depois que o driver cliente terminar de usar o identificador USBD, o driver deverá fechar o identificador chamando a rotina de USBD_CloseHandle .
Exemplos
O código de exemplo a seguir mostra como registrar um driver de cliente chamando USBD_CreateHandle.
DRIVER_ADD_DEVICE MyAddDevice;
NTSTATUS MyAddDevice( __in PDRIVER_OBJECT DriverObject,
__in PDEVICE_OBJECT PhysicalDeviceObject)
{
NTSTATUS ntStatus;
PDEVICE_OBJECT deviceObject;
PDEVICE_EXTENSION deviceExtension;
PDEVICE_OBJECT stackDeviceObject;
USBD_HANDLE usbdHandle;
...
ntStatus = IoCreateDevice(DriverObject,
sizeof(DEVICE_EXTENSION),
NULL,
FILE_DEVICE_UNKNOWN,
FILE_AUTOGENERATED_DEVICE_NAME,
FALSE,
&deviceObject);
if (!NT_SUCCESS(ntStatus))
{
return ntStatus;
}
...
// Attach the FDO to the top of the PDO in the client driver's
// device stack.
deviceExtension->StackDeviceObject = IoAttachDeviceToDeviceStack (
deviceObject,
PhysicalDeviceObject);
...
// Initialize the DeviceExtension
deviceExtension = deviceObject->DeviceExtension;
...
//Register the client driver with the USB driver stack.
//Obtain a USBD handle for registration.
ntStatus = USBD_CreateHandle(deviceObject,
deviceExtension->StackDeviceObject,
USBD_CLIENT_CONTRACT_VERSION_602,
POOL_TAG,
&deviceExtension->USBDHandle);
if (!NT_SUCCESS(ntStatus))
{
return ntStatus;
}
...
// Call USBD_QueryUsbCapability to determine
// stream support.
ntStatus = USBD_QueryUsbCapability ( deviceExtension->USBDHandle,
(GUID*)&GUID_USB_CAPABILITY_STATIC_STREAMS,
sizeof(ULONG),
(PUCHAR) &deviceExtension.MaxSupportedStreams);
if (!NT_SUCCESS(ntStatus))
{
deviceExtension->MaxSupportedStreams = 0;
ntStatus = STATUS_SUCCESS;
}
...
}
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Requer WDK para Windows 8. Tem como destino o Windows Vista e versões posteriores do sistema operacional Windows. |
| Plataforma de Destino | Área de Trabalho |
| Cabeçalho | usbdlib.h (inclua usbdlib.h, usb.h) |
| Biblioteca | Usbdex.lib; Ntstrsafe.lib |
| IRQL | PASSIVE_LEVEL |