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

Статья
10/30/2024

Функция обратного вызова событий EvtSerCx2Control вызывается версией 2 расширения последовательной платформы (SerCx2) для обработки последовательного запроса элемента управления ввода-вывода.

Синтаксис

EVT_SERCX2_CONTROL EvtSercx2Control;

NTSTATUS EvtSercx2Control(
  [in] WDFDEVICE Device,
  [in] WDFREQUEST Request,
  [in] size_t OutputBufferLength,
  [in] size_t InputBufferLength,
  [in] ULONG IoControlCode
)
{...}

Параметры

[in] Device

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

[in] Request

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

[in] OutputBufferLength

Длина в байтах выходного буфера для запроса последовательного ввода-вывода, указанного параметром запроса .

[in] InputBufferLength

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

[in] IoControlCode

Указывает код элемента управления ввода-вывода (IOCTL) из запроса последовательного ввода-вывода, указанного параметром request. Списки операций ввода-вывода для запросов управления последовательными ввода-выводами определяются в файле заголовка Ntddser.h. Дополнительные сведения см. в разделе "Примечания".

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

Функция EvtSerCx2Control возвращает STATUS_SUCCESS, если вызов выполнен успешно. В противном случае возвращается соответствующий код состояния ошибки.

Замечания

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

Функция EvtSerCx2Control позволяет драйверу обрабатывать определенные последовательные запросы управления ввода-вывода, которые SerCx2 не могут обрабатывать. SerCx2 обрабатывает всю обработку для подмножества серийных операций ввода-вывода, определенных в файле заголовка Ntddser.h. Однако SerCx2 использует драйвер для обработки запросов на управление последовательным вводом-выводом для выполнения аппаратных операций.

Когда SerCx2 получает последовательный запрос управления ввода-вывода, который может обрабатываться только драйвером последовательного контроллера, SerCx2 вызывает функцию EvtSerCx2Control, чтобы передать запрос управления ввода-вывода драйверу. Драйвер отвечает за выполнение этого запроса. Драйвер, который не реализует поддержку определенного запроса управления ввода-вывода, должен завершить этот запрос элемента управления ввода-вывода с помощью кода состояния ошибки STATUS_NOT_SUPPORTED.

Чтобы завершить запрос элемента управления ввода-вывода, драйвер обычно вызывает метод WdfRequestComplete и предоставляет в качестве входных параметров, значение параметра request и значение состояния, указывающее, выполнен ли запрос успешно. Это значение состояния записывается в блок состояния запроса.

Возвращаемое значение функции EvtSerCx2 Control должно всегда соответствовать значению состояния, которое эта функция записывает в блок состояния запроса управления ввода-вывода. Текущая реализация SerCx2 игнорирует это возвращаемое значение.

SerCx2 вызывает функцию EvtSerCx2Control для обработки ioCTLs, показанных в следующей таблице. Столбец справа от таблицы указывает, требуется ли функция EvtSerCx2Control для реализации поддержки определенного IOCTL.

Имя запроса элемента управления ввода-вывода	Обязательный или необязательный
IOCTL_SERIAL_CLR_DTR	Необязательный
IOCTL_SERIAL_CLR_RTS	Обязательно
IOCTL_SERIAL_GET_BAUD_RATE	Обязательно
IOCTL_SERIAL_GET_COMMSTATUS	Обязательно
IOCTL_SERIAL_GET_DTRRTS	Обязательно
IOCTL_SERIAL_GET_HANDFLOW	Обязательно
IOCTL_SERIAL_GET_LINE_CONTROL	Обязательно
IOCTL_SERIAL_GET_MODEM_CONTROL	Обязательно
IOCTL_SERIAL_GET_MODEMSTATUS	Обязательно
IOCTL_SERIAL_GET_PROPERTIES	Обязательно
IOCTL_SERIAL_SET_BAUD_RATE	Обязательно
IOCTL_SERIAL_SET_BREAK_OFF	Обязательно
IOCTL_SERIAL_SET_BREAK_ON	Обязательно
IOCTL_SERIAL_SET_DTR	Необязательный
IOCTL_SERIAL_SET_FIFO_CONTROL	Необязательный
IOCTL_SERIAL_SET_HANDFLOW	Обязательно
IOCTL_SERIAL_SET_LINE_CONTROL	Обязательно
IOCTL_SERIAL_SET_MODEM_CONTROL	Обязательно
IOCTL_SERIAL_SET_RTS	Обязательно

В предыдущей таблице перечислены все последовательные операции ввода-вывода, которые SerCx2 представляют функции EvtSerCx2Control. Для любого IOCTL, не в этом списке, SerCx2 обрабатывает IOCTL или немедленно завершается сбоем IOCTL и задает состояние запроса на STATUS_NOT_SUPPORTED. SerCx2 обрабатывает IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION запросы, но вызывает функцию обратного вызова событий EvtSerCx2ApplyConfig во время обработки такого запроса. SerCx2 обрабатывает запросы IOCTL_SERIAL_PURGE, но может вызывать функцию обратного вызова события EvtSerCx2PurgeFifos во время обработки такого запроса. SerCx выполняет предварительную обработку запросов IOCTL_SERIAL_SET_WAIT_MASK, но вызывает функцию обратного вызова событий EvtSerCx2SetWaitMask обратного вызова событий, если она реализована, чтобы завершить обработку такого запроса. Дополнительные сведения о поддержке SerCx2 для сериальных операций ввода-вывода см. в интерфейса запросов последовательного ввода-вывода.

