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

Статья
03/05/2024

[Относится к 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	Параметр Config имеет неправильный размер.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно памяти для создания нового объекта USB-устройства платформы.
STATUS_INVALID_PARAMETER	Обнаружен недопустимый параметр. Дополнительные сведения см. в разделе "Примечания".
STATUS_UNSUCCESSFUL	Не удалось получить сведения о конфигурации USB.

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

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

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

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

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

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

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

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

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

Примеры

Следующий пример кода является частью функции обратного вызова 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 (включая 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

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