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