Event Callback Function

If you wish to use a callback function to handle events, you must write a callback event handler function in your code and instruct the API to call your function whenever an event arrives. You instruct the API to do this by setting up a callback event handler with the eth32_set_event_handler function.

The callback function is a function written by you, the programmer. Because it is a function you write, you have complete freedom to inspect whichever aspects of the event data you need to and react however you see fit.

Your callback function will be executed by a separate thread. You should be aware of this fact if you will be doing any tasks in your callback that are not thread safe. The API waits for your callback to return before calling it again with the next event. Therefore, be aware that if you perform any long operations within the callback, it will delay more events from being processed. Note that each connection handle has its own event thread, so if you are using a single callback function for multiple connections, be aware that at times there may be more than one instance of your callback function executing.

Callback Prototype and Parameters

Your callback function may be given any name, but regardless of its name, it must have one of the following prototypes, depending on your platform.

On Windows, you must use the standard calling convention (stdcall) as follows:

void __stdcall your_function_name(eth32 handle, eth32_event *event, void *extra);

On Linux, no calling convention modifier is needed:

void your_function_name(eth32 handle, eth32_event *event, void *extra);

If your application opens a connection to more than one device, you may still use the same callback function for all connections if you desire. Two parameters are passed to your callback that can be used to differentiate between connections: The handle for the connection on which the event occurred is passed to your function, and the extra member of the eth32_handler structure (as it was passed to the eth32_set_event_handler function) is also passed to your callback.

Of course, your callback is also provided with the details about the event that caused it to fire. The event parameter points to an eth32_event structure containing all of the event information. You should not modify any of the information contained in the structure.

Example

// This code shows an example of how to set up a 
// callback function event handler.

// Somewhere in your code, define a callback function, which may be
// named anything you want.
// On Windows, it must be stdcall calling convention
void __stdcall event_fired(eth32 handle, eth32_event *event, void *extra)
{
	switch(event->id)
	{
		case 1000:
			// React accordingly to Port 1, Bit 3 event
			break;
		case 1001:
			// React accordingly to Port 1, Bit 4 event
			break;
	}
}

         
         
eth32 handle;
int result;
eth32_handler event_handler={0}; // Initialize all data in the structure to zero.

// .... Your code that establishes a connection here

// Set up our callback function as the event handler for this connection
event_handler.type=HANDLER_CALLBACK;
event_handler.maxqueue=1000;
event_handler.fullqueue=QUEUE_DISCARD_NEW;
event_handler.eventfn=event_fired; // Store the address of the callback
result=eth32_set_event_handler(handle, &event_handler);
if(result)
{
	// handle error
}

// Enable events on Port 1, bits 3 and 4
result=eth32_enable_event(handle, EVENT_DIGITAL, 1, 3, 1000);
if(result)
{
	// handle error
}

result=eth32_enable_event(handle, EVENT_DIGITAL, 1, 4, 1001);
if(result)
{
	// handle error
}