eCosPro® Reference Manual
Prev | Chapter 4. Sequential API | Next

# 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 synchronisation since lwIP is entitled to change structure contents at any time.

### IP address representation

Some API functions take an argument of type `struct ip_addr`. The type may be accessed as if it has the following structure:

    struct ip_addr {
      u32_t addr;
    };

Caution
API users must use the declaration of this structure from the header file `<lwip/ip_addr.h>` which is included implicitly by `<lwip/api.h>`. This type must not be declared by the application itself.

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>`.

### 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 4-1. lwIP sequential API error codes

Code | Meaning
--- | ---
`ERR_OK` | No error, operation successful.
`ERR_MEM` | Out of memory error.
`ERR_BUF` | Buffer error.
`ERR_ABRT` | Connection aborted.
`ERR_RST` | Connection reset.
`ERR_CLSD` | Connection closed.
`ERR_CONN` | Not connected.
`ERR_VAL` | Illegal value.
`ERR_ARG` | Illegal argument.
`ERR_RTE` | Routing problem.
`ERR_USE` | Address in use.
`ERR_IF` | Low-level network interface error.
`ERR_ISCONN` | Already connected.

Prev | Home | Next
TCP/IP thread | Up | API reference