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 */
#include “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


Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.

Latest News

FreeRTOS v10.2.1 is available for immediate download. MIT licensed, includes 64-bit RISC-V, NXP Cortex-M33 demo & Nuvoton Cortex-M23 demo & STM32H745 dual core (AMP) demo.

New Updates to MIT licensed IoT MQTT and POSIX libraries are now available. New library IoT HTTPS is available.  Includes demo projects.

View a recording of the “OTA Update Security and Reliability” webinar, presented by TI and AWS.

Careers

FreeRTOS and other embedded software careers at AWS.

FreeRTOS Partners
ARM Connected RTOS partner for all ARM microcontroller cores
Espressif ESP32
IAR Partner
Microchip Premier RTOS Partner
Renesas
STMicro RTOS partner supporting ARM7, ARM Cortex-M3, ARM Cortex-M4 and ARM Cortex-M0
Texas Instruments MCU Developer Network RTOS partner for ARM and MSP430 microcontrollers
OpenRTOS and SafeRTOS
Xilinx Microblaze and Zynq partner