Events

One of the powerful and useful features of the ETH32 is its event monitoring capabilities. In a nutshell, event monitoring allows the ETH32 to monitor different input signals and send a notification to your application when that signal has changed or met your criteria. Since the monitoring is constantly performed directly by the ETH32, it provides a much better alternative to polling. It provides faster response, is very efficient with network traffic and CPU resources, and is typically much easier to implement in your application.

Notifications of specific events are enabled and disabled on a per-connection basis on the ETH32. This means that each connection may individually select which events it wants to be notified of. This also provides efficient use of network traffic and the processing time of the ETH32. When events are sent from the ETH32 device, they are received on the PC side by the ETH32 API and then passed to your application, allowing your application to react accordingly.

Handling Events in Your Application

Handling events in your application is very easy although there are a few steps that must be performed first depending on your programming language. Essentially you must set up the mechanism that allows the ETH32 API to pass event information to your application whenever events occur.

.NET Languages and Visual Basic 6

In .NET languages and Visual Basic 6, events are handled by your application in a manner very similar to the way that Click events of buttons are handled. In other words, you must write an event handler routine that will be automatically called whenever events occur. If events occur faster than your code is processing them, they will be held in an internal queue. Class members are provided that allow you to configure the maximum size of the queue, to configure the queue behavior if the queue ever becomes full, and to retrieve the current number of events waiting in the queue. Events in the queue cannot be retrieved by calling a member function, but rather they are automatically passed to your event handler routine.

C/C++

In C/C++, there are two separate ways of receiving event data and/or being notified of new events. First, there is an event handler mechanism that you may configure to one of the predefined mechanisms, either a callback or a Windows message. The callback mechanism causes the API to call a function that you have written and pass in all of the information about the event each time an event fires. The Windows message mechanism sends a configurable Windows message to a window that you specify. The Windows message notifies you that an event has occurred, but does not include the information about the event. The second way of receiving event data is the event queue. If enabled, each event is added to the queue along with its event information. Events are stored in the queue until you have a chance to retrieve them. The event queue can be used independently of the event handler, but using them together can be very appropriate for the Windows message event handler. In other words, a Windows message can notify you that an event has occurred, which prompts you to retrieve the event information from the event queue.

The C/C++ function eth32_dequeue_event allows you to efficiently wait for new events to arrive if the event queue is empty. This capability can be used to synchronously wait for and process events, which can be desirable in some situations. Note that since the event handler and the event queue are independent of each other, both will receive a copy of each event that occurs if they are both enabled at the same time. For example, if the event handler is configured with a callback function and the event queue is enabled, both will receive a copy of the event information for each event that fires.

Applicable Functions and Information

TaskC / C++.NET LanguagesVisual Basic 6
Create event handler Event HandlerEvent Handler
Configure event queue
Empty event queueeth32_empty_event_queueEmptyEventQueue MethodEmptyEventQueue Method
Retrieve event from queueeth32_dequeue_eventNot applicableNot applicable