The FreeRTOS Ecosystem Showcase . . .
A Selection of Add-on and Complementary Products

 Real time embedded FreeRTOS RSS feed 
Homepage FreeRTOS+ Products FreeRTOS Labs Support Forum Contact / Enquiries

 FreeRTOS+POSIX:
 POSIX API for FreeRTOS
 FreeRTOS+FAT:
 Thread aware file system

FreeRTOS_recv()

[FreeRTOS+TCP API Reference]

FreeRTOS_sockets.h 
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.

Parameters:

xSocket   The handle of the socket from which data is being read.

pvBuffer   The buffer into which received data will be placed.

xBufferLength   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.

ulFlags   Not currently used. Future FreeRTOS+TCP versions may implement receive options using the ulFlags parameter.

Returns:

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.

Example usage:

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.


[ Back to the top ]    [ About FreeRTOS ]    [ Privacy ]    [ FreeRTOS Labs Sitemap ]    [ Main FreeRTOS Sitemap ]    [ ]




Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.