Open Ethernet Networking (OpEN) API Guide and Reference Manual  3.6.0.3
Routing Configuration and State

This RPPI service serves applications that require access to the ICOS router configuration and state, both global and per-interface. The service includes RPC APIs an application can call to get current routing configuration and state and events that RPPI sends to notify applications of changes.

Router Configuration and State APIs

This service includes RPC APIs to do the following:

Router Events

Changes to router configuration and state are called router events. An application can register to receive router events using the following RPC API:

open_error_t openapiRouterEventRegister(OPEN_AF_t af, uint32_t pid, open_buffdesc *clientName, uint32_t *clientId);

The application calls the registration API once for each address family it is interested in. The RPC call returns a client ID as an output parameter. A separate API is provided to deregister from this service. After registering through the RPC API, the application opens a UNIX datagram socket and binds to /tmp/rppi_rec.<client-id>.

RPPI maintains a router event list for each address family (IPv4 and IPv6) per registered application.

When the routing configuration or state changes, RPPI sends a message over its UNIX socket to each registered application for the address family of the event. Router event messages have the following format:

        0                   1                   2                   3
        0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |   Message Type                |         Message Length        |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |                  Sequence Number                              |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |                  Internal Interface Number                    |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Applications can use RPC APIs to get the interface name, interface type, or IP stack interface index for a given internal interface number. The Internal Interface Number field is only included in messages for interface-specific events.

Router Event Type Codes

Acknowledging Router Events

Applications are required to acknowledge router events. If an application does not respond to an event within 10 seconds, RPPI deregisters the application for all address families and closes the application's socket, and responds to IP MAP as if the application had responded. An application acknowledges a router event by calling an RPC API:

open_error_t openapiRouterEventAcknowledge(uint32_t clientId, uint32_t eventId);

If an application deregisters while RPPI has outstanding events unacknowledged by the application, RPPI immediately considers the application to have acknowledged the outstanding events.

Querying Initial Routing Configuration and Status

An application only receives router events that occur after it has registered. To get a baseline of interface state, an application must first register for router events, then iterate through the current set of routing interfaces using the RPC API openapiRtrIntfNextGet(). For each routing interface, the application gets the current state and configuration using the other RPC APIs for interfaces.