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! All packet processing (input as well as output) 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_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 tomeout value for a netconn structure
- netconn_gethostbyname() – resolve DNS name to IP address
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_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!