Real time embedded FreeRTOS RSS feed 
Real time embedded FreeRTOS mailing list 
Homepage FreeRTOS+ Products FreeRTOS Labs Integration Services Contact / Enquiries

FreeRTOS_setsockopt()

[FreeRTOS Embedded IP Stack API]

FreeRTOS_sockets.h
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


[ Back to the top ]    [ About FreeRTOS ]    [ FreeRTOS+ Sitemap ]    [ Main FreeRTOS Sitemap ]    [ ]


Copyright (C) 2004-2010 Richard Barry. Copyright (C) 2010-2016 Real Time Engineers Ltd.
Any and all data, files, source code, html content and documentation included in the FreeRTOSTM distribution or available on this site are the exclusive property of Real Time Engineers Ltd.. See the files license.txt (included in the distribution) and this copyright notice for more information. FreeRTOSTM and FreeRTOS.orgTM are trade marks of Real Time Engineers Ltd.