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

Статья
08/08/2023

[Относится только к KMDF]

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

Синтаксис

NTSTATUS WdfUsbTargetDeviceFormatRequestForUrb(
  [in]           WDFUSBDEVICE      UsbDevice,
  [in]           WDFREQUEST        Request,
  [in]           WDFMEMORY         UrbMemory,
  [in, optional] PWDFMEMORY_OFFSET UrbMemoryOffset
);

Параметры

[in] UsbDevice

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

[in] Request

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

[in] UrbMemory

Дескриптор объекта памяти платформы, который содержит структуру URB или один из членов объединения структуры. (Все члены объединения структуры URB содержат структуру _URB_HEADER .)

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

[in, optional] UrbMemoryOffset

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

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

WdfUsbTargetDeviceFormatRequestForUrb возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод может возвращать одно из следующих значений:

Код возврата	Описание
STATUS_INVALID_PARAMETER	Обнаружен недопустимый параметр.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно памяти.
STATUS_INTEGER_OVERFLOW	Смещение, указанное параметром UsbMemoryOffset , было недопустимым.

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

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

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

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

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

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

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

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

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

Дополнительные сведения о методе WdfUsbTargetDeviceFormatRequestForUrb и целевых объектах USB-ввода-вывода см. в разделе Usb I/O Targets.

Примеры

В следующем примере кода создается объект памяти для хранения структуры URB, инициализируется структура URB и вызывается WdfUsbTargetDeviceFormatRequestForUrb для форматирования запроса, использующего содержимое структуры URB. Затем в примере регистрируется функция обратного вызова CompletionRoutine и отправляется запрос целевому объекту ввода-вывода.

WDFMEMORY urbMemory;
URB *urbBuffer;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST),
                         &urbMemory,
                         NULL
                         );

if (!NT_SUCCESS(status)){
    return status;
}
urbBuffer = (PURB) WdfMemoryGetBuffer(
                                      urbMemory,
                                      NULL
                                      );
urbBuffer->UrbHeader.Function =  URB_FUNCTION_GET_CONFIGURATION;
urbBuffer->UrbHeader.Length = sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST);
urbBuffer->UrbControlGetConfigurationRequest.TransferBufferLength = 1 ;
urbBuffer->UrbControlGetConfigurationRequest.TransferBufferMDL = NULL;
urbBuffer->UrbControlGetConfigurationRequest.TransferBuffer = outBuffer;
urbBuffer->UrbControlGetConfigurationRequest.UrbLink = NULL;

status = WdfUsbTargetDeviceFormatRequestForUrb(
                                               deviceContext->WdfUsbTargetDevice,
                                               request,
                                               urbMemory,
                                               NULL
                                               );
WdfRequestSetCompletionRoutine(
                              request,
                              MyCompletionRoutine,
                              NULL);

if (WdfRequestSend(
                   request,
                   WdfUsbTargetDeviceGetIoTarget(UsbDevice),
                   NULL
                   ) == FALSE) {
    status = WdfRequestGetStatus(request);
}

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия 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)