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

Статья
02/07/2025

[Применимо к 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-устройства. (Элемент ParentObj ect структуры должен быть 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 из функции обратного вызова EvtDriverDeviceAd d.)

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

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

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

Дополнительные сведения о методе WdfUsbTargetDeviceCreate и целевых объектах ввода-вывода USB см. в целевых объектов USB-ввода-вывода.

Примеры

Следующий пример кода является частью функции обратного вызова 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 (include Wdfusb.h)
библиотеки	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
правил соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbDeviceCreate(kmdf), UsbDeveviticeCreateFail(kmdf), UsbDeviceCreateTarget(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

См. также

EvtDevicePrepareHardware

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceGetNumInterfaces

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