FreeRTOS_setsockopt() API Reference

FreeRTOS_setsockopt()

[FreeRTOS+TCP API Reference]

BaseType_t FreeRTOS_setsockopt( Socket_t xSocket, int32_t lLevel,
                                int32_t lOptionName, const void *pvOptionValue,
                                size_t xOptionLength );

Sets a socket option.

Parameters:

xSocket

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.

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+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.


/* FreeRTOS+TCP sockets include. */
#define "FreeRTOS_sockets.h"

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_INET,
                               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

lOptionName Value

Description

FREERTOS_SO_RCVTIMEO

Sets the receive timeout when FreeRTOS_recvfrom() is called with a UDP socket, or FreeRTOS_recv() is called with a TCP socket.

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.

FREERTOS_SO_SNDTIMEO

Sets the transmit timeout when FreeRTOS_send() is used with a TCP socket, or FreeRTOS_sendto() is used with a UDP socket.

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.

FREERTOS_SO_SET_SEMAPHORE

Only available if ipconfigSOCKET_HAS_USER_SEMAPHORE is set to 1 in FreeRTOSIPConfig.h.

This option allows a reference to a semaphore to be passed to a socket. The TCP/IPIP 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 );
}

Example of passing a semaphore to a socket

FREERTOS_SO_RCVBUF

Only valid for TCP sockets.

Sets the size of the receive buffer. Ideally this should be set to twice the size of the sliding window.

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.

FREERTOS_SO_WIN_PROPERTIES

Advanced users only.

Only valid for TCP sockets.

Sets the size of the receive buffer, receive sliding window, transmit buffer and transmit sliding window in one call.

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;

    /* Fill in the required buffer and window sizes. */
    /* Unit: bytes */
    xWinProps.lTxBufSize = 4 * ipconfigTCP_MSS;
    /* Unit: MSS */
    xWinProps.lTxWinSize = 2;
    /* Unit: bytes */
    xWinProps.lRxBufSize = 4 * ipconfigTCP_MSS;
    /* Unit: MSS */
    xWinProps.lRxWinSize = 2;

    /* 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.

Example use:


BaseType_t xReuseSocket = pdTRUE;
FreeRTOS_setsockopt( xSocket,
                     0,
                     FREERTOS_SO_REUSE_LISTEN_SOCKET,
                     ( void * ) &xReuseSocket,
                     sizeof( xReuseSocket ) );

Example of setting the re-use option to true

FREERTOS_SO_CLOSE_AFTER_SEND

Advanced users only.

Only valid for TCP sockets.

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 use:


BaseType_t xCloseAfterNextSend = pdTRUE;
FreeRTOS_setsockopt( xSocket,
                     0,
                     FREERTOS_SO_CLOSE_AFTER_SEND,
                     ( void * ) &xCloseAfterNextSend,
                     sizeof( xCloseAfterNextSend ) );

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. */
}

xValue = pdFALSE;

/* Allow further reception */
FreeRTOS_setsockopt( xSocket,
                     0,
                     FREERTOS_SO_STOP_RX,
                     ( void * ) &xValue,
                     sizeof( xValue ) );

Example of using the FREERTOS_SO_STOP_RX parameter

FREERTOS_SO_UDP_MAX_RX_PACKETS

Only valid for UDP sockets and if ipconfigUDP_MAX_RX_PACKETS is set to 1 in FreeRTOSIPConfig.h.

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;

FreeRTOS_setsockopt( xSocket,
                     0,
                    FREERTOS_SO_UDP_MAX_RX_PACKETS,
                    ( void * ) &xValue,
                    sizeof( xValue ) );

Example of using the FREERTOS_SO_UDP_MAX_RX_PACKETS parameter

FREERTOS_SO_TCP_CONNECT_HANDLER

Advanced users only.

Only valid for TCP sockets.

Stores the address of a function to call on connect and disconnect events on the TCP socket.

FREERTOS_SO_TCP_RECV_HANDLER

Advanced users only.

Only valid for TCP sockets.

Stores the address of a function to call when data is received on the TCP socket.

FREERTOS_SO_TCP_SENT_HANDLER

Advanced users only.

Only valid for TCP sockets.

Stores the address of a function to call when data sent to the TCP socket has been delivered and confirmed by the peer.

FREERTOS_SO_UDP_RECV_HANDLER

Advanced users only.

Only valid for UDP sockets.

Stores the address of a function to call immediately upon reception of data on the UDP socket.

FREERTOS_SO_UDP_SENT_HANDLER

Advanced users only.

Only valid for UDP sockets.

Stores the address of a function to call immediately that data has been sent to the UDP socket.

The FreeRTOS Ecosystem Showcase . . .
A Selection of Add-on and Complementary Products

FreeRTOS_setsockopt()

[FreeRTOS+TCP API Reference]

Valid lOptionName Values

The FreeRTOS Ecosystem Showcase . . . A Selection of Add-on and Complementary Products

FreeRTOS_setsockopt() [FreeRTOS+TCP API Reference]

Valid lOptionName Values

The FreeRTOS Ecosystem Showcase . . .
A Selection of Add-on and Complementary Products

FreeRTOS_setsockopt()

[FreeRTOS+TCP API Reference]