lwIP Wiki

The netconn API is a sequential API designed to make the stack easier to use (compared to the event-driven raw API) while still preserving zero-copy functionality.

Multithreading implementation[]

To use the netconn API, an operating system is needed as this API requires the use of threads. All packet processing (input as well as output) in the core of the stack is done inside a dedicated thread (aka. the tcpip-thread). Application threads using the netconn API communicate with this core thread using message boxes and semaphores.

Netconn API from an application perspective[]

Applications using the netconn API may use all functions defined in api.h (netconn_*() functions) and netbuf.h (netbuf_*() functions).

Transport layer protocols supported by the netconn API include UDP, TCP and RAW IP.

An application can use the following functions to work with a netconn:

For TCP connections, additional functions are supported:

  • netconn_listen() - set a TCP connection into listen mode
  • netconn_accept() - accept an incoming connection on a listening TCP connection
  • netconn_write() - send data on a connected TCP netconn
  • netconn_close() - close a TCP netconn without deleting it

Some higher-level protocol support is provided for applications:

  • netconn_gethostbyname() - Does a name lookup (queries dns server if req'd) to resolve a host name to an IP address
  • netconn_join_leave_group() - basic IGMP multicast support

The send and receive functions use netbufs, which provide functionality for zero-copy receive and transmit. The following functions can be used to work with netbufs:

@todo explain netbuf

Nonblocking IO[]

Nonblocking connect[]

From CVS versions of Feb. 2010, the netconn API supports nonblocking connect:

You have to create your own callback function that handles the netconn_evt events:

- conn = netconn_new_with_callback(NETCONN_TCP, your_callback_function)

- netconn_set_nonblocking(conn, 1)

- netconn_connect(...) -> does not block (as above)

- wait for your_callback_function() to be called with event NETCONN_EVT_SENDPLUS (connected) or NETCONN_EVT_ERROR (connect failed)

Watch out for threading: the callback is called in tcpip_thread, not in your application thread!