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

Artículo
08/07/2023

La función de devolución de llamada de eventos EvtSerCx2SetWaitMask se llama a la versión 2 de la extensión del marco de trabajo 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 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 IOCTL_SERIAL_SET_WAIT_MASK .

[in] WaitMask

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

Valor devuelto

None

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 al método SerCx2InitializeDevice 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 de 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 se pueden especificar mediante 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 de 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 a la que apunta el parámetro Request . Después de que el controlador de serie habilite las interrupciones necesarias, 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.

Antes de que el controlador de 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 anterior.

Inicialmente, después de que un cliente abra una conexión lógica al puerto serie y antes de la primera llamada evtSerCx2SetWaitMask , la máscara de espera es eficazmente 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 siguientes marcas de eventos SERIAL_EV_XXX :

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 preparada para el conjunto de datos (DSR), la función EvtSerCx2SetWaitMask debe admitir SERIAL_EV_DSR. Como opción, un controlador puede admitir cualquiera de las otras marcas de eventos 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 una función de devolución de llamada EvtSerCx2SetWaitMask , 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 Code Analysis for Drivers, Static Driver Verifier (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 EvtSerCx2SetWaitMask 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 roles 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.