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