SOCKETS_SetSockOpt

Manipulates the options for the socket.

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

See the Berkeley Sockets API in wikipedia

Parameters

[in]	xSocket	The handle of the socket to set the option for.
[in]	lLevel	Not currently used. Should be set to 0.
[in]	lOptionName	See SetSockOptOptions.
[in]	pvOptionValue	A buffer containing the value of the option to set.
[in]	xOptionLength	The length of the buffer pointed to by pvOptionValue.

Warning

SOCKETS_Close() is not safe to be called on the same socket from multiple threads simultaneously with SOCKETS_Connect(), SOCKETS_SetSockOpt(), SOCKETS_Shutdown(), SOCKETS_Close().

Note

Socket option support and possible values vary by port. Please see PORT_SPECIFIC_LINK to check the valid options and limitations of your device.

• Berkeley Socket Options
  • SOCKETS_SO_RCVTIMEO
    • Sets the receive timeout
    • pvOptionValue (TickType_t) is the number of milliseconds that the receive function should wait before timing out.
    • Setting pvOptionValue = 0 causes receive to wait forever.
    • See PORT_SPECIFIC_LINK for device limitations.
  • SOCKETS_SO_SNDTIMEO
    • Sets the send timeout
    • pvOptionValue (TickType_t) is the number of milliseconds that the send function should wait before timing out.
    • Setting pvOptionValue = 0 causes send to wait forever.
    • See PORT_SPECIFIC_LINK for device limitations.
• Non-Standard Options
  • SOCKETS_SO_NONBLOCK
    • Makes a socket non-blocking.
    • Non-blocking connect is not supported - socket option should be called after connect.
    • pvOptionValue is ignored for this option.
  • SOCKETS_SO_WAKEUP_CALLBACK
    • Set the callback to be called whenever there is data available on the socket for reading
    • This option provides an asynchronous way to handle received data
    • pvOptionValue is a pointer to the callback function
    • See PORT_SPECIFIC_LINK for device limitations.
• Security Sockets Options
  • SOCKETS_SO_REQUIRE_TLS
    • Use TLS for all connect, send, and receive on this socket.
    • This socket options MUST be set for TLS to be used, even if other secure socket options are set.
    • This socket option should be set before SOCKETS_Connect() is called.
    • pvOptionValue is ignored for this option.
  • SOCKETS_SO_TRUSTED_SERVER_CERTIFICATE
    • Set the root of trust server certificate for the socket.
    • This socket option only takes effect if SOCKETS_SO_REQUIRE_TLS is also set. If SOCKETS_SO_REQUIRE_TLS is not set, this option will be ignored.
    • pvOptionValue is a pointer to the formatted server certificate. TODO: Link to description of how to format certificates with
      
    • xOptionLength (BaseType_t) is the length of the certificate in bytes.
  • SOCKETS_SO_SERVER_NAME_INDICATION
    • Use Server Name Indication (SNI)
    • This socket option only takes effect if SOCKETS_SO_REQUIRE_TLS is also set. If SOCKETS_SO_REQUIRE_TLS is not set, this option will be ignored.
    • pvOptionValue is a pointer to a string containing the hostname
    • xOptionLength is the length of the hostname string in bytes.
  • SOCKETS_SO_ALPN_PROTOCOLS
    • Negotiate an application protocol along with TLS.
    • The ALPN list is expressed as an array of NULL-terminated ANSI strings.
    • xOptionLength is the number of items in the array.
  • SOCKETS_SO_TCPKEEPALIVE
    • Enable or disable the TCP keep-alive functionality.
    • pvOptionValue is the value to enable or disable Keepalive.
  • SOCKETS_SO_TCPKEEPALIVE_INTERVAL
    • Set the time in seconds between individual TCP keep-alive probes.
    • pvOptionValue is the time in seconds.
  • SOCKETS_SO_TCPKEEPALIVE_COUNT
    • Set the maximum number of keep-alive probes TCP should send before dropping the connection.
    • pvOptionValue is the maximum number of keep-alive probes.
  • SOCKETS_SO_TCPKEEPALIVE_IDLE_TIME
    • Set the time in seconds for which the connection needs to remain idle before TCP starts sending keep-alive probes.
    • pvOptionValue is the time in seconds.

Returns

• On success, 0 is returned.
• If an error occurred, a negative value is returned. SocketsErrors