cnet's Application Programming Interface

NAME

CNET_set_handler - register function to be called when an event occurs.

SYNOPSIS

#include <cnet.h> int CNET_set_handler(CnetEvent ev, void (*function)(), CnetData data);

DESCRIPTION

CNET_set_handler() registers a function (its address) to be called when one of cnet's events occurs. Calls to CNET_set_handler() will typically be made during the execution of a node's EV_REBOOT handler, to register all handlers for the remainder of the simulation.

Multiple calls may be made to CNET_set_handler() to register the same handler for multiple events. It is then up to the event handler to determine why it was called. Event handlers are properties of each node, and each node may have different handlers for each of the events in which it is interested.

Registering a NULL handler indicates that the calling node has no interest in the indicated event (this is the default).

In most circumstances, a copy of the third parameter, data, is passed as the third parameter to the registered event handler. The most significant exception to this rule is for the timer events, for which each call to CNET_start_timer() provides the data value to be delivered to the event handler.

RETURN VALUE

The value 0 is returned on success. On failure, the value -1 is returned, and the global variable cnet_errno is set to one of the following values to describe the error:

ER_BADEVENT

The first parameter was not a valid cnet event.

ER_NOTSUPPORTED

An attempt was made to register a handler for an event that cannot occur on the current node. Examples include registering a handler for EV_APPLICATIONREADY from nodes without an Application Layer, or registering a handler for EV_KEYBOARDREADY from nodes without a keyboard.

SEE ALSO

CNET_get_handler, CNET_unused_debug_event, CNET_unused_timer_event, and CNET_start_timer.