Macros

group group_secure_sockets_macros

Defines

CY_SOCKET_INVALID_HANDLE

Assigned to a cy_socket_t variable when the socket handle is not valid.

DEFAULT_RECV_TIMEOUT_IN_MSEC

Default socket receive timeout value, in milliseconds.

DEFAULT_SEND_TIMEOUT_IN_MSEC

Default socket send timeout value, in milliseconds.

ARP_WAIT_TIME_IN_MSEC

Maximum time in milliseconds the cy_socket_sendto function waits for MAC address-to-IP address resolution.

CY_SOCKET_DOMAIN_AF_INET

Domain option for cy_socket_create() - IPv4 internet protocols.

CY_SOCKET_DOMAIN_AF_INET6

Domain option for cy_socket_create() - IPv6 internet protocols.

CY_SOCKET_TYPE_DGRAM

Type parameter for cy_socket_create() - Datagram.

CY_SOCKET_TYPE_STREAM

Type parameter for cy_socket_create() - Byte-stream.

CY_SOCKET_IPPROTO_TCP

Protocol option for cy_socket_create() - TCP.

CY_SOCKET_IPPROTO_UDP

Protocol option for cy_socket_create() - UDP.

CY_SOCKET_IPPROTO_TLS

Protocol option for cy_socket_create() - TLS.

CY_SOCKET_SOL_SOCKET

Level option for cy_socket_setsockopt() - Socket-level option.

CY_SOCKET_SOL_TCP

Level option for cy_socket_setsockopt() - TCP protocol-level option.

CY_SOCKET_SOL_TLS

Level option for cy_socket_setsockopt() - TLS protocol-level option.

CY_SOCKET_SOL_IP

Level option for cy_socket_setsockopt() - IP protocol-level option.

CY_SOCKET_SO_RCVTIMEO

Set the receive timeout in milliseconds.

Arguments related to this optname:

note

Configuring the receive timeout value on a server socket impacts the cy_socket_accept() API function. If the client does not send a connect request within the timeout, cy_socket_accept() returns the CY_RSLT_MODULE_SECURE_SOCKETS_TIMEOUT error.

CY_SOCKET_SO_SNDTIMEO

Set the send timeout in milliseconds.

Arguments related to this optname:

CY_SOCKET_SO_NONBLOCK

Set the blocking status of socket API function calls.

This option is currently not supported; will be supported in a future release.

Arguments related to this optname:

  • Option value: Pointer holding the blocking status in uint8_t type. Value “1” indicates blocking status to non-blocking. Value “0” indicates blocking status to blocking.

  • Level: CY_SOCKET_SOL_SOCKET

CY_SOCKET_SO_TCP_KEEPALIVE_ENABLE

Enable/Disable the TCP keepalive mechanism on the socket.

Arguments related to this optname:

  • Option value: Pointer holding the keepalive configuration in int type. Value “1” indicates enable TCP keepalive. Value “0” indicates disable TCP keepalive.

  • Level: CY_SOCKET_SOL_SOCKET

CY_SOCKET_SO_TCP_KEEPALIVE_INTERVAL

Set the interval in milliseconds between TCP keepalive probes.

Keepalives are sent only when the feature is enabled with the CY_SOCKET_SO_TCP_KEEPALIVE_ENABLE socket option.

Arguments related to this optname:

  • Option value: Pointer holding value of the keepalive interval in uint32_t type.

  • Level: CY_SOCKET_SOL_TCP

CY_SOCKET_SO_TCP_KEEPALIVE_COUNT

Set the maximum number of TCP keepalive probes to be sent before giving up and killing the connection if no response is obtained from the other end.

Keepalives are sent only when the feature is enabled with the CY_SOCKET_SO_TCP_KEEPALIVE_ENABLE socket option.

Arguments related to this optname:

  • Option value: Pointer holding the value of maximum keepalive probe count in uint32_t type.

  • Level: CY_SOCKET_SOL_TCP

CY_SOCKET_SO_TCP_KEEPALIVE_IDLE_TIME

Set the duration for which the connection needs to be idle (in milliseconds) before TCP begins sending out keepalive probes.

Keepalive probes are sent only when the feature is enabled with CY_SOCKET_SO_TCP_KEEPALIVE_ENABLE socket option.

