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

Статья
08/08/2023

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

Метод WdfUsbTargetPipeFormatRequestForUrb создает ЗАПРОС USB для указанного USB-канала с использованием параметров запроса, описываемых указанным URB , но не отправляет запрос.

Синтаксис

NTSTATUS WdfUsbTargetPipeFormatRequestForUrb(
                 WDFUSBPIPE        PIPE,
  [in]           WDFREQUEST        Request,
  [in]           WDFMEMORY         UrbMemory,
  [in, optional] PWDFMEMORY_OFFSET UrbMemoryOffset
);

Параметры

PIPE

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

[in] Request

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

[in] UrbMemory

Дескриптор объекта памяти платформы, который содержит структуру URB .

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

[in, optional] UrbMemoryOffset

Указатель на структуру WDFMEMORY_OFFSET , выделенную вызывающим объектом, которая предоставляет необязательные значения смещения и длины байтов. Платформа использует эти значения для определения начального адреса URB в памяти, указанной UrbMemory . Если этот указатель имеет значение NULL, URB находится в начале памяти UrbMemory .

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

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

Код возврата	Описание
STATUS_INVALID_PARAMETER	Обнаружен недопустимый параметр.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно памяти.
STATUS_INTEGER_OVERFLOW	Недопустимое смещение, указанное параметром UsbMemoryOffset .
STATUS_REQUEST_NOT_ACCEPTED	Пакет запроса ввода-вывода (IRP), который представляет параметр Request , не предоставляет достаточно IO_STACK_LOCATION структур, позволяющих драйверу пересылать запрос.

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

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

Используйте WdfUsbTargetPipeFormatRequestForUrb, а затем WdfRequestSend, чтобы отправить ЗАПРОС USB синхронно или асинхронно. Кроме того, используйте метод WdfUsbTargetPipeSendUrbSynchronously для синхронной отправки запроса.

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

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

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

Чтобы создать новый запрос ввода-вывода, вызовите WdfRequestCreate , чтобы предварительно выделить объект запроса. Укажите дескриптор запроса для параметра Request метода WdfUsbTargetPipeFormatRequestForUrb. Вы можете повторно использовать объект запроса, вызвав WdfRequestReuse, чтобы функция обратного вызова EvtDriverDeviceAdd вашего драйвера может предварительно выделить объекты запроса для устройства.

После вызова WdfUsbTargetPipeFormatRequestForUrb для форматирования запроса ввода-вывода драйвер должен вызвать WdfRequestSend для отправки запроса (синхронно или асинхронно) целевому объекту ввода-вывода.

Несколько вызовов WdfUsbTargetPipeFormatRequestForUrb , использующих один и тот же запрос, не приводят к выделению дополнительных ресурсов. Таким образом, чтобы снизить вероятность того, что WdfRequestCreate вернет STATUS_INSUFFICIENT_RESOURCES, функция обратного вызова EvtDriverDeviceAdd драйвера может вызвать WdfRequestCreate для предварительного выделения одного или нескольких объектов запроса для устройства. Впоследствии драйвер может повторно использовать (вызвать WdfRequestReuse), переформатировать (вызвать WdfUsbTargetPipeFormatRequestForUrb) и повторно отправить (вызвать WdfRequestSend) каждый объект запроса без риска STATUS_INSUFFICIENT_RESOURCES возвращаемого значения при последующем вызове WdfRequestCreate. Все последующие вызовы WdfUsbTargetPipeFormatRequestForUrb для повторно использованного объекта запроса будут возвращать STATUS_SUCCESS, если значения параметров не изменяются. (Если драйвер не вызывает один и тот же метод форматирования запросов каждый раз, могут быть выделены дополнительные ресурсы.)

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

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

Примеры

В следующем примере кода создается объект памяти, представляющий URB. Затем пример инициализирует URB, форматирует ЗАПРОС USB, содержащий URB, регистрирует функцию обратного вызова CompletionRoutine и отправляет запрос.

URB  urb;
PURB  pUrb = NULL;
WDFMEMORY  urbMemory
NTSTATUS status;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         sizeof(struct _URB_GET_CURRENT_FRAME_NUMBER),
                         &urbMemory,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return status;
}

pUrb = WdfMemoryGetBuffer(
                          urbMemory,
                          NULL
                          );

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 = WdfUsbTargetPipeFormatRequestForUrb(
                                             pipe,
                                             Request,
                                             urbMemory,
                                             NULL
                                             );
if (!NT_SUCCESS(status)) {
    goto Exit;
}
WdfRequestSetCompletionRoutine(
                               Request,
                               UrbCompletionRoutine,
                               pipe
                               );
if (WdfRequestSend(
                   Request,
                   WdfUsbTargetPipeGetIoTarget(pipe),
                   WDF_NO_SEND_OPTIONS
                   ) == FALSE) {
    status = WdfRequestGetStatus(Request);
    goto Exit;
}
Exit:
if (!NT_SUCCESS(status)) {
    WdfRequestCompleteWithInformation(
                                      Request,
                                      status,
                                      0
                                      );
}
return;

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Верхняя часть	wdfusb.h (включая Wdfusb.h)
Библиотека	Wdf01000.sys (см. раздел Управление версиями библиотеки платформы).
IRQL	<=DISPATCH_LEVEL
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)