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_send()

[FreeRTOS+TCP API Reference]

FreeRTOS_sockets.h 
BaseType_t FreeRTOS_send( Socket_t xSocket,
                          const void *pvBuffer,
                          size_t xDataLength,
                          BaseType_t xFlags );

Send data to a TCP socket (see FreeRTOS_sendto() 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_send() has an optional timeout. The timeout defaults to ipconfigSOCK_DEFAULT_SEND_BLOCK_TIME, and is modified using the FREERTOS_SO_SNDTIMEO parameter in a call to FreeRTOS_setsockopt(). If the send operation cannot queue the bytes for transmission immediately then the calling RTOS task will be held in the Blocked state (so that other tasks can execute) until either the bytes can be queued for sending, 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 to which data is being sent. The socket must have already been created and bound to a port number (see FreeRTOS_socket() and FreeRTOS_bind()).

pvBuffer   Points to the source of the data being transmitted.
xDataLength   The number of bytes to send.

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

Returns:

If the send was successful then the number of bytes queued for sending is returned (note this may be fewer bytes than the number requested by the xTotalDataLength parameter).

If no data could be sent because the socket was closed or got closed then -pdFREERTOS_ERRNO_ENOTCONN is returned.

If no data could be sent because there was insufficient memory then -pdFREERTOS_ERRNO_ENOMEM is returned.

If no data could be sent because xSocket was not a valid TCP socket then -pdFREERTOS_ERRNO_EINVAL is returned.

If a timeout occurred before any data could be sent then -pdFREERTOS_ERRNO_ENOSPC is returned.

Note that, because FreeRTOS does not implement errno, the behaviour in the presence of an error is necessarily different to that of send() 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 sending data.

See the "Sending TCP Data" section of the FreeRTOS+TCP networking tutorial pages for examples of sending data to 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.