FreeRTOS_sockets.h
int32_t FreeRTOS_sendto( Socket_t xSocket,
const void *pvBuffer,
size_t xTotalDataLength,
uint32_t ulFlags,
const struct freertos_sockaddr *pxDestinationAddress,
socklen_t xDestinationAddressLength );
Send data to a UDP socket (see FreeRTOS_send() 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 sendto() semantics
Data is copied from the address pointed to by the pvBuffer
parameter into a network buffer allocated internally by the TCP/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 TCP/IP stack.
-
Writes the data to be sent into the buffer obtained from
the TCP/IP stack.
-
Uses a pointer to the (already complete) buffer as the
pvBuffer parameter.
the TCP/IP stack then passes a reference to the same buffer through
the TCP/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
ipconfigSOCK_DEFAULT_SEND_BLOCK_TIME,
and is modified using 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. A timeout will occur if:
-
The standard sendto() semantics are used, and the TCP/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 RTOS 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 TCP/IP stack will automatically bind the socket
to a port number from the private address range.
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 to which data is being sent. The socket
must have already been created (see
FreeRTOS_socket()).
|
pvBuffer
|
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 TCP/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 TCP/IP stack and already contains the data being sent.
the TCP/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.
|
xTotalDataLength
|
The number of bytes to send.
|
ulFlags
|
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-Plus-TCP versions may implement other bits.
|
pxDestinationAddress
|
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.
|
xDestinationAddressLength
|
Not currently used, but should be set to
sizeof( struct freertos_sockaddr ) to ensure future
compatibility.
|
Returns:
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.
Example usage:
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().
#include "FreeRTOS_sockets.h"
void vStandardSendExample( Socket_t xSocket )
{
uint8_t ucBuffer[ 128 ];
struct freertos_sockaddr xDestinationAddress;
int32_t iReturned;
xDestinationAddress.sin_addr = FreeRTOS_inet_addr_quick( 192, 168, 0, 100 );
xDestinationAddress.sin_port = FreeRTOS_htons( 1024 );
memset( ucBuffer, 0xff, 128 );
iReturned = FreeRTOS_sendto(
xSocket,
ucBuffer,
128,
0,
&xDestinationAddress,
sizeof( xDestinationAddress )
);
if( iReturned == 128 )
{
}
}
Example using FreeRTOS_sendto() with the standard (as opposed to zero copy) calling semantics
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().
#include "FreeRTOS_sockets.h"
void vZeroCopySendExample( Socket_t xSocket )
{
struct freertos_sockaddr xDestinationAddress;
uint8_t *pucUDPPayloadBuffer;
int32_t iReturned;
xDestinationAddress.sin_addr = FreeRTOS_inet_addr_quick( 192, 168, 0, 100 );
xDestinationAddress.sin_port = FreeRTOS_htons( 1024 );
pucUDPPayloadBuffer = ( uint8_t * ) FreeRTOS_GetUDPPayloadBuffer( 128,
portMAX_DELAY );
if( pucUDPPayloadBuffer != NULL )
{
memset( pucUDPPayloadBuffer, 0xff, 128 );
iReturned = FreeRTOS_sendto(
xSocket,
&xBufferDescriptor,
128,
FREERTOS_ZERO_COPY,
&xDestinationAddress,
sizeof( xDestinationAddress )
);
if( iReturned != 0 )
{
}
else
{
FreeRTOS_ReleaseUDPPayloadBuffer( ( void * ) pucUDPPayloadBuffer );
}
}
}
Example using FreeRTOS_sendto() with the zero copy calling semantics
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.