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

Статья
07/16/2024

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

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

Синтаксис

NTSTATUS WdfUsbTargetPipeSendUrbSynchronously(
  [in]           WDFUSBPIPE                Pipe,
  [in, optional] WDFREQUEST                Request,
  [in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [in]           PURB                      Urb
);

Параметры

[in] Pipe

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

[in, optional] Request

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

[in, optional] RequestOptions

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

[in] Urb

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

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

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

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

Возвращаемый код	Описание
STATUS_INFO_LENGTH_MISMATCH	Размер структуры WDF_REQUEST_SEND_OPTIONS, указанной параметром RequestOptions, был неверным.
STATUS_INVALID_PARAMETER	Обнаружен недопустимый параметр.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно памяти было доступно.
STATUS_INVALID_DEVICE_REQUEST	IrQL вызывающего объекта не был PASSIVE_LEVEL, или указанный запрос ввода-вывода уже был помещен в очередь в целевой объект ввода-вывода.
STATUS_IO_TIMEOUT	Драйвер предоставил значение времени ожидания и запрос не завершился в течение выделенного времени.
STATUS_REQUEST_NOT_ACCEPTED	Пакет запроса ввода-вывода (IRP), который представляет параметр запроса , не предоставляет достаточно IO_STACK_LOCATION структур, чтобы разрешить драйверу пересылать запрос.

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

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

Замечания

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

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

Платформа не проверяет USB-запрос. Если запрос изменяет состояние USB-канала, платформа не будет знать об изменении.

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

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

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

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

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

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

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

Примеры

Следующий пример кода инициализирует URB и отправляет URB в USB-канал.

URB  urb;
PURB  pUrb = NULL;
NTSTATUS status;

pUrb = &urb;
pUrb->UrbHeader.Length = (USHORT) sizeof(struct _URB_GET_CURRENT_FRAME_NUMBER);
pUrb->UrbHeader.Function = URB_FUNCTION_GET_CURRENT_FRAME_NUMBER;
pUrb->UrbGetCurrentFrameNumber.FrameNumber = 0; 

status = WdfUsbTargetPipeSendUrbSynchronously(
                                              Pipe,
                                              Request,
                                              NULL,
                                              pUrb
                                              );

Требования

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

См. также

WDF_REQUEST_SEND_OPTIONS

WdfRequestCancelSentRequest

WdfUsbInterfaceGetConfiguredPipe

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