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

Artículo
10/30/2024

La función de devolución de llamada de eventos EvtSerCx2SetWaitMas k se llama a la versión 2 de la extensión de marco serie (SerCx2) para configurar el controlador serie para supervisar un conjunto de eventos de hardware especificados por una máscara de espera.

Sintaxis

EVT_SERCX2_SET_WAIT_MASK EvtSercx2SetWaitMask;

void EvtSercx2SetWaitMask(
  [in] WDFDEVICE Device,
  [in] WDFREQUEST Request,
  [in] ULONG WaitMask
)
{...}

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] Request

Un identificador WDFREQUEST para el objeto de solicitud de marco que representa la solicitud de IOCTL_SERIAL_SET_WAIT_MASK.

[in] WaitMask

Nueva máscara de espera. Para obtener más información, vea Comentarios.

Valor devuelto

Ninguno

Observaciones

El controlador de controlador serie puede, como opción, implementar esta función. Si se implementa, el controlador registra la función en la llamada a la SerCx2InitializeDevice método que finaliza la inicialización del objeto de dispositivo de marco para el controlador serie.

Cuando SerCx recibe una solicitud de IOCTL_SERIAL_SET_WAIT_MASK de un cliente, el controlador de solicitudes de SerCx2 llama a la función EvtSerCx2SetWaitMask, si se implementa, para notificar al controlador que la máscara de espera ha cambiado. Si la máscara de espera no es cero, el controlador comienza inmediatamente a supervisar los eventos en la nueva máscara de espera y descarta cualquier máscara de espera antigua que se haya proporcionado en una llamada anterior a EvtSerCx2SetWaitMask. Si la nueva máscara de espera es cero, el controlador simplemente descarta la máscara de espera antigua y deja de supervisar los eventos de la máscara de espera. Para obtener más información sobre los tipos de eventos que puede especificar una máscara de espera, vea SERIAL_EV_XXX.

Si el controlador no implementa esta función, SerCx2 produce un error en todas las solicitudes de IOCTL_SERIAL_SET_WAIT_MASK con código de estado de error STATUS_NOT_SUPPORTED.

Para supervisar los eventos de la máscara de espera, la función EvtSerCx2SetWaitMask normalmente habilita interrupciones para estos eventos. Más adelante, cuando se detecta un evento en la máscara de espera, el controlador del controlador serie llama al método SerCx2CompleteWait para notificar a SerCx2 del evento.

La función EvtSerCx2SetWaitMask es responsable de completar la solicitud de IOCTL_SERIAL_SET_WAIT_MASK apuntada por el parámetro request Request. Una vez que el controlador de controlador serie habilita las interrupciones necesarias, llama al método WdfRequestComplete y proporciona, como parámetros de entrada, el valor de parámetro Request y un valor de estado para indicar si la solicitud se realizó correctamente.

Antes de que el controlador del controlador serie llame a WdfRequestComplete para completar la solicitud, el controlador debe finalizar las llamadas a SerCx2CompleteWait que podrían estar pendientes debido a eventos en la máscara de espera antigua.

Inicialmente, después de que un cliente abra una conexión lógica al puerto serie y antes del primer EvtSerCx2SetWaitMask llamada, la máscara de espera es efectivamente cero y el controlador del controlador serie no supervisa ningún evento de SERIAL_EV_XXX.

SerCx2 produce un error en una solicitud de IOCTL_SERIAL_SET_WAIT_MASK que tiene una máscara de espera que incluye cualquiera de las marcas de eventos SERIAL_EV_XXX siguientes:

SERIAL_EV_PERR
SERIAL_EV_RING
SERIAL_EV_RXFLAG

Por lo tanto, la máscara de espera proporcionada a la función EvtSerCx2SetWaitMask nunca contiene ninguna de las marcas de evento de la lista anterior.

Si se implementa, la función EvtSerCx2SetWaitMask debe admitir las siguientes marcas de evento:

SERIAL_EV_CTS
SERIAL_EV_BREAK
SERIAL_EV_ERR

Además, si el controlador serie tiene una línea de señal conjunto de datos listo (DSR), la función EvtSerCx2SetWaitMask debe admitir SERIAL_EV_DSR. Como opción, un controlador puede admitir cualquiera de las otras marcas de evento descritas en SERIAL_EV_XXX. Si la máscara de espera especifica un evento que el controlador no admite, la función EvtSerCx2SetWaitMask debe producir un error en la solicitud y establecer el valor de estado en la solicitud en STATUS_INVALID_PARAMETER.

Ejemplos

Para definir un EvtSerCx2SetWaitMask 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 EvtSerCx2SetWaitMask función de devolución de llamada denominada MySetWaitmask, use el tipo de función EVT_SERCX2_SET_WAIT_MASK, como se muestra en este ejemplo de código:

EVT_SERCX2_SET_WAIT_MASK  MySetWaitmask;

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

_Use_decl_annotations_
VOID
  MySetWaitmask(
    WDFDEVICE  Device,
    WDFREQUEST Request,
    ULONG WaitMask
    )
  {...}

El tipo de función EVT_SERCX2_SET_WAIT_MASK 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_SET_WAIT_MASK 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.

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 a irQL <= DISPATCH_LEVEL.