[FreeRTOS+TCP API Reference]
BaseType_t FreeRTOS_recv( Socket_t xSocket, void *pvBuffer, size_t xBufferLength, BaseType_t xFlags );
Receive data from a TCP socket (see FreeRTOS_recvfrom() for the UDP equivalent).
The socket must have already been created using a call to FreeRTOS_socket(), bound to a port number, and connected to a remote socket.
The socket can be explicitly bound to a port number by calling FreeRTOS_bind().
The socket can actively connect to a remote socket using FreeRTOS_connect(). If FreeRTOS_connect() is called on a socket that is not bound to a port number, and the value of ipconfigALLOW_SOCKET_SEND_WITHOUT_BIND is set to 1 in FreeRTOSIPConfig.h, then the TCP/IP stack will automatically bind the socket to a port number from the private address range.
Alternatively the socket can wait for incoming connections using FreeRTOS_accept().
FreeRTOS_recv() has an optional timeout. The timeout defaults to ipconfigSOCK_DEFAULT_RECEIVE_BLOCK_TIME, and is modified using the FREERTOS_SO_RCVTIMEO parameter in a call to FreeRTOS_setsockopt(). If the receive operation cannot return received bytes immediately then the calling RTOS task will be held in the Blocked state (so that other tasks can execute) until either bytes are received, or the timeout expires.
FreeRTOS+TCP does not [currently] use all the function parameters. The parameters that are not used are retained in the function’s prototype to ensure consistency with the expected standard Berkeley sockets API, and to ensure compatibility with future versions of FreeRTOS+TCP.
The handle of the socket from which data is being read.
The buffer into which received data will be placed.
The size of the buffer (in bytes) pointed to by the
pvBuffer parameter – and therefore also the maximum number
of bytes that will be read.
Not currently used. Future FreeRTOS+TCP versions may
implement receive options using the ulFlags parameter.
If the receive was successful then the number of bytes received (placed in the buffer pointed to by pvBuffer) is returned.
If a time out occurred before data could be received then 0 is returned.
If there was not enough memory for the socket to be able to create either an Rx or Tx stream then -pdFREERTOS_ERRNO_ENOMEM is returned.
If the socket was closed or got closed then -pdFREERTOS_ERRNO_ENOTCONN is returned.
If the socket received a signal, causing the read operation to be aborted, then -pdFREERTOS_ERRNO_EINTR is returned.
If the socket is not valid, is not a TCP socket, or is not bound then -pdFREERTOS_ERRNO_EINVAL is returned;
Note that, because FreeRTOS does not implement errno, the behaviour in the presence of an error is necessarily different to that of recv() functions that are fully compliant with the expected Berkeley sockets behaviour.
See the “Creating, Configuring and Binding TCP Client and Server Sockets” section of the FreeRTOS+TCP networking tutorial pages for examples of how to prepare a TCP socket for receiving data.
See the “Receiving TCP Data” section of the FreeRTOS+TCP networking tutorial pages for examples of receiving data from a TCP socket.