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:
-
SER_INVALID_PORT - port number specified is out of valid range
-
SER_INVALID_BIT - bit number specified is out of valid range
-
SER_INVALID_EVENTID - specified event ID is invalid; event ID's
cannot be negative. They must be positive
numbers
-
SER_WRONG_PORTMODE - current mode of the port prohibits events
from being registered; events cannot be
registered on an analog port
-
SER_EVENT_CONFLICT - A bit event cannot be registered on the same
port as a byte event. Note however that this
error is not returned when a byte event is
registered when a bit event has already been
registered on a port. Instead, the byte event
simply overrides the bit event(s); the bit events
are silently discarded.
-
SER_INVALID_HANDLE - returned if a NULL pointer was passed for the handle
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