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

Статья
08/07/2023

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

Синтаксис

EVT_SPB_CONTROLLER_READ EvtSpbControllerRead;

void EvtSpbControllerRead(
  [in] WDFDEVICE Controller,
  [in] SPBTARGET Target,
  [in] SPBREQUEST Request,
  [in] size_t Length
)
{...}

Параметры

[in] Controller

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

[in] Target

Дескриптор SPBTARGET для целевого объекта для этого запроса ввода-вывода. Целевой объект — это периферийное устройство или порт, подключенный к шине. Расширение платформы SPB (SpbCx) ранее назначило этот дескриптор целевому объекту в обратном вызове EvtSpbTargetConnect , открывшем подключение к целевому объекту.

[in] Request

Дескриптор SPBREQUEST для запроса ввода-вывода. Драйвер контроллера SPB должен выполнить этот запрос, выполнив запрошенную операцию или возвратив состояние ошибки. Дополнительные сведения см. в разделе Примечания.

[in] Length

Число байтов для чтения с целевого устройства.

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

None

Remarks

SpbCx управляет очередью ввода-вывода для контроллера SPB. SpbCx вызывает функцию обратного вызова EvtSpbControllerIoRead драйвера контроллера SPB, когда клиент (драйвер периферийного устройства) контроллера SPB отправляет запрос IRP_MJ_READ на целевое устройство, подключенное к шине. Значение параметра Request — это дескриптор, который инкапсулирует этот запрос.

Обратный вызов EvtSpbControllerIoRead не возвращает значение состояния. Вместо этого драйвер контроллера SPB указывает состояние операции чтения в состоянии завершения запроса ввода-вывода.

Обратный вызов EvtSpbControllerIoRead является асинхронным. То есть функция обратного вызова должна инициировать запрошенную операцию чтения, а затем возвращать ее, не дожидаясь завершения операции. Позже драйвер контроллера SPB завершает запрос на чтение во время прерывания DPC или DPC таймера.

Если операция чтения завершается полностью, драйвер контроллера SPB должен установить состояние завершения в STATUS_SUCCESS. Если целевое устройство указывает, что оно может предоставить некоторые, но не все запрошенные данные, драйвер контроллера SPB должен получить столько данных, сколько доступно, указать количество полученных байтов данных и задать состояние завершения в запросе ввода-вывода STATUS_SUCCESS. Такая частично завершенная операция чтения не может выполняться в шине SPI или I²C, но может произойти в шине другого типа.

Если операция чтения завершается сбоем из-за шума строки, ошибки оборудования контроллера или ошибки драйвера, драйвер контроллера SPB должен задать для состояния завершения в запросе ввода-вывода соответствующий код ошибки. Не все автобусы предоставляют целевому устройству механизм для сообщения о транспортной ошибке или частично завершенной передаче, и не все контроллеры могут обнаружить эти условия.

Чтобы зарегистрировать функцию обратного вызова EvtSpbControllerIoRead , вызовите метод SpbDeviceInitialize .

Примеры

Чтобы определить функцию обратного вызова EvtSpbControllerIoRead , необходимо сначала предоставить объявление функции, определяющее тип определяемой функции обратного вызова. Windows предоставляет набор типов функций обратного вызова для драйверов. Объявление функции с помощью типов функций обратного вызова помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.

Например, чтобы определить функцию обратного вызова EvtSpbControllerIoRead с именем MyEvtSpbControllerIoRead, используйте тип функции EVT_SPB_CONTROLLER_READ, как показано в следующем примере кода:

EVT_SPB_CONTROLLER_READ  MyEvtSpbControllerIoRead;

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

_Use_decl_annotations_
VOID
  MyEvtSpbControllerIoRead(
    WDFDEVICE Controller,
    SPBTARGET Target,
    SPBREQUEST Request,
    size_t Length
    )
{ ... }

Тип функции EVT_SPB_CONTROLLER_READ определяется в файле заголовка Spbcx.h. Чтобы более точно определить ошибки при запуске средств анализа кода, обязательно добавьте заметку Use_decl_annotations в определение функции. Заметка Use_decl_annotations гарантирует использование заметок, применяемых к типу функции EVT_SPB_CONTROLLER_READ в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в разделе Объявление функций с помощью типов ролей функций для драйверов KMDF. Дополнительные сведения о Use_decl_annotations см. в статье Поведение функции с заметками.

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается начиная с Windows 8.
Целевая платформа	Персональный компьютер
Верхняя часть	spbcx.h
IRQL	Вызывается в IRQL <= DISPATCH_LEVEL.

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