Метод IWDFUsbTargetPipe2::ConfigureContinuousReader (wudfusb.h)

Статья
08/08/2023

[Предупреждение: UMDF 2 является последней версией UMDF и заменяет UMDF 1. Все новые драйверы UMDF должны быть написаны с помощью UMDF 2. Новые функции не добавляются в UMDF 1, а поддержка UMDF 1 в более новых версиях Windows 10 ограничена. Универсальные драйверы Windows должны использовать UMDF 2. Дополнительные сведения см. в разделе начало работы с помощью UMDF.]

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

Синтаксис

HRESULT ConfigureContinuousReader(
  [in]           SIZE_T                                              TransferLength,
  [in]           SIZE_T                                              HeaderLength,
  [in]           SIZE_T                                              TrailerLength,
  [in]           UCHAR                                               NumPendingReads,
  [in, optional] IUnknown                                            *pMemoryCleanupCallbackInterface,
  [in]           IUsbTargetPipeContinuousReaderCallbackReadComplete  *pOnCompletion,
  [in, optional] PVOID                                               pCompletionContext,
  [in, optional] IUsbTargetPipeContinuousReaderCallbackReadersFailed *pOnFailure
);

Параметры

[in] TransferLength

Максимальная длина (в байтах) данных, которые могут быть получены с устройства.

[in] HeaderLength

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

[in] TrailerLength

Длина в байтах пространства буфера в конце. Это пространство следует за пространством размера TransferLength, в котором платформа хранит данные с устройства.

[in] NumPendingReads

Количество запросов на чтение, которые платформа будет ставить в очередь для получения данных от целевого объекта ввода-вывода. Если это значение равно нулю, платформа использует количество запросов на чтение по умолчанию. Если указанное значение больше допустимого максимального значения, платформа использует максимально допустимое значение. Дополнительные сведения о параметре NumPendingReads см. в следующем разделе Примечаний.

[in, optional] pMemoryCleanupCallbackInterface

Указатель на предоставленный драйвером интерфейс IUnkown , который платформа использует для доступа к необязательной функции обратного вызова IObjectCleanup::OnCleanup . Платформа вызывает функцию обратного вызова, когда освобождает буфер чтения, создаваемый для обработки непрерывной операции чтения. Этот параметр является необязательным и может иметь значение NULL.

[in] pOnCompletion

Указатель на предоставленный драйвером интерфейс IUsbTargetPipeContinuousReaderCallbackReadComplete , предоставляющий функцию обратного вызова OnReaderCompletion .

[in, optional] pCompletionContext

Нетипизированный указатель на определяемые драйвером сведения о контексте, которые платформа передает в функцию обратного вызова IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion драйвера.

[in, optional] pOnFailure

Указатель на предоставленный драйвером интерфейс IUsbTargetPipeContinuousReaderCallbackReadersFailed , предоставляющий функцию обратного вызова OnReaderFailure .

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

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

Код возврата	Описание
HRESULT_FROM_NT (STATUS_INVALID_DEVICE_STATE)	Драйвер уже настроил непрерывное средство чтения для USB-канала. USB-канал не настроен для массовой передачи или передачи данных с прерыванием.
E_OUTOFMEMORY	Попытка платформы выделить буфер завершилась сбоем.
ERROR_ARITHMETIC_OVERFLOW	Параметр TransferLength, HeaderLength или TrailerLength указывает слишком большой или недопустимый размер.

Этот метод может возвращать одно из других значений, содержащихся в Winerror.h.

После вызова ConfigureContinuousReader для настройки непрерывного средства чтения драйвер должен вызвать IWDFIoTargetStateManagement::Start , чтобы запустить средство чтения. Чтобы остановить средство чтения, драйвер должен вызвать IWDFIoTargetStateManagement::Stop.

Как правило, драйвер вызывает ConfigureContinuousReader из функции обратного вызова IPnpCallbackHardware::OnPrepareHardware . Драйвер должен вызывать IWDFIoTargetStateManagement::Start из функции обратного вызова IPnpCallback::OnD0Entry и вызывать IWDFIoTargetStateManagement::Stop из функции обратного вызова IPnpCallback::OnD0Exit .

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

