Zephyr OS Network Events: Match the Layer and Interface Before Changing Connection State

A network event is not a device-wide Boolean saying that every connection is ready or unavailable. In a multi-interface application, the same event category can refer to different interfaces. An incorrectly constructed event mask can also prevent the expected callback from running. Check both selection and identity before wiring notifications into a reconnect state machine.

The implementation reviewed here is Zephyr 4.4.0's network management subsystem. The proposed state model is illustrative; it does not establish internet reachability or test a particular network driver.

Do not combine unrelated layers into one mask

The tagged network management header documents that only the command portion of an event value is treated as a mask. Layer and layer code require an exact match. Receiving events from multiple layers therefore requires multiple listeners. The callback receives the actual event and its interface, or NULL for an event that is not interface-specific.

When subscribing to several event types, first group them by their documented layer and layer code. Do not assume that bitwise-OR of every desired constant produces a universal subscription. A compact expression can look plausible in code review while encoding a layer combination that no emitted event matches.

Keep each subscription's purpose visible. One handler may track interface lifecycle while another tracks a distinct protocol event family. They can feed a common application state machine, but their registration should preserve the event encoding rules.

Apply the event to the interface that generated it

The tagged dispatch implementation checks layer and layer code equality before command matching, then passes the emitted interface to ordinary callbacks. Its interface-specific synchronous wait additionally compares the requested interface with the event's interface.

For a hypothetical device with Ethernet and a cellular backup, an Ethernet loss should not automatically overwrite the cellular interface's state. Store observations per interface and derive the application's chosen connection policy from those states. Keep a global summary only if its meaning is explicit, such as whether any eligible path is currently selected.

Handle NULL according to the event's contract. Do not turn it into the default interface merely to avoid a branch. That substitution changes an event without interface identity into an assertion about a specific interface.

Separate an observation from the next connection action

An event can justify reevaluating a connection, but the action may need more context. Associate delayed reconnect work with the interface and generation of state that caused it. Before acting, confirm that the request still applies; a later event may have superseded it.

Consider a hypothetical down-then-up sequence arriving while a reconnect task is queued. If the task carries only a global “offline” flag, it can tear down a healthy replacement connection after state has already changed. Capturing the relevant interface and validating current state makes that decision reviewable.

This article does not prescribe that one network-management event proves end-to-end service availability. Address assignment, routing and application session establishment have their own requirements. Use the specific event's meaning rather than expanding it into a broader guarantee.

Copy event information before deferring its use

When event information is enabled, inspect its expected type and supplied length before reading it. Copy the fields needed by deferred application work into owned storage. In the inspected implementation, queued event information belongs to event-dispatch storage, while the nonqueued path can refer to the notifying caller's data. Neither is a basis for retaining an unqualified pointer indefinitely.

Test subscriptions separately from policy. First confirm that each expected event family reaches the correct listener with the intended interface. Then exercise two interfaces changing state in opposite directions and a delayed action overtaken by a newer event.

The integration is ready when every state transition can be traced to an exact event and interface, and listeners are registered with valid layer-specific masks. That removes two preventable causes of unreliable reconnect behavior without guessing at network conditions from a single global flag.