1.. _net_mgmt_interface:
2
3Network Management
4##################
5
6.. contents::
7    :local:
8    :depth: 2
9
10Overview
11********
12
13The Network Management APIs allow applications, as well as network
14layer code itself, to call defined network routines at any level in
15the IP stack, or receive notifications on relevant network events. For
16example, by using these APIs, application code can request a scan be done on a
17Wi-Fi- or Bluetooth-based network interface, or request notification if
18a network interface IP address changes.
19
20The Network Management API implementation is designed to save memory
21by eliminating code at build time for management routines that are not
22used. Distinct and statically defined APIs for network management
23procedures are not used.  Instead, defined procedure handlers are
24registered by using a :c:macro:`NET_MGMT_REGISTER_REQUEST_HANDLER`
25macro. Procedure requests are done through a single :c:func:`net_mgmt` API
26that invokes the registered handler for the corresponding request.
27
28The current implementation is experimental and may change and improve
29in future releases.
30
31Requesting a defined procedure
32******************************
33
34All network management requests are of the form
35``net_mgmt(mgmt_request, ...)``. The ``mgmt_request`` parameter is a bit
36mask that tells which stack layer is targeted, if a ``net_if`` object is
37implied, and the specific management procedure being requested. The
38available procedure requests depend on what has been implemented in
39the stack.
40
41To avoid extra cost, all :c:func:`net_mgmt` calls are direct. Though this
42may change in a future release, it will not affect the users of this
43function.
44
45.. _net_mgmt_listening:
46
47Listening to network events
48***************************
49
50You can receive notifications on network events by registering a
51callback function and specifying a set of events used to filter when
52your callback is invoked. The callback will have to be unique for a
53pair of layer and code, whereas on the command part it will be a mask of
54events.
55
56At runtime two functions are available, :c:func:`net_mgmt_add_event_callback`
57for registering the callback function, and :c:func:`net_mgmt_del_event_callback`
58for unregistering a callback. A helper function,
59:c:func:`net_mgmt_init_event_callback`, can
60be used to ease the initialization of the callback structure.
61
62Additionally :c:macro:`NET_MGMT_REGISTER_EVENT_HANDLER` can be used to
63register a callback handler at compile time.
64
65When an event occurs that matches a callback's event set, the
66associated callback function is invoked with the actual event
67code. This makes it possible for different events to be handled by the
68same callback function, if desired.
69
70.. warning::
71
72   Event set filtering allows false positives for events that have the same
73   layer and layer code.  A callback handler function **must** check
74   the event code (passed as an argument) against the specific network
75   events it will handle, **regardless** of how many events were in the
76   set passed to :c:func:`net_mgmt_init_event_callback`.
77
78   Note that in order to receive events from multiple layers, one must have
79   multiple listeners registered, one for each layer being listened.
80   The callback handler function can be shared between different layer events.
81
82   (False positives can occur for events which have the same layer and
83   layer code.)
84
85An example follows.
86
87.. code-block:: c
88
89	/*
90	 * Set of events to handle.
91	 * See e.g. include/net/net_event.h for some NET_EVENT_xxx values.
92	 */
93	#define EVENT_IFACE_SET (NET_EVENT_IF_xxx | NET_EVENT_IF_yyy)
94	#define EVENT_IPV4_SET (NET_EVENT_IPV4_xxx | NET_EVENT_IPV4_yyy)
95
96	struct net_mgmt_event_callback iface_callback;
97	struct net_mgmt_event_callback ipv4_callback;
98
99	void callback_handler(struct net_mgmt_event_callback *cb,
100			      uint32_t mgmt_event,
101			      struct net_if *iface)
102	{
103		if (mgmt_event == NET_EVENT_IF_xxx) {
104			/* Handle NET_EVENT_IF_xxx */
105		} else if (mgmt_event == NET_EVENT_IF_yyy) {
106			/* Handle NET_EVENT_IF_yyy */
107		} else if (mgmt_event == NET_EVENT_IPV4_xxx) {
108			/* Handle NET_EVENT_IPV4_xxx */
109		} else if (mgmt_event == NET_EVENT_IPV4_yyy) {
110			/* Handle NET_EVENT_IPV4_yyy */
111		} else {
112			/* Spurious (false positive) invocation. */
113		}
114	}
115
116	void register_cb(void)
117	{
118		net_mgmt_init_event_callback(&iface_callback, callback_handler,
119					     EVENT_IFACE_SET);
120		net_mgmt_init_event_callback(&ipv4_callback, callback_handler,
121					     EVENT_IPV4_SET);
122		net_mgmt_add_event_callback(&iface_callback);
123		net_mgmt_add_event_callback(&ipv4_callback);
124	}
125
126Or similarly using :c:macro:`NET_MGMT_REGISTER_EVENT_HANDLER`.
127
128.. note::
129
130   The ``info`` and ``info_length`` arguments are only usable if
131   :kconfig:option:`CONFIG_NET_MGMT_EVENT_INFO` is enabled. Otherwise these are
132   ``NULL`` and zero.
133
134.. code-block:: c
135
136	/*
137	 * Set of events to handle.
138	 */
139	#define EVENT_IFACE_SET (NET_EVENT_IF_xxx | NET_EVENT_IF_yyy)
140	#define EVENT_IPV4_SET (NET_EVENT_IPV4_xxx | NET_EVENT_IPV4_yyy)
141
142	static void event_handler(uint32_t mgmt_event, struct net_if *iface,
143				  void *info, size_t info_length,
144				  void *user_data)
145	{
146		if (mgmt_event == NET_EVENT_IF_xxx) {
147			/* Handle NET_EVENT_IF_xxx */
148		} else if (mgmt_event == NET_EVENT_IF_yyy) {
149			/* Handle NET_EVENT_IF_yyy */
150		} else if (mgmt_event == NET_EVENT_IPV4_xxx) {
151			/* Handle NET_EVENT_IPV4_xxx */
152		} else if (mgmt_event == NET_EVENT_IPV4_yyy) {
153			/* Handle NET_EVENT_IPV4_yyy */
154		} else {
155			/* Spurious (false positive) invocation. */
156		}
157	}
158
159	NET_MGMT_REGISTER_EVENT_HANDLER(iface_event_handler, EVENT_IFACE_SET,
160					event_handler, NULL);
161	NET_MGMT_REGISTER_EVENT_HANDLER(ipv4_event_handler, EVENT_IPV4_SET,
162					event_handler, NULL);
163
164See :zephyr_file:`include/zephyr/net/net_event.h` for available generic core events that
165can be listened to.
166
167
168Defining a network management procedure
169***************************************
170
171You can provide additional management procedures specific to your
172stack implementation by defining a handler and registering it with an
173associated mgmt_request code.
174
175Management request code are defined in relevant places depending on
176the targeted layer or eventually, if l2 is the layer, on the
177technology as well. For instance, all IP layer management request code
178will be found in the :zephyr_file:`include/zephyr/net/net_event.h` header file. But in case
179of an L2 technology, let's say Ethernet, these would be found in
180:zephyr_file:`include/zephyr/net/ethernet.h`
181
182You define your handler modeled with this signature:
183
184.. code-block:: c
185
186   static int your_handler(uint32_t mgmt_event, struct net_if *iface,
187                           void *data, size_t len);
188
189and then register it with an associated mgmt_request code:
190
191.. code-block:: c
192
193   NET_MGMT_REGISTER_REQUEST_HANDLER(<mgmt_request code>, your_handler);
194
195This new management procedure could then be called by using:
196
197.. code-block:: c
198
199   net_mgmt(<mgmt_request code>, ...);
200
201
202Signaling a network event
203*************************
204
205You can signal a specific network event using the :c:func:`net_mgmt_event_notify`
206function and provide the network event code. See
207:zephyr_file:`include/zephyr/net/net_mgmt.h` for details. As for the management request
208code, event code can be also found on specific L2 technology mgmt headers,
209for example :zephyr_file:`include/zephyr/net/ieee802154_mgmt.h` would be the right place if
210802.15.4 L2 is the technology one wants to listen to events.
211
212API Reference
213*************
214
215.. doxygengroup:: net_mgmt
216