Arguments related to this optname:

  • Option value: Pointer holding the value of keepalive idle time in uint32_t type.

  • Level: CY_SOCKET_SOL_TCP

CY_SOCKET_SO_CONNECT_REQUEST_CALLBACK

Set the callback to be called upon incoming client connection request.

This option is supported only for TCP server sockets. The callback function registered with this option runs in the secure sockets worker thread context. This option is not supported in cy_socket_getsockopt.

Arguments related to this optname:

CY_SOCKET_SO_RECEIVE_CALLBACK

Set the callback to be called when the socket has received data.

The callback function registered with this option runs in the secure sockets worker thread context. This option is not supported in cy_socket_getsockopt.

note

The registered receive callback function is invoked when a network packet is received from the network stack, hence this callback is invoked per network packet. If the data in the packet is consumed partially, the Secure Sockets Library doesn't provide another callback for the remaining data in that packet. Hence it is recommended to read the entire network packet by providing a buffer of MTU size (1460 bytes) to the cy_socket_recv function.

Arguments related to this optname:

CY_SOCKET_SO_DISCONNECT_CALLBACK

Set the callback to be called when the socket is disconnected.

This option is supported only for TCP sockets. The callback function registered with this option runs in the secure sockets worker thread context. This option is not supported in cy_socket_getsockopt.

note

This callback is invoked whenever the peer disconnects. In the callback, cy_socket_disconnect should be invoked. This callback will not be invoked during self-initiated disconnections i.e., when cy_socket_disconnect is called by self.

Arguments related to this optname:

CY_SOCKET_SO_NWRITE

Get the number of bytes pending to be sent by the protocol.

This option is used only with cy_socket_getsockopt. This option is currently not supported; will be supported in a future release.

Arguments related to this optname:

  • Option value: Pointer to the uint32_t type into which the API function fills the number of bytes.

  • Level: CY_SOCKET_SOL_SOCKET

CY_SOCKET_SO_TCP_USER_TIMEOUT

Set the user timeout value that controls the duration transmitted data may remain unacknowledged before a connection is forcefully closed.

This option is currently not supported; will be supported in a future release.

Arguments related to this optname:

  • Option value: Pointer holding the timeout value in uint32_t type.

  • Level: CY_SOCKET_SOL_TCP

CY_SOCKET_SO_TRUSTED_ROOTCA_CERTIFICATE

Set a RootCA certificate specific to the socket, in PEM format.

By default, the RootCA certificates loaded with cy_tls_load_global_root_ca_certificates are used to validate the peer’s certificate. If specific RootCA needs to be used for a socket, this socket option should be used to configure a connection-specific RootCA.

This option is not supported in cy_socket_getsockopt.

Arguments related to this optname:

  • Option value: Pointer to a buffer (char array) holding the certificate data.

  • Level: CY_SOCKET_SOL_TLS

CY_SOCKET_SO_TLS_IDENTITY

Set TLS identity.

This option is not supported in cy_socket_getsockopt.

Arguments related to this optname:

CY_SOCKET_SO_SERVER_NAME_INDICATION

Set the hostname to be used for TLS Server Name Indication (SNI) extension of TLS ClientHello.

Arguments related to this optname:

  • Option value: Pointer to the stream of bytes (char array) holding the hostname.

  • Level: CY_SOCKET_SOL_TLS

CY_SOCKET_SO_ALPN_PROTOCOLS

Set the application protocol list to be included in TLS ClientHello.

This option is not supported in cy_socket_getsockopt.

Arguments related to this optname:

  • Option value: Pointer to the stream of bytes (char array) with protocol names separated by comma. e.g., “h2-16,h2-15,h2-14,h2,spdy/3.1,http/1.1”

  • Level: CY_SOCKET_SOL_TLS

CY_SOCKET_SO_TLS_AUTH_MODE

Set TLS authenticate mode.

Arguments related to this optname:

CY_SOCKET_SO_TLS_MFL

Set the TLS maximum fragment length.

Arguments related to this optname:

CY_SOCKET_SO_JOIN_MULTICAST_GROUP

Join an IPv4 (or) IPv6 multicast group.

This option is not supported in cy_socket_getsockopt.

