FreeRTOS_recvfrom()

FreeRTOS_sockets.h

1int32_t FreeRTOS_recvfrom( Socket_t xSocket,
2                           void *pvBuffer,
3                           size_t xBufferLength,
4                           uint32_t ulFlags,
5                           struct freertos_sockaddr *pxSourceAddress,
6                           socklen_t *pxSourceAddressLength );

Receive data from a UDP socket (see FreeRTOS_recv() for the TCP equivalent). The socket must have already been created by a successful call to FreeRTOS_socket().

This function can be used with standard calling semantics, or zero copy calling semantics:

Standard recvfrom() semantics

Data is copied from a network buffer inside the TCP/IP stack into the buffer pointed to by the pvBuffer parameter.

The standard recvfrom() semantics are used when the ulFlags parameter does not have the FREERTOS_ZERO_COPY bit set. See the example at the bottom of this page, and other application examples provided on this website.
Zero copy recvfrom() semantics

The application writer receives from the TCP/IP stack a reference to the buffer that already contains the received data. No data is copied.

The zero copy recvfrom() semantics are used when the ulFlags parameter has the FREERTOS_ZERO_COPY bit set. See the examples at the bottom of this page, and other application examples provided on this website.

FreeRTOS_recvfrom() has an optional timeout. The timeout defaults to portMAX_DELAY and is modified using FreeRTOS_setsockopt(). If the receive operation cannot complete immediately because there is no data queued on the socket to receive then the calling RTOS task will be held in the Blocked state (so that other tasks can execute) until either data has been received, or the timeout expires.

FreeRTOS-Plus-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-Plus-TCP.

Parameters:

xSocket

The handle of the socket from which data is being read. The socket must have already been created (see FreeRTOS_socket()).
pvBuffer

If the standard calling semantics are used (the ulFlags parameter does not have the FREERTOS_ZERO_COPY bit set) then pvBuffer points to the buffer into which received data will be copied. If the zero copy calling semantics are used (the ulFlags parameter does have the FREERTOS_ZERO_COPY bit set) then *pvBuffer will be set (by FreeRTOS_recvfrom()) to point to the buffer that already holds the received data. pvBuffer is used to pass a reference to the received data out of FreeRTOS_recvfrom() without any data being copied. The example at the bottom of this page, and other application examples provided on this website, demonstrate FreeRTOS_recvfrom() being used with both the standard and zero copy calling semantics.
xBufferLength

If the standard calling semantics are used (the ulFlags parameter does not have the FREERTOS_ZERO_COPY bit set) then xBufferLength must be set to the size in bytes of the buffer pointed to by the pvBuffer parameter. If the zero copy calling semantics are used (the ulFlasg parameter does not have the FREERTOS_ZERO_COPY bit set) then pvBuffer does not point to a buffer and xBufferLength is not used.
ulFlags

A bitwise set of options that affect the receive operation. If ulFlags has the FREERTOS_ZERO_COPY bit set, then the function will use the zero copy semantics, otherwise the function will use the traditional copy mode semantics. See the description of the pvBuffer parameter above. Future FreeRTOS-Plus-TCP versions may implement other bits.
pxSourceAddress

A pointer to a freertos_sockaddr structure that will be set (by FreeRTOS_recvrom()) to contain the IP address and port number of the socket that sent the data just received. See the example below.
pxSourceAddressLength

Not currently used, but should be set to sizeof( struct freertos_sockaddr ) to ensure future compatibility.

Returns:

If no bytes are received before the configured block time expires then -pdFREERTOS_ERRNO_EWOULDBLOCK is returned.
If the socket is not bound to a port number then -pdFREERTOS_ERRNO_EINVAL is returned.
If the socket received a signal, causing the read operation to be aborted, then -pdFREERTOS_ERRNO_EINTR is returned.
If data is successfully received then the number of bytes received is returned.

Example usage:

The first example receives from a socket using the standard calling semantics (see below for another example that uses the zero copy calling semantics). The socket is passed in as the function parameter, and is assumed to have already been created using a call to FreeRTOS_socket(), and bound to an address using a call to FreeRTOS_bind()

