MgslWaitEvent

Prototype
`ULONG MgslWaitEvent( HANDLE hDevice, ULONG EventMask, PULONG pEvents, LPOVERLAPPED pOverlapped );`
Parameters
`hDevice`	handle to open port
`EventMask`	ULONG containing bit flags that indicate which events should cause the function to return:
	MgslEvent_DsrActive ⁽¹⁾
	MgslEvent_DsrInactive ⁽¹⁾
	MgslEvent_CtsActive
	MgslEvent_CtsInactive
	MgslEvent_DcdActive
	MgslEvent_DcdInactive
	MgslEvent_RiActive ⁽¹⁾
	MgslEvent_RiInactive ⁽¹⁾
	MgslEvent_ExitHuntMode⁽²⁾
	MgslEvent_IdleReceived ⁽²⁾
pEvents	pointer to ULONG to hold returned event bit flags
`pOverlapped`	pointer to overlapped structure initialized with a WIN32 manual reset event object which will be signaled when the receive operation completes
Return Value
`ERROR_SUCCESS (0)`	one of the specified events already occurred
`ERROR_INVALID_HANDLE`	hDevice is invalid
`ERROR_INVALID_PARAMETER`	pEvents is invalid.
`ERROR_BUSY`	a request of this type is already pending
`ERROR_IO_PENDING`	waiting for operation to complete when specified event occurs

Wait for a specified serial signal event to occur, as specified by the application in EventMask. The API sets pEvents to indicate the state of ALL serial signals at the time the first specified event occurs.

The MgslEvent_ExitHuntMode event occurs when the receiver is enabled and a flag is received, causing the receiver to exit hunt mode. This event can be used to detect idling flags transmitted from the remote station. Note that this event occurs on the 1st received flag and will not occur again until the receiver has gone back to hunt mode (after receiving an idle) and another flag is received.

The MgslEvent_IdleReceived event occurs when the receiver is enabled and encounters 15 consecutive ones. The receiver is placed into hunt mode (looking for a flag) after receiving an idle character. This event will not occur again until the receiver has received a flag (exiting hunt mode) and another idle is received.

If one or more of the events specified in EventMask has already occurred then the function returns immediately with ERROR_SUCCESS. For instance, if MgslEvent_DcdActive is specified in EventMask and DCD is already active when MgslWaitEvent is called, the API returns ERROR_SUCCESS with MgslEvent_DcdActive set in pEvents.

If none of the specified events has already occurred, the API returns ERROR_IO_PENDING. When a specified event occurs, the API sets pEvents and signals the event object in the OVERLAPPED structure.

NOTE:

If MgslWaitEvent, returns ERROR_IO_PENDING, it is important that MgslWaitEvent not be called again, until the request completes. See the Caution note in the Asynchronous API Notification topic for more information.

Note that pEvents specifies the state of the serial signals when the first specified event occurs and not the current state of the serial signals. Call MgslGetSerialSignals to get the current state of the serial signals.

Contents