Используйте следующие рекомендации, чтобы выбрать значение для параметра NumPendingReads :

Задайте для NumPendingReads значение 0, если вы хотите, чтобы драйвер использовал значение платформы по умолчанию.
Значение по умолчанию больше единицы и обеспечивает достаточно высокую производительность для многих устройств во многих конфигурациях процессора.
Задайте для NumPendingReads значение , если важно, чтобы драйвер получал буферы данных в точном порядке, в котором устройство доставляет данные.
Если платформа помещает в очередь несколько запросов на чтение, драйвер может не получать буферы данных в том же порядке, в котором устройство доставляет данные.
Задайте для NumPendingReads число, соответствующее требованиям к производительности устройства, на основе тщательного измерения производительности.
Сначала протестируйте устройство со значением по умолчанию (0) для NumPendingReads. Тесты должны включать различные конфигурации оборудования, в том числе различные типы и количество процессоров, а также разные usb-контроллеры узлов и конфигурации USB. Затем можно поэкспериментировать с более высокими значениями, используя те же тесты. Драйвер, для которого может потребоваться более высокое значение, — это драйвер для устройства с высокой частотой прерываний, где данные могут быть потеряны, если прерывания не обслуживаются быстро.

Слишком большое значение NumPendingReads может замедлить производительность системы. Следует использовать наименьшее значение, соответствующее вашим требованиям к производительности. Как правило, значения, превышающие три или четыре, не повышают пропускную способность данных. Но более высокие значения могут снизить задержку или вероятность отсутствия данных в высокочастотном канале.

После вызова драйвера ConfigureContinuousReader драйвер не может использовать IWDFIoRequest::Send для отправки запросов ввода-вывода в канал, если только функция обратного вызова IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure не вызывается и не возвращает значение FALSE.

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

Примеры

В следующем примере кода настраивается непрерывное средство чтения. В этом примере максимальный размер буфера равен размеру буфера, определяемого драйвером. Смещения буфера заголовка и прицепа равны нулю, а количество ожидающих операций чтения — два. В примере используется указатель интерфейса целевого канала для параметра pCompletionContext , поэтому функция обратного вызова OnReaderCompletion может определить канал, по которому была завершена операция чтения.

HRESULT hr, hrQI;
IUsbTargetPipeContinuousReaderCallbackReadComplete *pOnCompletionCallback = NULL;
IUsbTargetPipeContinuousReaderCallbackReadersFailed *pOnFailureCallback= NULL;
IWDFUsbTargetPipe2 * pIUsbInterruptPipe2;

//
// Obtain interfaces.
//
hrQI = this->QueryInterface(IID_PPV_ARGS(&pOnCompletionCallback));
if (!SUCCEEDED(hrQI)) goto Error;
hrQI = this->QueryInterface(IID_PPV_ARGS(&pOnFailureCallback));
if (!SUCCEEDED(hrQI)) goto Error;
hrQI = m_pIUsbInterruptPipe->QueryInterface(IID_PPV_ARGS(&pIUsbInterruptPipe2));
if (!SUCCEEDED(hrQI)) goto Error;

//
// Configure the reader.
//
hr = pIUsbInterruptPipe2->ConfigureContinuousReader(
                                                    sizeof(m_MyBuffer), 
                                                    0,
                                                    0,
                                                    2, 
                                                    NULL,
                                                    pOnCompletionCallback,
                                                    m_pIUsbTargetPipe,
                                                    pOnFailureCallback
                                                    );
...

Требования

Требование	Значение
Дата окончания поддержки	Недоступно в UMDF 2.0 и более поздних версиях.
Целевая платформа	Персональный компьютер
Минимальная версия UMDF	1,9
Верхняя часть	wudfusb.h (включая Wudfusb.h)
DLL	WUDFx.dll