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

Статья
08/07/2023

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

Синтаксис

EVT_SPB_CONTROLLER_LOCK EvtSpbControllerLock;

void EvtSpbControllerLock(
  [in] WDFDEVICE Controller,
  [in] SPBTARGET Target,
  [in] SPBREQUEST LockRequest
)
{...}

Параметры

[in] Controller

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

[in] Target

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

[in] LockRequest

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

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

None

Remarks

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

Функции EvtSpbControllerLock и EvtSpbControllerUnlock выполняют дополнительные операции. Обе функции являются необязательными. Если драйвер контроллера SPB реализует функцию EvtSpbControllerUnlock , драйвер не требуется для реализации функции EvtSpbControllerLock , но может это сделать. Однако если драйвер контроллера SPB реализует функцию EvtSpbControllerLock , он также должен реализовывать функцию EvtSpbControllerUnlock . Дополнительные сведения см. в разделе Примечания в SPB_CONTROLLER_CONFIG.

Пока блокировка действует, контроллер не должен разрешать доступ к целевым объектам в шине, кроме целевого объекта, указанного параметром LockRequest .

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

Если операция блокировки завершается в DPC, драйвер контроллера SPB должен предварительно выделить все ресурсы, необходимые для операции блокировки.

Обратный вызов EvtSpbControllerLock не должен завершать запрос на блокировку. Если средство проверки драйверов включено, такой сбой вызовет ловушку средства проверки, которая сообщит диспетчеру Plug and Play о сбое контроллера. SpbCx игнорирует сбой запроса на блокировку и не пытается обработать или устранить сбой.

Функция EvtSpbControllerLock не возвращает значение. Вместо этого драйвер контроллера SPB указывает состояние операции блокировки в состоянии завершения запроса ввода-вывода, определяемого параметром LockRequest . Задайте состояние завершения STATUS_SUCCESS.

SpbCx вызывает функцию обратного вызова события EvtSpbControllerUnlock , чтобы разблокировать контроллер, который ранее был заблокирован обратным вызовом EvtSpbControllerLock .

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

Дополнительные сведения о функции EvtSpbControllerLock см. в разделе Обработка последовательностей Client-Implemented.

Примеры

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

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

EVT_SPB_CONTROLLER_LOCK  MyEvtSpbControllerLock;

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

_Use_decl_annotations_
VOID
  MyEvtSpbControllerLock(
    WDFDEVICE Controller,
    SPBTARGET Target,
    SPBREQUEST LockRequest
    )
{ ... }

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

Требования

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

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