The target socket (the socket being modified). The socket must have already been created by a successful
call to FreeRTOS_socket().

lLevel

FreeRTOS+TCP does not [currently] use the lLevel
parameter. The parameter is included
to ensure consistency with the expected standard Berkeley sockets API,
and to ensure compatibility with future versions of FreeRTOS+TCP.

The meaning of pvOptionValue is dependent on the value of
lOptionName. See the description of the lOptionName
parameter.

xOptionLength

FreeRTOS+TCP does not [currently] use the xOptionLength
parameter. The parameter is included
to ensure consistency with the expected standard Berkeley sockets API,
and to ensure compatibility with future versions of FreeRTOS+TCP.

Returns:

-FREERTOS_EINVAL is returned if an invalid lOptionName value is used,
otherwise 0 is returned.
(0 is the standard Berkeley sockets success return value, contrary to the
FreeRTOS standard where 0 means fail!)

Example usage:

This example creates a UDP socket, configures the socket's behaviour in accordance
with the function's parameters, then returns the created and configured socket.

This parameter can only be set between the socket being
created and data being received on the socket because the
size of the receive buffer is fixed after the buffer has been created.

If lOptionName is FREERTOS_SO_RCVBUF then
pvOptionValue must point to a variable of type
int32_t.

The receive buffer size is specified in bytes. Internally
the specified size will get rounded up to the nearest multiple
of the ipconfigTCP_MSS
size. For example, if ipconfigTCP_MSS is 500 then setting
a buffer size of 400 will result in a buffer size of 500 (1 * ipconfigTCP_MSS),
setting a buffer size of 500 will result in a buffer size of
500 (1 * ipconfigTCP_MSS), and setting a buffer size of 510 will result in a buffer
size of 1000 (2 * ipconfigTCP_MSS).

FREERTOS_SO_SNDBUF

Only valid for TCP sockets.

Sets the size of the transmit buffer.
This is not related to the size of the packets or the sliding
window, it only sets the size of the buffer.

This parameter can only be set between the socket being
created and data being sent on the socket because the
size of the send buffer is fixed after the buffer has been created.

If lOptionName is FREERTOS_SO_SNDBUF then
pvOptionValue must point to a variable of type
int32_t.

The receive buffer size is specified in bytes. Internally
the specified size will get rounded up to the nearest multiple
of the ipconfigTCP_MSS
size. For example, if ipconfigTCP_MSS is 500 then setting
a buffer size of 400 will result in a buffer size of 500 (1 * ipconfigTCP_MSS),
setting a buffer size of 500 will result in a buffer size of
500 (1 * ipconfigTCP_MSS), and setting a buffer size of 510 will result in a buffer
size of 1000 (2 * ipconfigTCP_MSS).

By default a listening
socket will create a new socket to handle any accepted connections.
FREERTOS_SO_REUSE_LISTEN_SOCKET can be used to change this
behaviour so accepted connections are handled by the listening
socket itself.

If lOptionName is FREERTOS_SO_REUSE_LISTEN_SOCKET then
pvOptionValue must point to a variable of type
BaseType_t that is set to 1 to indicate that the listening
socket should be re-used for incoming connections, or 0 to
indicate that the listening socket should create a new
socket to handle each incoming connection.

For a re-usable socket it is optional to call FreeRTOS_accept().
You can also call FreeRTOS_connected() to determine if the socket is already
connected. It is preferred to call FreeRTOS_accept() because it marks the
change from unconnected to connected.

When successful, FreeRTOS_accept() will return a reference to the parent
socket that has connected. It is now marked as accepted and it
stops listening for new connections.

At the end of the connection, the socket must be closed by calling
FreeRTOS_closesocket().
After that a new socket can be created and bound to the same
port.

FREERTOS_SO_CLOSE_AFTER_SEND TCP allows a socket to be closed
immediately after the last data has been delivered. This option
is useful for example in FTP where a file is being sent.
Before calling FreeRTOS_send() for the last time, set this
option, so the stack knows that the last packet must include
the FIN flag. The stack will make sure that the connection
is only closed after the last byte has been delivered, and
acknowledged by the peer.

If lOptionName is FREERTOS_SO_CLOSE_AFTER_SEND then
pvOptionValue must point to a variable of type
BaseType_t that is set to 1 to indicate that the socket
should be closed after the last data has been sent, or 0 to
indicate that the socket should use its default behaviour
of keeping the socket open until explicitly by either peer.

The FREERTOS_SO_SET_FULL_SIZE option tells the TCP/IP stack
not to send any data from the socket until there is at least
one complete MSS
size of data ready to be sent. This option
can be used to improve performance, but must be used with care.
This option does not expire, so make sure the option is
switched off on the last send, so that the last bytes
(less than MSS) will also be delivered.

If lOptionName is FREERTOS_SO_SET_FULL_SIZE then
pvOptionValue must point to a variable of type
BaseType_t that is set to 1 to indicate that the socket
should only send when there is at least MSS bytes waiting to
be delivered, or 0 to
indicate that the socket should use its default behaviour.

FREERTOS_SO_STOP_RX

Advanced users only.

Only valid for TCP sockets.

A TCP socket will constantly advertise a window size to its
peer, so the peer knows how many bytes it may send until it
has to wait for an acknowledge. This all happens automatically
with a low and a high water mark.

FREERTOS_SO_STOP_RX forces the socket to advertise a window
of zero, enabling the socket to temporarily stop receiving
data.

If lOptionName is FREERTOS_SO_STOP_RX then
pvOptionValue must point to a variable of type
BaseType_t that is set to 1 to indicate that the socket
should advertise a window size of 0, or 0 to
indicate that the socket should use its default behaviour.