winbase.h


WaitCommEvent

Espera a que ocurra un evento para el dispositivo de comunicaciones especificado. El conjunto de eventos que son monitorizados por esta función está contenido en la máscara de eventos asociada con el manipulador del dispositivo.

Sintaxis

BOOL WaitCommEvent(
    HANDLE hCommDev,       // manipulador del dispositivo de comunicaciones
    LPDWORD lpfdwEvtMask,  // dirección de la variable para el evento que ocurra
    LPOVERLAPPED lpo,      // dirección de la estructura overlapped
   );

Parámetros:

hCommDev: identifica el dispositivo de comunicaciones. La función CreateFile devuelve este manipulador.

lpfdwEvtMask: apunta a una variable de 32 bits que recibirá una máscara indicando el tipo de evento ocurrido. Si ocurre un error, el valor es cero; en otro caso, puede tomar uno de los siguientes valores:

Valor Significado
EV_BREAK Se ha detectado un corte en la entrada.
EV_CTS Cambio de estado en la señal CTS (clear-to-send: preparado para enviar).
EV_DSR Cambio de estado en la señal DSR (data-set-ready: datos preparados).
EV_ERR Error en línea de estatus. Este error puede ser CE_FRAME, CE_OVERRUN y CE_RXPARITY.
EV_RING Se ha recibido un indicador de llamada.
EV_RLSD Cambio de estado en señal RLSD (receive-line-signal-detect: detección de señal en línea de entrada).
EV_RXCHAR Se ha recibido un carácter y se ha colocado en el buffer de entrada.
EV_RXFLAG El carácter de evento se ha recibido y colocado en el buffer de entrada. El carácter de evento se especifica en la estructura DCB del dispositivo, que es aplicada al puerto serie usando la función SetCommState.
EV_TXEMPTY El último carácter del buffer de salida ha sido enviado.

lpo: apunta a una estructura OVERLAPPED. Este parámetro se ignora si el manipulador hCommDev fue abierto sin especificar el flag FILE_FLAG_OVERLAPPED. Si no se desea una operación de solapamiento (overlapped), este parámetros puede ser NULL.

Valor de retorno

Si la función tiene éxito, el valor de retorno es TRUE.

Si la función falla, el valor de retorno es FALSE. Para obtener mayor información sobre el error, llamar a GetLastError.

Observaciones

Esta función monitoriza un conjunto de eventos para un recurso de comunicaciones. Para modificar y consultar la máscara de eventos actual de un recurso de comunicaciones, usar las funciones SetCommMask y GetCommMask.

Si el parámetro lpo es NULL o el manipulador hCommDev fue abierto sin especificar el flag FILE_FLAG_OVERLAPPED, WaitCommEvent no vuelve hasta que no ocurra uno de los eventos especificados o un error.

Si lpo apunta a una estructura OVERLAPPED y se especificó FILE_FLAG_OVERLAPPED cuando se abrió el manipulador hCommDev, WaitCommEvent se lleva a cabo como una operación superpuesta (overlapped). En este caso, la estructura OVERLAPPED debe contener un manipulador a un objeto de evento manual-reset (creado mediante el uso de la función CreateEvent).

Si la operación superpuesta no puede ser completada inmediatamente, la función retorna con FALSE y la función GetLastError devuelve ERROR_IO_PENDING, indicando que la operación se está ejecutando en segundo plano. Cuando esto ocurre, el sistema modifica el miembro hEvent de la estructura OVERLAPPED la estado "no-señalado" antes de que WaitCommEvent vuelva, y entonces lo cambia al estado "señalado" cuando ocurra uno de los eventos especificados o un error. El proceso que llama puede usar la función de espera para determinar el estado del objeto evento y después usar GetOverlappedResult para determinar el resultado de la operación WaitCommEvent. GetOverlappedResult notifica el suceso o fallo de la operación, y la variable apuntada por el parámetro lpfdwEvtMask se cambia para indicar que el evento ha ocurrido.

Si un proceso intenta cambiar la máscara de eventos del manipulador del dispositivo usando SetCommMask mientras una operación WaitCommEvent superpuesta está en proceso, WaitCommEvent vuelve inmediatamente. La variable apuntada por el parámetro lpfdwEvtMask se pone a cero.