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

Статья
08/08/2023

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

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

Примечание Если вы создаете драйвер с помощью KMDF 1.11 или UMDF 2.0 или более поздней версии, рекомендуется вызывать WdfUsbTargetDeviceCreateWithParameters вместо WdfUsbTargetDeviceCreate.

Синтаксис

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

Параметры

[in] Device

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

[in, optional] Attributes

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

[out] UsbDevice

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

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

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

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

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

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

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

Драйвер, использующий целевой объект ввода-вывода USB, должен вызывать WdfUsbTargetDeviceCreate после того, как его устройство перейдет в рабочее состояние (D0). Как правило, драйвер вызывает WdfUsbTargetDeviceCreate из функции обратного вызова EvtDevicePrepareHardware . (Драйвер не может вызвать WdfUsbTargetDeviceCreate из функции обратного вызова EvtDriverDeviceAdd .)

WdfUsbTargetDeviceCreate получает дескриптор USB-устройства и первый дескриптор конфигурации USB от устройства и сохраняет их. Он также создает объект интерфейса USB платформы для каждого интерфейса в первой конфигурации устройства. Чтобы определить количество интерфейсов, поддерживаемых конфигурацией, драйвер может вызвать WdfUsbTargetDeviceGetNumInterfaces.

После вызова WdfUsbTargetDeviceCreate драйвер может вызывать дополнительные методы объекта usb-устройства платформы.

Родительским элементом каждого объекта USB-устройства является объект драйвера платформы драйвера драйвера. Драйвер не может изменить этот родительский элемент, а элемент ParentObject или структура WDF_OBJECT_ATTRIBUTES должны иметь значение NULL.

Дополнительные сведения о методе WdfUsbTargetDeviceCreate и целевых объектах USB-ввода-вывода см. в разделе Usb I/O Targets.

Примеры

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

NTSTATUS
MyEvtDevicePrepareHardware(
    IN WDFDEVICE  Device,
    IN WDFCMRESLIST  ResourceList,
    IN WDFCMRESLIST  ResourceListTranslated
    )
{
    NTSTATUS  status;
    PMY_DEVICE_CONTEXT  pMyDeviceContext;

    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;
    }
 status = WdfUsbTargetDeviceCreate(
                                      Device,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &pMyDeviceContext->UsbDevice
                                      );
    if (!NT_SUCCESS(status)) {
        return status;
    }
...
}

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Минимальная версия UMDF	2,0
Верхняя часть	wdfusb.h (включая Wdfusb.h)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

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

EvtDevicePrepareHardware

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceGetNumInterfaces

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