int eth32_enable_event(eth32 handle, int type, int port, int bit, int id);
This function enables reception of the specified event on the current connection. The ETH32 device only sends event notifications to those connections that specifically request them, so this function requests notification for the specified event from the device, as well as internally assigns the event an ID number provided by you.
handle - The value returned by the eth32_open function.
type - The type of event to enable. The valid event types are:
EVENT_DIGITAL - Digital I/O event. This includes port events and bit events.
EVENT_ANALOG - Analog event based on thresholds defined with the eth32_set_analog_eventdef function.
EVENT_COUNTER_ROLLOVER - Counter rollover event, which occurs when the counter rolls over to zero.
EVENT_COUNTER_THRESHOLD - Counter threshold event, which occurs when the counter passes a threshold defined with eth32_set_counter_threshold.
EVENT_HEARTBEAT - Periodic event sent by the device to indicate the TCP/IP connection is still good.
port - For digital events, specifies the port number, for analog events, specifies the bank number, and for either counter event, specifies the counter number.
bit - For digital events, this should be -1 for port events or the bit number (0-7) for bit events. For analog events, this specifies the analog channel number (0-7).
id - You may specify any number to be associated with this event.
This function returns zero on success and a negative error code on failure. Please see the Error Codes section for possible error codes.
The id parameter allows you to assign any arbitrary number to this particular event. The ID you assign is included with the event information whenever this event fires. The idea is that you can identify a particular event with a single comparison rather than needing to inspect several pieces of data such as the event type, port number, and bit number. The ID number is completely arbitrary and multiple events may be given the same ID number if desired. The ID numbers are stored within the API and are not sent to the ETH32 device.
One other minor technicality is that the heartbeat event is permanently enabled on the ETH32 device itself for purposes of connection maintenance. Therefore, for the heartbeat event, this function simply enables the event within the API, meaning that when the event comes in, rather than being discarded it will be added to the event queue (if it is enabled) and handled by the configured event handler. The one small side-effect to this fact is that if you have enabled reception of the heartbeat event and another connection calls eth32_reset, you will continue to receive heartbeat events, whereas all other event types will have been disabled on the device itself. Note that if you call eth32_reset on your own connection, it automatically disables the heartbeat event within the API for your connection, so in that case it is not an issue.
eth32 handle; int result; eth32_event event_info; // .... Your code that establishes a connection here // This example shows using the event queue to receive events ... // you could use a callback function instead. // Enable the event queue result=eth32_set_event_queue_config(handle, 1000, QUEUE_DISCARD_NEW); if(result) { // handle error } // Enable an event that will fire whenever port 2, bit 5 changes state // Assign it an arbitrary ID of 1000 result=eth32_enable_event(handle, EVENT_DIGITAL, 2, 5, 1000); if(result) { // handle error } // Enable the rollover event on Counter 0 // Assign it an arbitrary ID of 1001 result=eth32_enable_event(handle, EVENT_COUNTER_ROLLOVER, 0, 0, 1001); if(result) { // handle error } // Somewhere later in your code .... you want to process any events in the // queue. Do not wait at all for events - just process the ones already // in the queue. eth32_dequeue_event will return zero as long as there // was an event in the queue. while( (result=eth32_dequeue_event(handle, &event_info, 0)) == 0 ) { switch(event_info.id) { case 1000: printf("Port 2 bit 5 has changed to have value %d\n", event_info.value); break; case 1001: printf("Counter 0 has rolled over %d times " "since we last received this event.\n", event_info.value); break; } }