EVT_SERCX2_CONTROL función de devolución de llamada (sercx.h)
La función de devolución de llamada de eventos EvtSerCx2Control se llama a la versión 2 de la extensión del marco de trabajo serie (SerCx2) para controlar una solicitud de control de E/S serie.
Sintaxis
EVT_SERCX2_CONTROL EvtSercx2Control;
NTSTATUS EvtSercx2Control(
[in] WDFDEVICE Device,
[in] WDFREQUEST Request,
[in] size_t OutputBufferLength,
[in] size_t InputBufferLength,
[in] ULONG IoControlCode
)
{...}
Parámetros
[in] Device
Un controlador WDFDEVICE para el objeto de dispositivo de marco que representa el controlador serie. El controlador del controlador serie creó este objeto en su función de devolución de llamada EvtDriverDeviceAdd . Para obtener más información, vea SerCx2InitializeDevice.
[in] Request
Un identificador WDFREQUEST para el objeto de solicitud de marco que representa la solicitud de control de E/S serie.
[in] OutputBufferLength
Longitud, en bytes, del búfer de salida de la solicitud de control de E/S serie especificada por el parámetro Request .
[in] InputBufferLength
Longitud, en bytes, del búfer de entrada de la solicitud de control de E/S serie especificada por el parámetro Request .
[in] IoControlCode
Especifica el código de control de E/S (IOCTL) de la solicitud de control de E/S serie especificada por el parámetro Request . Las ICTL para las solicitudes de control de E/S serie se definen en el archivo de encabezado Ntddser.h. Para obtener más información, vea la sección Comentarios.
Valor devuelto
La función EvtSerCx2Control devuelve STATUS_SUCCESS si la llamada es correcta. De lo contrario, devuelve un código de estado de error adecuado.
Comentarios
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.
La función EvtSerCx2Control permite al controlador controlar determinadas solicitudes de control de E/S serie que SerCx2 no puede controlar. SerCx2 controla todo el procesamiento de un subconjunto de las ICTL serie definidas en el archivo de encabezado Ntddser.h. Sin embargo, SerCx2 se basa en el controlador para controlar las solicitudes de control de E/S serie para realizar operaciones dependientes del hardware.
Cuando SerCx2 recibe una solicitud de control de E/S serie que solo puede controlar el controlador de controlador serie, SerCx2 llama a la función EvtSerCx2Control para entregar la solicitud de control de E/S al controlador. El controlador es responsable de completar esta solicitud. Un controlador que no implemente compatibilidad con una solicitud de control de E/S determinada debe completar esta solicitud de control de E/S con el código de estado de error STATUS_NOT_SUPPORTED.
Para completar la solicitud de control de E/S, el controlador normalmente llama al método WdfRequestComplete y proporciona, como parámetros de entrada, el valor del parámetro Request y un valor de estado para indicar si la solicitud se realizó correctamente. Este valor de estado se escribe en el bloque de estado de la solicitud.
El valor devuelto de la función EvtSerCx2Control siempre debe coincidir con el valor de estado que esta función escribe en el bloque de estado de la solicitud de control de E/S. La implementación actual de SerCx2 omite este valor devuelto.
SerCx2 llama a la función EvtSerCx2Control para controlar las ICTLs que se muestran en la tabla siguiente. La columna del lado derecho de la tabla indica si la función EvtSerCx2Control es necesaria para implementar la compatibilidad con un IOCTL determinado.
| Nombre de la solicitud de control de E/S | Obligatorio u opcional |
|---|---|
| IOCTL_SERIAL_CLR_DTR | Opcionales |
| IOCTL_SERIAL_CLR_RTS | Requerido |
| IOCTL_SERIAL_GET_BAUD_RATE | Requerido |
| IOCTL_SERIAL_GET_COMMSTATUS | Requerido |
| IOCTL_SERIAL_GET_DTRRTS | Requerido |
| IOCTL_SERIAL_GET_HANDFLOW | Requerido |
| IOCTL_SERIAL_GET_LINE_CONTROL | Requerido |
| IOCTL_SERIAL_GET_MODEM_CONTROL | Requerido |
| IOCTL_SERIAL_GET_MODEMSTATUS | Requerido |
| IOCTL_SERIAL_GET_PROPERTIES | Requerido |
| IOCTL_SERIAL_SET_BAUD_RATE | Requerido |
| IOCTL_SERIAL_SET_BREAK_OFF | Requerido |
| IOCTL_SERIAL_SET_BREAK_ON | Requerido |
| IOCTL_SERIAL_SET_DTR | Opcionales |
| IOCTL_SERIAL_SET_FIFO_CONTROL | Opcionales |
| IOCTL_SERIAL_SET_HANDFLOW | Requerido |
| IOCTL_SERIAL_SET_LINE_CONTROL | Requerido |
| IOCTL_SERIAL_SET_MODEM_CONTROL | Requerido |
| IOCTL_SERIAL_SET_RTS | Requerido |
En la tabla anterior se enumeran todas las ICTL serie que SerCx2 presenta a la función EvtSerCx2Control . Para cualquier IOCTL que no esté en esta lista, SerCx2 controla el IOCTL o produce un error inmediato en el IOCTL y establece el estado de la solicitud en STATUS_NOT_SUPPORTED. SerCx2 controla IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION solicitudes, pero llama a la función de devolución de llamada de eventos EvtSerCx2ApplyConfig durante el procesamiento de dicha solicitud. SerCx2 controla IOCTL_SERIAL_PURGE solicitudes, pero puede llamar a la función de devolución de llamada de eventos EvtSerCx2PurgeFifos durante el procesamiento de dicha solicitud. SerCx procesa preliminarmente las solicitudes de IOCTL_SERIAL_SET_WAIT_MASK , pero llama a la función de devolución de llamada de eventos EvtSerCx2SetWaitMask , si se implementa, para terminar de controlar dicha solicitud. Para obtener más información sobre la compatibilidad de SerCx2 con ioCTLs serie, consulte Interfaz de solicitud de E/S serie.
IOCTL_SERIAL_CLR_DTR y IOCTL_SERIAL_SET_DTR
Si la función EvtSerCx2Control del controlador serie admite la solicitud de IOCTL_SERIAL_SET_DTR , esta función también debe admitir la solicitud de IOCTL_SERIAL_CLR_DTR y viceversa. Si el controlador no admite estas dos solicitudes, el controlador del controlador para la solicitud de IOCTL_SERIAL_GET_DTRRTS debe establecer el bit de marca de SERIAL_DTR_STATE en el valor de salida de esta solicitud en cero.
IOCTL_SERIAL_GET_DTRRTS
La función EvtSerCx2Control del controlador serie debe admitir la solicitud de IOCTL_SERIAL_GET_DTRRTS , pero el controlador del controlador para esta solicitud es necesario para admitir solo el bit de marca de SERIAL_RTS_STATE en el valor de salida de esta solicitud. Como opción, el controlador también puede admitir el bit de marca de SERIAL_DTR_STATE. Si no se admite el bit de marca SERIAL_DTR_STATE, establezca este bit en cero.
IOCTL_SERIAL_GET_COMMSTATUS
La función EvtSerCx2Control del controlador serie debe admitir la solicitud de IOCTL_SERIAL_GET_COMMSTATUS , pero el controlador del controlador para esta solicitud es necesario para admitir solo los siguientes miembros de la estructura de SERIAL_STATUS usada por esta solicitud:
- Errores
- HoldReasons
IOCTL_SERIAL_GET_PROPERTIES
La función EvtSerCx2Control del controlador serie debe admitir la solicitud de IOCTL_SERIAL_GET_PROPERTIES . El controlador del controlador para esta solicitud debe establecer el miembro MaxBaud de la estructura de SERIAL_COMMPROP utilizada por esta solicitud para la velocidad máxima de baudios admitida, expresada en bits por segundo (bps). Por ejemplo, si el controlador serie admite una velocidad máxima de baudios de 115 200 bps, el controlador establece MaxBaud = 115200.
IOCTL_SERIAL_GET_MODEMSTATUS
La función EvtSerCx2Control del controlador serie debe admitir la solicitud de IOCTL_SERIAL_GET_MODEMSTATUS . El controlador del controlador para esta solicitud debe establecer el valor de salida de la solicitud en el valor de registro de estado del módem sin formato leído del hardware del controlador serie.
IOCTL_SERIAL_GET_HANDFLOW y IOCTL_SERIAL_SET_HANDFLOW
La función EvtSerCx2Control del controlador de serie debe admitir las solicitudes de IOCTL_SERIAL_GET_HANDFLOW y IOCTL_SERIAL_SET_HANDFLOW , pero es necesaria para admitir solo un subconjunto de los bits de marca definidos para estas solicitudes. Los bits de marca se definen para los miembros ControlHandShake y FlowReplace de la estructura SERIAL_HANDFLOW que usan estas solicitudes.
El controlador debe admitir el siguiente bit de marca en el miembro ControlHandshake :
- SERIAL_CTS_HANDSHAKE
El controlador debe admitir los siguientes bits de marca en el miembro FlowReplace :
- SERIAL_RTS_CONTROL
- SERIAL_RTS_HANDSHAKE
Un controlador que no admite un bit de marca determinado en el miembro ControlHandShake o FlowReplace debe establecer este bit de marca en cero en el valor de salida de la solicitud de IOCTL_SERIAL_GET_HANDFLOW . Si una solicitud de IOCTL_SERIAL_SET_HANDFLOW especifica un bit de marca ControlHandshake o FlowReplace que el controlador no admite, la función EvtSerCx2Control debe producir un error en la solicitud y devolver STATUS_INVALID_PARAMETER.
Como opción, un controlador puede admitir los miembros XonLimit y XoffLimit de la estructura SERIAL_HANDFLOW . Sin embargo, estos miembros rara vez, si es necesario, y Microsoft recomienda no admitirlos. Un controlador que no admite los miembros XonLimit y XoffLimit debe establecer estos miembros en cero en el valor de salida de la solicitud de IOCTL_SERIAL_GET_HANDFLOW . Si una solicitud de IOCTL_SERIAL_SET_HANDFLOW especifica un miembro XonLimit o XoffLimit distinto de cero y el controlador no admite estos miembros, la función EvtSerCx2Control debe producir un error en la solicitud y devolver STATUS_NOT_IMPLEMENTED.
Ejemplos
Para definir una función de devolución de llamada EvtSerCx2Control , 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 una función de devolución de llamada EvtSerCx2Control denominada MyControl, use el tipo de función EVT_SERCX2_CONTROL , como se muestra en este ejemplo de código:
EVT_SERCX2_CONTROL MyControl;
A continuación, implemente la función de devolución de llamada de la siguiente manera:
_Use_decl_annotations_
NTSTATUS
MyControl(
WDFDEVICE Device,
WDFREQUEST Request,
size_t OutputBufferLength,
size_t InputBufferLength,
ULONG IoControlCode
)
{...}
El tipo de función EVT_SERCX2_CONTROL 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_CONTROL 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, consulte Anotación del comportamiento de la función.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Disponible a partir de Windows 8.1. |
| Plataforma de destino | Escritorio |
| Encabezado | sercx.h |
| IRQL | Se llama en IRQL <= DISPATCH_LEVEL. |
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de