There are a few data structures defined by the API that are passed to or from functions. Each is described below.
The eth32_event structure holds all of the information about an event that has fired. It is passed from the API to your code when information about an event is retrieved, for example, with the eth32_dequeue_event function.
typedef struct { int id; int type; int port; int bit; int prev_value; int value; int direction; } eth32_event;
id - The user-assigned event ID that you gave this event when enabling it.
type - Event type, as defined by the constants EVENT_DIGITAL, EVENT_ANALOG, EVENT_COUNTER_ROLLOVER, EVENT_COUNTER_THRESHOLD, and EVENT_HEARTBEAT.
port - For digital events, this specifies the port number the event occurred on. For analog events, it specifies the event bank number (0 or 1), and for counter events, it specifies which counter the event occurred on.
bit - For a digital bit event, this specifies the bit number that changed. For an analog event, it specifies the analog channel, and for a digital port event, this will be -1.
prev_value - The old value of the bit, port, or analog channel (as appropriate) before the event fired.
value - The new value of the bit, port, or analog channel that caused the event to fire. In the case of counter events, this indicates the number of times the event occurred since the last time this event was fired (almost always 1).
direction - Indicates whether the new value of the bit, port, or channel is greater or less than the previous value. It is 1 for greater than or -1 for less than.
The eth32_handler structure is used to specify how events should be handled when they occur.
typedef struct { int type; int maxqueue; int fullqueue; eth32_eventfn eventfn; void *extra; HWND window; unsigned int msgid; WPARAM wparam; LPARAM lparam; } eth32_handler;
type - Specifies how events should be handled and received by your code. It can be any of the following:
HANDLER_NONE - Your code will not be notified of new events. However, you may still receive event information by using the event queue functions.
HANDLER_CALLBACK - A callback function written and specified by you will be called whenever an event occurs. All of the data pertaining to the event will be passed to your callback function.
HANDLER_MESSAGE - For Windows platforms only. A Windows message that you specify will be sent to the window that you specify whenever an event occurs. No event data is included with the windows message. Therefore, this option should be used along with the event queue functions in order to actually receive the event data. In other words, the Windows message indicates that you should check the event queue for new events.
The best option is usually determined by how and where you wish to receive event information in your program's code. If you are using a programming language that does not handle multiple threads well, you should not use the callback handler, since your callback function is called from a separate thread.
maxqueue - Applies only to HANDLER_CALLBACK. If a callback function takes a while to finish executing and more events are received during that time, they are queued up by the API. This specifies the maximum number of events that are allowed to be queued.
fullqueue - Applies only to HANDLER_CALLBACK. If the queue is already full and more events arrive, this specifies what to do. QUEUE_DISCARD_NEW specifies that the newly arriving events will be discarded if the queue is full. QUEUE_DISCARD_OLD specifies that the oldest events in the queue should be discarded and shifted out to make room for the new events at the end of the queue.
eventfn - Applies only to HANDLER_CALLBACK. Specifies the address of your callback function. See the Event Callback Function section for more information about the callback function.
extra - Applies only to HANDLER_CALLBACK. Whatever value is specified here will be passed to the "extra" parameter of the callback function whenever it is called. It may be any value you choose.
window - Applies only to HANDLER_MESSAGE. Specifies the handle of the window to which a message should be sent when an event occurs.
msgid - Applies only to HANDLER_MESSAGE. Specifies the message ID that should be sent. For example, WM_COMMAND.
wparam - Applies only to HANDLER_MESSAGE. Specifies the wparam message parameter that should be sent.
lparam - Applies only to HANDLER_MESSAGE. Specifies the lparam message parameter that should be sent.