IOCTL_SERIAL_CLR_DTR и IOCTL_SERIAL_SET_DTR

Если функция EvtSerCx2Control в драйвере последовательного контроллера поддерживает запрос IOCTL_SERIAL_SET_DTR, эта функция также должна поддерживать запрос IOCTL_SERIAL_CLR_DTR и наоборот. Если драйвер не поддерживает эти два запроса, обработчик драйвера для запроса IOCTL_SERIAL_GET_DTRRTS должен задать бит флага SERIAL_DTR_STATE в выходном значении этого запроса равным нулю.

IOCTL_SERIAL_GET_DTRRTS

Функция EvtSerCx2Control в драйвере последовательного контроллера должна поддерживать запрос IOCTL_SERIAL_GET_DTRRTS, но обработчик драйвера для этого запроса необходим для поддержки только бита флага SERIAL_RTS_STATE в выходном значении этого запроса. В качестве параметра драйвер может дополнительно поддерживать бит флага SERIAL_DTR_STATE. Если бит флага SERIAL_DTR_STATE не поддерживается, установите этот бит равным нулю.

IOCTL_SERIAL_GET_COMMSTATUS

Функция EvtSerCx2Control в драйвере последовательного контроллера должна поддерживать запрос IOCTL_SERIAL_GET_COMMSTATUS, но обработчик драйвера для этого запроса необходим для поддержки только следующих членов структуры SERIAL_STATUS, используемой этим запросом:

ошибки
HoldReasons

В качестве варианта драйвер может дополнительно поддерживать любой из других членов этой структуры. Задайте для всех неподдерживаемых элементов значение нулю.

IOCTL_SERIAL_GET_PROPERTIES

Функция EvtSerCx2Control в драйвере последовательного контроллера должна поддерживать запрос IOCTL_SERIAL_GET_PROPERTIES. Обработчик драйвера для этого запроса должен задать MaxBaud элемент структуры SERIAL_COMMPROP, используемой этим запросом, максимально поддерживаемую скорость baud, выраженную в битах в секунду (в секунду). Например, если последовательный контроллер поддерживает максимальную скорость 115 200 б/с, драйвер задает MaxBaud = 115200.

IOCTL_SERIAL_GET_MODEMSTATUS

Функция EvtSerCx2Control в драйвере последовательного контроллера должна поддерживать запрос IOCTL_SERIAL_GET_MODEMSTATUS. Обработчик драйвера для этого запроса должен задать выходное значение запроса на значение регистра состояния необработанного модема, считываемое из оборудования последовательного контроллера.

IOCTL_SERIAL_GET_HANDFLOW и IOCTL_SERIAL_SET_HANDFLOW

Функция EvtSerCx2Control в драйвере последовательного контроллера должна поддерживать запросы IOCTL_SERIAL_GET_HANDFLOW и IOCTL_SERIAL_SET_HANDFLOW, но требуется для поддержки только подмножества битов флагов, определенных для этих запросов. Биты флагов определяются для ControlHandShake и FlowReplace членов структуры SERIAL_HANDFLOW, используемой этими запросами.

Драйвер должен поддерживать следующий бит флага в элементе ControlHandshake:

SERIAL_CTS_HANDSHAKE

В качестве параметра драйвер может поддерживать любой из других битов флагов, определенных для элемента ControlHandshake.

Драйвер должен поддерживать следующие биты флагов в элементе FlowReplace:

SERIAL_RTS_CONTROL
SERIAL_RTS_HANDSHAKE

В качестве параметра драйвер может поддерживать любой из других битов флагов, определенных для элемента FlowReplace. Однако эти другие биты флагов редко, если когда-либо, необходимы, и Корпорация Майкрософт рекомендует их поддерживать.

Драйвер, который не поддерживает определенный бит флага в элементе ControlHandShake или FlowReplace, должен задать этот флаг равным нулю в выходном значении запроса IOCTL_SERIAL_GET_HANDFLOW. Если запрос IOCTL_SERIAL_SET_HANDFLOW указывает ControlHandshake или FlowReplace бит, что драйвер не поддерживает, функция EvtSerCx2Control должна завершить запрос и вернуть STATUS_INVALID_PARAMETER.

В качестве параметра драйвер может поддерживать XonLimit и XoffLimit членов структуры SERIAL_HANDFLOW. Однако эти члены редко, если когда-либо, необходимы, и корпорация Майкрософт рекомендует поддерживать их. Драйвер, который не поддерживает XonLimit и членов XoffLimit, должен задать эти элементы равным нулю в выходном значении запроса IOCTL_SERIAL_GET_HANDFLOW. Если запрос IOCTL_SERIAL_SET_HANDFLOW указывает ненулевое XonLimit или член XoffLimit и драйвер не поддерживает эти элементы, функция EvtSerCx2Control должна завершить запрос и вернуть STATUS_NOT_IMPLEMENTED.

Примеры

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

Например, чтобы определить функцию обратного вызова EvtSerCx2Control с именем MyControl, используйте тип функции EVT_SERCX2_CONTROL, как показано в этом примере кода:

EVT_SERCX2_CONTROL  MyControl;

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

_Use_decl_annotations_
NTSTATUS
  MyControl(
    WDFDEVICE  Device,
    WDFREQUEST  Request,
    size_t  OutputBufferLength,
    size_t  InputBufferLength,
    ULONG  IoControlCode
    )
  {...}

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

Требования

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