Функция WdfUsbTargetDeviceCreateWithParameters (wdfusb.h)

Статья
02/07/2025

[Применимо к KMDF и UMDF]

Метод WdfUsbTargetDeviceCreateWithParameters создает объект USB-устройства платформы для указанного объекта устройства платформы и открывает USB-устройство для операций ввода-вывода. Метод также указывает сведения о конфигурации объекта USB-устройства платформы.

Синтаксис

NTSTATUS WdfUsbTargetDeviceCreateWithParameters(
  [in]           WDFDEVICE                     Device,
  [in]           PWDF_USB_DEVICE_CREATE_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES        Attributes,
  [out]          WDFUSBDEVICE                  *UsbDevice
);

Параметры

[in] Device

Дескриптор объекта устройства платформы.

[in] Config

Указатель на структуру WDF_USB_DEVICE_CREATE_CONFIG, содержащую сведения о конфигурации для объекта USB-устройства платформы.

[in, optional] Attributes

Указатель на структуру, предоставляемую вызывающим WDF_OBJECT_ATTRIBUTES, которая содержит атрибуты для нового объекта USB-устройства платформы. (Элемент в структуре ParentObject должен иметь значение NULL.) Этот параметр является необязательным и может быть WDF_NO_OBJECT_ATTRIBUTES.

[out] UsbDevice

Указатель на расположение, которое получает дескриптор к новому объекту USB-устройства платформы.

Возвращаемое значение

WdfUsbTargetDeviceCreateWithParameters возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод может вернуть одно из следующих значений:

Возвращаемый код	Описание
STATUS_INFO_LENGTH_MISMATCH	Параметр конфигурации не является правильным.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно памяти для создания нового объекта USB-устройства платформы.
STATUS_INVALID_PARAMETER	Обнаружен недопустимый параметр. Дополнительные сведения см. в разделе "Примечания".
STATUS_UNSUCCESSFUL	Не удалось получить сведения о конфигурации USB.

Список других возвращаемых значений, которые может возвращать метод WdfUsbTargetDeviceCreateWithParameters, см. в разделе Ошибки создания объектов Framework.

Этот метод также может возвращать другие значения NTSTATUS.

Ошибка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Замечания

Windows 8 включает новый стек USB-драйверов для поддержки устройств USB 3.0.

Прежде чем драйвер клиента на основе платформы может использовать новые возможности стека USB-драйверов для Windows 8, драйвер должен зарегистрировать себя в базовом стеке USB-драйверов, загруженном Windows для устройства. Чтобы зарегистрировать драйвер клиента, вызовите WdfUsbTargetDeviceCreateWithParameters и укажите версию контракта в структуре WDF_USB_DEVICE_CREATE_CONFIG.

Если драйвер клиента предназначен для сборки, запуска и использования улучшений и новых возможностей в Windows 8, версия контракта клиента USBD_CLIENT_CONTRACT_VERSION_602.

Как правило, драйверы вызывают WdfUsbTargetDeviceCreateWithParameters из функции обратного вызова EvtDevicePrepareHardware. Драйверы также могут вызывать WdfUsbTargetDeviceCreateWithParameters из функции обратного вызова EvtDriverDeviceAd d.

Сведения о том, как драйверы USB-клиента WDM взаимодействуют с стеком драйверов USB 3.0, см. в статье Рекомендации. Использование URI.

Если драйвер вызывает WdfUsbTargetDeviceCreateWithParameters для создания объекта USB-устройства платформы, драйвер должен создавать URI только путем вызова WdfUsbTargetDeviceCreateUrb или WdfUsbTargetDeviceCreateIsochUrb.

При вызове этого метода из драйвера UMDF необходимо указать директиву UmdfDispatcher в INF-файле драйвера. В противном случае этот метод может вернуть STATUS_INVALID_PARAMETER. Дополнительные сведения об этой директиве см. в разделе Указание директив WDF в INF Files.

Примеры

Следующий пример кода является частью функции обратного вызова EvtDevicePrepareHardware, которая вызывает WdfUsbTargetDeviceCreateWithParameters. В этом примере дескриптор хранится в объекте USB-устройства платформы в пространстве контекста, определяемом драйвером.

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;
    }
...
}

Требования

Требование	Ценность
целевая платформа	Всеобщий
минимальная версия KMDF	1.11
минимальная версия UMDF	2.0
заголовка	wdfusb.h (include Wdfusb.h)
библиотеки	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
правил соответствия DDI	DriverCreate(kmdf), RequestForUrbXrb(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf)

См. также

USBD_CreateHandle

WDF_USB_DEVICE_CREATE_CONFIG

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreate

Поделиться через