функция USBD_CreateHandle (usbdlib.h)
Подпрограмма USBD_CreateHandle вызывается драйвером КЛИЕНТА WDM USB для получения дескриптора USBD. Подпрограмма регистрирует драйвер клиента в базовом стеке драйверов USB.
Примечание для драйверов Windows Driver Framework (WDF): Если драйвер клиента является драйвером на основе WDF, дескриптор USBD не требуется. Драйвер клиента регистрируется в вызове метода WdfUsbTargetDeviceCreateWithParameters .
Синтаксис
NTSTATUS USBD_CreateHandle(
[in] PDEVICE_OBJECT DeviceObject,
[in] PDEVICE_OBJECT TargetDeviceObject,
[in] ULONG USBDClientContractVersion,
[in] ULONG PoolTag,
[out] USBD_HANDLE *USBDHandle
);
Параметры
[in] DeviceObject
Указатель на объект устройства для драйвера клиента.
[in] TargetDeviceObject
Указатель на следующий нижний объект устройства в стеке устройств. Драйвер клиента получает указатель на этот объект устройства при предыдущем вызове IoAttachDeviceToDeviceStack.
[in] USBDClientContractVersion
Версия контракта, которую поддерживает драйвер клиента. USBDClientContractVersion должен быть USBD_CLIENT_CONTRACT_VERSION_602. Дополнительные сведения см. в подразделе "Примечания".
[in] PoolTag
Тег пула, используемый для выделения памяти.
[out] USBDHandle
Непрозрачный дескриптор, указывающий, что драйвер клиента был зарегистрирован в стеке драйверов USB. Дополнительные сведения см. в подразделе "Примечания".
Возвращаемое значение
Подпрограмма возвращает код NTSTATUS. Возможные значения включают эти значения, приведенные в следующей таблице.
| Код возврата | Описание |
|---|---|
|
Обычный вызов выполнен успешно. |
|
Вызывающий объект не выполняется со значением IRQL PASSIVE_LEVEL. |
|
Вызывающий объект передал одно из следующих недопустимых значений параметров:
|
Комментарии
Регистрация версии
Windows 8 включает новый стек драйверов USB для поддержки устройств USB 3.0. Новый стек драйверов USB предоставляет несколько новых возможностей, таких как поддержка потоков, цепочки многомерных выражений и т. д. Прежде чем драйвер клиента сможет использовать любую из этих возможностей USB, необходимо зарегистрировать драйвер клиента в стеке usb-драйверов и получить дескриптор USBD. Дескриптор необходим для вызова подпрограмм, которые используют или настраивают новые возможности. Чтобы получить дескриптор USBD, вызовите USBD_CreateHandle.Драйвер клиента должен вызывать USBD_CreateHandle независимо от того, подключено ли устройство к хост-контроллеру USB 3.0, 2.0 или 1.1. Если устройство подключено к хост-контроллеру USB 3.0, Windows загружает стек драйверов USB 3.0. В противном случае загружается стек драйверов USB 2.0. В любом случае драйверу клиента не требуется знать версию, поддерживаемую базовым стеком драйверов USB. USBD_CreateHandle оценивает версию стека драйверов и выделяет ресурсы соответствующим образом.
Драйвер клиента должен указать USBD_CLIENT_CONTRACT_VERSION_602 в параметре USBDClientContractVersion и следовать набору правил, описанных в разделе Рекомендации: использование URB.
Вызов USBD_CreateHandle
Подпрограмма USBD_CreateHandle должна вызываться клиентским драйвером модели драйвера Windows (WDM), прежде чем драйвер отправляет любые другие запросы через URB или IOCTL в стек драйверов USB. Как правило, драйвер клиента получает дескриптор USBD в своей процедуре AddDevice.Драйвер клиента Windows Driver Frameworks (WDF) не требуется для вызова USBD_CreateHandle , так как платформа вызывает эту подпрограмму от имени клиентского драйвера на этапе инициализации устройства. Вместо этого драйвер клиента может указать версию контракта клиента в структуре WDF_USB_DEVICE_CREATE_CONFIG и передать ее в вызове WdfUsbTargetDeviceCreateWithParameters.
Завершение вызова USBD_CreateHandle
Если вызов USBD_CreateHandle выполнен успешно, в параметре USBDHandle будет получен допустимый дескриптор USBD. Драйвер клиента должен использовать дескриптор USBD в будущих запросах драйвера клиента к стеку драйверов USB.Если вызов USBD_CreateHandle завершается сбоем, драйвер клиента может завершиться ошибкой процедуры AddDevice.
После завершения работы драйвера клиента с помощью дескриптора USBD драйвер должен закрыть дескриптор, вызвав подпрограмму USBD_CloseHandle .
Примеры
В следующем примере кода показано, как зарегистрировать драйвер клиента, вызвав 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;
}
...
}
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Требуется WDK для Windows 8. Предназначен для Windows Vista и более поздних версий операционной системы Windows. |
| Целевая платформа | Персональный компьютер |
| Верхняя часть | usbdlib.h (включая usbdlib.h, usb.h) |
| Библиотека | Usbdex.lib; Ntstrsafe.lib |
| IRQL | PASSIVE_LEVEL |