Receiving data with LWIP

For all LWIP APIs (raw, netconn and sockets), you cannot predict the pattern of receive data, as it is affected by many factors beyond your control. You should never assume that data will be received in the same sized chunks as were written by the sender.

Your application must be able to deal with receiving only a few of the bytes you need, storing them in your own buffer, then using the appropriate method to get the next chunk. This is repeated until you have the number of bytes you want.

With the sockets API, lwip_recv() is typically used to receive data on a TCP connection. You request a number of bytes, but this is a maximum which will be returned. LWIP may choose to return a fewer number of bytes for a variety of reasons. This is true even if you do a blocking receive operation. There is no option to make lwip_recv() block until a certain minimum number of bytes have been received.

With the netconn API, netconn_recv() returns a netbuf which may contain a chain of pbufs. You have no control over how much data will be returned in a single request, which may be more or less than you want to deal with. You can use various netbuf functions to copy data out of the buffer. If you need more data, you must call netconn_recv() again to get the next netbuf. If you received more data than you wanted, you will have to manage the extra data yourself.

With the raw API, tcp_recv() sets up to receive data via a callback function. Your callback is delivered chains of pbufs as they become available. You have to manage extracting data from the pbuf chain, and don't forget to watch out for multiple pbufs in a single callback: the 'tot_len' field indicates the total length of data in the pbuf chain. You must call tcp_recved() to tell LWIP when you have processed the received data. As with the netconn API, you may receive more or less data than you want, and will have to either wait for further callbacks, or hold onto excess data for later processing.

Error checking will also be required with all APIs, e.g. to detect premature closure of the connection.