Programming Interfaces Guide

Event Registration

Just as the handling of instances and protocols is dynamic, the handling of the events that live under each protocol also is dynamic. Two types of events are supported by this API: network interface events and packet events.

In the function below, the announcement for the presence of the event for inbound packets for IPv4 is being checked for. When that announcement is seen, a hook_t structure is allocated, describing the function to be called for each inbound IPv4 packet.

static int
mynewevent(hook_notify_cmd_t cmd, void *arg, const char *parent,
    const char *event, const char *hook)
{
    mytype_t *ctx = arg;
    char buffer[32];
    hook_t *h;

    if ((strcmp(event, NH_PHYSICAL_IN) == 0) &&
        (strcmp(parent, NHF_INET) == 0)) {
            sprintf(buffer, "mypkthook_%s_%s", parent, event);
            h = hook_alloc(HOOK_VERSION);
            h->h_hint = HH_NONE;
            h->h_arg = s;
            h->h_name = strdup(buffer);
            h->h_func = mypkthook;
            s->hook_in = h;
            net_hook_register(ctx->inet, (char *)event, h);
    } else {
            h = NULL;
    }
    return (0);
}

The function mynewevent() will be called for each event that is added and removed. The following events are available.

Event Name	Data Structure	Comment
NH_PHYSICAL_IN	hook_pkt_event_t	This event is generated for every packet that arrives at the network protocol and has been received from a network interface driver.
NH_PHYSICAL_OUT	hook_pkt_event_t	This event is generated for every packet prior to delivery to the network interface driver for sending from the network protocol layer.
NH_FORWARDING	hook_pkt_event_t	This event is for all packets that have been received by the system and will be sent out another network interface. This event happens after NH_PHYSICAL_IN and before NH_PHYSICAL_OUT.
NH_LOOPBACK_IN	hook_pkt_event_t	This event is generated for packets that are received on the loopback interface or that are received by a zone that is sharing its network instance with the global zone.
NH_LOOPBACK_OUT	hook_pkt_event_t	This event is generated for packets that are sent on the loopback interface or that are being sent by a zone that is sharing its network instance with the global zone.
NH_NIC_EVENTS	hook_nic_event_t	This event is generated for specific changes of state for network interfaces.

For packet events, there is one specific event for each particular point in the IP stack. This is to enable you to be selective about exactly where in the flow of the packets you wish to intercept packets, without being overburdened by examining every packet event that happens inside the kernel. For network interface events the model is different, in part because the events are much lower in volume and because it is more likely that the developer will be interested in several of them, not just one.

The network interface event announces one of the following events:

An interface is created (NE_PLUMB) or destroyed (NE_UNPLUMB).
An interface changes state to up (NE_UP) or down (NE_DOWN).
An interface has an address change (NE_ADDRESS_CHANGE).

New network interface events could be added in the future, so you must always return 0 for any unknown or unrecognized event that the callback function receives.