FreeRTOS_setsockopt() API Reference

FreeRTOS_setsockopt()

[FreeRTOS Embedded IP Stack API]

BaseType_t FreeRTOS_setsockopt( xSocket_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+UDP 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+UDP.

lOptionName

The option being set or modified. Valid values are:

lOptionName Value	Description
FREERTOS_SO_RCVTIMEO	Sets the receive timeout. See FreeRTOS_recvfrom() for a description of the receive timeout. 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.
FREERTOS_SO_SNDTIMEO	Sets the transmit timeout. See FreeRTOS_sendto() for a description of the transmit timeout. 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.
FREERTOS_SO_UDPCKSUM_OUT	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.

pvOptionValue

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

xOptionLength

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

Returns:

If lOptionName does not contain a permitted value (as documented above) then FREERTOS_ENOPROTOOPT is returned.

If lOptionName does contain a permitted value then 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 socket, configures the socket's behaviour in accordance with the function's parameters, then returns the created and configured socket.


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

xSocket_t xCreateASocket( TickType_t xReceiveTimeout_ms,
                          TickType_t xSendTimeout_ms,
                          int32_t iUseChecksum )
{
/* Variable to hold the created socket. */
xSocket_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

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

FreeRTOS_setsockopt() [FreeRTOS Embedded IP Stack API]

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

FreeRTOS_setsockopt()

[FreeRTOS Embedded IP Stack API]