Usage

API declarations

Declarations for all sequential API types and functions may be obtained by including the <lwip/api.h> header file:

#include <lwip/api.h>

Types

Objects of type struct netconn and struct netbuf are intended to be used as opaque types and the structure contents are intended to be maintained and viewed only by lwIP itself. User applications accessing internal members do so at their own risk, and future API compatibility is not guaranteed, nor is thread synchronization since lwIP is entitled to change structure contents at any time.

IP address representation

Depending on the lwIP configuration some API functions take an IP address, which can either be an IPv4 or an IPv6 address.

The IPv4 type struct ip_addr may be accessed as if it has the following structure:

struct ip_addr {
  u32_t addr;
};
           
The IPv6 type struct ip6_addr may be accessed as if it has the following structure:
struct ip6_addr {
  u32_t addr[4];
};
           

Caution

API users must use the declarations of these structures from the header file <lwip/ip_addr.h> which is included implicitly by <lwip/api.h>. These types must not be declared by the application itself.

To make it easier to work with either IPv4 or IPv6 addresses the type ipX_addr_t is provided. This is a union of the IPv4 and IPv6 address structures, and may be accessed as if it has the following structure:

typedef union {
  ip_addr_t ip4;
  ip6_addr_t ip6;
} ipX_addr_t;
           

See the Section called ipX Helpers for an overview of the IP version neutral address support. As with the caveat regarding the declarations of the specific IPv4 and IPv6 address structures, the ipX declarations should be accessed via including the <lwip/ip_addr.h> header file.

IPv4 Addresses

For convenience, predefined struct ip_addr instances are provided for the special cases of "any" IP address (0.0.0.0), and the global broadcast address (255.255.255.255). These instances can be accessed with the macro defines IP_ADDR_ANY and IP_ADDR_BROADCAST which return values of type struct ip_addr *.

The addr field is a 32-bit integral value representing the IP address in network byte order (not host byte order).

A variety of convenience function-like macros exist for manipulation or evaluation of IP addresses:

IP_ADDR_ANY

This macro evaluates to an expression of type struct ip_addr * identifying an IP address structure which can be used to represent the special "any" IP address 0.0.0.0.

IP_ADDR_BROADCAST

This macro evaluates to an expression of type struct ip_addr * identifying an IP address structure which can be used to represent the special global IP address 255.255.255.255.

IN_CLASSA(a)

An expression which evaluates to non-zero if a (of type u32_t and in host byte order) is a class A internet address.

IN_CLASSB(a)

An expression which evaluates to non-zero if a (of type u32_t and in host byte order) is a class B internet address.

IN_CLASSC(a)

An expression which evaluates to non-zero if a (of type u32_t and in host byte order) is a class C internet address.

IN_CLASSD(a)

An expression which evaluates to non-zero if a (of type u32_t and in host byte order) is a class D internet address.

IP4_ADDR(ipaddr, a, b, c, d)

Sets ipaddr (of type struct ip_addr *) to the internet address a.b.c.d. For example:

  struct ip_addr host;
  IP4_ADDR(&host, 192, 168, 1, 1);
                

ip_addr_cmp(addr1, addr2)

Returns non-zero if the arguments addr1 and addr2, both of type struct ip_addr * are identical. Zero if they differ.

ip_addr_netcmp(addr1, addr2, mask)

Returns non-zero if the arguments addr1 and addr2, both of type struct ip_addr * are on the same network, as indicated by the network mask mask which is itself also of type struct ip_addr *. Zero if they are on different networks.

htons(s)

Portably converts s of type u16_t from host byte order to a u16_t in network byte order.

ntohs(s)

Portably converts s of type u16_t from network byte order to a u16_t in host byte order.

htonl(l)

Portably converts l of type u32_t from host byte order to a u32_t in network byte order.

ntohl(l)

Portably converts l of type u32_t from network byte order to a u32_t in host byte order.

Some further potentially useful macro definitions can be viewed in <lwip/ip_addr.h>.

