функция обратного вызова EVT_WDF_USB_READER_COMPLETION_ROUTINE (wdfusb.h)

Статья
08/08/2023

[Применимо к KMDF и UMDF]

Функция обратного вызова события EvtUsbTargetPipeReadComplete драйвера информирует драйвер о том, что непрерывное средство чтения успешно завершило запрос на чтение.

Синтаксис

EVT_WDF_USB_READER_COMPLETION_ROUTINE EvtWdfUsbReaderCompletionRoutine;

void EvtWdfUsbReaderCompletionRoutine(
  [in] WDFUSBPIPE Pipe,
  [in] WDFMEMORY Buffer,
  [in] size_t NumBytesTransferred,
  [in] WDFCONTEXT Context
)
{...}

Параметры

[in] Pipe

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

[in] Buffer

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

[in] NumBytesTransferred

Количество байтов данных, которые находятся в буфере чтения.

[in] Context

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

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

None

Remarks

Чтобы зарегистрировать функцию обратного вызова EvtUsbTargetPipeReadComplete , драйвер должен поместить адрес функции в структуру WDF_USB_CONTINUOUS_READER_CONFIG .

Если драйвер создал непрерывное средство чтения для USB-канала, платформа вызывает функцию обратного вызова EvtUsbTargetPipeReadComplete драйвера каждый раз, когда целевой объект ввода-вывода драйвера успешно завершает запрос на чтение. Функция обратного вызова вызывается в IRQL, когда целевой объект ввода-вывода завершил запрос на чтение, который обычно имеет значение IRQL = DISPATCH_LEVEL, но не выше DISPATCH_LEVEL. (Если целевой объект ввода-вывода не завершает запрос, платформа вызывает функцию обратного вызова EvtUsbTargetPipeReadersFailed драйвера.)

Чтобы получить доступ к буферу, который содержит данные, считанные с устройства, драйвер может вызвать WdfMemoryGetBuffer. Платформа записывает данные в буфер после заголовка, определенного членом HeaderLengthструктуры WDF_USB_CONTINUOUS_READER_CONFIG . Обратите внимание, что указатель, возвращаемый WdfMemoryGetBuffer, указывает на начало заголовка, но параметр NumBytesTransferred функции обратного вызова EvtUsbTargetPipeReadCompleteне включает длину заголовка.

По умолчанию платформа удаляет объект памяти буфера после возврата функции обратного вызова EvtUsbTargetPipeReadComplete . Однако может потребоваться, чтобы объект памяти оставался действительным после возврата функции обратного вызова. Например, может потребоваться, чтобы драйвер хранил дескриптор объекта в пространстве контекста объекта канала платформы, чтобы драйвер мог обрабатывать содержимое объекта памяти после возврата функции обратного вызова. Чтобы продлить время существования объекта памяти, функция обратного вызова должна передать дескриптор объекта памяти в WdfObjectReference. Впоследствии драйвер должен вызвать WdfObjectDereference , чтобы платформа удаляла объект .

Платформа синхронизирует вызовы функций обратного вызова EvtUsbTargetPipeReadComplete и EvtUsbTargetPipeReadersFailed в соответствии со следующими правилами:

Эти функции обратного вызова не выполняются одновременно для отдельного USB-канала.
Если драйвер создает несколько непрерывных модулей чтения для нескольких USB-каналов с несколькими функциями обратного вызова EvtUsbTargetPipeReadlete и EvtUsbTargetPipeReadersFailed , несколько функций обратного вызова могут выполняться одновременно.
Если драйвер указал значение NumPendingReads по умолчанию или значение, которое больше 1, и если запрос на чтение завершается во время выполнения функции обратного вызова EvtUsbTargetPipeReadComplete , платформа может снова вызвать функцию обратного вызова EvtUsbTargetPipeReadComplete , прежде чем функция обратного вызова возвращается.
Платформа не синхронизирует эти функции обратного вызова с другими функциями обратного вызова.

В элементе BufferAttributes структуры WDF_USB_CONTINUOUS_READER_CONFIG драйвер может указать функции обратного вызова EvtCleanupCallback и EvtDegradCallback для объекта памяти. Если указать функцию обратного вызова EvtCleanupCallback , платформа будет вызывать эту функцию обратного вызова при попытке удалить объект памяти после возврата функции обратного вызова EvtUsbTargetPipeReadComplete . Если функция обратного вызова EvtUsbTargetPipeReadComplete вызвала WdfObjectReference, функция обратного вызова EvtCleanupCallback (если она указана) не должна вызывать WdfObjectDereference.

После завершения работы с объектом памяти драйвер должен вызвать WdfObjectDereference . Затем платформа может вызвать функцию обратного вызова EvtDestroyCallback драйвера (если она указана) и удалить объект памяти.

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

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Минимальная версия UMDF	2,0
Верхняя часть	wdfusb.h (включая Wdf.h)
IRQL	<=DISPATCH_LEVEL (см. раздел "Примечания"))

См. также раздел

EvtUsbTargetPipeReadersFailed

WDF_USB_CONTINUOUS_READER_CONFIG

WdfMemoryGetBuffer

Поделиться через