Netconn API

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:

• netconn_new() – create a new connection
• netconn_new_with_callback() – create new connection
• netconn_new_with_proto_and_callback() - create a new connection
• netconn_delete() - delete an existing connection
• netconn_bind() - bind a connection to a local port/ip
• netconn_connect() - connect a connection to a remote port/ip
• netconn_disconnect() - disconnect a connection from a remote port/ip
• netconn_send() - send data to the currently connected remote port/ip (not applicable for TCP)
• netconn_sendto() - send data to a specified remote port/ip (not applicable for TCP)
• netconn_recv() - receive data from a netconn
• netconn_set_recvtimeout() – set a receive timeout value for a netconn structure
• netconn_get_recvtimeout() – get the receive timeout value for a netconn structure

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:

• netbuf_new()
• netbuf_delete()
• netbuf_alloc()
• netbuf_free()
• netbuf_ref()
• netbuf_chain()
• netbuf_len()
• netbuf_data()
• netbuf_copy()
• netbuf_next()
• netbuf_first()

@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!