IPv6 Addresses

The header file <lwip/ip6_addr.h> (which is included by default from <lwip/api.h>) contains definitions for many IPv6 address convenience function-like macros, as well as utility function prototypes.

The following is not an exhaustive list, so the reader is recommended to inspect the header file to get a complete overview of the IPv6 address support macros and functions.

IP6_ADDR_ANY

This macro evaluates to an expression of type struct ip6_addr * identifying an IP address structure which can be used to represent the special "any" IPv6 address ::/128. It actually just returns the address of the exported ip6_addr_any variable.

ip6_addr_copy(dest, src)

This implements a fast (no NULL check) address copy.

ip6_addr_set(dest, src)

Set the dest address from the supplied src. If src is NULL the destination is written with zeroes.

ip6_addr_set_zero(ip6addr)

Sets the ip6addr address to all zeroes.

ip6_addr_set_any(ip6addr)

This explicitly sets the IP6_ADDR_ANY address value.

ip6_addr_set_loopback(ip6addr)

This sets the destination ip6addr parameters to the ::1 loopback address.

ip6_addr_set_hton(dest, src)

Copy the src address to the dest address converting from host to network byte order.

ip6_addr_netcmp(addr1, addr2)

An expression which evaluates to non-zero if the supplied addr1 and addr2 parameters are on the same network, by comparing the most-significant 64-bits of the addresses.

ip6_addr_cmp(addr1, addr2)

An expression which evaluates to non-zero if there is an exact match between the supplied addr1 and addr2 parameters.

ip6_get_subnet_id(ip6addr)

This returns in host byte order the 16-bit subnet identifier.

ip6_addr_isany(ip6addr)

An expression which evaluates to non-zero if ip6addr matches the IP6_ADDR_ANY address (all zeroes).

ip6_addr_isglobal(ip6addr)

An expression which evaluates to non-zero if the supplied ip6addr is a valid global address.

ip6_addr_islinklocal(ip6addr)

An expression which evaluates to non-zero if the ip6addr parameter is a valid link-local address.

ip6_addr_issitelocal(ip6addr)

An expression which evaluates to non-zero if the ip6addr parameter is a valid site-local address.

ip6_addr_isuniquelocal(ip6addr)

An expression which evaluates to non-zero if the ip6addr parameter is a valid unique link-local address.

ip6_addr_ismulticast(ip6addr)

An expression which evaluates to non-zero if the supplied ip6addr is a valid multicast address.

There are various other function-like macros provided to further decode whether the multicast address is a loopback, link-local, admin-local, global, etc. address. The definitions for these variants can be found by inspecting the <lwip/ip6_addr.h> header file.

ip6_addr_isallnodes_iflocal(ip6addr)

An expression which evaluates to non-zero if the supplied ip6addr matches the IPv6 ff01::1 loopback "all nodes" address.

ip6_addr_isallnodes_linklocal(ip6addr)

An expression which evaluates to non-zero if the supplied ip6addr matches the IPv6 link-local "all nodes" address.

ip6_addr_isallrouters_linklocal(ip6addr)

An expression which evaluates to non-zero if the supplied ip6addr matches the IPv6 link-local "all routers" address.

ip6_addr_set_allnodes_linklocal(ip6addr)

Sets the given ip6addr to the ff02::1 link-local "all nodes" multicast address.

ip6_addr_set_allrouters_linklocal(ip6addr)

Sets the given ip6addr to the ff02::2 link-local "all routers" multicast address.

ip6_addr_isinvalid(addr_state)

An expression which evaluates to non-zero if the supplied addr_state parameter is IP6_ADDR_INVALID.

ip6_addr_isvalid(addr_state)

An expression which evaluates to non-zero if the supplied addr_state parameter denotes a valid address state, where the IP6_ADDR_VALID bitmask is set.

ip6_addr_istentative(addr_state)

An expression which evaluates to non-zero if the supplied addr_state parameter has the IP6_ADDR_TENTATIVE bitmask set.

