ser_sr24_register_event


int   ser_sr24_register_event(
     ser_sr24 handle,   //serial board handle
     int port,   //serial board port for which we are registering an event
     int bit,   //the bit for which we are registering an event
     int id   //the value which will be passed to the event handler when an event occurs
     );

Summary

The ser_sr24_register_event function is used to configure a hardware event on the serial board. It is used to configure both byte events and bit events. Note that configuring a byte event automatically disables any bit events on that same port.

When a hardware event is registered either for an entire port (byte event) or an individual bit (bit event), then the serial board will send a message to the host computer whenever the value of that port or bit changes. The API receives this message and dispatches an event notification to your event-handling code (you must tell the API about your event-handling code using the ser_sr24_set_event_handler() function). Since there may be several different events enabled at any one time, the API must pass an 'event id' which tells your event handler exactly which event just occurred. This event id is defined by you when you register the event. It is up to you to pick a unique event id for each event that you are interested in.

If you are programming in C or C++, your event handler mechanism can be a callback function or a Windows message processing loop. In Visual Basic, the included class provides an event handler function for you; you simply fill in the code. In any case, the event id you specify will be passed to your event handler.

Note: The specified event id must be a positive integer or zero. Passing a negative number will return an error. Passing a zero will disable that event on the serial board. This is the method used to 'turn off' or 'unregister' a particular event after it has been enabled.

Parameters

handle:
    This is the handle to the serial board; it is actually a pointer to the data structure for the board.
port:
    This identifies the port on the serial board for which we are configuring an event; valid range is 1 - 3.
bit:
    This specifies which bit of the port is being configured. Valid range is 0 - 7 for a bit event; specify negative one (-1) for a byte event.
id:
    This is the 'event id' which is passed to your callback function when this particular event occurs. Valid range is any positive integer, including zero. A zero will disable the event on the serial board itself. A negative integer will return an error.

Return Values

Function returns 0 upon success. Possible error codes include:

Visual Basic Notes

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

Prototype:
object.RegisterEvent(
     ByVal port As Long   'serial board port for which we are registering an event
     ByVal bit As Long   'the bit for which we are registering an event
     ByVal id As Long   'the value which will be passed to the event handler when an event occurs
     ) As Long

Example
result = object.RegisterEvent(2, 0, 200)   'configure event for Bit 0 of Port 2 and assign it an id of 200



Back to Contents Winford Engineering (2000)