FreeRTOS_sockets.h
int32_t FreeRTOS_recvfrom( Socket_t xSocket,
void *pvBuffer,
size_t xBufferLength,
uint32_t ulFlags,
struct freertos_sockaddr *pxSourceAddress,
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()
#include "FreeRTOS_sockets.h"
void vStandardReceiveExample( Socket_t xSocket )
{
uint8_t ucBuffer[ 128 ];
int8_t cIPAddressString[ 16 ];
struct freertos_sockaddr xSourceAddress;
socklen_t xAddressLength = sizeof(xSourceAddress);
int32_t iReturned;
iReturned = FreeRTOS_recvfrom(
xSocket,
ucBuffer,
128,
0,
&xSourceAddress,
&xAddressLength
);
if( iReturned > 0 )
{
FreeRTOS_inet_ntoa( xSourceAddress.sin_address.ulIP_IPv4, ( char * ) cIPAddressString );
printf( "Received %d bytes from IP address %s port number %drn",
iReturned,
cIPAddressString,
FreeRTOS_ntohs( xSourceAddress.sin_port ) );
}
}
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().
#include "FreeRTOS_sockets.h"
void vZeroCopyReceiveExample( Socket_t xSocket )
{
struct freertos_sockaddr xSourceAddress;
socklen_t xAddressLength = sizeof(xSourceAddress);
uint8_t *pucReceivedUDPPayload;
int32_t iReturned;
iReturned = FreeRTOS_recvfrom(
xSocket,
&pucReceivedUDPPayload,
[/code-comment]/* Ignored because the pvBuffer parameter
does not point to a buffer. */[/code-comment]
0,
FREERTOS_ZERO_COPY,
[/code-comment]/* Will get set to the source of the received
data. */[/code-comment]
&xSourceAddress,
&xAddressLength
);
if( iReturned > 0 )
{
FreeRTOS_inet_ntoa( xSourceAddress.sin_address.ulIP_IPv4, ( char * ) cIPAddressString );
printf( "Received %d bytes from IP address %s port number %drn",
iReturned,
cIPAddressString,
FreeRTOS_ntohs( xSourceAddress.sin_port ) );
FreeRTOS_ReleaseUDPPayloadBuffer( ( void * ) pucReceivedUDPPayload );
}
}
Example using FreeRTOS_recvfrom() with the zero copy calling semantics
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.