|Hint: Use the tree menu to navigate groups of related pages|
|FreeRTOS+UDP was removed from the FreeRTOS kernel download from FreeRTOS V10.1.0. See the FreeRTOS+TCP stack, which can be configured for UDP only use, as an alternative.|
[FreeRTOS Embedded IP Stack API]
int32_t FreeRTOS_sendto( xSocket_t xSocket, const void *pvBuffer, size_t xTotalDataLength, uint32_t ulFlags, const struct freertos_sockaddr *pxDestinationAddress, socklen_t xDestinationAddressLength );
Send data to a socket. 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 sendto() semantics
Data is copied from the address pointed to by the pvBuffer parameter into a network buffer allocated internally by the IP stack.
The standard sendto() 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 sendto() semantics
The application writer:
- Obtains a buffer from the IP stack.
- Writes the data to be sent into the buffer obtained from the IP stack.
- Uses a pointer to the (already complete) buffer as the pvBuffer parameter.
The IP stack then passes a reference to the same buffer through the IP stack to the Ethernet driver, where it is transmitted (normally by DMA where the hardware permits).
The zero copy sendto() 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_sendto() has an optional timeout. The timeout defaults to zero, and is modified using FreeRTOS_setsockopt(). If the send operation cannot queue the bytes for transmission immediately then the calling 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. A timeout will occur if:
- The standard sendto() semantics are used, and the IP stack was not able to obtain a network buffer in time. Or,
- No space became available on the queue used to send messages to the IP task (see the ipconfigEVENT_QUEUE_LENGTH setting in the FreeRTOSIPConfig.h header file).
If FreeRTOS_sendto() 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 IP stack will automatically bind the socket to a port number from the private address range.
FreeRTOS+UDP 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+UDP.
The handle of the socket to which data is being sent. The socket
must have already been created (see
If the standard calling semantics are being used (the ulFlags
parameter does not have the FREERTOS_ZERO_COPY bit set)
then pvBuffer points to the source of the data being
transmitted. FreeRTOS_sendto() will copy data from pvBuffer
into a network buffer inside the IP stack.
If the zero copy calling semantics are being sued (the ulFlags parameter does have the FREERTOS_ZERO_COPY bit set) then pvBuffer points to a buffer that was previously obtained from the IP stack and already contains the data being sent. The IP stack will take control of the buffer rather than copy data out of the buffer.
See the example usage section below, and the application examples provided on this website.
The number of bytes to send.
A bitwise set of options that affect the send 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 standard copy mode semantics. See the description of the pvBuffer parameter above.
Future FreeRTOS+UDP versions may implement other bits.
A pointer to a freertos_sockaddr structure that
contains the destination IP address and port number (the
socket the data is being sent to). See the example below.
Not currently used, but should be set to
sizeof( struct freertos_sockaddr ) to ensure future
The number of bytes that were actually queue for sending, which will be 0 if an error or timeout occurred.
Note that, because FreeRTOS does not implement errno, the behaviour in the presence of an error is necessarily different to that of sendto() functions that are fully compliant with the expected Berkeley sockets behaviour.
The first example sends to 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(). If ipconfigALLOW_SOCKET_SEND_WITHOUT_BIND is not set to 1 in FreeRTOSIPConfig.h, then the socket is also assumed to have been bound to a port number using FreeRTOS_bind().
This second example sends to 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(). If ipconfigALLOW_SOCKET_SEND_WITHOUT_BIND is not set to 1 in FreeRTOSIPConfig.h, then the socket is also assumed to have been bound to a port number using FreeRTOS_bind().