функция 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. Возможные значения включают эти значения, приведенные в следующей таблице.

Код возврата Описание
STATUS_SUCCESS
 Обычный вызов выполнен успешно.
STATUS_INVALID_LEVEL
 Вызывающий объект не выполняется со значением IRQL PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER
 Вызывающий объект передал одно из следующих недопустимых значений параметров:
  • DeviceObject, TargetDeviceObject или USBDHandle имеет значение NULL.
  • Недопустимое значение контракта клиента, указанное в параметре USBDClientContractVersion .
  • Значение PoolTag равно нулю.

Комментарии

Регистрация версии

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

См. также раздел

Выделение и создание urb

Рекомендации по использованию urb

USBD_CloseHandle