EVT_SERCX2_APPLY_CONFIG función de devolución de llamada (sercx.h)
La EvtSerCx2ApplyConfig función de devolución de llamada de eventos se llama mediante la versión 2 de la extensión del marco de serie (SerCx2) para proporcionar al controlador de controlador serie una lista de opciones de configuración específicas del dispositivo que se aplicarán al hardware del controlador serie.
Sintaxis
EVT_SERCX2_APPLY_CONFIG EvtSercx2ApplyConfig;
NTSTATUS EvtSercx2ApplyConfig(
[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. El controlador de controlador serie creó este objeto en su función de devolución de llamada EvtDriverDeviceAdd. Para obtener más información, vea SerCx2InitializeDevice.
[in] ConnectionParameters
Puntero a la estructura de parámetros de conexión. Esta función debe convertir el puntero al 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 SerCx2 como para el sistema operativo. Para obtener más información, vea Comentarios.
Valor devuelto
La función EvtSerCx2ApplyConfig devuelve STATUS_SUCCESS si la llamada se realiza correctamente. De lo contrario, devuelve un código de estado de error adecuado.
Observaciones
El controlador de controlador serie debe implementar esta función. El controlador registra la función en la llamada al método SerCx2InitializeDevice que finaliza la inicialización del objeto de dispositivo de marco para el controlador serie.
SerCx2 llama a la función
SerCx2 obtiene los parámetros de configuración del campo de datos definido por el proveedor en el 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. Para obtener más información, vea la descripción del descriptor de conexión de bus serie UART en la especificación ACPI 5.0 de .
Cuando un cliente envía una solicitud IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION a un puerto serie administrado por SerCx2, SerCx2 llama a la función EvtSerCx2ApplyConfig para pasar los parámetros de configuración al controlador del controlador serie. Una vez que se devuelve esta devolución de llamada, SerCx2 completa la solicitud y usa el valor devuelto de la devolución de llamada como código de estado de la solicitud.
Ejemplos
Para definir un EvtSerCx2ApplyConfig función de devolución de llamada, primero debe proporcionar una declaración de función que identifique el tipo de función de devolución de llamada que está definiendo. Windows proporciona un conjunto de tipos de función de devolución de llamada para controladores. Declarar una función mediante los tipos de función de devolución de llamada ayuda a Análisis de código para controladores, comprobador de controladores estáticos (SDV) y otras herramientas de comprobación encuentran errores y es un requisito para escribir controladores para el sistema operativo Windows.
Por ejemplo, para definir un EvtSerCx2ApplyConfig función de devolución de llamada denominada MyApplyConfig, use el tipo de función EVT_SERCX2_APPLY_CONFIG, como se muestra en este ejemplo de código:
EVT_SERCX2_APPLY_CONFIG MyApplyConfig;
A continuación, implemente la función de devolución de llamada de la siguiente manera:
_Use_decl_annotations_
NTSTATUS
MyApplyConfig(
WDFDEVICE Device,
PVOID ConnectionParameters
)
{...}
El tipo de función EVT_SERCX2_APPLY_CONFIG se define en el archivo de encabezado Sercx.h. Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación Use_decl_annotations a la definición de función. La anotación Use_decl_annotations garantiza que se usen las anotaciones que se aplican al tipo de función EVT_SERCX2_APPLY_CONFIG en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, consulte Declaración de funciones mediante tipos de rol de función para controladores kmDF. Para obtener más información sobre Use_decl_annotations, vea Anotación del comportamiento de la función.
En el ejemplo de código siguiente se muestra una implementación parcial de una función EvtSerCx2ApplyConfig 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
#include <pshpack1.h>
//
// 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;
#include <poppack.h>
EVT_SERCX_APPLY_CONFIG MyApplyConfig;
//
// Implementation of an EvtSerCx2ApplyConfig callback function
//
_Use_decl_annotations_
VOID
MyApplyConfig(
WDFDEVICE Device,
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 platform-specific configuration settings
// from the UART descriptor here:
...
}
return status;
}
Los archivos de encabezado pshpack1.h y poppack.h del ejemplo de código anterior controlan el modo de alineación de la estructura usado por el compilador. Los tipos de puntero PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER y PPNP_SERIAL_BUS_DESCRIPTOR son punteros a estructuras RH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER y PNP_SERIAL_BUS_DESCRIPTOR. Para obtener más información sobre los miembros de la estructura de
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Disponible a partir de Windows 8.1. |
| de la plataforma de destino de |
Escritorio |
| encabezado de |
sercx.h |
| irQL | Se llama en PASSIVE_LEVEL. |
Consulte también
IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION