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

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

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

Синтаксис

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, если операция выполнена успешно. В противном случае этот метод может возвращать одно из следующих значений:

Список других возвращаемых значений, которые может возвращать метод 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;
    }
...
}

Требования

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

EvtDevicePrepareHardware

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceGetNumInterfaces