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-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.
|
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-Plus-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-Plus-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-Plus-TCP networking tutorial pages for examples
of receiving data from a TCP socket.
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.