1 /** 2 * @file 3 * netif API (to be used from non-TCPIP threads) 4 */ 5 /* 6 * Copyright (c) <2013-2016>, <Huawei Technologies Co., Ltd> 7 * All rights reserved. 8 * Redistribution and use in source and binary forms, with or without modification, 9 * are permitted provided that the following conditions are met: 10 * 11 * 1. Redistributions of source code must retain the above copyright notice, 12 * this list of conditions and the following disclaimer. 13 * 2. Redistributions in binary form must reproduce the above copyright notice, 14 * this list of conditions and the following disclaimer in the documentation 15 * and/or other materials provided with the distribution. 16 * 3. The name of the author may not be used to endorse or promote products 17 * derived from this software without specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED 20 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 21 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 22 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 23 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 24 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 27 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 28 * OF SUCH DAMAGE. 29 * 30 * This file is part of the lwIP TCP/IP stack. 31 * 32 */ 33 34 #ifndef LWIP_HDR_NETIFAPI_H 35 #define LWIP_HDR_NETIFAPI_H 36 37 #include "lwip/opt.h" 38 39 #if LWIP_NETIF_API /* don't build if not configured for use in lwipopts.h */ 40 41 #include "lwip/sys.h" 42 #include "lwip/netif.h" 43 #include "lwip/dhcp.h" 44 #if LWIP_IPV6_DHCP6 45 #include "lwip/dhcp6.h" 46 #endif /* LWIP_IPV6_DHCP6 */ 47 #include "lwip/autoip.h" 48 #include "lwip/priv/tcpip_priv.h" 49 #include "lwip/prot/ethernet.h" 50 51 #if defined (__cplusplus) && __cplusplus 52 extern "C" { 53 #endif 54 55 #if LWIP_MPU_COMPATIBLE 56 #define NETIFAPI_IPADDR_DEF(type, m) type m 57 #else /* LWIP_MPU_COMPATIBLE */ 58 #define NETIFAPI_IPADDR_DEF(type, m) const type * m 59 #endif /* LWIP_MPU_COMPATIBLE */ 60 61 typedef void (*netifapi_void_fn)(struct netif *netif); 62 typedef err_t (*netifapi_arg_fn)(struct netif *netif, void *arg); 63 64 typedef err_t (*netifapi_errt_fn)(struct netif *netif); 65 66 #if LWIP_IPV6 && LWIP_NETIF_NBR_CACHE_API 67 struct ipv6_neighbor { 68 struct ip6_addr nbripaddr; 69 u32_t reachabletime; 70 u8_t hwaddr[NETIF_MAX_HWADDR_LEN]; 71 u8_t hwlen; 72 u8_t curstate; 73 }; 74 #endif 75 76 typedef struct name_for_netif { 77 struct netif *p_netif; 78 char name[IFNAMSIZ]; 79 } name_for_netif_t; 80 81 struct netifapi_msg { 82 struct tcpip_api_call_data call; 83 struct netif *netif; 84 #if LWIP_MAC_SECURITY 85 u8_t authstatus; 86 #endif 87 union { 88 struct { 89 struct netif *main_netif; 90 #if LWIP_IPV4 91 NETIFAPI_IPADDR_DEF(ip4_addr_t, ipaddr); 92 NETIFAPI_IPADDR_DEF(ip4_addr_t, netmask); 93 NETIFAPI_IPADDR_DEF(ip4_addr_t, gw); 94 #endif /* LWIP_IPV4 */ 95 void *state; 96 netif_init_fn init; 97 netif_input_fn input; 98 } add; 99 struct { 100 netifapi_void_fn voidfunc; 101 netifapi_errt_fn errtfunc; 102 } common; 103 #if LWIP_NETIFAPI_GET_ADDR 104 struct { 105 struct netif *main_netif; 106 #if LWIP_IPV4 107 ip4_addr_t *ipaddr; 108 ip4_addr_t *netmask; 109 ip4_addr_t *gw; 110 #endif /* LWIP_IPV4 */ 111 void *state; 112 netif_init_fn init; 113 netif_input_fn input; 114 } add_get; 115 #endif 116 struct { 117 netifapi_arg_fn argfunc; 118 void *arg; 119 } arg_cb; 120 #if LWIP_DHCP 121 struct { 122 struct dhcp *dhcp; 123 } dhcp_struct; 124 #endif 125 #if LWIP_DHCPS 126 struct { 127 char *start_ip; 128 u16_t ip_num; 129 } dhcp_start_params; 130 #if LWIP_NETIFAPI_DHCPS_IP 131 struct { 132 u8_t *mac; 133 u8_t maclen; 134 ip_addr_t *ip; 135 } dhcp_get_ip_params; 136 #endif 137 #endif 138 #if LWIP_NETIFAPI_LINK_CALLBACK 139 struct { 140 netif_status_callback_fn link_callback; 141 } netif_link_cb; 142 #endif 143 #if LWIP_NETIF_EXT_STATUS_CALLBACK 144 struct { 145 netif_ext_callback_t *cb; 146 netif_ext_callback_fn fn; 147 } netif_ext_cb; 148 #endif 149 #if LWIP_NETIFAPI_MTU 150 struct { 151 u16_t mtu; 152 } netif_mtu; 153 #endif 154 struct { 155 u8_t num; 156 } netif_num; 157 #if LWIP_NETIF_HOSTNAME 158 struct { 159 char *name; 160 u8_t namelen; 161 } hostname; 162 #endif /* LWIP_NETIF_HOSTNAME */ 163 #if LWIP_NETIFAPI_IF_INDEX 164 struct { 165 #if LWIP_MPU_COMPATIBLE 166 char name[IF_NAMESIZE]; 167 #else /* LWIP_MPU_COMPATIBLE */ 168 char *name; 169 #endif /* LWIP_MPU_COMPATIBLE */ 170 u8_t index; 171 } ifs; 172 struct if_nameindex *p_if_list; 173 #endif 174 #if LWIP_DHCP_VENDOR_CLASS_IDENTIFIER 175 struct { 176 char *vci; 177 u8_t *vci_len; 178 } vci; 179 #endif /* LWIP_DHCP_VENDOR_CLASS_IDENTIFIER */ 180 #if LWIP_IP_FILTER | LWIP_IPV6_FILTER 181 struct { 182 ip_filter_fn filter_fn; 183 int type; 184 } ip_filter; 185 #endif /* LWIP_IP_FILTER | LWIP_IP_FILTER */ 186 187 #if LWIP_IPV6 && (LWIP_NETIF_NBR_CACHE_API || LWIP_ND6_STATIC_DEFAULT_ROUTE) 188 struct { 189 struct ipv6_neighbor *nbrinfo; 190 struct ip6_addr *nodeip; 191 } ipv6_tables_access_params; 192 #endif 193 #if LWIP_IPV6 && LWIP_6LOWPAN 194 struct { 195 struct ip6_addr *ctxprefix; 196 u8_t index; 197 } lowpanctx; 198 #endif 199 #if LWIP_IPV6 200 struct { 201 u8_t state; 202 } ip6_state; 203 #endif 204 #if LWIP_IPV6 && LWIP_ND6_STATIC_PREFIX 205 struct { 206 struct ip6_addr *prefix; 207 u8_t auto_config_flags; 208 } prefix_params; 209 #endif 210 #if LWIP_ENABLE_ROUTER || LWIP_API_MESH 211 struct { 212 const struct linklayer_event_info *evt; 213 } linklayer_event; 214 #endif 215 #if LWIP_NETIFAPI_IF_HW 216 struct { 217 u8_t *hw_addr; 218 s32_t hw_len; 219 } hw; 220 #endif 221 #if LWIP_LOWPOWER 222 struct { 223 enum lowpower_mod mod; 224 } lp; 225 #endif 226 #if LWIP_IPV4 && LWIP_ARP 227 struct { 228 ip4_addr_t *ip; 229 u8_t *mac; 230 u8_t *maclen; 231 } arp; 232 #endif 233 } msg; 234 }; 235 236 /* User can add neighbors with below states */ 237 #define ND6_STATE_REACHABLE 2 238 #if LWIP_ND6_STATIC_NBR 239 #define ND6_STATE_PERMANENT 6 240 #endif 241 242 #define AUTHENTICATION_SUCCESS 1 243 #define AUTHENTICATION_FAILURE 0 244 245 #if LWIP_ARP && LWIP_IPV4 246 /* Used for netfiapi_arp_* APIs */ 247 enum netifapi_arp_entry { 248 NETIFAPI_ARP_PERM /* Permanent entry */ 249 /* Other entry types can be added here */ 250 }; 251 252 /** @ingroup netifapi_arp */ 253 err_t netifapi_arp_add(const ip4_addr_t *ipaddr, struct eth_addr *ethaddr, enum netifapi_arp_entry type); 254 /** @ingroup netifapi_arp */ 255 err_t netifapi_arp_remove(const ip4_addr_t *ipaddr, enum netifapi_arp_entry type); 256 #endif /* LWIP_ARP && LWIP_IPV4 */ 257 258 /** 259 * @cond liteosnetif 260 * @defgroup Threadsafe_Network_Interfaces Network Interfaces 261 * This section contains the Thread safe Network related interfaces. 262 */ 263 /** 264 * @defgroup Threadsafe_DHCP_Interfaces DHCP Interfaces 265 * This section contains the Thread safe DHCP interfaces. 266 */ 267 /** 268 * @ingroup Threadsafe_Network_Interfaces 269 * @brief 270 * This is a thread safe API, used to add a network interface to the list of lwIP netifs. It is recommended 271 * to use this API instead of netif_add(). 272 * 273 * @param[in] netif Indicates the pre-allocated netif structure. 274 * @param[in] ipaddr Indicates the IP_add for the new netif. 275 * @param[in] netmask Indicates the network mask for the new netif. 276 * @param[in] gw Indicates the default gateway IP_add for the new netif. 277 * 278 * @returns 279 * 0 : On success. \n 280 * Negative value : On failure. 281 * 282 * struct netif is a shared data structure across driver and lwIP. So, Following paramters MUST be initialized by driver 283 * when netifapi_netif_add is called: 284 * 1, state, maybe private handler only used by driver, not accessed by lwip protocol, MUST be initialized by driver. 285 * 2, drv_send, used to do packet transmission, driver MUST initialized it with NON NULL value. 286 * 3, drv_config, used to configure promisic mode, driver MUST initialized it with NON NULL value. 287 * 4, drv_set_hwaddr, used to set hardware address, MUST be initialized by driver. NULL is also a valid value. 288 * 5, ethtool_ops, used to configure phy mode(10/100M, duplex), can be NULL if phy mode change not supported by driver. 289 * 6, link_layer_type, MUST be ETHERNET_DRIVER_IF or WIFI_DRIVER_IF. 290 * 7, hwaddr, hardware address. 291 * 8, hwaddr_len, hardware address length. 292 * 293 * @note 294 * For IPv4 stack, if NULL is passed to ipaddr/netmask/gw then 0.0.0.0 will be set as the corresponding address on 295 * the netif. \n 296 * For IPv6: Don't forget to call netif_create_ip6_linklocal_address() after setting the MAC address 297 * in struct netif.hwaddr (IPv6 requires a link-local address). 298 * 299 * @par Related Topics 300 * netif_add() 301 */ 302 err_t netifapi_netif_add(struct netif *netif 303 #if LWIP_IPV4 304 , const ip4_addr_t *ipaddr, const ip4_addr_t *netmask, const ip4_addr_t *gw 305 #endif /* LWIP_IPV4 */ 306 ); 307 308 /* 309 * Func Name: netifapi_netif_remove 310 */ 311 /** 312 * @ingroup Threadsafe_Network_Interfaces 313 * @brief 314 * This API is used to remove a network interface from the list of lwIP netifs 315 * in a thread-safe manner. 316 * The Ethernet driver calls this API in a thread-safe manner to remove a network 317 * interface from the list of lwIP netifs. 318 * 319 * @param[in] netif Indicates the network interface to be removed. 320 * 321 * @returns 322 * ERR_OK: On success. \n 323 * ERR_VAL: On failure due to illegal value. \n 324 * ERR_ARG: On passing invalid arguments. 325 * 326 * @note 327 - Any data sent by the application will return success, 328 but the data will not be sent if only netifapi_netif_remove() API is called and not the sockets. 329 - The adaptor must close all the connections on socket before netifapi_netif_remove() 330 API is called, as netifapi_netif_remove() does not close established connections. 331 */ 332 err_t netifapi_netif_remove(struct netif *netif); 333 334 #if LWIP_NETIFAPI_IF_HW 335 /* 336 * Func Name: netifapi_netif_set_hwaddr 337 */ 338 /** 339 * @ingroup Threadsafe_Network_Interfaces 340 * @brief 341 * This API is used to change the hardware address for a network interface 342 * in a thread-safe manner. 343 * 344 * @param[in] netif Indicates the network interface to change the hardware address. 345 * @param[in] hw_addr Indicates the new hardware address. 346 * @param[in] hw_len Indicates the length of new hardware address. 347 * 348 * @returns 349 * ERR_OK: On success. \n 350 * ERR_IF: On failure due to netif driver error. \n 351 * ERR_ARG: On passing invalid arguments. 352 * 353 * @note 354 - This API will try to call netif registed function drv_set_hwaddr() if this function is registed. 355 If this API returns ERR_IF, this means that some error occur while carrying out function drv_set_hwaddr(). 356 */ 357 err_t netifapi_netif_set_hwaddr(struct netif *netif, u8_t *hw_addr, s32_t hw_len); 358 359 /* 360 * Func Name: netifapi_netif_get_hwaddr 361 */ 362 /** 363 * @ingroup Threadsafe_Network_Interfaces 364 * @brief 365 * This API is used to get the hardware address for a network interface 366 * in a thread-safe manner. 367 * 368 * @param[in] netif Indicates the network interface to get the hardware address. 369 * @param[out] hw_addr Indicates the buffer to record hardware address. 370 * @param[in] hw_len Indicates the length of hw_addr. 371 * 372 * @note 373 - hw_len MUST be equal to NETIF_MAX_HWADDR_LEN. 374 */ 375 void netifapi_netif_get_hwaddr(struct netif *netif, u8_t *hw_addr, s32_t hw_len); 376 #endif /* LWIP_NETIFAPI_IF_HW */ 377 378 #if LWIP_IPV4 379 380 /* 381 * Func Name: netifapi_netif_set_addr 382 */ 383 /** 384 * @ingroup Threadsafe_Network_Interfaces 385 * This is a thread safe API, used to change IP_add configuration for a 386 * network interface (including netmask and default gateway). 387 * It is recommended to use this API instead of netif_set_addr(). 388 * @param[in] netif Indicates the network interface to change. 389 * @param[in] ipaddr Indicates the new IP address. 390 * @param[in] netmask Indicates the new network mask. 391 * @param[in] gw Indicates the new default gateway IP address. 392 * @returns 393 * 0 : On success. \n 394 * Negative value : On failure. 395 * 396 * @par Related Topics 397 * netif_set_addr() 398 * 399 * @note 400 * - If NULL is passed to ipaddr/netmask/gw, then 0.0.0.0 will be set as the corresponding address on the netif 401 */ 402 err_t netifapi_netif_set_addr(struct netif *netif, 403 const ip4_addr_t *ipaddr, 404 const ip4_addr_t *netmask, 405 const ip4_addr_t *gw); 406 407 #if LWIP_NETIFAPI_GET_ADDR 408 /* 409 * Func Name: netifapi_netif_get_addr 410 */ 411 /** 412 * @ingroup Threadsafe_Network_Interfaces 413 * 414 * @brief 415 * 416 * This is a thread safe API, used to get IP_add configuration for a network interface 417 * (including netmask and default gateway). 418 * It is recommended to use this API instead of netif_get_addr() 419 * 420 * @param[in] netif Indicates the network interface to get. 421 * @param[in] ipaddr Indicates the IP address. 422 * @param[in] netmask Indicates the network mask. 423 * @param[in] gw Indicates the default gateway IP address. 424 * 425 * @returns 426 * 0 : On success \n 427 * Negative value : On failure \n 428 * 429 * @par Related Topics 430 * netif_get_addr() 431 * 432 * @note 433 * - netmask and/or gw can be passed NULL, if these details about the netif are not needed 434 */ 435 err_t netifapi_netif_get_addr(struct netif *netif, 436 ip4_addr_t *ipaddr, 437 ip4_addr_t *netmask, 438 ip4_addr_t *gw); 439 #endif /* LWIP_NETIFAPI_GET_ADDR */ 440 #endif /* LWIP_IPV4 */ 441 /** 442 * @ingroup Threadsafe_Network_Interfaces 443 * @brief 444 * This API is used to call all netif related APIs in a thread safe manner. The netif related APIs must be 445 * of prototype to receive only struct netif* as argument and return type can of type err_t or void. You 446 * must pass either viodfunc or errtfunc. 447 * 448 * @param[in] netif Indicates the network interface to be passed as argument. 449 * @param[in] voidfunc Callback with return type of void, will be called if errtfunc is NULL. 450 * @param[in] errtfunc Callback with return type of err_t. 451 * 452 * @returns 453 * 0 : On success. \n 454 * Negative value : On failure. 455 * 456 * @note 457 * The prototype for netifapi_void_fn and netifapi_errt_fn are as follows:\n 458 * typedef void (*netifapi_void_fn)(struct netif *netif); \n 459 * typedef err_t (*netifapi_errt_fn)(struct netif *netif); \n 460 */ 461 err_t netifapi_netif_common(struct netif *netif, netifapi_void_fn voidfunc, 462 netifapi_errt_fn errtfunc); 463 464 #if LWIP_NETIFAPI_IP6_ADDR 465 /** 466 * @ingroup Threadsafe_Network_Interfaces 467 * @brief 468 * This function allows for the easy addition of a new IPv6 address to an interface. 469 * It takes care of finding an empty slot and then sets the address tentative 470 * (to make sure that all the subsequent processing happens). 471 * 472 * @param[in] netif Indicates the netif to add the address on. 473 * @param[in] ip6addr Indicates the address to add. 474 */ 475 err_t 476 netifapi_netif_add_ip6_address(struct netif *netif, ip_addr_t *ipaddr); 477 478 /** 479 * @ingroup Threadsafe_Network_Interfaces 480 * @brief 481 * This function allows for the easy removal of an existing IPv6 address from an interface. 482 * 483 * 484 * @param[in] netif Indicates the netif to remove the address from. 485 * @param[in] ip6addr Indicates the address to remove. 486 * @note 487 * - This interface may force any blocking accept() to return failure with errno ECONNABORTED. 488 */ 489 #endif /* LWIP_NETIFAPI_IP6_ADDR */ 490 491 #if LWIP_NETIFAPI_IP6_ADDR || LWIP_ENABLE_BASIC_SHELL_CMD 492 void 493 netifapi_netif_rmv_ip6_address(struct netif *netif, ip_addr_t *ipaddr); 494 #endif 495 496 #if LWIP_IPV6_MLD && LWIP_NETIFAPI_MLD6 497 /** 498 * @ingroup Threadsafe_Network_Interfaces 499 * @brief 500 * This function allows to join a group without sending out MLD6 Report message. 501 * This function is not RFC 2710 compliant and is a custom function 502 * 503 * 504 * @param[in] netif Indicates the netif which want to join a group. 505 * @param[in] ip6addr Indicates the group address. 506 */ 507 err_t 508 netifapi_netif_join_ip6_multicastgroup(struct netif *netif, ip6_addr_t *ip6addr); 509 #endif 510 511 512 /* 513 * @ingroup Threadsafe_Network_Interfaces 514 * This function allows for the easy addition of a new IPv6 link local address to an interface. 515 * It uses slot fixed for link local address and then sets the address tentative 516 * (to make sure that all the subsequent processing happens). 517 * This Interface MUST be called to configure link local IP address, after addition of netif. 518 * 519 * @param netif netif to add the address on 520 * @param ip6addr address to add 521 * @param from_mac_48bit specifies whether mac address is 48 bit for 64 bit format */ 522 err_t 523 netifapi_netif_add_ip6_linklocal_address(struct netif *netif, u8_t from_mac_48bit); 524 525 #if LWIP_IPV6_AUTOCONFIG 526 /** 527 * @ingroup Threadsafe_Network_Interfaces 528 * @brief 529 * This function is used to enable autoconfig for IPv6 address in a thread-safe way. 530 * That is, the indicated network interface will send out an RS packet immediately to obtain RA. 531 * 532 * @param[in] netif Indicates the lwIP network interface. 533 * 534 * @note 535 * 536 * For netifapi_set_ip6_autoconfig_enabled(): 537 * - It enables stateless autoconfiguration. 538 * - It requires the router/default-gateway to understand and implement RFC-4862, but requires no DHCPv6 server. 539 * - No server keeps track of what has or hasn't been assigned, and no server approves the use of the address, 540 * or pass it out. 541 * - Once called: send out an RS packet immediately to obtain RA. 542 * - When receiving an RA, lwIP can generate an IPv6 address (DAD first) and update routing information. 543 * 544 * For netifapi_dhcp6_enable_stateful(): 545 * - It enables stateful DHCPv6 client autoconfiguration (stateless disabled). 546 * - It requires the DHCPv6 server(s) to provide addressing and service information. 547 * - The DHCP server and the client both maintain state information to keep addresses from conflicting, 548 * to handle leases, and to renew addresses over time. 549 * - Once called: disable autoconfig for IPv6 address (clean autoconfig generated addresses), 550 * and start DHCPv6 procedure to create a stateful DHCPv6 client (if no stateful DHCPv6 client). 551 * 552 * For netifapi_dhcp6_enable_stateless(): 553 * - It is used to get "Other configuration" in RFC-4861. 554 * - It requires the DHCPv6 server(s) to provide service information (like DNS servers and NTP servers), 555 * but no addressing information. 556 * - Once called: no effect to current IPv6 addresses, 557 * and start DHCPv6 procedure to create a stateless DHCPv6 client (if no DHCPv6 client). 558 * 559 * @par Related Topics 560 * netifapi_dhcp6_enable_stateful() 561 * netifapi_dhcp6_enable_stateless() 562 */ 563 err_t 564 netifapi_set_ip6_autoconfig_enabled(struct netif *netif); 565 566 /** 567 * @ingroup Threadsafe_Network_Interfaces 568 * @brief 569 * This function is used to disable autoconfig for IPv6 address in a thread-safe way. 570 * That is, autoconfig generated addresses on the indicated network interface will be invalid. 571 * 572 * @param[in] netif Indicates the lwIP network interface. 573 * 574 * @note 575 * For now, since only prefixes have the autoconfig generated flag, while IPv6 addresses don't have, 576 * lwIP can only invalid addresses by prefixes rather than addresses. So, when a network interface has 577 * a manually configured IPv6 address, and an autoconfig generated IPv6 address which have the same 578 * prefix, calling netifapi_set_ip6_autoconfig_disabled() will invalid both addresses. 579 * 580 * @par Related Topics 581 * netifapi_dhcp6_disable() 582 * netifapi_dhcp6_release_stateful() 583 */ 584 err_t 585 netifapi_set_ip6_autoconfig_disabled(struct netif *netif); 586 #endif /* LWIP_IPV6_AUTOCONFIG */ 587 588 /* 589 * @ingroup Threadsafe_Network_Interfaces 590 * @brief 591 * Call the "argfunc" with argument arg in a thread-safe way by running that function inside the tcpip_thread context. 592 * @note Use this function only for functions where there is only "netif" parameter. 593 */ 594 err_t 595 netifapi_netif_call_argcb(struct netif *netif, netifapi_arg_fn argfunc, void *arg); 596 597 /* 598 * @ingroup Threadsafe_Network_Interfaces 599 * @brief 600 * Call the "argfunc" with argument arg in a thread-safe way by running that function inside the tcpip_thread context. 601 */ 602 err_t 603 netifapi_call_argcb(netifapi_arg_fn argfunc, void *arg); 604 605 /** 606 * @ingroup Threadsafe_Network_Interfaces 607 * @brief 608 * This interface is used to bring an interface up in a thread-safe way. 609 * That is, the interface is available for processing traffic. 610 * 611 * @param[in] n Indicates the network interface. 612 * 613 * @note 614 * Enabling DHCP on a down interface will make it come up once configured. 615 * 616 * @par Related Topics 617 * netifapi_dhcp_start() 618 */ 619 err_t netifapi_netif_set_up(struct netif *netif); 620 621 /** 622 * @ingroup Threadsafe_Network_Interfaces 623 * @brief 624 * This interface is used to bring an interface down in a thread-safe way. 625 * That is, the interface disables any traffic processing. 626 * 627 * @param[in] n Indicates the network interface. 628 * 629 * @note 630 * Enabling DHCP on a down interface will make it come up once configured. 631 * 632 * @par Related Topics 633 * netifapi_dhcp_start() 634 */ 635 err_t netifapi_netif_set_down(struct netif *netif); 636 637 /* 638 Func Name: netifapi_netif_set_default 639 */ 640 /** 641 * @ingroup Threadsafe_Network_Interfaces 642 * 643 * @param[in] netif Indicates the network interface to be set as default. 644 * 645 * @brief 646 * This interface is used to set a network interface as the default network interface. 647 * It is used to output all packets for which no specific route is found. 648 */ 649 err_t netifapi_netif_set_default(struct netif *netif); 650 651 #if LWIP_NETIFAPI_IF_GET_DEFAULT 652 /* 653 Func Name: netifapi_netif_get_default 654 */ 655 /** 656 * @ingroup Threadsafe_Network_Interfaces 657 658 * @brief 659 * This API is used to get the default network interface. 660 * It is used to output all packets for which no specific route is found. 661 * 662 * @return 663 * NULL: if either the default netif was NOT exist or the default netif was down \n 664 * Others: the default netif \n 665 */ 666 struct netif *netifapi_netif_get_default(void); 667 #endif 668 669 /** 670 * @ingroup Threadsafe_Network_Interfaces 671 * @brief 672 * This thread-safe interface is called when to find interface 673 */ 674 struct netif *netifapi_netif_find(const char *name); 675 676 /** 677 * @ingroup Threadsafe_Network_Interfaces 678 * @brief 679 * This thread-safe interface is called by the driver when its link goes up. 680 */ 681 err_t netifapi_netif_set_link_up(struct netif *netif); 682 683 /** 684 * @ingroup Threadsafe_Network_Interfaces 685 * @brief 686 * This thread-safe interface is called by the driver when its link goes down. 687 */ 688 err_t netifapi_netif_set_link_down(struct netif *netif); 689 690 /* 691 * @defgroup netifapi_dhcp4 DHCPv4 692 * @ingroup netifapi 693 * To be called from non-TCPIP threads 694 */ 695 #if LWIP_DHCP 696 /** @ingroup Threadsafe_DHCP_Interfaces 697 * @brief 698 * This interface is used to start DHCP negotiation for a network interface. If no DHCP client instance 699 * is attached to this interface, a new client is created first. If a DHCP client instance is already 700 * present, it restarts negotiation. It is the thread-safe way for calling dhcp_start in the user space. 701 * */ 702 err_t netifapi_dhcp_start(struct netif *netif); 703 704 /** @ingroup Threadsafe_DHCP_Interfaces 705 * @brief 706 * This interface is used to remove the DHCP client from the interface. It stops DHCP configuration. 707 * It is the thread-safe way for calling dhcp_stop in the user space. */ 708 err_t netifapi_dhcp_stop(struct netif *netif); 709 710 /** @ingroup Threadsafe_DHCP_Interfaces 711 * @brief 712 * This interface is used to make the DHCP client inform the DHCP server regarding its manual(static) IP configuration. 713 * This is done by sending a DHCP_INFORM message from the client to the server. 714 * It is the thread-safe way for calling dhcp_inform in the user space. */ 715 err_t netifapi_dhcp_inform(struct netif *netif); 716 717 /** @ingroup Threadsafe_DHCP_Interfaces 718 * @brief 719 * This interface is used to make the DHCP client running on the interface to renew its existing IP configuration to the 720 * DHCP server from whom it has leased the IP Configuration. 721 * This is done by sending a DHCP_REQUEST message from the client to the server after T1-Timer Expiry. 722 * It is the thread-safe way for calling dhcp_renew in the user space. */ 723 err_t netifapi_dhcp_renew(struct netif *netif); 724 725 726 /** @ingroup Threadsafe_DHCP_Interfaces 727 * @brief 728 * This interface is used to release the IP Configuration on a network interface that it has leased from the DHCP Server 729 * and informs the DHCP server that this IP Configuration is no longer needed by the client. 730 * This is done by sending a DHCP_RELEASE message from the client to the server. 731 * It is the thread-safe way for calling dhcp_release in the user space. */ 732 err_t netifapi_dhcp_release(struct netif *netif); 733 734 /** 735 * @ingroup Threadsafe_DHCP_Interfaces 736 * @brief 737 * This interface is used to free the memory allocated for DHCP during DHCP start. 738 * It is the thread-safe way for calling dhcp_cleanup in the user space. 739 * 740 */ 741 err_t netifapi_dhcp_cleanup(struct netif *netif); 742 743 /** @ingroup Threadsafe_DHCP_Interfaces 744 * @brief 745 * This interface is used to get the DHCP negotiation status for a network interface. 746 * It is the thread-safe way for calling dhcp_is_bound() in the user space. 747 */ 748 err_t netifapi_dhcp_is_bound(struct netif *netif); 749 750 #if LWIP_API_RICH 751 /** @ingroup Threadsafe_DHCP_Interfaces 752 * @brief 753 * This API is used to set a static DHCP structure to the netif. 754 * @note 755 * If this API is used before netifapi_dhcp_start(), the application needs to use 756 * netifapi_dhcp_remove_struct() instead of netifapi_dhcp_cleanup() to remove 757 * the struct dhcp. */ 758 err_t netifapi_dhcp_set_struct(struct netif *netif, struct dhcp *dhcp); 759 760 /** @ingroup Threadsafe_DHCP_Interfaces 761 * @brief 762 * This interface is used to remove the static DHCP structure from netif, which was set 763 * using the netifapi_dhcp_set_struct() API. 764 * @note 765 * The application needs to use this API instead of netifapi_dhcp_cleanup() if the 766 * DHCP structure is previously set on netif using netifapi_dhcp_set_struct(). */ 767 err_t netifapi_dhcp_remove_struct(struct netif *netif); 768 #endif /* LWIP_API_RICH */ 769 770 #if LWIP_DHCP_SUBSTITUTE 771 /** @ingroup Threadsafe_DHCP_Interfaces 772 * @brief 773 * This API is used to get MAC and IP of all the dhcp clients to the netif. 774 * 775 * @param[in] netif Indicates the netif structure on which DHCPC start. 776 * @param[out] clis_info To get the dhcp clients information. 777 * 778 * @returns 779 * ERR_OK : On success. \n 780 * Negative value : On failure. \n 781 * 782 * @note 783 * The clis_info got from this API must be freed by netifapi_dhcp_clients_info_free(). 784 * If the last got clis_info not freed, this API will fail with return value ERR_INPROGRESS. */ 785 err_t netifapi_dhcp_clients_info_get(struct netif *netif, struct dhcp_clients_info **clis_info); 786 787 /** @ingroup Threadsafe_DHCP_Interfaces 788 * @brief 789 * This API is used to free clis_info to the netif. 790 * 791 * @param[in] netif Indicates the netif structure on which DHCPC start. 792 * @param[in] clis_info To clis_info got from netifapi_dhcp_clients_info_get(). 793 * 794 * @returns 795 * ERR_OK : On success. \n 796 * Negative value : On failure. \n 797 * 798 * @note 799 * The clis_info must be got from netifapi_dhcp_clients_info_get(). */ 800 err_t netifapi_dhcp_clients_info_free(struct netif *netif, struct dhcp_clients_info **clis_info); 801 #endif /* LWIP_DHCP_SUBSTITUTE */ 802 #endif /* LWIP_DHCP */ 803 804 /** 805 * @defgroup Threadsafe_DHCPv6_Interfaces DHCPv6 Interfaces 806 * @ingroup Threadsafe_DHCP_Interfaces 807 * This section contains the Thread safe DHCPv6 interfaces. 808 * To be called from non-TCPIP threads 809 */ 810 #if LWIP_IPV6_DHCP6 811 /* 812 Func Name: netifapi_dhcp6_enable_stateful 813 */ 814 /** 815 * @ingroup Threadsafe_DHCPv6_Interfaces 816 * 817 * @brief 818 * This interface is used to enable stateful DHCPv6 client negotiation for a network interface (stateless disabled). 819 * If no DHCPv6 client instance is attached to this interface, a new client is created first. If a DHCPv6 client 820 * instance is already present and stateful DHCPv6 client has been enabled, it will return without doing anything. 821 * It is the thread-safe way for calling dhcp6_enable_stateful in the user space. 822 * 823 * @param[in] netif Indicates the lwIP network interface. 824 * 825 * @return 826 * ERR_OK: On success \n 827 * ERR_MEM: On failure due to memory \n 828 * ERR_VAL: On failure due to Illegal value or linklocal address is not preferred \n 829 * ERR_NOADDR: No available address 830 831 832 * @note 833 * \n 834 * - Only one addr of IA_NA is supported. Multiple addresses is not supported yet. 835 * - Not supported options : IA_TA/Relay/Authentication/Rapid Commit/User Class/Vendor Class/Vendor-specific 836 * Information/Interface-Id/Reconfigure Message/Reconfigure Accept/DOMAIN_LIST/IA_PD/IAPREFIX 837 * - First SOLICIT will not be sent until linklocal IPv6 address is REFERRED 838 * 839 * @par Related Topics 840 * netifapi_set_ip6_autoconfig_enabled() 841 * netifapi_dhcp6_release_stateful() 842 * netifapi_dhcp6_disable() 843 */ 844 err_t netifapi_dhcp6_enable_stateful(struct netif *netif); 845 846 /* 847 Func Name: netifapi_dhcp6_enable_stateless 848 */ 849 /** 850 * @ingroup Threadsafe_DHCPv6_Interfaces 851 852 * 853 * @brief 854 * This interface is used to enable stateless DHCPv6 client negotiation for a network interface (stateful disabled). 855 * If no DHCPv6 client instance is attached to this interface, a new client is created first. If a DHCPv6 client 856 * instance is already present and stateless DHCPv6 client has been enabled, it will return without doing anything. 857 * This interface only enables other config for DHCPv6. Autoconfig for IPv6 address will not be enabled by this 858 * interface. 859 * It is the thread-safe way for calling dhcp6_enable_stateless in the user space. 860 * 861 * @param[in] netif Indicates the lwIP network interface. 862 * 863 * @return 864 * ERR_OK: On success \n 865 * ERR_MEM: On failure due to memory \n 866 * ERR_VAL: On failure due to Illegal value 867 868 * @note 869 * \n 870 * - Only RA from one Router will be handled correctly. RAs from multi Routers will cause unexpected problem. 871 * - Device will send INFORM-REQUEST after every receved RA. 872 * 873 * @par Related Topics 874 * netifapi_dhcp6_disable() 875 */ 876 err_t netifapi_dhcp6_enable_stateless(struct netif *netif); 877 878 /* 879 Func Name: netifapi_dhcp6_disable 880 */ 881 /** 882 * @ingroup Threadsafe_DHCPv6_Interfaces 883 * 884 * @brief 885 * This interface is used to disable stateful or stateless DHCPv6 on a network interface. 886 * If no DHCPv6 client instance is attached to this interface, it will return without doing anything. 887 * If stateful DHCPv6 is enabled, it will try to send a RELEASE, but won't handle the REPLY of this RELEASE. 888 * It is the thread-safe way for calling dhcp6_disable in the user space. 889 * 890 * @param[in] netif Indicates the lwIP network interface. 891 * 892 * @return 893 * ERR_OK: On success \n 894 * ERR_VAL: On failure due to Illegal value 895 * 896 897 * @note 898 * \n 899 * - To disable stateful DHCPv6, call after netifapi_dhcp6_release_stateful. 900 */ 901 err_t netifapi_dhcp6_disable(struct netif *netif); 902 903 /* 904 Func Name: netifapi_dhcp6_release_stateful 905 */ 906 /** 907 * @ingroup Threadsafe_DHCPv6_Interfaces 908 909 * 910 * @brief 911 * This interface is used to try to send a RELEASE when stateful DHCPv6 is enabled on a network interface. 912 * If stateful DHCPv6 client is doing RELEASE, it will return without doing anything. 913 * If stateless DHCPv6 is enabled on a network interface, it will return ERR_VAL and do nothing else. 914 * If no DHCPv6 client instance is attached to this interface, it will return ERR_VAL and do nothing else. 915 * If stateful DHCPv6 is enabled and a valid IPv6 address is using, it will try to send a RELEASE and will 916 * handle the REPLY of this RELEASE. It will stop using the IPv6 address to be released as soon as the client 917 * begins the Release message exchange process. 918 * It is the thread-safe way for calling dhcp6_release_stateful in the user space. 919 * 920 * @param[in] netif Indicates the lwIP network interface. 921 * 922 * @return 923 * ERR_OK: On success \n 924 * ERR_VAL: On failure due to Illegal value 925 926 */ 927 err_t netifapi_dhcp6_release_stateful(struct netif *netif); 928 929 /* 930 Func Name: netifapi_dhcp6_cleanup 931 */ 932 /** 933 * @ingroup Threadsafe_DHCPv6_Interfaces 934 * 935 * @brief 936 * This interface is used to free the memory allocated for DHCPv6 during DHCPv6 enable. 937 * It is the thread-safe way for calling dhcp_cleanup in the user space. 938 * 939 * @param[in] netif Indicates the lwIP network interface. 940 * 941 * @return 942 * ERR_OK: On success \n 943 * ERR_VAL: On failure due to Illegal value 944 * 945 946 * @note 947 * \n 948 * - Call after DHCPv6 client is disabled. 949 * - Call netifapi_dhcp6_disable() before calling netifapi_dhcp6_cleanup. 950 */ 951 err_t netifapi_dhcp6_cleanup(struct netif *netif); 952 #endif /* LWIP_IPV6_DHCP6 */ 953 954 #if LWIP_AUTOIP 955 956 /** 957 * @ingroup Threadsafe_Network_Interfaces 958 * @par Description 959 * Call autoip_start() in a thread-safe way by running that function inside the tcpip_thread context. 960 961 * 962 * @param[in] netif Indicates the lwIP network interface. 963 * 964 * @returns 965 * ERR_OK: On success \n 966 * ERR_MEM: On failure due to memory \n 967 * ERR_VAL: On failure due to Illegal value. 968 */ 969 err_t netifapi_autoip_start(struct netif *netif); 970 971 /** 972 * @ingroup Threadsafe_Network_Interfaces 973 * @brief 974 * Thread-safe API to stop the AutoIP client. 975 * 976 * @param[in] netif Indicates the lwIP network interface. 977 * 978 * @returns 979 * ERR_OK: On success. \n 980 * ERR_ARG: On passing invalid arguments. 981 * 982 * @note 983 * - Call the autoip_stop API to stop the AutoIP service. 984 * - Use only for functions where there is only "netif" parameter. 985 */ 986 err_t netifapi_autoip_stop(struct netif *netif); 987 988 #endif /* LWIP_AUTOIP */ 989 990 #if LWIP_NETIF_LINK_CALLBACK && LWIP_NETIFAPI_LINK_CALLBACK 991 /* 992 Func Name: netifapi_netif_set_link_callback 993 */ 994 /** 995 * @ingroup Threadsafe_Network_Interfaces 996 * @brief 997 * This API is used to set callback to netif. This API is called whenever a link is brought up or down. 998 * 999 * @param[in] netif Indicates the lwIP network interface. 1000 * @param[in] link_callback The callback pointer. 1001 * 1002 * @returns 1003 * ERR_OK: This API always returns this value. \n 1004 */ 1005 err_t 1006 netifapi_netif_set_link_callback(struct netif *netif, netif_status_callback_fn link_callback); 1007 #endif /* LWIP_NETIF_LINK_CALLBACK && LWIP_NETIFAPI_LINK_CALLBACK */ 1008 1009 #if LWIP_NETIF_EXT_STATUS_CALLBACK 1010 /* 1011 Func Name: netifapi_netif_add_ext_callback 1012 */ 1013 /** 1014 * @ingroup Threadsafe_Network_Interfaces 1015 * @brief 1016 * This API is used to add an extended netif status callback (NSC). 1017 * 1018 * @param[in] callback Indicates the NSC data structure. 1019 * @param[in] fn The callback function pointer. 1020 * 1021 * @returns 1022 * ERR_OK: On success. \n 1023 * ERR_ARG: On passing invalid arguments. 1024 */ 1025 err_t netifapi_netif_add_ext_callback(netif_ext_callback_t *callback, netif_ext_callback_fn fn); 1026 1027 /* 1028 Func Name: netifapi_netif_remove_ext_callback 1029 */ 1030 /** 1031 * @ingroup Threadsafe_Network_Interfaces 1032 * @brief 1033 * This API is used to remove an extended netif status callback (NSC). 1034 * 1035 * @param[in] callback Indicates the NSC data structure. 1036 * 1037 * @returns 1038 * ERR_OK: On success. \n 1039 * ERR_VAL: On passing invalid arguments. 1040 */ 1041 err_t netifapi_netif_remove_ext_callback(netif_ext_callback_t *callback); 1042 #endif /* LWIP_NETIF_EXT_STATUS_CALLBACK */ 1043 1044 #if LWIP_NETIFAPI_MTU 1045 /* 1046 Func Name: netifapi_netif_set_mtu 1047 */ 1048 /** 1049 * @ingroup Threadsafe_Network_Interfaces 1050 * @brief 1051 * This API is used to set the MTU of the netif. Call this API whenever the MTU needs to be changed. 1052 * @param[in] netif Indicates the lwIP network interface. 1053 * @param[in] mtu Indicates the new MTU of the network interface. Valid values are 68 to 1500. 1054 * 1055 * @returns 1056 * ERR_OK: On success. \n 1057 * ERR_ARG: On passing invalid arguments. 1058 * 1059 * @note 1060 * - The value of the new mtu which is passed should be in the range 68 to 1500. 1061 * - On modifying the MTU, the MTU change comes into effect immediately. 1062 * - IP packets for existing connections are also sent according to new MTU. 1063 * - Ideally, the application must ensure that connections are terminated before MTU modification or at 1064 * init time to avoid side effects, since peer might be expecting a different MTU. 1065 * - Effective MSS for existing connection will not change, it might remain same. It is not 1066 * suggested to change the MTU at runtime. 1067 * - Only for new connections, effective MSS is used for connection setup. \n 1068 * 1069 */ 1070 err_t netifapi_netif_set_mtu(struct netif *netif, u16_t mtu); 1071 #endif /* LWIP_NETIFAPI_MTU */ 1072 1073 #if LWIP_NETIFAPI_IF_NUM 1074 /* 1075 Func Name: netifapi_netif_change_if_num 1076 */ 1077 /** 1078 * @ingroup Threadsafe_Network_Interfaces 1079 * @brief 1080 * This API is used to change the num of the netif. 1081 * @param[in] netif Indicates the lwIP network interface. 1082 * @param[in] num Indicates the new num of the network interface. Valid values are 0 to 9. 1083 * 1084 * @returns 1085 * ERR_OK: On success. \n 1086 * ERR_ARG: On passing invalid arguments. 1087 * ERR_VAL: On passing the same num in the netif_list. 1088 */ 1089 err_t 1090 netifapi_netif_change_if_num(struct netif *netif, u8_t num); 1091 #endif 1092 1093 #if LWIP_DHCPS 1094 1095 /* 1096 Func Name: netifapi_dhcps_start 1097 */ 1098 /** 1099 * @ingroup Threadsafe_DHCP_Interfaces 1100 * @brief 1101 * This API is used to start DHCPv4 Server on the netif. This should be called only 1102 once when the DHCPv4 Server needs to be started on the netif. 1103 * 1104 * @param[in] netif Indicates the lwIP network interface. 1105 * @param[in] start_ip Indicates the starting IP address of the DHCPv4 address pool. 1106 * @param[in] ip_num Indicates the number of IP addresses that need to be in the pool. 1107 * 1108 * @par Return values 1109 * ERR_OK: On success \n 1110 * ERR_ARG: On passing invalid arguments. \n 1111 * ERR_MEM: On trying to start a DHCPv4 server on a netif where DHCPv4 server is already running \n 1112 * 1113 * @par Note 1114 * - If the DHCPv4 scope (Address Pool) use the default configuration, then both 1115 * start_ip and ip_num must be NULL. 1116 * - If the DHCPv4 scope (Address Pool) is manually configured, then both start_ip And 1117 * ip_num must not be NULL. 1118 * - In case of default DHCPv4 scope (Address Pool) configuration, the default start IP is ((netif_ip & netif_mask) + 2). 1119 * - In case of manual DHCPv4 scope (Address Pool) configuration, start_ip should be in the same subnet of the netif. 1120 * - The total number of addresses in the DHCPv4 Scope will be the minimum of non-zero ip_num & LWIP_DHCPS_MAX_LEASE. 1121 * - No matter in case of default configuration or manual configuration, if the IP address of the DHCPv4 server lies in 1122 * the range of address pool, then the total number of addresses available in the pool for clients will be decreased 1123 * one, since one of the addresses in the pool has been taken up by the DHCPv4 Server and only others will be available 1124 * to the DHCPv4 Clients. \n 1125 * - In case of manual DHCPv4 scope configuration, if ip_start+ip_num goes beyond the maximum host IP, then the total 1126 * number of addresses in the pool will be from [ip_start, maximum host IP] only. 1127 * e.g. netmask is 255.255.255.0 and so maximum host IP is x.y.z.254, if ip_start+ip_num goes beyond x.y.z.254, 1128 * then the total number of addresses in the pool will be from [ip_start, x.y.z.254] only. 1129 */ 1130 err_t netifapi_dhcps_start(struct netif *netif, char *start_ip, u16_t ip_num); 1131 1132 /* 1133 Func Name: netifapi_dhcps_stop 1134 */ 1135 /** 1136 1137 * @ingroup Threadsafe_DHCP_Interfaces 1138 * 1139 * @brief 1140 * This API is used to stop DHCPv4 Server on the netif where a DHCPv4 server is running. 1141 * 1142 1143 * @param[in] netif Indicates the lwIP network interface. 1144 * @par Return values 1145 * ERR_OK: On success \n 1146 1147 * 1148 * @par Note 1149 * The DHCPv4 server can be restarted on a netif only after it is stopped on that netif. 1150 * 1151 */ 1152 err_t netifapi_dhcps_stop(struct netif *netif); 1153 1154 #if LWIP_NETIFAPI_DHCPS_IP 1155 err_t netifapi_dhcps_get_client_ip(struct netif *netif, u8_t *mac, u8_t maclen, ip_addr_t *ip); 1156 #endif 1157 #endif /* LWIP_DHCPS */ 1158 1159 #if DRIVER_STATUS_CHECK 1160 1161 /** 1162 * @ingroup Threadsafe_Network_Interfaces 1163 * @brief 1164 * This API is used to set the netif driver status to the "Driver Not Ready" state. the driver must call this API 1165 * to intimate the stack that the send buffer in the driver is full. 1166 * 1167 * @param[in] netif Indicates the lwIP network interface. 1168 * 1169 * @returns 1170 * ERR_OK: On success \n 1171 * ERR_ARG: On passing invalid arguments. \n 1172 */ 1173 err_t netifapi_stop_queue(struct netif *netif); 1174 1175 /** 1176 * @ingroup Threadsafe_Network_Interfaces 1177 * @brief 1178 * This API is used to set the netif driver status to the "Driver Ready" state. This API is called by the driver to 1179 * inform the stack that the driver send buffer is available to send after netifapi_stop_queue() was called 1180 * previously. 1181 * 1182 * @param[in] netif Indicates the lwIP network interface. 1183 * 1184 * @returns 1185 * ERR_OK: On success \n 1186 * ERR_ARG: On passing invalid arguments. \n 1187 */ 1188 err_t netifapi_wake_queue(struct netif *netif); 1189 #endif 1190 1191 #if LWIP_NETIFAPI_IF_INDEX 1192 /* @ingroup netifapi_netif */ 1193 err_t netifapi_netif_name_to_index(const char *name, u8_t *uIndex); 1194 /* @ingroup netifapi_netif */ 1195 err_t netifapi_netif_index_to_name(u8_t uIndex, char *name); 1196 1197 /* @ingroup netifapi_netif */ 1198 err_t netifapi_netif_nameindex_all(struct if_nameindex **pp_if_list); 1199 #endif /* LWIP_NETIFAPI_IF_INDEX */ 1200 1201 #if LWIP_NETIF_HOSTNAME 1202 /* 1203 Func Name: netifapi_set_hostname 1204 */ 1205 /** 1206 * @ingroup Threadsafe_DHCP_Interfaces 1207 1208 * 1209 * @brief 1210 * This API is used to set the hostname of the netif, which is using in DHCP 1211 * message. The hostname string lenght should be less than NETIF_HOSTNAME_MAX_LEN, 1212 * otherwise the hostname will truncate to (NETIF_HOSTNAME_MAX_LEN-1). 1213 * 1214 * @param[in] netif Indicates the lwIP network interface. 1215 * @param[in] hostname The new hostname to use. 1216 * @param[in] namelen The hostname string length, should be within the scope of 0~NETIF_HOSTNAME_MAX_LEN-1. 1217 * 1218 * @return 1219 * ERR_OK: On success \n 1220 * ERR_ARG: On passing invalid arguments. \n 1221 * 1222 1223 */ 1224 err_t netifapi_set_hostname(struct netif *netif, char *hostname, u8_t namelen); 1225 1226 #if LWIP_NETIF_GET_HOSTNAME 1227 /* 1228 Func Name: netifapi_get_hostname 1229 */ 1230 /** 1231 * @ingroup Threadsafe_DHCP_Interfaces 1232 1233 * 1234 * @brief 1235 * This API is used to get the hostname of the netif, which is using in DHCP 1236 * message. the hostname buffer length shoud not smaller than NETIF_HOSTNAME_MAX_LEN, 1237 * otherwise it will get a truncated hostname. 1238 * 1239 * @param[in] netif Indicates the lwIP network interface. 1240 * @param[out] hostname The buffer to stroe hostname string of the netif. 1241 * @param[in] namelen The hostname string buffer length. 1242 * 1243 * @return 1244 * ERR_OK: On success \n 1245 * ERR_ARG: On passing invalid arguments. \n 1246 * 1247 1248 */ 1249 err_t netifapi_get_hostname(struct netif *netif, char *hostname, u8_t namelen); 1250 #endif /* LWIP_NETIF_GET_HOSTNAME */ 1251 #endif /* LWIP_NETIF_HOSTNAME */ 1252 1253 #if LWIP_DHCP_VENDOR_CLASS_IDENTIFIER 1254 /* 1255 Func Name: netifapi_set_vci 1256 */ 1257 /** 1258 * @ingroup Threadsafe_DHCP_Interfaces 1259 1260 * 1261 1262 * @brief 1263 * This API is used to set the vendor class identifier information, which is used in 1264 * DHCP message. Length of vendor class identifier information string 1265 * should be not more than DHCP_VCI_MAX_LEN(default 32), otherwise it 1266 * will return with ERR_ARG. vci_len is the real length of vendor class identifier 1267 * information string. 1268 * 1269 * @param[in] vci The new vendor class identifier information to use. 1270 * It is a string of n octets [RFC2132 Section 9.13]. 1271 * @param[in] vci_len The length of vendor class identifier information string, 1272 * should be not more than DHCP_VCI_MAX_LEN. 1273 * 1274 * @return 1275 * ERR_OK: On success \n 1276 * ERR_ARG: On passing invalid arguments. \n 1277 * ERR_VAL: On failure. \n 1278 1279 */ 1280 err_t netifapi_set_vci(char *vci, u8_t vci_len); 1281 1282 #if LWIP_DHCP_GET_VENDOR_CLASS_IDENTIFIER 1283 /* 1284 Func Name: netifapi_get_vci 1285 */ 1286 /** 1287 * @ingroup Threadsafe_DHCP_Interfaces 1288 1289 * @brief 1290 * This API is used to get the vendor class identifier information, which is used in 1291 * DHCP message. Length of the buffer which is used to store vendor 1292 * class identifier string must be not smaller than DHCP_VCI_MAX_LEN, otherwise 1293 * it will return with ERR_ARG. Default value of DHCP_VCI_MAX_LEN is 32. 1294 * If there is no vendor class identifier information related to DHCP, it will 1295 * return with ERR_VAL. 1296 * 1297 * @param[out] vci The buffer to store vendor class identifier string of DHCP. 1298 * @param[in,out] vci_len The length of buffer to store vendor class identifier string, 1299 * and the real length of the vendor class identifier string. 1300 * 1301 * @return 1302 * ERR_OK: On success \n 1303 * ERR_ARG: On passing invalid arguments. \n 1304 * ERR_VAL: On failure. \n 1305 * 1306 */ 1307 err_t netifapi_get_vci(char *vci, u8_t *vci_len); 1308 #endif /* LWIP_DHCP_GET_VENDOR_CLASS_IDENTIFIER */ 1309 #endif /* LWIP_DHCP_VENDOR_CLASS_IDENTIFIER */ 1310 1311 #if LWIP_IP_FILTER 1312 /* 1313 Func Name: netifapi_set_ip_filter 1314 */ 1315 /** 1316 * @ingroup Threadsafe_Network_Interfaces 1317 1318 * 1319 1320 * 1321 * @brief 1322 * This API is used to set an ip filter for ip packets. The filter function will be called when 1323 * a packet pass to ip_input. User can define rules to accept or drop a packet in filter_fn, 1324 * returning 0 means accept, -1 means drop. 1325 * 1326 * @param[in] filter_fn The filter function which user implement. Prototype for filter_fn 1327 * is err_t (*ip_filter_fn)(const struct pbuf *p, struct netif *inp); 1328 * NULL indicate to disable the filter. 1329 * @param[in] type IP address type as IPv4 or IPv6. IPADDR_TYPE_V4 is for IPv4 and IPADDR_TYPE_V6 1330 * is for IPv6. 1331 * 1332 * @return 1333 * ERR_OK: On success \n 1334 * ERR_VAL: On failure due to Illegal value 1335 * 1336 1337 * 1338 * @note 1339 * 1. User can access pbuf in filter_fn, modify pbuf data and access pbuf after filter_fn return are 1340 * not allowed. \n 1341 * 2. User can define rules to accept or drop a packet in filter_fn, return 0 means accept the 1342 * packet, -1 means drop the packet and user no need to care about free pbuf. \n 1343 * 3. Rules in filter_fn which user implement should be light and not complex, sleep and other block 1344 * function must not be called, or it will have a negative influence to TCP/IP stack. \n 1345 * 4. Filter only effect to IP packet. 1346 * 1347 * 1348 * @endcond 1349 */ 1350 err_t 1351 netifapi_set_ip_filter(ip_filter_fn filter_fn, int type); 1352 #endif /* LWIP_IP_FILTER */ 1353 1354 #if LWIP_IPV6 1355 #if LWIP_NETIF_NBR_CACHE_API 1356 1357 /* 1358 Func Name: netifapi_add_ipv6_neighbor 1359 */ 1360 /** 1361 * @ingroup Threadsafe_Network_Interfaces 1362 1363 * 1364 * @brief 1365 * This API is used to add a neighbor entry to the neighbor cache table. User 1366 * can use this to add both static and non-sttaic neighbor. The neighbor state 1367 * passed to the API will determine if the neighbor to be added is static or 1368 * dynamic. To add static neighbor using this API user must set the confiburation 1369 * LWIP_ND6_STATIC_NBR to 1 1370 1371 * 1372 * @param[in] netif Indicates the network interface object through which this neighbor can be 1373 reached. 1374 * @param[in] nbr Provides information about the neighbor to be added. It includes 1375 * IPv6 address of the neighbor, Its hardware 1376 * address and its length, current state of the 1377 neighbor, and Initial reachable duration of the neighbor. 1378 * 1379 * @return 1380 * ERR_OK: On success \n 1381 * ERR_ARG: If any parameter is invalid \n 1382 * ERR_VAL: On failure due to illegal value \n 1383 * ERR_MEM: If no more space available \n 1384 * ERR_NBR_OVERWRITEFORBIDDEN: If try to add a neighbor that already exists 1385 * 1386 1387 * 1388 * @note 1389 * 1. The allowed states for the neighbor are ND6_STATE_REACHABLE(2) for non 1390 * static neighbor and ND6_STATE_PERMANENT(6) for static neighbor \n 1391 * 2. For static neighbor user must set the reachable time to 0. \n 1392 * 3. For non static neighbors the initial reachable time cannot be greater than 1393 * the LWIP_ND6_REACHABLE_TIME configured. Once the rechable time set by the 1394 * user expires, neighbor will move to stale state. When it again moves to the 1395 * reachable state, the rechable time will be set to LWIP_ND6_REACHABLE_TIME. \n 1396 * 4. If you try to add a neighbor that already exists and it is not a static 1397 * neighbor we do not allow it to be overwritten. For static neighbor we will 1398 * update the new hw address. \n 1399 * 5. To use this API user MUST set LWIP_NETIF_NBR_CACHE_API configuration to 1. 1400 * \n 1401 1402 */ 1403 err_t netifapi_add_ipv6_neighbor(struct netif *netif, struct ipv6_neighbor *nbr); 1404 1405 /* 1406 Func Name: netifapi_del_ipv6_neighbor 1407 */ 1408 /** 1409 * @ingroup Threadsafe_Network_Interfaces 1410 1411 * @brief 1412 * This API is used to delete a neighbor entry to the neighbor cache table. User 1413 * can use this to delete both static and non-sttaic neighbor. 1414 * 1415 * @param[in] netif Indicates the network interface object which the neighbor is part of. 1416 * @param[in] ipaddr Indicates the IP address of the neighbor to remove. 1417 * 1418 * @return 1419 * ERR_OK: On success \n 1420 * ERR_ARG: If any parameter is invalid \n 1421 * ERR_NBR_NOTFOUND: If the neighbor does not exist 1422 1423 * @note 1424 * 1. If the neighbor to be deleted has an associated default router entry we 1425 * will remove the default route also. \n 1426 * 1427 * 2. To use this API user MUST set LWIP_NETIF_NBR_CACHE_API configuration to 1 1428 * \n 1429 */ 1430 err_t netifapi_del_ipv6_neighbor(struct netif *netif, struct ip6_addr *ipaddr); 1431 1432 /* 1433 Func Name: netifapi_query_ipv6_neighbor 1434 */ 1435 /** 1436 * @ingroup Threadsafe_Network_Interfaces 1437 1438 * @brief 1439 * This API is used to query a neighbor entry from the neighbor cache table. User 1440 * can use this to query both static and non-static neighbor. 1441 * 1442 * @param[in] netif Indicates the network interface object which the neighbor is part of. 1443 * @param[in] ipaddr Indicates the IP address of the neighbor to be queried. 1444 * @param[out] nbrinfo Indicates information about the neighbor. 1445 * 1446 * @return 1447 * ERR_OK: On success \n 1448 * ERR_ARG: If any parameter is invalid \n 1449 * ERR_NBR_NOTFOUND: If the neighbor does not exist 1450 1451 * 1452 * @note 1453 * 1. The nbrinfo parameter must be a valid memory of type struct ipv6_neighbor. \n 1454 * 1455 * 2. To use this API user must set LWIP_NETIF_NBR_CACHE_API configuration to 1 1456 * \n 1457 */ 1458 err_t netifapi_query_ipv6_neighbor(struct netif *netif, struct ip6_addr *ipaddr, 1459 struct ipv6_neighbor *nbrinfo); 1460 #endif /* LWIP_NETIF_NBR_CACHE_API */ 1461 1462 #if LWIP_6LOWPAN 1463 /* 1464 Func Name: netifapi_set_6lowpan_context 1465 */ 1466 /** 1467 * @ingroup Threadsafe_Network_Interfaces 1468 * @brief 1469 * This API is used to add 6lowpan context identifier. 1470 * 1471 * @param[in] netif Indicates the network interface object which this network prefix is part of. 1472 * @param[in] ctxid Indicates the identifier (ID) associated with the context. This value must be within the 1473 * range 0 to 15. 1474 * @param[out] context_prefix Indicates the IPv6 prefix to be represented by the context ID. 1475 * 1476 * @return 1477 * ERR_OK: On success \n 1478 * ERR_ARG: If any parameter is invalid \n 1479 * ERR_MEM: No more free CB available 1480 * 1481 * 1482 * @par Note 1483 * 1. If the user adds a 6lowpan context with context ID that already exists, we 1484 * will overwrite the existing one. \n 1485 * 2. To use this API, the user must set LWIP_6LOWPAN configuration to 1. \n 1486 * 3. User must also set LWIP_6LOWPAN_NUM_CONTEXTS to a value greater than 0 as per 1487 * the need. 1488 * 4. If netifapi_set_6lowpan_context returns ERR_MEM then user must call the 1489 * netifapi_remove_6lowpan_context() API to free some unused context then call the 1490 * netifapi_set_6lowpan_context() API to add the new context. 1491 * 5. If you have multiple interfaces, context IDs on the interfaces must not be 1492 * same as we use the context ID as a unique key. This limitation will be removed in a future version. 1493 * \n 1494 */ 1495 err_t netifapi_set_6lowpan_context(struct netif *netif, u8_t ctxid, 1496 struct ip6_addr *context_prefix); 1497 1498 /* 1499 Func Name: netifapi_remove_6lowpan_context 1500 */ 1501 /** 1502 * @ingroup Threadsafe_Network_Interfaces 1503 * @brief 1504 * This API is used to remove 6lowpan context identifier. 1505 * 1506 * @param[in] netif Indicates the network interface object which this network prefix is part of. 1507 * @param[in] ctxid Indicates the identifier (ID) associated with the context. This value must be within the range 1508 * 0 to 15. 1509 * 1510 * @return 1511 * ERR_OK: On success \n 1512 * ERR_ARG: If any parameter is invalid \n 1513 * ERR_LOWPAN_CTX_NOTFOUND: If the given context id doesn't exists 1514 * 1515 * \n 1516 */ 1517 err_t netifapi_remove_6lowpan_context(struct netif *netif, u8_t ctxid); 1518 1519 #endif /* LWIP_6LOWPAN */ 1520 1521 #if LWIP_ND6_STATIC_DEFAULT_ROUTE 1522 /* 1523 Func Name: netifapi_add_ipv6_static_default_route 1524 */ 1525 /** 1526 * @ingroup Threadsafe_Network_Interfaces 1527 1528 * @brief 1529 * This API is used to add a static deafult route entry. It adds the 1530 * corresponding non static neighbor cache entry if the neighbor does not exist. 1531 1532 * @param[in] netif Indicates the network interface which this default route belongs to. 1533 * @param[in] router_addr Indicates the ink local IPv6 address of the deafult route entry. 1534 * 1535 * @return 1536 * ERR_OK: On success \n 1537 * ERR_ARG: If any parameter is invalid \n 1538 * ERR_DEFAULT_ROUTE_EXISTS: Default route already exists \n 1539 * ERR_NO_FREE_ENTRY: No free 1540 * 1541 * @note 1542 * 1. To use this API user MUST set LWIP_ND6_STATIC_DEFAULT_ROUTE configuration to 1. 1543 * \n 1544 1545 * 1546 */ 1547 err_t netifapi_add_ipv6_static_default_route(struct netif *netif, 1548 struct ip6_addr *router_addr); 1549 1550 /* 1551 Func Name: netifapi_del_ipv6_static_default_route 1552 */ 1553 /** 1554 * @ingroup Threadsafe_Network_Interfaces 1555 1556 * 1557 * @brief 1558 * This API is used to delete a static default route entry. 1559 * 1560 1561 * @param[in] netif Indicates the network interface which this default route belongs to. 1562 * @param[in] router_addr Indicates the link local IPv6 address of the default route entry. 1563 * 1564 * @return 1565 * ERR_OK: On success \n 1566 * ERR_ARG: If any parameter is invalid \n 1567 * ERR_DEFAULT_ROUTER_NOTFOUND: default route does not exists 1568 * 1569 * @note 1570 * 1. To use this API the user must set LWIP_ND6_STATIC_DEFAULT_ROUTE configuration to 1. 1571 * \n 1572 * N/A 1573 * 1574 */ 1575 err_t netifapi_del_ipv6_static_default_route(struct netif *netif, 1576 struct ip6_addr *router_addr); 1577 1578 #endif /* LWIP_ND6_STATIC_DEFAULT_ROUTE */ 1579 1580 #if LWIP_ND6_STATIC_PREFIX 1581 #define USE_PREFIX_AUTOCONFIG_AUTONOMOUS 0x01 1582 /* 1583 Func Name: netifapi_add_static_prefix 1584 */ 1585 /** 1586 * @ingroup Threadsafe_Network_Interfaces 1587 1588 * @brief 1589 * This API is used to add static network prefix. 1590 * 1591 1592 * 1593 * @param[in] netif Indicates the network interface which this default route belongs to. 1594 * @param[in] prefix Indicates the network prefix. 1595 * @param[in] flags Indicates the address auto configuration flag. 1596 * 1597 * 1598 * @return 1599 * ERR_OK: On success \n 1600 * ERR_ARG: If any parameter is invalid \n 1601 * ERR_PREFIX_EXISTS: Given prefix already exists \n 1602 * ERR_NO_FREE_ENTRY: No free entry exists to add this prefix. 1603 * 1604 1605 * @par Note 1606 * 1. If the address needs to be auto configured using this prefix to be added, then the user must 1607 * set the USE_PREFIX_AUTOCONFIG_AUTONOMOUS flag. \n 1608 * 2. To use this API the user must set LWIP_ND6_STATIC_PREFIX configuration to 1. 1609 * \n 1610 */ 1611 err_t netifapi_add_static_prefix(struct netif *netif, struct ip6_addr *prefix, 1612 u8_t flags); 1613 /* 1614 Func Name: netifapi_del_static_prefix 1615 */ 1616 /** 1617 * @ingroup Threadsafe_Network_Interfaces 1618 1619 * 1620 * @brief 1621 * This API is used to remove static network prefix. When the prefix is removed 1622 * address configured from this prefix on the network interface will also be 1623 * removed. 1624 * 1625 * @param[in] netif Indicates the network interface which this default route belongs to. 1626 * @param[in] prefix Indicates the network prefix. 1627 * 1628 * 1629 * @return 1630 * ERR_OK: On success \n 1631 * ERR_ARG: If any parameter is invalid \n 1632 * ERR_PREFIX_NOT_FOUND: Prefix to be removed is not found. \n 1633 * ERR_VAL: If prefix to be removed is not a static one 1634 * 1635 1636 * @note 1637 * 1. To use this API the user must set the LWIP_ND6_STATIC_PREFIX configuration to 1. 1638 * \n 1639 */ 1640 err_t netifapi_del_static_prefix(struct netif *netif, struct ip6_addr *prefix); 1641 #endif /* LWIP_ND6_STATIC_PREFIX */ 1642 1643 #if LWIP_ND6_ROUTER 1644 err_t netifapi_set_ra_enable(struct netif *netif, u8_t ra_enable); 1645 err_t netifapi_set_ipv6_forwarding(struct netif *netif, u8_t forwarding); 1646 err_t netifapi_set_accept_ra(struct netif *netif, u8_t accept_ra); 1647 #endif 1648 1649 #if LWIP_6LOWPAN 1650 err_t netifapi_set_6lowpan_enable(struct netif *netif, u8_t enable); 1651 #endif 1652 1653 #endif /*LWIP_IPV6*/ 1654 1655 #if LWIP_MAC_SECURITY 1656 1657 /* 1658 Func Name: netifapi_set_authentication_status 1659 */ 1660 /** 1661 * @ingroup Threadsafe_Network_Interfaces 1662 1663 * 1664 * @brief 1665 * This API is used by the MAC driver layer to indicate network interface 1666 * about the status of the authentication procedure. 1667 * 1668 * @param[in] netif Indicates the network interface which this default route belongs to. 1669 * @param[in] authstatus Indicates the authentication procedure status. It can be 1670 * either AUTHENTICATION_SUCCESS or 1671 * AUTHENTICATION_FAILURE. 1672 * 1673 * 1674 * @return 1675 * ERR_OK: On success \n 1676 * ERR_ARG: If any parameter is invalid \n 1677 * ERR_PREFIX_NOT_FOUND: Prefix to be removed is not found. \n 1678 * ERR_VAL: If prefix to be removed is not a static one \n 1679 * 1680 * 1681 * @note 1682 * 1. To use this API the user must set the LWIP_MAC_SECURITY configuration to 1. \n 1683 * 1684 * 2. Currently when user adds a network interface of type PLC, we will set 1685 * a flag NETIF_FLAG_MAC_SECURITY_SUPPORT to the interface object to 1686 * indicate that this interface will have MAC layer security and we need to 1687 * apply below mentioned rule for the network traffic via this network interface. \n 1688 * 3. When the user enables MAC layer security its considered that all the traffic 1689 * to and from the network will be secured using the MAC layer security. \n 1690 * 4. When MAC layer security is enabled for application messages sent or received 1691 * via TCP or UDP protocols over IPv6, by default all will be secure, unless the 1692 * user allows unsecure traffic by setting the socket option. \n 1693 * 5. For IPv6 layer control messages, all traffic will be secure by default. We 1694 * will consider exception for the ND6 messages like (NS/RS) which an already 1695 * joined router/host can receive from a new node. We will also add exception 1696 * for echo request send to the link local addresses. \n 1697 * 6. Currently in smart grid network with PLC or RF there will be no RS traffic so 1698 * we can ignore that. There will be NS/NA traffic from an unauthorized host/ 1699 * router to an authorized router (i) or from authorized router to the new un- 1700 * authorized host/router (ii). These two kinds of NS/NA traffic need to be 1701 * allowed unsecure \n 1702 * 7. For a new node, once this API is called and flag is set the outgoing NS 1703 * message will also be always secure.\n 1704 * 1705 */ 1706 err_t netifapi_set_authentication_status(struct netif *netif, 1707 u8_t authstatus); 1708 1709 #endif /*LWIP_MAC_SECURITY*/ 1710 1711 #if LWIP_LOWPOWER 1712 err_t netifapi_enable_lowpower(void); 1713 err_t netifapi_disable_lowpower(void); 1714 #endif 1715 1716 #if LWIP_IPV4 && LWIP_ARP 1717 /* 1718 Func Name: netifapi_ip_to_mac 1719 */ 1720 /** @ingroup Threadsafe_Network_Interfaces 1721 * @brief 1722 * This API is used to get MAC address through IPv4 address. 1723 * 1724 * @param[in] ip Indicates the IPv4 address to find related MAC address. 1725 * @param[out] mac The buffer to record the related MAC address. 1726 * @param[in/out] maclen As in parameter, indicates the length of mac buffer. 1727 * As out parameter, indicates the length of related MAC address. 1728 * 1729 * @returns 1730 * ERR_OK : On success. \n 1731 * Negative value : On failure. \n 1732 */ 1733 err_t netifapi_ip_to_mac(const ip4_addr_t *ip, u8_t *mac, u8_t *maclen); 1734 #endif 1735 1736 #if defined (__cplusplus) && __cplusplus 1737 } 1738 #endif 1739 1740 #endif /* LWIP_NETIF_API */ 1741 1742 #endif /* LWIP_HDR_NETIFAPI_H */ 1743