ip6_addr_ispreferred(addr_state)

An expression which evaluates to non-zero if the supplied addr_state parameter is IP6_ADDR_PREFERRED.

ip6_addr_isdeprecated(addr_state)

An expression which evaluates to non-zero if the supplied addr_state parameter is IP6_ADDR_DEPRECATED.

int ip6addr_aton(const char *cp, ip6_addr_t *addr)

Checks whether cp is a valid ASCII representation of an IPv6 address, and if valid converts it to the binary IPv6 address destination addr. The function returns 1 on successful conversion, or 0 on failure.

char *ip6addr_ntoa_r(const ip6_addr_t *addr, char *buf, int buflen)

Converts the binary IPv6 address addr into an ASCII representation written into the supplied buf buffer of buflen bytes.

Returns the buf parameter on success if the buffer has been updated to hold the ASCII address representation, or NULL if the buffer was too small.

ipX Helpers

Instead of directly referencing the IPv4 or IPv6 versions of the utility routines, applications should ideally use the common ipX_* variants. These functions, and function-like macros, take as their first parameter a boolean is_ipv6 value denoting when zero that the referenced addresses are IPv4 structures, or when non-zero that the referenced addresses are IPv6 structures. Note: If IPv6 support is not enabled for lwIP then the ipX_* implementations default to only using IPv4 addresses.

ipX_addr_copy(is_ipv6, dest, src)

This implements a fast (no NULL check) address copy.

ipX_addr_set(is_ipv6, dest, src)

Set the dest address from the supplied src. If src is NULL the destination is written with zeroes.

ipX_addr_set_ipaddr(is_ipv6, dest, src)

Sets the dest address parameter from the specified src. If src is NULL the destination is written with zeroes.

ipX_addr_set_zero(is_ipv6, ipaddr)

Sets the address to all zeroes. This is normally the ANY address.

ipX_addr_set_any(is_ipv6, ipaddr)

This explicitly sets the ANY address.

ipX_addr_set_loopback(is_ipv6, ipaddr)

This sets the destination ipaddr to the respective loopback interface address. For IPv4 this is 127.0.0.1 and ::1 for IPv6.

ipX_addr_set_hton(is_ipv6, dest, src)

Copy the src address to the dest address converting from host to network byte order.

ipX_addr_cmp(is_ipv6, addr1, addr2)

An expression which evaluates to non-zero if there is an exact match between the supplied addr1 and addr2 parameters.

ipX_addr_isany(is_ipv6, ipaddr)

An expression which evaluates to non-zero if ipaddr is NULL or points at the ANY address value.

ipX_addr_ismulticast(is_ipv6, ipaddr)

An expression which evaluates to non-zero if ipaddr references a valid multicast address value.

ipX_addr_debug_print(is_ipv6, debug, ipaddr)

This debugging helper macro will output the raw IPv4 or IPv6 address via the printf-alike debug support calls if the relevant lwIP debugging option specified by the debug parameter is enabled.

Error codes

While the BSD sockets API uses POSIX standard error codes (ENOMEM, EINVAL, etc.) the lwIP sequential API has its own separate set of error code definitions.

These error definitions are used by any API function that returns a value of type err_t. The following table indicates possible error code values and their meaning:

Table 153-1. lwIP sequential API error codes

CodeMeaning
ERR_OKNo error, operation successful.
ERR_MEMOut of memory error.
ERR_BUFBuffer error.
ERR_ABRTConnection aborted.
ERR_RSTConnection reset.
ERR_CLSDConnection closed.
ERR_CONNNot connected.
ERR_VALIllegal value.
ERR_ARGIllegal argument.
ERR_RTERouting problem.
ERR_USEAddress in use.
ERR_IFLow-level network interface error.
ERR_ISCONNAlready connected.
ERR_TIMEOUTTimeout.
ERR_INPROGRESSOperation in progress.
ERR_WOULDBLOCKOperation would block.

2017-02-09
Documentation license for this page: eCosPro License