1/* FreeRTOS-Plus-TCP sockets include. */  
2#include "FreeRTOS_sockets.h"  
3  
4void vStandardReceiveExample( Socket_t xSocket )  
5{  
6/* Note - the RTOS task stack must be big enough to hold this array!. */  
7uint8_t ucBuffer[ 128 ];  
8int8_t cIPAddressString[ 16 ];  
9struct freertos_sockaddr xSourceAddress;  
10socklen_t xAddressLength = sizeof(xSourceAddress);  
11int32_t iReturned;   
12  
13    /* Receive into the buffer with ulFlags set to 0, so the FREERTOS\_ZERO\_COPY bit  
14       is clear. */  
15    iReturned = FreeRTOS_recvfrom(  
16                                    /* The socket data is being received on. */  
17                                    xSocket,  
18                                    /* The buffer into which received data will 
19                                       be  copied. */  
20                                    ucBuffer,  
21                                    /* The length of the buffer into which data 
22                                       will be  copied. */  
23                                    128,  
24                                    /* ulFlags with the FREERTOS\_ZERO\_COPY bit clear. */ 
25                                    0,  
26                                    /* Will get set to the source of the received data. */  
27                                    &xSourceAddress,  
28                                    /* Not used but should be set as shown. */  
29                                    &xAddressLength  
30                               );  
31  
32    if( iReturned > 0 )  
33    {  
34        /* Data was received from the socket. Prepare the IP address for  
35           printing to the console by converting it to a string. */  
36        FreeRTOS_inet_ntoa( xSourceAddress.sin_addr, ( char * ) cIPAddressString );  
37  
38        /* Print out details of the data source. */  
39        printf( "Received %d bytes from IP address %s port number %drn",  
40                    iReturned, /* The number of bytes received. */  
41                    cIPAddressString, /* The IP address that sent the data. */  
42                    FreeRTOS_ntohs( xSourceAddress.sin_port ) ); /* The source port. */  
43    }  
44}

Example using FreeRTOS_recvfrom() with the standard (as opposed to zero copy) calling semantics

This second example received from a socket using the zero copy calling semantics (see above for an example that uses the standard calling semantics). The socket is passed in as the function parameter, and is assumed to have already been created using a call to FreeRTOS_socket(), and bound to a port number using FreeRTOS_bind().

1/* FreeRTOS-Plus-TCP sockets include. */  
2#include "FreeRTOS_sockets.h"  
3  
4void vZeroCopyReceiveExample( Socket_t xSocket )  
5{  
6struct freertos_sockaddr xSourceAddress;  
7socklen_t xAddressLength = sizeof(xSourceAddress);  
8uint8_t *pucReceivedUDPPayload;  
9int32_t iReturned;  
10  
11    /* Receive using the zero copy semantics. The address of the  
12       pucReceivedUDPPayload pointer is passed in the pvBuffer parameter. */  
13    iReturned = FreeRTOS_recvfrom(  
14                                   /* The socket being received from. */  
15                                      xSocket,  
16                                   /* pucReceivedUDPPayload will get  
17                                      set to points to the received data. */ 
18                                   &pucReceivedUDPPayload,  
19                                   /* Ignored because the pvBuffer parameter  
20                                      does not point to a buffer. */  
21                                   0,  
22                                   /* ulFlags with the FREERTOS\_ZERO\_COPY bit set. */
23                                   FREERTOS_ZERO_COPY,  
24                                   /* Will get set to the source of the received  
25                                      data. */  
26                                   &xSourceAddress,  
27                                   /* Not used but should be set as shown. */  
28                                   &xAddressLength  
29                                 );  
30  
31    if( iReturned > 0 )  
32    {  
33        /* Data was received from the socket. Convert the IP address to a  
34           string. */  
35        FreeRTOS_inet_ntoa( xSourceAddress.sin_addr, ( char * ) cIPAddressString );  
36  
37        /* Print out details of the data source. */  
38        printf( "Received %d bytes from IP address %s port number %drn",  
39                    iReturned, /* The number of bytes received. */  
40                    cIPAddressString, /* The IP address that sent the data. */  
41                    FreeRTOS_ntohs( xSourceAddress.sin_port ) ); /* The source port. */  
42  
43        /* pucReceivedUDPPayload now points to the received data. For  
44           example, *pucReceivedUDPPayload (or pucReceivedUDPPayload[ 0 ]) is the first  
45           received byte. *(pucReceivedUDPPayload + 1 ) (or pucReceivedUDPPayload[ 1 ])  
46           is the second received byte, etc.  
47  
48           The application writer is now responsible for the buffer. To prevent  
49           memory and network buffer leaks the buffer *must* be returned to the IP  
50           stack when it is no longer required. The following call is used to  
51           return the buffer. */  
52        FreeRTOS_ReleaseUDPPayloadBuffer( ( void * ) pucReceivedUDPPayload );  
53    }  
54}

Example using FreeRTOS_recvfrom() with the zero copy calling semantics

FreeRTOS_recvfrom()

Related links