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

Статья
07/16/2024

[Применимо только к KMDF]

Метод WdfUsbTargetDeviceSendUrbSynchronous отправляет USB-запрос синхронно на указанное USB-устройство, используя параметры запроса, описанные URB.

Синтаксис

NTSTATUS WdfUsbTargetDeviceSendUrbSynchronously(
  [in]           WDFUSBDEVICE              UsbDevice,
  [in, optional] WDFREQUEST                Request,
  [in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [in]           PURB                      Urb
);

Параметры

[in] UsbDevice

Дескриптор объекта USB-устройства, полученный из предыдущего вызова WdfUsbTargetDeviceCreateWithParameters.

[in, optional] Request

Дескриптор объекта запроса платформы. Этот параметр является необязательным и может быть null. Дополнительные сведения см. в следующем разделе "Примечания".

[in, optional] RequestOptions

Указатель на структуру, выделенную вызывающим объектом, WDF_REQUEST_SEND_OPTIONS, которая задает параметры запроса. Этот указатель необязателен и может быть null. Дополнительные сведения см. в следующем разделе "Примечания".

[in] Urb

Указатель на структуру URB, инициализируемый вызывающим .

Если драйвер, ранее называемый WdfUsbTargetDeviceCreateWithParameters для создания UsbDevice, драйвер должен использовать WdfUsbTargetDeviceCreateUrb или WdfUsbTargetDeviceCreateIsochUrb для создания этого URB.

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

WdfUsbTargetDeviceSendUrbSynchronous возвращает значение состояния завершения целевого объекта ввода-вывода, если операция завершится успешно. В противном случае этот метод может вернуть одно из следующих значений:

Возвращаемый код	Описание
STATUS_INVALID_PARAMETER	Обнаружен недопустимый параметр.
STATUS_INVALID_DEVICE_REQUEST	IrQL вызывающего абонента был недопустим.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно памяти было доступно.
STATUS_IO_TIMEOUT	Драйвер предоставил значение времени ожидания и запрос не завершился в течение выделенного времени.

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

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

Замечания

Используйте метод WdfUsbTargetDeviceSendUrbSynchronous для отправки запроса передачи USB-элемента управления синхронно. Чтобы отправлять такие запросы асинхронно, используйте WdfUsbTargetDeviceFormatRequestForUrb, а затем WdfRequestSend.

Метод WdfUsbTargetDeviceSendUrbSynchronous не возвращается до завершения запроса, если драйвер не предоставляет значение времени ожидания в структуре WDF_REQUEST_SEND_OPTIONS параметра или если не обнаружена ошибка.

Вы можете пересылать запрос ввода-вывода, полученный драйвером в очереди ввода-вывода, или создать и отправить новый запрос.

Чтобы пересылать запрос ввода-вывода, полученный драйвером в очереди ввода-вывода, укажите дескриптор полученного запроса для параметра WdfUsbTargetDeviceSendUrbSynchronous метода request.

Чтобы создать и отправить новый запрос, укажите маркер запроса NULL для параметра запроса или создайте объект запроса и предоставьте его дескриптор:

Если вы предоставляете дескриптор запроса NULL, платформа использует внутренний объект запроса. Этот метод прост в использовании, но драйвер не может отменить запрос.
При вызове WdfRequestCreate для создания одного или нескольких объектов запроса можно повторно использовать эти объекты запроса, вызвав WdfRequestReuse. Этот метод позволяет драйвера EvtDriverDeviceAdd функцию обратного вызова для предварительного размещения объектов запросов для устройства. Кроме того, другой поток драйвера может вызывать WdfRequestCancelSentRequest, чтобы отменить запрос при необходимости.

Драйвер может указать параметр, отличный отNULLRequestOptions, предоставляет ли драйвер параметрNULL или параметр NULLRequest. Например, можно использовать параметр RequestOptions для указания значения времени ожидания.

Сведения о получении сведений о состоянии после завершения запроса ввода-вывода см. в получения сведений о завершении.

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

Примеры

В следующем примере кода инициализируется структура URB и вызывается WdfUsbTargetDeviceSendUrbSynchronous.

URB Urb;
NTSTATUS status;

Urb.UrbHeader.Function =  URB_FUNCTION_GET_CONFIGURATION;
Urb.UrbHeader.Length = sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST);
Urb.UrbControlGetConfigurationRequest.TransferBufferLength = 1 ; // Must be 1
Urb.UrbControlGetConfigurationRequest.TransferBufferMDL = NULL;
Urb.UrbControlGetConfigurationRequest.TransferBuffer = outBuffer;
Urb.UrbControlGetConfigurationRequest.UrbLink = NULL;

status = WdfUsbTargetDeviceSendUrbSynchronously(
                                                UsbDevice,
                                                NULL,
                                                NULL,
                                                &Urb
                                                );

Требования

Требование	Ценность
целевая платформа	Всеобщий
минимальная версия KMDF	1.0
заголовка	wdfusb.h (include Wdfusb.h)
библиотеки	Wdf01000.sys (см. управление версиями библиотеки Платформы).)
IRQL	PASSIVE_LEVEL
правил соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)