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

Статья
08/08/2023

[Относится к KMDF и UMDF]

Метод WdfUsbTargetPipeConfigContinuousReader настраивает платформу для непрерывного чтения из указанного USB-канала.

Синтаксис

NTSTATUS WdfUsbTargetPipeConfigContinuousReader(
  [in] WDFUSBPIPE                        Pipe,
  [in] PWDF_USB_CONTINUOUS_READER_CONFIG Config
);

Параметры

[in] Pipe

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

[in] Config

Указатель на структуру WDF_USB_CONTINUOUS_READER_CONFIG , выделенную вызывающим объектом.

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

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

Код возврата	Описание
STATUS_INFO_LENGTH_MISMATCH	Неправильный размер структуры WDF_USB_CONTINUOUS_READER_CONFIG , указанной параметром Config .
STATUS_INVALID_PARAMETER	Обнаружен недопустимый параметр.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно памяти.
STATUS_INVALID_DEVICE_REQUEST	Недопустимый тип канала.
STATUS_INTEGER_OVERFLOW	Элемент HeaderLength, TransferLength или TrailerLengthWDF_USB_CONTINUOUS_READER_CONFIG структуры, в которую параметр Config указал слишком большой или недопустимый размер.
STATUS_INVALID_BUFFER_SIZE	Размер буфера чтения не был кратным максимальному размеру пакета канала.

Список других возвращаемых значений, которые может возвращать метод WdfUsbTargetPipeConfigContinuousReader , см. в разделе Ошибки при создании объекта платформы.

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

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

После вызова WdfUsbTargetPipeConfigContinuousReader для настройки непрерывного средства чтения драйвер должен вызвать WdfIoTargetStart , чтобы запустить средство чтения. Чтобы остановить средство чтения, драйвер должен вызвать WdfIoTargetStop.

Как правило, драйвер вызывает WdfUsbTargetPipeConfigContinuousReader из функции обратного вызова EvtDevicePrepareHardware . Драйвер должен вызывать WdfIoTargetStart из функции обратного вызова EvtDeviceD0Entry и вызывать WdfIoTargetStop из функции обратного вызова EvtDeviceD0Exit .

Каждый раз, когда целевой объект ввода-вывода канала успешно завершает запрос на чтение, платформа вызывает функцию обратного вызова EvtUsbTargetPipeReadComplete драйвера. Если целевой объект ввода-вывода сообщает о сбое при обработке запроса, платформа вызывает функцию обратного вызова EvtUsbTargetPipeReadersFailed драйвера после завершения всех запросов на чтение. (Таким образом, функция обратного вызова EvtUsbTargetPipeReadComplete не будет вызываться при выполнении функции обратного вызова EvtUsbTargetPipeReadersFailed .

Если не указать необязательный обратный вызов EvtUsbTargetPipeReadersFailed , платформа отвечает на неудачную попытку чтения, отправляя другой запрос на чтение. Таким образом, если шина находится в состоянии, когда она не принимает операции чтения, платформа постоянно отправляет новые запросы на восстановление после неудачного чтения.

После вызова драйвера WdfUsbTargetPipeConfigContinuousReader драйвер не может использовать WdfUsbTargetPipeReadSynchronously или WdfRequestSend для отправки запросов ввода-вывода в канал, если непрерывное средство чтения не было остановлено. Чтобы остановить средство чтения, драйвер может вызвать WdfIoTargetStop или вернуть значение FALSE из функции обратного вызова EvtUsbTargetPipeReadersFailed . Если драйвер вызывает WdfUsbTargetPipeReadSynchronous во время остановки средства чтения, он должен задать флаг WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE в элементе Flags параметра RequestOptions . В противном случае запрос будет выполняться до перезапуска целевого объекта.

Платформа устанавливает флаг USBD_SHORT_TRANSFER_OK во внутренней urb. Установка этого флага позволяет, чтобы последний пакет передачи данных был меньше максимального размера пакета.

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

Примеры

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

WDF_USB_CONTINUOUS_READER_CONFIG  contReaderConfig;
NTSTATUS  status;

WDF_USB_CONTINUOUS_READER_CONFIG_INIT(
                                      &contReaderConfig,
                                      OsrFxEvtUsbInterruptPipeReadComplete,
                                      DeviceContext,
                                      sizeof(UCHAR)
                                      );
status = WdfUsbTargetPipeConfigContinuousReader(
                                      Pipe,
                                      &contReaderConfig
                                      );

Требования

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