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

Статья
08/08/2023

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

Метод WdfUsbTargetDeviceFormatRequestForCyclePort создает запрос цикла питания для порта, к которому подключено указанное устройство, но не отправляет запрос.

Синтаксис

NTSTATUS WdfUsbTargetDeviceFormatRequestForCyclePort(
  [in] WDFUSBDEVICE UsbDevice,
  [in] WDFREQUEST   Request
);

Параметры

[in] UsbDevice

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

[in] Request

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

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

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

Код возврата	Описание
STATUS_INVALID_DEVICE_STATE	USB-устройство устройства было недоступно.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно памяти.

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

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

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

Прежде чем драйвер вызовет WdfRequestSend, он должен вызвать WdfIoTargetStop и завершить или отменить все запросы ввода-вывода, отправленные в целевой объект ввода-вывода. Драйвер не должен отправлять дополнительные запросы ввода-вывода в целевой объект ввода-вывода до завершения цикла запроса.

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

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

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

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

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

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

Примеры

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

status = WdfUsbTargetDeviceFormatRequestForCyclePort(
                                            UsbDevice,
                                            request
                                            );
if (!NT_SUCCESS(status)){
    return status;
}
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)