EVT_SERCX_APPLY_CONFIG回调函数 (sercx.h)

  • 项目

EvtSerCxApplyConfig 事件回调函数指示串行控制器驱动程序将配置设置列表应用于串行控制器硬件。

语法

EVT_SERCX_APPLY_CONFIG EvtSercxApplyConfig;

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

参数

[in] Device

表示串行控制器的框架设备对象的 WDFDEVICE 句柄。

[in] ConnectionParameters

指向连接参数结构的指针。 此函数必须将此参数强制转换为适当的指针类型，分析数据结构以获取配置设置，并将这些设置应用于串行控制器硬件。 连接参数结构由硬件平台供应商定义，对于串行框架扩展 (SerCx) 和操作系统都是不透明的。

返回值

如果调用成功， EvtSerCxApplyConfig 函数将返回STATUS_SUCCESS。 否则，它将返回相应的错误状态代码。

注解

SerCx 在串行控制器初始化期间调用此函数，以确保硬件处于有效的初始状态。 此外，每当客户端向控制器发送 IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION I/O 控制请求时，就会调用此函数。

SerCx 从串行控制器设备的 ACPI 资源描述符获取这些配置参数。 ACPI 固件用于存储这些配置设置的数据格式应与串行控制器驱动程序预期的数据格式相同。

当客户端向 SerCx 管理的串行端口发送 IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION 请求时，SerCx 将确定串行端口的串行控制器驱动程序是否支持 EvtSerCxApplyConfig 回调，以及串行端口的 ACPI 资源描述符是否提供默认连接设置。 否则，SerCx 会以错误状态代码STATUS_NOT_SUPPORTED完成请求。 否则，SerCx 会将连接参数传递给驱动程序的 EvtSerCxApplyConfig 回调函数。 此回调返回后，SerCx 完成请求并使用回调的返回值作为请求的状态代码。

如果串行控制器驱动程序需要在 EvtSerCxApplyConfig 回调期间以外的时间获取默认连接参数，则驱动程序可以调用 SerCxGetConnectionParameters 方法。

若要注册 EvtSerCxApplyConfig 回调函数，驱动程序必须调用 SerCxInitialize 方法。

示例

此回调的函数类型在 Sercx.h 中声明，如下所示。

typedef NTSTATUS
  EVT_SERCX_APPLY_CONFIG(
    __in WDFDEVICE Device
    );

若要定义名为 MyEvtSerCxApplyConfig的 EvtSerCxApplyConfig 回调函数，必须先提供静态驱动程序验证程序 (SDV) 和其他验证工具所需的函数声明，如下所示。

EVT_SERCX_APPLY_CONFIG MyEvtSerCxApplyConfig;

然后，按如下所示实现回调函数。

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

有关函数声明的 SDV 要求的详细信息，请参阅 使用 KMDF 驱动程序的函数角色类型声明函数。

下面的代码示例演示 UART 的 EvtSerCxApplyConfig 函数的部分实现。 
//
// 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