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