Open Ethernet Networking (OpEN) API Guide and Reference Manual  3.6.0.3
Events

Overview

Applications can register with the NOS main process to receive notifications when various events occur. This allows an application process to avoid polling for changes in the switch's state. Applications register for categories of events that are of interest. Examples of event categories are interface events and VLAN events. Samples of how an application interfaces with the event notification mechanism may be found in the example applications in the "events" directory.

It should be noted that the RPPI part of the OpEN API has an event notification mechanism that is distinct from the one discussed here. Please refer to Routing Protocol Process Interface (RPPI) for information about RPPI events.

Registering for Event Notification

Applications register for events by calling openapiEventRegister(). This function takes a parameter that lists the event categories for which the application is registering. The application need only to register for the events it requires.

The event categories are selected using the members of the enum OPEN_EVENT_e and the macro OPEN_EVENT_SET().

Receiving Event Notifications

After event registration, an application receives event notifications by calling openapiPendingEventsGet(). In order to only call this function only when events are available for retrieval, applications can block on a call to openapiEventWait() or on a call to select().

Waiting for Events Using openapiEventWait()

The application process can call openapiEventWait() with a timeout value. This call will return when events are available or when the specified time has expired. This method is useful when the application thread is blocking only on OpEN events.

This method is illustrated in the example application link_status_example.c.

Waiting for Events Using select()

Applications can call select() with the file descriptor associated with the OpEN event subsystem. This file descriptor is retrieved by calling openapiClientNotifySocketFDGet(). The file descriptor is then added to the fd_set used to call select(). This method is useful when the application wants to wait on events from OpEN as well as events from other parts of the system (by also adding those file descriptors to the fd_set).

This method is illustrated in the example application vlan_status_example.c.

Receiving Event Notifications

Information about the events for the application are retrieved by calling openapiPendingEventsGet(). This returns two pieces of information for each registered event category. These are:

These masks are tested using the OPEN_EVENT_IS_SET() macro for event categories. If the flag is set, the application retrieves state information about items in the event category to process the change or purge event.

Change Notification

When notified that a change has occurred, the application iterates over the change records using function calls provided in each category. Examples of these functions are openapiVlanNextChangedGet() and openapiIfNextChangedGet(). These return the index of the change event that has changed. In these cases the indices are the VLAN ID and the interface number, respectively. Using these indices, the application retrieves status of interest by calling the various "get" functions.

Purge Notification

Receiving notification that a purge is required indicates that the application should validate any saved state received from the NOS process for an event category. This can occur when an event was not delivered to the application. Handling this notification usually involves the application iterating through its tables and calling "get" functions to retrieve state for each entry.