note

  1. This implementation supports up to 10 multicast groups in total, and across the sockets. This is due to the underlying Wi-Fi Host Driver (WHD) limitation.

  2. The maximum number of IPv4 and IPv6 multicast groups to be supported can be configured using the configuration options provided by the network stack. However, if the total count of both IPv4 and IPv6 multicast groups is more than 10, any attempts to join a new multicast group will fail.

Arguments related to this optname:

CY_SOCKET_SO_LEAVE_MULTICAST_GROUP

Leave an IPv4 (or) IPv6 multicast group.

This option is not supported in cy_socket_getsockopt.

Arguments related to this optname:

CY_SOCKET_SO_IP_MULTICAST_TTL

Set the time-to-live value of outgoing multicast packets for this socket.

Arguments related to this optname:

  • Option value: Pointer holding the time-to-live value in uint8_t type. The value of this socket option should be in the range 0 <= value <= 255. For IPv4, this value is measured in seconds; for IPv6, it is measured in hop limit.

  • Level: CY_SOCKET_SOL_IP

CY_SOCKET_SO_BROADCAST

Enable/disable sending and receiving broadcast messages on the socket.

note

Use this socket option only when broadcast filter is enabled in the network stack configuration. If broadcast filter is disabled in network stack configuration, broadcast messages cannot be controlled with this socket option.

Arguments related to this optname:

  • Option value: Pointer holding the uint8_t value. Value “1” enables broadcast messages. Value “0” disables broadcast messages.

  • Level: CY_SOCKET_SOL_SOCKET

CY_SOCKET_SO_BINDTODEVICE

Set the network interface to be used for sending and receiving data on the socket.

This socket option can be called for more than once for a socket to change the interface it’s bound to.

This option is not supported in cy_socket_getsockopt.

Arguments related to this optname:

CY_SOCKET_SO_IP_TOS

Set the Type-Of-Service (TOS) field that is sent with every IP packet originating from this socket.

Arguments related to this optname:

  • Option value: Pointer holding the type of service value in uint8_t type. The value of this socket option should be in the range 0 <= value <= 255.

  • Level: CY_SOCKET_SOL_IP

CY_SOCKET_SO_BYTES_AVAILABLE

Get the number of bytes immediately available for reading.

Arguments related to this optname:

  • Option value: Pointer to the uint32_t type into which the API function fills the number of bytes available for reading.

  • Level: CY_SOCKET_SOL_SOCKET

CY_SOCKET_SO_TCP_NODELAY

Enable/disable TCP no delay socket option.

If this option is enabled, Nagle’s algorithm is disabled. If Nagle’s algorithm is disabled data packets are sent as soon as possible, even if there is only a small amount of data. If Nagle’s algorithm is enabled data is buffered until there is a sufficient amount to send out.

Arguments related to this optname:

  • Option value: Pointer holding the uint8_t value. Value “0” enables Nagle’s algorithm. Value “1” disables Nagle’s algorithm.

  • Level: CY_SOCKET_SOL_TCP

CY_SOCKET_FLAGS_NONE

cy_socket_send() input flags - No flag.

CY_SOCKET_FLAGS_MORE

cy_socket_send() input flags - The caller indicates that there is additional data to be sent.

This flag is applicable only for TCP connections. Caller will not set this flag for the last data chunk to be sent.

CY_SOCKET_FLAGS_RECVFROM_NONE

cy_socket_recvfrom() input flags - No flag.

CY_SOCKET_FLAGS_RECVFROM_SRC_FILTER

cy_socket_recvfrom() input flags - Used for filtering of input packets.

Packets are received only from the user-specified source address.

CY_SOCKET_POLL_READ

cy_socket_poll() input flags - Check for pending data.

CY_SOCKET_POLL_WRITE

cy_socket_poll() input flags - Check whether write is possible.

CY_SOCKET_SHUT_RD

Option for the “how” parameter of cy_socket_shutdown() - Disables further receive operations.

CY_SOCKET_SHUT_WR

Option for the “how” parameter of cy_socket_shutdown() - Disables further send operations.

CY_SOCKET_SHUT_RDWR

Option for the “how” parameter of cy_socket_shutdown() - Disables further send and receive.

operations.

CY_SOCKET_NEVER_TIMEOUT

Never timeout.