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

Статья
10/30/2024

Функция обратного вызова событий EvtSerCx2SetWaitMask вызывается версией 2 расширения последовательной платформы (SerCx2), чтобы настроить последовательный контроллер для мониторинга набора аппаратных событий, указанных маской ожидания.

Синтаксис

EVT_SERCX2_SET_WAIT_MASK EvtSercx2SetWaitMask;

void EvtSercx2SetWaitMask(
  [in] WDFDEVICE Device,
  [in] WDFREQUEST Request,
  [in] ULONG WaitMask
)
{...}

Параметры

[in] Device

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

[in] Request

Дескриптор WDFREQUEST для объекта запроса платформы, представляющего запрос IOCTL_SERIAL_SET_WAIT_MASK.

[in] WaitMask

Новая маска ожидания. Дополнительные сведения см. в разделе "Примечания".

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

Никакой

Замечания

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

Когда SerCx получает IOCTL_SERIAL_SET_WAIT_MASK запрос от клиента, обработчик запросов в SerCx2 вызывает функцию EvtSerCerCx2SetWaitMask, чтобы уведомить драйвер о том, что маска ожидания изменилась. Если маска ожидания не является ненулевой, драйвер немедленно начинает отслеживать события в новой маске ожидания и удаляет любую старую маску ожидания, которая, возможно, была предоставлена в предыдущем EvtSerCx2SetWaitMask вызова. Если новая маска ожидания равна нулю, драйвер просто удаляет старую маску ожидания и перестает отслеживать любые события маски ожидания. Дополнительные сведения о типах событий, которые можно указать маской ожидания, см. в SERIAL_EV_XXX.

Если драйвер не реализует эту функцию, SerCx2 завершает работу всех IOCTL_SERIAL_SET_WAIT_MASK запросов с кодом состояния ошибки STATUS_NOT_SUPPORTED.

Чтобы отслеживать события в маске ожидания, функция EvtSerCx2SetWaitMask обычно включает прерывания этих событий. Позже при обнаружении события в маске ожидания драйвер последовательного контроллера вызывает метод SerCx2CompleteWait, чтобы уведомить SerCx2 о событии.

Функция EvtSerCx2SetWaitMa sk отвечает за выполнение запроса IOCTL_SERIAL_SET_WAIT_MASK, на который указывает параметр request. После включения необходимых прерываний драйвер последовательного контроллера вызывает метод WdfRequestComplete и предоставляет в качестве входных параметров, значение параметра запроса запроса и значение состояния, указывающее, был ли запрос выполнен успешно.

Прежде чем драйвер последовательного контроллера вызывает WdfRequestComplete, чтобы завершить запрос, драйвер должен завершить все вызовы SerCx2CompleteWait, которые могут по-прежнему ожидаться из-за событий в старой маске ожидания.

Изначально после того, как клиент открывает логическое подключение к последовательному порту и до первого вызова EvtSerCerCx2SetWaitMask вызов, маска ожидания фактически равна нулю, а драйвер последовательного контроллера не отслеживает какие-либо события SERIAL_EV_XXX.

SerCx2 завершается сбоем запроса IOCTL_SERIAL_SET_WAIT_MASK с маской ожидания, которая включает любой из следующих флагов событий SERIAL_EV_XXX:

SERIAL_EV_PERR
SERIAL_EV_RING
SERIAL_EV_RXFLAG

Таким образом, маска ожидания, предоставленная EvtSerCx2SetWaitMask, никогда не содержит никаких флагов событий в предыдущем списке.

Если эта функция реализована, функция EvtSerCx2SetWaitMask должна поддерживать следующие флаги событий:

SERIAL_EV_CTS
SERIAL_EV_BREAK
SERIAL_EV_ERR

Кроме того, если последовательный контроллер имеет набор данных, готовый (DSR), функция EvtSerCerCx2SetWaitMask должна поддерживать SERIAL_EV_DSR. В качестве параметра драйвер может поддерживать любой из других флагов событий, описанных в SERIAL_EV_XXX. Если маска ожидания указывает событие, которое драйвер не поддерживает, функция EvtSerCx2SetWaitMask должна завершить запрос и задать значение состояния в запросе на STATUS_INVALID_PARAMETER.

Примеры

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

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

EVT_SERCX2_SET_WAIT_MASK  MySetWaitmask;

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

_Use_decl_annotations_
VOID
  MySetWaitmask(
    WDFDEVICE  Device,
    WDFREQUEST Request,
    ULONG WaitMask
    )
  {...}

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно начиная с Windows 8.1.
целевая платформа	Настольный
заголовка	sercx.h
IRQL	Вызывается в IRQL <= DISPATCH_LEVEL.