Line data Source code
1 1 : /** @file
2 : * @brief DHCPv4 Client Handler
3 : */
4 :
5 : /*
6 : * Copyright (c) 2016 Intel Corporation
7 : *
8 : * SPDX-License-Identifier: Apache-2.0
9 : */
10 :
11 : #ifndef ZEPHYR_INCLUDE_NET_DHCPV4_H_
12 : #define ZEPHYR_INCLUDE_NET_DHCPV4_H_
13 :
14 : #include <zephyr/sys/slist.h>
15 : #include <zephyr/types.h>
16 :
17 : #ifdef __cplusplus
18 : extern "C" {
19 : #endif
20 :
21 : /**
22 : * @brief DHCPv4
23 : * @defgroup dhcpv4 DHCPv4
24 : * @since 1.7
25 : * @version 0.8.0
26 : * @ingroup networking
27 : * @{
28 : */
29 :
30 : /** @cond INTERNAL_HIDDEN */
31 :
32 : /** Current state of DHCPv4 client address negotiation.
33 : *
34 : * Additions removals and reorders in this definition must be
35 : * reflected within corresponding changes to net_dhcpv4_state_name.
36 : */
37 : enum net_dhcpv4_state {
38 : NET_DHCPV4_DISABLED,
39 : NET_DHCPV4_INIT,
40 : NET_DHCPV4_INIT_REBOOT,
41 : NET_DHCPV4_SELECTING,
42 : NET_DHCPV4_REQUESTING,
43 : NET_DHCPV4_RENEWING,
44 : NET_DHCPV4_REBINDING,
45 : NET_DHCPV4_BOUND,
46 : NET_DHCPV4_DECLINE,
47 : } __packed;
48 :
49 : /** @endcond */
50 :
51 : /**
52 : * @brief DHCPv4 message types
53 : *
54 : * These enumerations represent RFC2131 defined msy type codes, hence
55 : * they should not be renumbered.
56 : *
57 : * Additions, removald and reorders in this definition must be reflected
58 : * within corresponding changes to net_dhcpv4_msg_type_name.
59 : */
60 1 : enum net_dhcpv4_msg_type {
61 : NET_DHCPV4_MSG_TYPE_DISCOVER = 1, /**< Discover message */
62 : NET_DHCPV4_MSG_TYPE_OFFER = 2, /**< Offer message */
63 : NET_DHCPV4_MSG_TYPE_REQUEST = 3, /**< Request message */
64 : NET_DHCPV4_MSG_TYPE_DECLINE = 4, /**< Decline message */
65 : NET_DHCPV4_MSG_TYPE_ACK = 5, /**< Acknowledge message */
66 : NET_DHCPV4_MSG_TYPE_NAK = 6, /**< Negative acknowledge message */
67 : NET_DHCPV4_MSG_TYPE_RELEASE = 7, /**< Release message */
68 : NET_DHCPV4_MSG_TYPE_INFORM = 8, /**< Inform message */
69 : };
70 :
71 : struct net_dhcpv4_option_callback;
72 :
73 : /**
74 : * @typedef net_dhcpv4_option_callback_handler_t
75 : * @brief Define the application callback handler function signature
76 : *
77 : * @param cb Original struct net_dhcpv4_option_callback owning this handler
78 : * @param length The length of data returned by the server. If this is
79 : * greater than cb->max_length, only cb->max_length bytes
80 : * will be available in cb->data
81 : * @param msg_type Type of DHCP message that triggered the callback
82 : * @param iface The interface on which the DHCP message was received
83 : *
84 : * Note: cb pointer can be used to retrieve private data through
85 : * CONTAINER_OF() if original struct net_dhcpv4_option_callback is stored in
86 : * another private structure.
87 : */
88 1 : typedef void (*net_dhcpv4_option_callback_handler_t)(struct net_dhcpv4_option_callback *cb,
89 : size_t length,
90 : enum net_dhcpv4_msg_type msg_type,
91 : struct net_if *iface);
92 :
93 : /** @cond INTERNAL_HIDDEN */
94 :
95 : /**
96 : * @brief DHCP option callback structure
97 : *
98 : * Used to register a callback in the DHCPv4 client callback list.
99 : * As many callbacks as needed can be added as long as each of them
100 : * are unique pointers of struct net_dhcpv4_option_callback.
101 : * Beware such structure should not be allocated on stack.
102 : *
103 : * Note: To help setting it, see net_dhcpv4_init_option_callback() below
104 : */
105 : struct net_dhcpv4_option_callback {
106 : /** This is meant to be used internally and the user should not
107 : * mess with it.
108 : */
109 : sys_snode_t node;
110 :
111 : /** Actual callback function being called when relevant. */
112 : net_dhcpv4_option_callback_handler_t handler;
113 :
114 : /** The DHCP option this callback is attached to. */
115 : uint8_t option;
116 :
117 : /** Maximum length of data buffer. */
118 : size_t max_length;
119 :
120 : /** Pointer to a buffer of size max_length that is used to store the
121 : * option data.
122 : */
123 : void *data;
124 : };
125 :
126 : /** @endcond */
127 :
128 : /**
129 : * @brief Helper to initialize a struct net_dhcpv4_option_callback properly
130 : * @param callback A valid Application's callback structure pointer.
131 : * @param handler A valid handler function pointer.
132 : * @param option The DHCP option the callback responds to.
133 : * @param data A pointer to a buffer for max_length bytes.
134 : * @param max_length The maximum length of the data returned.
135 : */
136 1 : static inline void net_dhcpv4_init_option_callback(struct net_dhcpv4_option_callback *callback,
137 : net_dhcpv4_option_callback_handler_t handler,
138 : uint8_t option,
139 : void *data,
140 : size_t max_length)
141 : {
142 : __ASSERT(callback, "Callback pointer should not be NULL");
143 : __ASSERT(handler, "Callback handler pointer should not be NULL");
144 : __ASSERT(data, "Data pointer should not be NULL");
145 :
146 : callback->handler = handler;
147 : callback->option = option;
148 : callback->data = data;
149 : callback->max_length = max_length;
150 : }
151 :
152 : /**
153 : * @brief Add an application callback.
154 : * @param cb A valid application's callback structure pointer.
155 : * @return 0 if successful, negative errno code on failure.
156 : */
157 1 : int net_dhcpv4_add_option_callback(struct net_dhcpv4_option_callback *cb);
158 :
159 : /**
160 : * @brief Remove an application callback.
161 : * @param cb A valid application's callback structure pointer.
162 : * @return 0 if successful, negative errno code on failure.
163 : */
164 1 : int net_dhcpv4_remove_option_callback(struct net_dhcpv4_option_callback *cb);
165 :
166 : /**
167 : * @brief Helper to initialize a struct net_dhcpv4_option_callback for encapsulated vendor-specific
168 : * options properly
169 : * @param callback A valid Application's callback structure pointer.
170 : * @param handler A valid handler function pointer.
171 : * @param option The DHCP encapsulated vendor-specific option the callback responds to.
172 : * @param data A pointer to a buffer for max_length bytes.
173 : * @param max_length The maximum length of the data returned.
174 : */
175 : static inline void
176 1 : net_dhcpv4_init_option_vendor_callback(struct net_dhcpv4_option_callback *callback,
177 : net_dhcpv4_option_callback_handler_t handler, uint8_t option,
178 : void *data, size_t max_length)
179 : {
180 : __ASSERT(callback, "Callback pointer should not be NULL");
181 : __ASSERT(handler, "Callback handler pointer should not be NULL");
182 : __ASSERT(data, "Data pointer should not be NULL");
183 :
184 : callback->handler = handler;
185 : callback->option = option;
186 : callback->data = data;
187 : callback->max_length = max_length;
188 : }
189 :
190 : /**
191 : * @brief Add an application callback for encapsulated vendor-specific options.
192 : * @param cb A valid application's callback structure pointer.
193 : * @return 0 if successful, negative errno code on failure.
194 : */
195 1 : int net_dhcpv4_add_option_vendor_callback(struct net_dhcpv4_option_callback *cb);
196 :
197 : /**
198 : * @brief Remove an application callback for encapsulated vendor-specific options.
199 : * @param cb A valid application's callback structure pointer.
200 : * @return 0 if successful, negative errno code on failure.
201 : */
202 1 : int net_dhcpv4_remove_option_vendor_callback(struct net_dhcpv4_option_callback *cb);
203 :
204 : /**
205 : * @brief Start DHCPv4 client on an iface
206 : *
207 : * @details Start DHCPv4 client on a given interface. DHCPv4 client
208 : * will start negotiation for IPv4 address. Once the negotiation is
209 : * success IPv4 address details will be added to interface.
210 : *
211 : * @param iface A valid pointer on an interface
212 : */
213 1 : void net_dhcpv4_start(struct net_if *iface);
214 :
215 : /**
216 : * @brief Stop DHCPv4 client on an iface
217 : *
218 : * @details Stop DHCPv4 client on a given interface. DHCPv4 client
219 : * will remove all configuration obtained from a DHCP server from the
220 : * interface and stop any further negotiation with the server.
221 : *
222 : * @param iface A valid pointer on an interface
223 : */
224 1 : void net_dhcpv4_stop(struct net_if *iface);
225 :
226 : /**
227 : * @brief Restart DHCPv4 client on an iface
228 : *
229 : * @details Restart DHCPv4 client on a given interface. DHCPv4 client
230 : * will restart the state machine without any of the initial delays
231 : * used in start.
232 : *
233 : * @param iface A valid pointer on an interface
234 : */
235 1 : void net_dhcpv4_restart(struct net_if *iface);
236 :
237 : /** @cond INTERNAL_HIDDEN */
238 :
239 : /**
240 : * @brief DHCPv4 state name
241 : *
242 : * @internal
243 : */
244 : const char *net_dhcpv4_state_name(enum net_dhcpv4_state state);
245 :
246 : /** @endcond */
247 :
248 : /**
249 : * @brief Return a text representation of the msg_type
250 : *
251 : * @param msg_type The msg_type to be converted to text
252 : * @return A text representation of msg_type
253 : */
254 1 : const char *net_dhcpv4_msg_type_name(enum net_dhcpv4_msg_type msg_type);
255 :
256 : /**
257 : * @}
258 : */
259 :
260 : #ifdef __cplusplus
261 : }
262 : #endif
263 :
264 : #endif /* ZEPHYR_INCLUDE_NET_DHCPV4_H_ */
|
