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

Статья
12/15/2024

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

Синтаксис

EVT_SERCX_APPLY_CONFIG EvtSercxApplyConfig;

NTSTATUS EvtSercxApplyConfig(
  [in] WDFDEVICE Device,
  [in] PVOID ConnectionParameters
)
{...}

Параметры

[in] Device

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

[in] ConnectionParameters

Указатель на структуру параметров подключения. Эта функция должна привести этот параметр к соответствующему типу указателя, проанализировать структуру данных для получения параметров конфигурации и применить эти параметры к оборудованию последовательного контроллера. Структура параметров подключения определяется поставщиком аппаратной платформы и непрозрачна как для расширения последовательной платформы (SerCx), так и операционной системы.

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

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

Замечания

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

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

Когда клиент отправляет запрос IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION на последовательный порт, управляемый SerCx, SerCx определяет, поддерживает ли драйвер последовательного контроллера последовательный порт для последовательного порта EvtSerCerCxApplyConfig обратного вызова, а также предоставляет ли дескриптор ресурса ACPI для последовательного порта параметры подключения по умолчанию. Если нет, SerCx завершает запрос с кодом состояния ошибки STATUS_NOT_SUPPORTED. В противном случае SerCx передает параметры подключения в функцию обратного вызова драйвера EvtSerCerCxApplyConfig. После возврата обратного вызова SerCx завершает запрос и использует возвращаемое значение из обратного вызова в качестве кода состояния запроса.

Если драйвер последовательного контроллера должен получить параметры подключения по умолчанию за раз, отличный от EvtSerCerCxApplyConfig обратного вызова, драйвер может вызвать метод SerCxGetConnectionParameters.

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

Примеры

Тип функции для этого обратного вызова объявлен в Sercx.h, как показано ниже.

typedef NTSTATUS
  EVT_SERCX_APPLY_CONFIG(
    __in WDFDEVICE Device
    );

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

EVT_SERCX_APPLY_CONFIG MyEvtSerCxApplyConfig;

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

NTSTATUS
  MyEvtSerCxApplyConfig(
    __in WDFDEVICE Device
    )
{ ... }

Дополнительные сведения о требованиях SDV для объявлений функций см. в объявлении функций с помощью типов ролей функций для драйверов KMDF.

В следующем примере кода показана частичная реализация функции EvtSerCxApplyConfig для UART.

//
// Define the UART ACPI descriptor, plus any vendor-specific
// data that is needed by the serial controller (UART) driver.
//

#define ANYSIZE_ARRAY 1


//
// Common resource name descriptor
//
typedef struct _PNP_IO_DESCRIPTOR_RESOURCE_NAME {
    UCHAR ResourceIndex;
    UCHAR ResourceName[ANYSIZE_ARRAY];
} PNP_IO_DESCRIPTOR_RESOURCE_NAME, *PPNP_IO_DESCRIPTOR_RESOURCE_NAME;

//
// Bus descriptor for a UART
//
typedef struct _PNP_UART_SERIAL_BUS_DESCRIPTOR {
    PNP_SERIAL_BUS_DESCRIPTOR SerialBusDescriptor;
    ULONG BaudRate;
    USHORT RxBufferSize;
    USHORT TxBufferSize;
    UCHAR Parity;
    // Include any optional vendor data here:
    ...
    // Append the PNP_IO_DESCRIPTOR_RESOURCE_NAME here:
    ....
} PNP_UART_SERIAL_BUS_DESCRIPTOR, *PPNP_UART_SERIAL_BUS_DESCRIPTOR;

EVT_SERCX_APPLY_CONFIG UartEvtApplyConfig;

//
// Implementation of an EvtSerCxApplyConfig callback function
//
NTSTATUS
  UartEvtApplyConfig(
    __in WDFDEVICE Device,
    __in PVOID ConnectionParameters
    )
{
    NTSTATUS status = STATUS_SUCCESS; 
    PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER connection;
    PPNP_SERIAL_BUS_DESCRIPTOR descriptor;
    PPNP_UART_SERIAL_BUS_DESCRIPTOR uartDescriptor;

    if (ConnectionParameters == NULL)
    {
        status = STATUS_INVALID_PARAMETER; 
    }

    if (NT_SUCCESS(status))
    {
        connection = (PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER)ConnectionParameters;

        if (connection->PropertiesLength < sizeof(PNP_SERIAL_BUS_DESCRIPTOR))
        {
            status = STATUS_INVALID_PARAMETER;
        }
    }

    if (NT_SUCCESS(status))
    {
        descriptor = (PPNP_SERIAL_BUS_DESCRIPTOR)connection->ConnectionProperties;

        if (descriptor->SerialBusType != UART_SERIAL_BUS_TYPE)
        {
            status = STATUS_INVALID_PARAMETER;
        }
    }

    if (NT_SUCCESS(status))
    {
        uartDescriptor = (PPNP_UART_SERIAL_BUS_DESCRIPTOR)connection->ConnectionProperties; 

        // Apply the configuration settings from
        // the UART descriptor.
        ...
    }

    return status;
}

Типы указателей PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER и PPNP_SERIAL_BUS_DESCRIPTOR в предыдущем примере кода определяются в файле заголовка Reshub.h.

Требования

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

См. также

IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION

SerCxGetConnectionParameters

SerCxInitialize

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