EVT_SERCX_APPLY_CONFIG función de devolución de llamada (sercx.h)

La función de devolución de llamada de eventos EvtSerCxApplyConfig indica al controlador de controlador en serie que aplique una lista de opciones de configuración al hardware del controlador serie.

Sintaxis

EVT_SERCX_APPLY_CONFIG EvtSercxApplyConfig;

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

Parámetros

[in] Device

Un identificador WDFDEVICE para el objeto de dispositivo de marco que representa el controlador serie.

[in] ConnectionParameters

Puntero a la estructura de parámetros de conexión. Esta función debe convertir este parámetro en el tipo de puntero adecuado, analizar la estructura de datos para obtener los valores de configuración y aplicar estos valores al hardware del controlador serie. La estructura de parámetros de conexión se define mediante el proveedor de la plataforma de hardware y es opaca tanto para la extensión del marco serie (SerCx) como para el sistema operativo.

Valor devuelto

La función EvtSerCxApplyConfig devuelve STATUS_SUCCESS si la llamada se realiza correctamente. De lo contrario, devuelve un código de estado de error adecuado.

Observaciones

SerCx llama a esta función durante la inicialización del controlador serie para asegurarse de que el hardware está en un estado inicial válido. Además, se llama a esta función cada vez que un cliente envía una solicitud de control de E/S de IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION al controlador.

SerCx obtiene estos parámetros de configuración del descriptor de recursos ACPI para el dispositivo de controlador serie. El formato de datos que usa el firmware ACPI para almacenar estas opciones de configuración debe ser el mismo formato de datos esperado por el controlador de controlador serie.

Cuando un cliente envía una solicitud de IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION a un puerto serie administrado por SerCx, SerCx determina si el controlador de controlador serie para el puerto serie admite el EvtSerCxApplyConfig devolución de llamada y si el descriptor de recursos ACPI para el puerto serie proporciona la configuración de conexión predeterminada. Si no es así, SerCx completa la solicitud con código de estado de error STATUS_NOT_SUPPORTED. De lo contrario, SerCx pasa los parámetros de conexión al EvtSerCxApplyConfig del controlador función de devolución de llamada. Una vez que se devuelve esta devolución de llamada, SerCx completa la solicitud y usa el valor devuelto de la devolución de llamada como código de estado de la solicitud.

Si un controlador de controlador serie necesita obtener los parámetros de conexión predeterminados en un momento distinto de durante un EvtSerCxApplyConfig devolución de llamada, el controlador puede llamar al método SerCxGetConnectionParameters.

Para registrar un EvtSerCxApplyConfig función de devolución de llamada, el controlador debe llamar al método SerCxInitialize.

Ejemplos

El tipo de función para esta devolución de llamada se declara en Sercx.h, como se indica a continuación.

typedef NTSTATUS
  EVT_SERCX_APPLY_CONFIG(
    __in WDFDEVICE Device
    );

Para definir un EvtSerCxApplyConfig función de devolución de llamada denominada MyEvtSerCxApplyConfig, primero debe proporcionar una declaración de función que comprobador de controladores estáticos (SDV) y otras herramientas de comprobación necesarias, como se indica a continuación.

EVT_SERCX_APPLY_CONFIG MyEvtSerCxApplyConfig;

A continuación, implemente la función de devolución de llamada de la manera siguiente.

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

Para obtener más información sobre los requisitos de SDV para las declaraciones de función, consulte Declaración de funciones mediante tipos de rol de función para controladores kmDF.

En el ejemplo de código siguiente se muestra una implementación parcial de una función EvtSerCxApplyConfig para un 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;
}

Los tipos de puntero PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER y PPNP_SERIAL_BUS_DESCRIPTOR del ejemplo de código anterior se definen en el archivo de encabezado Reshub.h.

Requisitos

Requisito	Valor
cliente mínimo admitido	Disponible a partir de Windows 8.
de la plataforma de destino de	Escritorio
encabezado de	sercx.h
irQL	Se llama a irQL <= DISPATCH_LEVEL

Consulte también

IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION

SerCxGetConnectionParameters

SerCxInitialize