ser_sr24_wait_event


int   ser_sr24_wait_event(
     ser_sr24 handle,   //serial board handle
     int *events,   //integer array of event id's
     unsigned int length,   //number of elements in the events array
     unsigned int timeout,   //time (in milliseconds) before function will timeout
     unsigned int *value   //pointer to integer which receives the value returned from the event
     );

Summary

This function waits for any of several events (specified in an array) to occur. If any of the specified events occur, that event id is returned by the function and the event's value is written into the variable pointed to by 'value'. If zero is passed for the 'length' parameter, the function will return any event that occurs. In other words, when 'length' is zero, the very next event that comes in from the serial board will be returned by this function, regardless of its event ID. A timeout value (in milliseconds) may be specified by the timeout parameter. If none of the specified events occur within the specified amount of time, the function returns with the timeout error. If no timeout is desired, a value of zero may be passed. Note that any negative return value will always be an error code. This will always be true because negative event id's are not allowed (see the ser_sr24_register_event function).

Parameters

handle:
    This is the handle to the serial board; it is actually a pointer to the data structure for the board.
events:
    This is an array of integers; each integer is an event id which we are waiting for. If any of these events occurs, the function will return.
length:
    This specifies the number of elements in the events array. Setting this parameter to 0 causes the function to return any event that occurs.
timeout:
    This is the time (in milliseconds) before the function will timeout and return if none of the specified events has occurred. Pass a 0 to prevent the function from timing out.
value:
    This is a pointer to the integer variable where you want to store the value returned from the event. For example, a byte event would return the value present on the port.

Return Values

Function returns the event id (always positive) upon success. If an error or timeout occurs, a negative error code will be returned. Possible error codes include:

Visual Basic Notes

The Visual Basic equivalent of this function is the WaitEvent method. Return values are listed above.

Prototype:
object.WaitEvent(
     ByRef events( ) As Long   'array of event id's we are waiting for
     ByVal Timeout As Long   'time (in milliseconds) before function will timeout
     ByRef value As Long   'variable where the value associated with the event is stored
     ) As Long

Example:
  Dim e(1 to 2) as Long     'create array which holds events we are waiting for
  e(1) = 100 
  e(2) = 200 
  'Wait for events; time out in 2 seconds if they do not occur; store event value in 'value' 
  result = object.WaitEvent(e(), 2000, value) 


Back to Contents Winford Engineering (2000)