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

  • Статья

[Относится к 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.

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

Комментарии

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 из функции обратного вызова 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