The target socket (the socket being modified). The socket must have already been created by a successful
call to FreeRTOS_socket().
lLevel
FreeRTOS-Plus-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-Plus-TCP.
lOptionName
The option being set or modified. See the table below
for valid values.
pvOptionValue
The meaning of pvOptionValue is dependent on the value of
lOptionName. See the description of the lOptionName
parameter.
xOptionLength
FreeRTOS-Plus-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-Plus-TCP.
Returns:
-pdFREERTOS_ERRNO_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.
Socket_t xCreateASocket( TickType_t xReceiveTimeout_ms,
TickType_t xSendTimeout_ms,
int32_t iUseChecksum )
{ /* Variable to hold the created socket. */
Socket_t xSocket;
/* Create the socket. */
xSocket = FreeRTOS_socket( FREERTOS_AF_INET4, /* FREERTOS_AF_INET6 can be used for IPv6 UDP socket */
FREERTOS_SOCK_DGRAM,
FREERTOS_IPPROTO_UDP );
/* Check the socket was created successfully. */
if( xSocket != FREERTOS_INVALID_SOCKET )
{ /* Convert the receive timeout into ticks. */
xReceiveTimeout_ms /= portTICK_PERIOD_MS;
/* Set the receive timeout. */
FreeRTOS_setsockopt( xSocket, /* The socket being modified. */
0, /* Not used. */
FREERTOS_SO_RCVTIMEO,/* Setting receive timeout. */
&xReceiveTimeout_ms, /* The timeout value. */
0 ); /* Not used. */
/* Convert the send timeout into ticks. */
xSendTimeout_ms /= portTICK_PERIOD_MS;
/* Set the send timeout. */
FreeRTOS_setsockopt( xSocket, /* The socket being modified. */
0, /* Not used. */
FREERTOS_SO_SNDTIMEO,/* Setting send timeout. */
&xSendTimeout_ms, /* The timeout value. */
0 ); /* Not used. */
if( iUseChecksum == pdFALSE )
{ /* Turn the UDP checksum creation off for outgoing UDP packets. */
FreeRTOS_setsockopt( xSocket, /* The socket being modified. */
0, /* Not used. */
FREERTOS_SO_UDPCKSUM_OUT, /* Setting checksum on/off. */
NULL, /* NULL means off. */
0 ); /* Not used. */
}
else
{ /* The checksum is used by default, so there is nothing to do here.
If the checksum was off it could be turned on again using an option
value other than NULL, for example ( ( void * ) 1 ). */
}
}
return xSocket;
}
Example use of the FreeRTOS_setsockopt() API function
If lOptionName is FREERTOS_SO_RECTIMEO then
pvOptionValue must point to a variable of type
TickType_t.
Timeout values
are specified in ticks. To convert a time
in milliseconds to a time in ticks divide the
time in milliseconds by portTICK_PERIOD_MS or
use the pdMS_TO_TICKS() macro.
If lOptionName is FREERTOS_SO_SNDTIMEO then
pvOptionValue must point to a variable of type
TickType_t.
Timeout values
are specified in ticks. To convert a time
in milliseconds to a time in ticks divide the
time in milliseconds by portTICK_PERIOD_MS or
use the pdMS_TO_TICKS() macro.
FREERTOS_SO_UDPCKSUM_OUT
Only valid for UDP sockets.
Turn on or off the generation of checksum values
for outgoing UDP packets.
If lOptionName is FREERTOS_SO_UDPCKSUM_OUT and
lOptionValue is NULL (0) then outgoing UDP
packets will always have their checksum set
to 0.
if lOptionName is FREERTOS_SO_UDPCKSUM_OUT and
lOptionValue is any value other than NULL (0)
then outgoing UDP packets will include a
valid checksum value.
This option allows a reference to a semaphore to be passed
to a socket. The TCP/IP RTOS task will then give to the
semaphore on any of these events:
Arrival of new data
After delivering data, when new transmission buffer space becomes available
An outgoing TCP connection has succeeded
A new client has connected to a TCP socket
A TCP connection was closed or reset
Example use:
/* Declare the semaphore. */
SemaphoreHandle_t xSemaphore;
/* Create the semaphore. */
xSemaphore = xSemaphoreCreateBinary();
if( xSemaphore != NULL )
{ /* Pass the semaphore to the socket. */
FreeRTOS_setsockopt( xSocket,
0,
FREERTOS_SO_SET_SEMAPHORE,
( void * )&xSemaphore,
sizeof( xSemaphore ) );
/* The semaphore has been passed to the socket
and will be used.
Note: If a socket has a reference to a semaphore
then the semaphore must not be deleted! To
remove the semaphore call FreeRTOS_setsockopt()
again, but this time with a NULL semaphore. */
SemaphoreHandle_t xNoSem = NULL;
FreeRTOS_setsockopt( xSocket,
0,
FREERTOS_SO_SET_SEMAPHORE,
( void * ) &xNoSem,
sizeof( xNoSem ) );
/* Now the semaphore can be deleted. */
vSemaphoreDelete( xSemaphore );
}
Each socket can have a callback function that is executed when there is an event the socket's owner might want to process.
This is to register and set the wakeup callback function for the socket.
The callback function should be of the following type:
This is used to set the low- and the high-water values for TCP reception. It is useful when streaming music. The option value should
of the type LowHighWater_t with the following structure definition:
typedef struct xLOW_HIGH_WATER
{
size_t uxLittleSpace; /**< Send a STOP when buffer space drops below X bytes */
size_t uxEnoughSpace; /**< Send a GO when buffer space grows above X bytes */
} LowHighWater_t;
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).
The buffer and sliding window sizes can only be set between
the socket being created and any data being sent to the socket
or received from the socket.
Example use:
/* Declare an xWinProperties structure. */
WinProperties_t xWinProps;
/* Use the structure with the
FREERTOS_SO_WIN_PROPERTIES parameter in a call to
FreeRTOS_setsockopt(). */
FreeRTOS_setsockopt( xSocket,
0,
FREERTOS_SO_WIN_PROPERTIES,
( void * ) &xWinProps,
sizeof( xWinProps ) );
Example of setting the buffer and sliding window sizes
FREERTOS_SO_REUSE_LISTEN_SOCKET
Only valid for TCP sockets.
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.
Example of using the FREERTOS_SO_CLOSE_AFTER_SEND parameter
FREERTOS_SO_SET_FULL_SIZE
Advanced users only.
Only valid for TCP sockets.
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.
BaseType_t xValue = pdTRUE;
/* Temporarily advertise a window size of 0 to stop
reception of data */
FreeRTOS_setsockopt( xSocket,
0,
FREERTOS_SO_STOP_RX,
( void * ) &xValue,
sizeof( xValue ) );
{ /* Do what ever you need to do. */
}
The parameter ipconfigUDP_MAX_RX_PACKETS makes it possible
to limit the maximum number of packets stored in one UDP
socket. This option can change this limitation for an
individual socket
If lOptionName is FREERTOS_SO_UDP_MAX_RX_PACKETS then
pvOptionValue must point to a variable of type
BaseType_t that holds the maximum number of RX packets that
can be queued on the UDP socket.
/* Allow a maximum of ten packets. */
BaseType_t xValue = 10;