1 /* 2 * SPDX-FileCopyrightText: 2019-2022 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef _ESP_NETIF_H_ 8 #define _ESP_NETIF_H_ 9 10 #include <stdint.h> 11 #include "sdkconfig.h" 12 #include "esp_netif_ip_addr.h" 13 #include "esp_netif_types.h" 14 #include "esp_netif_defaults.h" 15 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 /** 22 * @defgroup ESP_NETIF_INIT_API ESP-NETIF Initialization API 23 * @brief Initialization and deinitialization of underlying TCP/IP stack and esp-netif instances 24 * 25 */ 26 27 /** @addtogroup ESP_NETIF_INIT_API 28 * @{ 29 */ 30 31 /** 32 * @brief Initialize the underlying TCP/IP stack 33 * 34 * @return 35 * - ESP_OK on success 36 * - ESP_FAIL if initializing failed 37 38 * @note This function should be called exactly once from application code, when the application starts up. 39 */ 40 esp_err_t esp_netif_init(void); 41 42 /** 43 * @brief Deinitialize the esp-netif component (and the underlying TCP/IP stack) 44 * 45 * Note: Deinitialization is not supported yet 46 * 47 * @return 48 * - ESP_ERR_INVALID_STATE if esp_netif not initialized 49 * - ESP_ERR_NOT_SUPPORTED otherwise 50 */ 51 esp_err_t esp_netif_deinit(void); 52 53 /** 54 * @brief Creates an instance of new esp-netif object based on provided config 55 * 56 * @param[in] esp_netif_config pointer esp-netif configuration 57 * 58 * @return 59 * - pointer to esp-netif object on success 60 * - NULL otherwise 61 */ 62 esp_netif_t *esp_netif_new(const esp_netif_config_t *esp_netif_config); 63 64 /** 65 * @brief Destroys the esp_netif object 66 * 67 * @param[in] esp_netif pointer to the object to be deleted 68 */ 69 void esp_netif_destroy(esp_netif_t *esp_netif); 70 71 /** 72 * @brief Configures driver related options of esp_netif object 73 * 74 * @param[inout] esp_netif pointer to the object to be configured 75 * @param[in] driver_config pointer esp-netif io driver related configuration 76 * @return 77 * - ESP_OK on success 78 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS if invalid parameters provided 79 * 80 */ 81 esp_err_t esp_netif_set_driver_config(esp_netif_t *esp_netif, 82 const esp_netif_driver_ifconfig_t *driver_config); 83 84 /** 85 * @brief Attaches esp_netif instance to the io driver handle 86 * 87 * Calling this function enables connecting specific esp_netif object 88 * with already initialized io driver to update esp_netif object with driver 89 * specific configuration (i.e. calls post_attach callback, which typically 90 * sets io driver callbacks to esp_netif instance and starts the driver) 91 * 92 * @param[inout] esp_netif pointer to esp_netif object to be attached 93 * @param[in] driver_handle pointer to the driver handle 94 * @return 95 * - ESP_OK on success 96 * - ESP_ERR_ESP_NETIF_DRIVER_ATTACH_FAILED if driver's pot_attach callback failed 97 */ 98 esp_err_t esp_netif_attach(esp_netif_t *esp_netif, esp_netif_iodriver_handle driver_handle); 99 100 /** 101 * @} 102 */ 103 104 /** 105 * @defgroup ESP_NETIF_DATA_IO_API ESP-NETIF Input Output API 106 * @brief Input and Output functions to pass data packets from communication media (IO driver) 107 * to TCP/IP stack. 108 * 109 * These functions are usually not directly called from user code, but installed, or registered 110 * as callbacks in either IO driver on one hand or TCP/IP stack on the other. More specifically 111 * esp_netif_receive is typically called from io driver on reception callback to input the packets 112 * to TCP/IP stack. Similarly esp_netif_transmit is called from the TCP/IP stack whenever 113 * a packet ought to output to the communication media. 114 * 115 * @note These IO functions are registerd (installed) automatically for default interfaces 116 * (interfaces with the keys such as WIFI_STA_DEF, WIFI_AP_DEF, ETH_DEF). Custom interface 117 * has to register these IO functions when creating interface using @ref esp_netif_new 118 * 119 */ 120 121 /** @addtogroup ESP_NETIF_DATA_IO_API 122 * @{ 123 */ 124 125 /** 126 * @brief Passes the raw packets from communication media to the appropriate TCP/IP stack 127 * 128 * This function is called from the configured (peripheral) driver layer. 129 * The data are then forwarded as frames to the TCP/IP stack. 130 * 131 * @param[in] esp_netif Handle to esp-netif instance 132 * @param[in] buffer Received data 133 * @param[in] len Length of the data frame 134 * @param[in] eb Pointer to internal buffer (used in Wi-Fi driver) 135 * 136 * @return 137 * - ESP_OK 138 */ 139 esp_err_t esp_netif_receive(esp_netif_t *esp_netif, void *buffer, size_t len, void *eb); 140 141 /** 142 * @} 143 */ 144 145 /** 146 * @defgroup ESP_NETIF_LIFECYCLE ESP-NETIF Lifecycle control 147 * @brief These APIS define basic building blocks to control network interface lifecycle, i.e. 148 * start, stop, set_up or set_down. These functions can be directly used as event handlers 149 * registered to follow the events from communication media. 150 */ 151 152 /** @addtogroup ESP_NETIF_LIFECYCLE 153 * @{ 154 */ 155 156 /** 157 * @brief Default building block for network interface action upon IO driver start event 158 * Creates network interface, if AUTOUP enabled turns the interface on, 159 * if DHCPS enabled starts dhcp server 160 * 161 * @note This API can be directly used as event handler 162 * 163 * @param[in] esp_netif Handle to esp-netif instance 164 * @param base 165 * @param event_id 166 * @param data 167 */ 168 void esp_netif_action_start(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data); 169 170 /** 171 * @brief Default building block for network interface action upon IO driver stop event 172 * 173 * @note This API can be directly used as event handler 174 * 175 * @param[in] esp_netif Handle to esp-netif instance 176 * @param base 177 * @param event_id 178 * @param data 179 */ 180 void esp_netif_action_stop(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data); 181 182 /** 183 * @brief Default building block for network interface action upon IO driver connected event 184 * 185 * @note This API can be directly used as event handler 186 * 187 * @param[in] esp_netif Handle to esp-netif instance 188 * @param base 189 * @param event_id 190 * @param data 191 */ 192 void esp_netif_action_connected(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data); 193 194 /** 195 * @brief Default building block for network interface action upon IO driver disconnected event 196 * 197 * @note This API can be directly used as event handler 198 * 199 * @param[in] esp_netif Handle to esp-netif instance 200 * @param base 201 * @param event_id 202 * @param data 203 */ 204 void esp_netif_action_disconnected(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data); 205 206 /** 207 * @brief Default building block for network interface action upon network got IP event 208 * 209 * @note This API can be directly used as event handler 210 * 211 * @param[in] esp_netif Handle to esp-netif instance 212 * @param base 213 * @param event_id 214 * @param data 215 */ 216 void esp_netif_action_got_ip(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data); 217 218 /** 219 * @brief Default building block for network interface action upon IPv6 multicast group join 220 * 221 * @note This API can be directly used as event handler 222 * 223 * @param[in] esp_netif Handle to esp-netif instance 224 * @param base 225 * @param event_id 226 * @param data 227 */ 228 void esp_netif_action_join_ip6_multicast_group(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data); 229 230 /** 231 * @brief Default building block for network interface action upon IPv6 multicast group leave 232 * 233 * @note This API can be directly used as event handler 234 * 235 * @param[in] esp_netif Handle to esp-netif instance 236 * @param base 237 * @param event_id 238 * @param data 239 */ 240 void esp_netif_action_leave_ip6_multicast_group(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data); 241 242 /** 243 * @brief Default building block for network interface action upon IPv6 address added by the underlying stack 244 * 245 * @note This API can be directly used as event handler 246 * 247 * @param[in] esp_netif Handle to esp-netif instance 248 * @param base 249 * @param event_id 250 * @param data 251 */ 252 void esp_netif_action_add_ip6_address(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data); 253 254 /** 255 * @brief Default building block for network interface action upon IPv6 address removed by the underlying stack 256 * 257 * @note This API can be directly used as event handler 258 * 259 * @param[in] esp_netif Handle to esp-netif instance 260 * @param base 261 * @param event_id 262 * @param data 263 */ 264 void esp_netif_action_remove_ip6_address(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data); 265 266 /** 267 * @brief Manual configuration of the default netif 268 * 269 * This API overrides the automatic configuration of the default interface based on the route_prio 270 * If the selected netif is set default using this API, no other interface could be set-default disregarding 271 * its route_prio number (unless the selected netif gets destroyed) 272 * 273 * @param[in] esp_netif Handle to esp-netif instance 274 * @return ESP_OK on success 275 */ 276 esp_err_t esp_netif_set_default_netif(esp_netif_t *esp_netif); 277 278 /** 279 * @brief Getter function of the default netif 280 * 281 * This API returns the selected default netif. 282 * 283 * @return Handle to esp-netif instance of the default netif. 284 */ 285 esp_netif_t* esp_netif_get_default_netif(void); 286 287 #if CONFIG_ESP_NETIF_BRIDGE_EN 288 /** 289 * @brief Add a port to the bridge 290 * 291 * @param esp_netif_br Handle to bridge esp-netif instance 292 * @param esp_netif_port Handle to port esp-netif instance 293 * @return ESP_OK on success 294 */ 295 esp_err_t esp_netif_bridge_add_port(esp_netif_t *esp_netif_br, esp_netif_t *esp_netif_port); 296 297 /** 298 * @brief Add a static entry to bridge forwarding database 299 * 300 * @param esp_netif_br Handle to bridge esp-netif instance 301 * @param addr MAC address entry to be added 302 * @param ports_mask Port(s) mask where to be the address forwarded 303 * @return ESP_OK on success 304 */ 305 esp_err_t esp_netif_bridge_fdb_add(esp_netif_t *esp_netif_br, uint8_t *addr, uint64_t ports_mask); 306 307 /** 308 * @brief Remove a static entry from bridge forwarding database 309 * 310 * @param esp_netif_br Handle to bridge esp-netif instance 311 * @param addr MAC address entry to be removed 312 * @return ESP_OK on success 313 */ 314 esp_err_t esp_netif_bridge_fdb_remove(esp_netif_t *esp_netif_br, uint8_t *addr); 315 #endif // CONFIG_ESP_NETIF_BRIDGE_EN 316 317 /** 318 * @brief Cause the TCP/IP stack to join a IPv6 multicast group 319 * 320 * @param[in] esp_netif Handle to esp-netif instance 321 * @param[in] addr The multicast group to join 322 * 323 * @return 324 * - ESP_OK 325 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS 326 * - ESP_ERR_ESP_NETIF_MLD6_FAILED 327 * - ESP_ERR_NO_MEM 328 */ 329 esp_err_t esp_netif_join_ip6_multicast_group(esp_netif_t *esp_netif, const esp_ip6_addr_t *addr); 330 331 /** 332 * @brief Cause the TCP/IP stack to leave a IPv6 multicast group 333 * 334 * @param[in] esp_netif Handle to esp-netif instance 335 * @param[in] addr The multicast group to leave 336 * 337 * @return 338 * - ESP_OK 339 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS 340 * - ESP_ERR_ESP_NETIF_MLD6_FAILED 341 * - ESP_ERR_NO_MEM 342 */ 343 esp_err_t esp_netif_leave_ip6_multicast_group(esp_netif_t *esp_netif, const esp_ip6_addr_t *addr); 344 345 /** 346 * @} 347 */ 348 349 /** 350 * @defgroup ESP_NETIF_GET_SET ESP-NETIF Runtime configuration 351 * @brief Getters and setters for various TCP/IP related parameters 352 */ 353 354 /** @addtogroup ESP_NETIF_GET_SET 355 * @{ 356 */ 357 358 /** 359 * @brief Set the mac address for the interface instance 360 361 * @param[in] esp_netif Handle to esp-netif instance 362 * @param[in] mac Desired mac address for the related network interface 363 * @return 364 * - ESP_OK - success 365 * - ESP_ERR_ESP_NETIF_IF_NOT_READY - interface status error 366 * - ESP_ERR_NOT_SUPPORTED - mac not supported on this interface 367 */ 368 esp_err_t esp_netif_set_mac(esp_netif_t *esp_netif, uint8_t mac[]); 369 370 /** 371 * @brief Get the mac address for the interface instance 372 373 * @param[in] esp_netif Handle to esp-netif instance 374 * @param[out] mac Resultant mac address for the related network interface 375 * @return 376 * - ESP_OK - success 377 * - ESP_ERR_ESP_NETIF_IF_NOT_READY - interface status error 378 * - ESP_ERR_NOT_SUPPORTED - mac not supported on this interface 379 */ 380 esp_err_t esp_netif_get_mac(esp_netif_t *esp_netif, uint8_t mac[]); 381 382 /** 383 * @brief Set the hostname of an interface 384 * 385 * The configured hostname overrides the default configuration value CONFIG_LWIP_LOCAL_HOSTNAME. 386 * Please note that when the hostname is altered after interface started/connected the changes 387 * would only be reflected once the interface restarts/reconnects 388 * 389 * @param[in] esp_netif Handle to esp-netif instance 390 * @param[in] hostname New hostname for the interface. Maximum length 32 bytes. 391 * 392 * @return 393 * - ESP_OK - success 394 * - ESP_ERR_ESP_NETIF_IF_NOT_READY - interface status error 395 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS - parameter error 396 */ 397 esp_err_t esp_netif_set_hostname(esp_netif_t *esp_netif, const char *hostname); 398 399 /** 400 * @brief Get interface hostname. 401 * 402 * @param[in] esp_netif Handle to esp-netif instance 403 * @param[out] hostname Returns a pointer to the hostname. May be NULL if no hostname is set. If set non-NULL, pointer remains valid (and string may change if the hostname changes). 404 * 405 * @return 406 * - ESP_OK - success 407 * - ESP_ERR_ESP_NETIF_IF_NOT_READY - interface status error 408 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS - parameter error 409 */ 410 esp_err_t esp_netif_get_hostname(esp_netif_t *esp_netif, const char **hostname); 411 412 /** 413 * @brief Test if supplied interface is up or down 414 * 415 * @param[in] esp_netif Handle to esp-netif instance 416 * 417 * @return 418 * - true - Interface is up 419 * - false - Interface is down 420 */ 421 bool esp_netif_is_netif_up(esp_netif_t *esp_netif); 422 423 /** 424 * @brief Get interface's IP address information 425 * 426 * If the interface is up, IP information is read directly from the TCP/IP stack. 427 * If the interface is down, IP information is read from a copy kept in the ESP-NETIF instance 428 * 429 * @param[in] esp_netif Handle to esp-netif instance 430 * @param[out] ip_info If successful, IP information will be returned in this argument. 431 * 432 * @return 433 * - ESP_OK 434 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS 435 */ 436 esp_err_t esp_netif_get_ip_info(esp_netif_t *esp_netif, esp_netif_ip_info_t *ip_info); 437 438 /** 439 * @brief Get interface's old IP information 440 * 441 * Returns an "old" IP address previously stored for the interface when the valid IP changed. 442 * 443 * If the IP lost timer has expired (meaning the interface was down for longer than the configured interval) 444 * then the old IP information will be zero. 445 * 446 * @param[in] esp_netif Handle to esp-netif instance 447 * @param[out] ip_info If successful, IP information will be returned in this argument. 448 * 449 * @return 450 * - ESP_OK 451 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS 452 */ 453 esp_err_t esp_netif_get_old_ip_info(esp_netif_t *esp_netif, esp_netif_ip_info_t *ip_info); 454 455 /** 456 * @brief Set interface's IP address information 457 * 458 * This function is mainly used to set a static IP on an interface. 459 * 460 * If the interface is up, the new IP information is set directly in the TCP/IP stack. 461 * 462 * The copy of IP information kept in the ESP-NETIF instance is also updated (this 463 * copy is returned if the IP is queried while the interface is still down.) 464 * 465 * @note DHCP client/server must be stopped (if enabled for this interface) before setting new IP information. 466 * 467 * @note Calling this interface for may generate a SYSTEM_EVENT_STA_GOT_IP or SYSTEM_EVENT_ETH_GOT_IP event. 468 * 469 * @param[in] esp_netif Handle to esp-netif instance 470 * @param[in] ip_info IP information to set on the specified interface 471 * 472 * @return 473 * - ESP_OK 474 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS 475 * - ESP_ERR_ESP_NETIF_DHCP_NOT_STOPPED If DHCP server or client is still running 476 */ 477 esp_err_t esp_netif_set_ip_info(esp_netif_t *esp_netif, const esp_netif_ip_info_t *ip_info); 478 479 /** 480 * @brief Set interface old IP information 481 * 482 * This function is called from the DHCP client (if enabled), before a new IP is set. 483 * It is also called from the default handlers for the SYSTEM_EVENT_STA_CONNECTED and SYSTEM_EVENT_ETH_CONNECTED events. 484 * 485 * Calling this function stores the previously configured IP, which can be used to determine if the IP changes in the future. 486 * 487 * If the interface is disconnected or down for too long, the "IP lost timer" will expire (after the configured interval) and set the old IP information to zero. 488 * 489 * @param[in] esp_netif Handle to esp-netif instance 490 * @param[in] ip_info Store the old IP information for the specified interface 491 * 492 * @return 493 * - ESP_OK 494 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS 495 */ 496 esp_err_t esp_netif_set_old_ip_info(esp_netif_t *esp_netif, const esp_netif_ip_info_t *ip_info); 497 498 /** 499 * @brief Get net interface index from network stack implementation 500 * 501 * @note This index could be used in `setsockopt()` to bind socket with multicast interface 502 * 503 * @param[in] esp_netif Handle to esp-netif instance 504 * 505 * @return 506 * implementation specific index of interface represented with supplied esp_netif 507 */ 508 int esp_netif_get_netif_impl_index(esp_netif_t *esp_netif); 509 510 /** 511 * @brief Get net interface name from network stack implementation 512 * 513 * @note This name could be used in `setsockopt()` to bind socket with appropriate interface 514 * 515 * @param[in] esp_netif Handle to esp-netif instance 516 * @param[out] name Interface name as specified in underlying TCP/IP stack. Note that the 517 * actual name will be copied to the specified buffer, which must be allocated to hold 518 * maximum interface name size (6 characters for lwIP) 519 * 520 * @return 521 * - ESP_OK 522 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS 523 */ 524 esp_err_t esp_netif_get_netif_impl_name(esp_netif_t *esp_netif, char* name); 525 526 /** 527 * @brief Enable NAPT on an interface 528 * 529 * @note Enable operation can be performed only on one interface at a time. 530 * NAPT cannot be enabled on multiple interfaces according to this implementation. 531 * 532 * @param[in] esp_netif Handle to esp-netif instance 533 * 534 * @return 535 * - ESP_OK 536 * - ESP_FAIL 537 * - ESP_ERR_NOT_SUPPORTED 538 */ 539 540 esp_err_t esp_netif_napt_enable(esp_netif_t *esp_netif); 541 542 /** 543 * @brief Disable NAPT on an interface. 544 * 545 * @param[in] esp_netif Handle to esp-netif instance 546 * 547 * @return 548 * - ESP_OK 549 * - ESP_FAIL 550 * - ESP_ERR_NOT_SUPPORTED 551 */ 552 esp_err_t esp_netif_napt_disable(esp_netif_t *esp_netif); 553 554 /** 555 * @} 556 */ 557 558 /** 559 * @defgroup ESP_NETIF_NET_DHCP ESP-NETIF DHCP Settings 560 * @brief Network stack related interface to DHCP client and server 561 */ 562 563 /** @addtogroup ESP_NETIF_NET_DHCP 564 * @{ 565 */ 566 567 /** 568 * @brief Set or Get DHCP server option 569 * 570 * @param[in] esp_netif Handle to esp-netif instance 571 * @param[in] opt_op ESP_NETIF_OP_SET to set an option, ESP_NETIF_OP_GET to get an option. 572 * @param[in] opt_id Option index to get or set, must be one of the supported enum values. 573 * @param[inout] opt_val Pointer to the option parameter. 574 * @param[in] opt_len Length of the option parameter. 575 * 576 * @return 577 * - ESP_OK 578 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS 579 * - ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED 580 * - ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED 581 */ 582 esp_err_t 583 esp_netif_dhcps_option(esp_netif_t *esp_netif, esp_netif_dhcp_option_mode_t opt_op, esp_netif_dhcp_option_id_t opt_id, 584 void *opt_val, uint32_t opt_len); 585 586 /** 587 * @brief Set or Get DHCP client option 588 * 589 * @param[in] esp_netif Handle to esp-netif instance 590 * @param[in] opt_op ESP_NETIF_OP_SET to set an option, ESP_NETIF_OP_GET to get an option. 591 * @param[in] opt_id Option index to get or set, must be one of the supported enum values. 592 * @param[inout] opt_val Pointer to the option parameter. 593 * @param[in] opt_len Length of the option parameter. 594 * 595 * @return 596 * - ESP_OK 597 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS 598 * - ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED 599 * - ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED 600 */ 601 esp_err_t 602 esp_netif_dhcpc_option(esp_netif_t *esp_netif, esp_netif_dhcp_option_mode_t opt_op, esp_netif_dhcp_option_id_t opt_id, 603 void *opt_val, uint32_t opt_len); 604 605 /** 606 * @brief Start DHCP client (only if enabled in interface object) 607 * 608 * @note The default event handlers for the SYSTEM_EVENT_STA_CONNECTED and SYSTEM_EVENT_ETH_CONNECTED events call this function. 609 * 610 * @param[in] esp_netif Handle to esp-netif instance 611 * 612 * @return 613 * - ESP_OK 614 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS 615 * - ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED 616 * - ESP_ERR_ESP_NETIF_DHCPC_START_FAILED 617 */ 618 esp_err_t esp_netif_dhcpc_start(esp_netif_t *esp_netif); 619 620 /** 621 * @brief Stop DHCP client (only if enabled in interface object) 622 * 623 * @note Calling action_netif_stop() will also stop the DHCP Client if it is running. 624 * 625 * @param[in] esp_netif Handle to esp-netif instance 626 * 627 * @return 628 * - ESP_OK 629 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS 630 * - ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED 631 * - ESP_ERR_ESP_NETIF_IF_NOT_READY 632 */ 633 esp_err_t esp_netif_dhcpc_stop(esp_netif_t *esp_netif); 634 635 /** 636 * @brief Get DHCP client status 637 * 638 * @param[in] esp_netif Handle to esp-netif instance 639 * @param[out] status If successful, the status of DHCP client will be returned in this argument. 640 * 641 * @return 642 * - ESP_OK 643 */ 644 esp_err_t esp_netif_dhcpc_get_status(esp_netif_t *esp_netif, esp_netif_dhcp_status_t *status); 645 646 /** 647 * @brief Get DHCP Server status 648 * 649 * @param[in] esp_netif Handle to esp-netif instance 650 * @param[out] status If successful, the status of the DHCP server will be returned in this argument. 651 * 652 * @return 653 * - ESP_OK 654 */ 655 esp_err_t esp_netif_dhcps_get_status(esp_netif_t *esp_netif, esp_netif_dhcp_status_t *status); 656 657 /** 658 * @brief Start DHCP server (only if enabled in interface object) 659 * 660 * @param[in] esp_netif Handle to esp-netif instance 661 * 662 * @return 663 * - ESP_OK 664 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS 665 * - ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED 666 */ 667 esp_err_t esp_netif_dhcps_start(esp_netif_t *esp_netif); 668 669 /** 670 * @brief Stop DHCP server (only if enabled in interface object) 671 * 672 * @param[in] esp_netif Handle to esp-netif instance 673 * 674 * @return 675 * - ESP_OK 676 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS 677 * - ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED 678 * - ESP_ERR_ESP_NETIF_IF_NOT_READY 679 */ 680 esp_err_t esp_netif_dhcps_stop(esp_netif_t *esp_netif); 681 682 /** 683 * @brief Populate IP addresses of clients connected to DHCP server listed by their MAC addresses 684 * 685 * @param[in] esp_netif Handle to esp-netif instance 686 * @param[in] num Number of clients with specified MAC addresses in the array of pairs 687 * @param[in,out] mac_ip_pair Array of pairs of MAC and IP addresses (MAC are inputs, IP outputs) 688 * @return 689 * - ESP_OK on success 690 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS on invalid params 691 * - ESP_ERR_NOT_SUPPORTED if DHCP server not enabled 692 */ 693 esp_err_t esp_netif_dhcps_get_clients_by_mac(esp_netif_t *esp_netif, int num, esp_netif_pair_mac_ip_t *mac_ip_pair); 694 695 /** 696 * @} 697 */ 698 699 /** 700 * @defgroup ESP_NETIF_NET_DNS ESP-NETIF DNS Settings 701 * @brief Network stack related interface to NDS 702 */ 703 704 /** @addtogroup ESP_NETIF_NET_DNS 705 * @{ 706 */ 707 708 /** 709 * @brief Set DNS Server information 710 * 711 * This function behaves differently if DHCP server or client is enabled 712 * 713 * If DHCP client is enabled, main and backup DNS servers will be updated automatically 714 * from the DHCP lease if the relevant DHCP options are set. Fallback DNS Server is never updated from the DHCP lease 715 * and is designed to be set via this API. 716 * If DHCP client is disabled, all DNS server types can be set via this API only. 717 * 718 * If DHCP server is enabled, the Main DNS Server setting is used by the DHCP server to provide a DNS Server option 719 * to DHCP clients (Wi-Fi stations). 720 * - The default Main DNS server is typically the IP of the DHCP server itself. 721 * - This function can override it by setting server type ESP_NETIF_DNS_MAIN. 722 * - Other DNS Server types are not supported for the DHCP server. 723 * - To propagate the DNS info to client, please stop the DHCP server before using this API. 724 * 725 * @param[in] esp_netif Handle to esp-netif instance 726 * @param[in] type Type of DNS Server to set: ESP_NETIF_DNS_MAIN, ESP_NETIF_DNS_BACKUP, ESP_NETIF_DNS_FALLBACK 727 * @param[in] dns DNS Server address to set 728 * 729 * @return 730 * - ESP_OK on success 731 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS invalid params 732 */ 733 esp_err_t esp_netif_set_dns_info(esp_netif_t *esp_netif, esp_netif_dns_type_t type, esp_netif_dns_info_t *dns); 734 735 /** 736 * @brief Get DNS Server information 737 * 738 * Return the currently configured DNS Server address for the specified interface and Server type. 739 * 740 * This may be result of a previous call to esp_netif_set_dns_info(). If the interface's DHCP client is enabled, 741 * the Main or Backup DNS Server may be set by the current DHCP lease. 742 * 743 * @param[in] esp_netif Handle to esp-netif instance 744 * @param[in] type Type of DNS Server to get: ESP_NETIF_DNS_MAIN, ESP_NETIF_DNS_BACKUP, ESP_NETIF_DNS_FALLBACK 745 * @param[out] dns DNS Server result is written here on success 746 * 747 * @return 748 * - ESP_OK on success 749 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS invalid params 750 */ 751 esp_err_t esp_netif_get_dns_info(esp_netif_t *esp_netif, esp_netif_dns_type_t type, esp_netif_dns_info_t *dns); 752 753 /** 754 * @} 755 */ 756 757 /** 758 * @defgroup ESP_NETIF_NET_IP ESP-NETIF IP address related interface 759 * @brief Network stack related interface to IP 760 */ 761 762 /** @addtogroup ESP_NETIF_NET_IP 763 * @{ 764 */ 765 #if CONFIG_LWIP_IPV6 766 /** 767 * @brief Create interface link-local IPv6 address 768 * 769 * Cause the TCP/IP stack to create a link-local IPv6 address for the specified interface. 770 * 771 * This function also registers a callback for the specified interface, so that if the link-local address becomes 772 * verified as the preferred address then a SYSTEM_EVENT_GOT_IP6 event will be sent. 773 * 774 * @param[in] esp_netif Handle to esp-netif instance 775 * 776 * @return 777 * - ESP_OK 778 * - ESP_ERR_ESP_NETIF_INVALID_PARAMS 779 */ 780 esp_err_t esp_netif_create_ip6_linklocal(esp_netif_t *esp_netif); 781 782 /** 783 * @brief Get interface link-local IPv6 address 784 * 785 * If the specified interface is up and a preferred link-local IPv6 address 786 * has been created for the interface, return a copy of it. 787 * 788 * @param[in] esp_netif Handle to esp-netif instance 789 * @param[out] if_ip6 IPv6 information will be returned in this argument if successful. 790 * 791 * @return 792 * - ESP_OK 793 * - ESP_FAIL If interface is down, does not have a link-local IPv6 address, 794 * or the link-local IPv6 address is not a preferred address. 795 */ 796 esp_err_t esp_netif_get_ip6_linklocal(esp_netif_t *esp_netif, esp_ip6_addr_t *if_ip6); 797 798 /** 799 * @brief Get interface global IPv6 address 800 * 801 * If the specified interface is up and a preferred global IPv6 address 802 * has been created for the interface, return a copy of it. 803 * 804 * @param[in] esp_netif Handle to esp-netif instance 805 * @param[out] if_ip6 IPv6 information will be returned in this argument if successful. 806 * 807 * @return 808 * - ESP_OK 809 * - ESP_FAIL If interface is down, does not have a global IPv6 address, 810 * or the global IPv6 address is not a preferred address. 811 */ 812 esp_err_t esp_netif_get_ip6_global(esp_netif_t *esp_netif, esp_ip6_addr_t *if_ip6); 813 814 /** 815 * @brief Get all IPv6 addresses of the specified interface 816 * 817 * @param[in] esp_netif Handle to esp-netif instance 818 * @param[out] if_ip6 Array of IPv6 addresses will be copied to the argument 819 * 820 * @return 821 * number of returned IPv6 addresses 822 */ 823 int esp_netif_get_all_ip6(esp_netif_t *esp_netif, esp_ip6_addr_t if_ip6[]); 824 #endif 825 826 /** 827 * @brief Sets IPv4 address to the specified octets 828 * 829 * @param[out] addr IP address to be set 830 * @param a the first octet (127 for IP 127.0.0.1) 831 * @param b 832 * @param c 833 * @param d 834 */ 835 void esp_netif_set_ip4_addr(esp_ip4_addr_t *addr, uint8_t a, uint8_t b, uint8_t c, uint8_t d); 836 837 838 /** 839 * @brief Converts numeric IP address into decimal dotted ASCII representation. 840 * 841 * @param addr ip address in network order to convert 842 * @param buf target buffer where the string is stored 843 * @param buflen length of buf 844 * @return either pointer to buf which now holds the ASCII 845 * representation of addr or NULL if buf was too small 846 */ 847 char *esp_ip4addr_ntoa(const esp_ip4_addr_t *addr, char *buf, int buflen); 848 849 /** 850 * @brief Ascii internet address interpretation routine 851 * The value returned is in network order. 852 * 853 * @param addr IP address in ascii representation (e.g. "127.0.0.1") 854 * @return ip address in network order 855 */ 856 uint32_t esp_ip4addr_aton(const char *addr); 857 858 /** 859 * @brief Converts Ascii internet IPv4 address into esp_ip4_addr_t 860 * 861 * @param[in] src IPv4 address in ascii representation (e.g. "127.0.0.1") 862 * @param[out] dst Address of the target esp_ip4_addr_t structure to receive converted address 863 * @return 864 * - ESP_OK on success 865 * - ESP_FAIL if conversion failed 866 * - ESP_ERR_INVALID_ARG if invalid parameter is passed into 867 */ 868 esp_err_t esp_netif_str_to_ip4(const char *src, esp_ip4_addr_t *dst); 869 870 /** 871 * @brief Converts Ascii internet IPv6 address into esp_ip4_addr_t 872 * Zeros in the IP address can be stripped or completely ommited: "2001:db8:85a3:0:0:0:2:1" or "2001:db8::2:1") 873 * 874 * @param[in] src IPv6 address in ascii representation (e.g. ""2001:0db8:85a3:0000:0000:0000:0002:0001") 875 * @param[out] dst Address of the target esp_ip6_addr_t structure to receive converted address 876 * @return 877 * - ESP_OK on success 878 * - ESP_FAIL if conversion failed 879 * - ESP_ERR_INVALID_ARG if invalid parameter is passed into 880 */ 881 esp_err_t esp_netif_str_to_ip6(const char *src, esp_ip6_addr_t *dst); 882 883 /** 884 * @} 885 */ 886 887 /** 888 * @defgroup ESP_NETIF_CONVERT ESP-NETIF Conversion utilities 889 * @brief ESP-NETIF conversion utilities to related keys, flags, implementation handle 890 */ 891 892 /** @addtogroup ESP_NETIF_CONVERT 893 * @{ 894 */ 895 896 /** 897 * @brief Gets media driver handle for this esp-netif instance 898 * 899 * @param[in] esp_netif Handle to esp-netif instance 900 * 901 * @return opaque pointer of related IO driver 902 */ 903 esp_netif_iodriver_handle esp_netif_get_io_driver(esp_netif_t *esp_netif); 904 905 /** 906 * @brief Searches over a list of created objects to find an instance with supplied if key 907 * 908 * @param if_key Textual description of network interface 909 * 910 * @return Handle to esp-netif instance 911 */ 912 esp_netif_t *esp_netif_get_handle_from_ifkey(const char *if_key); 913 914 /** 915 * @brief Returns configured flags for this interface 916 * 917 * @param[in] esp_netif Handle to esp-netif instance 918 * 919 * @return Configuration flags 920 */ 921 esp_netif_flags_t esp_netif_get_flags(esp_netif_t *esp_netif); 922 923 /** 924 * @brief Returns configured interface key for this esp-netif instance 925 * 926 * @param[in] esp_netif Handle to esp-netif instance 927 * 928 * @return Textual description of related interface 929 */ 930 const char *esp_netif_get_ifkey(esp_netif_t *esp_netif); 931 932 /** 933 * @brief Returns configured interface type for this esp-netif instance 934 * 935 * @param[in] esp_netif Handle to esp-netif instance 936 * 937 * @return Enumerated type of this interface, such as station, AP, ethernet 938 */ 939 const char *esp_netif_get_desc(esp_netif_t *esp_netif); 940 941 /** 942 * @brief Returns configured routing priority number 943 * 944 * @param[in] esp_netif Handle to esp-netif instance 945 * 946 * @return Integer representing the instance's route-prio, or -1 if invalid paramters 947 */ 948 int esp_netif_get_route_prio(esp_netif_t *esp_netif); 949 950 /** 951 * @brief Returns configured event for this esp-netif instance and supplied event type 952 * 953 * @param[in] esp_netif Handle to esp-netif instance 954 * 955 * @param event_type (either get or lost IP) 956 * 957 * @return specific event id which is configured to be raised if the interface lost or acquired IP address 958 * -1 if supplied event_type is not known 959 */ 960 int32_t esp_netif_get_event_id(esp_netif_t *esp_netif, esp_netif_ip_event_type_t event_type); 961 962 /** 963 * @} 964 */ 965 966 /** 967 * @defgroup ESP_NETIF_LIST ESP-NETIF List of interfaces 968 * @brief APIs to enumerate all registered interfaces 969 */ 970 971 /** @addtogroup ESP_NETIF_LIST 972 * @{ 973 */ 974 975 /** 976 * @brief Iterates over list of interfaces. Returns first netif if NULL given as parameter 977 * 978 * @param[in] esp_netif Handle to esp-netif instance 979 * 980 * @return First netif from the list if supplied parameter is NULL, next one otherwise 981 */ 982 esp_netif_t *esp_netif_next(esp_netif_t *esp_netif); 983 984 /** 985 * @brief Returns number of registered esp_netif objects 986 * 987 * @return Number of esp_netifs 988 */ 989 size_t esp_netif_get_nr_of_ifs(void); 990 991 /** 992 * @brief increase the reference counter of net stack buffer 993 * 994 * @param[in] netstack_buf the net stack buffer 995 * 996 */ 997 void esp_netif_netstack_buf_ref(void *netstack_buf); 998 999 /** 1000 * @brief free the netstack buffer 1001 * 1002 * @param[in] netstack_buf the net stack buffer 1003 * 1004 */ 1005 void esp_netif_netstack_buf_free(void *netstack_buf); 1006 1007 /** 1008 * @} 1009 */ 1010 1011 /** @addtogroup ESP_NETIF_TCPIP_EXEC 1012 * @{ 1013 */ 1014 1015 /** 1016 * @brief TCPIP thread safe callback used with esp_netif_tcpip_exec() 1017 */ 1018 typedef esp_err_t (*esp_netif_callback_fn)(void *ctx); 1019 1020 /** 1021 * @brief Utility to execute the supplied callback in TCP/IP context 1022 * @param fn Pointer to the callback 1023 * @param ctx Parameter to the callback 1024 * @return The error code (esp_err_t) returned by the callback 1025 */ 1026 esp_err_t esp_netif_tcpip_exec(esp_netif_callback_fn fn, void *ctx); 1027 1028 /** 1029 * @} 1030 */ 1031 1032 #ifdef __cplusplus 1033 } 1034 #endif 1035 1036 #endif /* _ESP_NETIF_H_ */ 1037
