Functions

group group_secure_sockets_functions

All API functions except cy_socket_init and cy_socket_deinit are thread-safe.

All API functions are blocking API functions.

Secure Sockets Library creates a worker thread for processing events from the network stack. The priority of the thread is CY_RTOS_PRIORITY_ABOVENORMAL. The macro CY_RTOS_PRIORITY_ABOVENORMAL is defined in abstraction-rtos/include/COMPONENT_FREERTOS/cyabs_rtos_impl.h.

Functions

cy_rslt_t cy_socket_init(void)

Does general allocation and initialization of resources needed for the library.

This API function must be called before using any other socket API.

note

cy_socket_init and cy_socket_deinit API functions are not thread-safe. The caller must ensure that these two API functions are not invoked simultaneously from different threads.

Return

CY_RSLT_SUCCESS on success; an error code on failure.

cy_rslt_t cy_socket_deinit(void)

Releases the resources allocated in cy_socket_init function.

Prior to calling this API function, all created sockets must be disconnected and deleted.

note

cy_socket_init and cy_socket_deinit API functions are not thread-safe. The caller must ensure that these two API functions are not invoked simultaneously from different threads.

Return

CY_RSLT_SUCCESS on success; an error code on failure. Important error code related to this API function is: CY_RSLT_MODULE_SECURE_SOCKETS_NOT_INITIALIZED

cy_rslt_t cy_socket_create(int domain, int type, int protocol, cy_socket_t *handle)

Creates a new socket.

note

  1. cy_socket_create() function creates a dual-stack socket if domain passed is CY_SOCKET_DOMAIN_AF_INET6.

  2. Secure Sockets Library configures default send and receive timeout values to 10 seconds for a newly created socket. These default values can be overridden using the cy_socket_setsockopt API. Adjust the default timeout values based on the network speed or use case. For example, to change the send timeout, use the CY_SOCKET_SO_SNDTIMEO socket option; similarly, for receive timeout, use the CY_SOCKET_SO_RCVTIMEO socket option.

  3. Secure Socket Library sets default TLS authentication mode for TLS client sockets to CY_SOCKET_TLS_VERIFY_REQUIRED. For TLS server sockets, it sets the default TLS authentication mode to CY_SOCKET_TLS_VERIFY_NONE. To override the default authentication mode, use cy_socket_setsockopt with the CY_SOCKET_SO_TLS_AUTH_MODE socket option.

  4. To use a socket for multicast operations over SoftAP interface, user must bind the socket to the SoftAP interface using CY_SOCKET_SO_BINDTODEVICE socket option after creating the socket.

Valid type/protocol combinations are:

Return

CY_RSLT_SUCCESS on success; an error code on failure. On success, it also returns the socket handle. Important error codes related to this API function are: CY_RSLT_MODULE_SECURE_SOCKETS_BADARG CY_RSLT_MODULE_SECURE_SOCKETS_NOMEM

Parameters

cy_rslt_t cy_socket_connect(cy_socket_t handle, cy_socket_sockaddr_t *address, uint32_t address_length)

Connects a TCP/TLS socket to the specified server IP address and port.

This API function is a blocking call.

For secure (TLS) sockets, before calling this API function, the following TLS configuration can be set:

  1. RootCA using the cy_tls_load_global_root_ca_certificates or cy_socket_setsockopt API function with CY_SOCKET_SO_TRUSTED_ROOTCA_CERTIFICATE.

  2. Certificate/key pair with cy_tls_create_identity and cy_socket_setsockopt with CY_SOCKET_SO_TLS_IDENTITY.

  3. For TLS client sockets, the default authentication mode set is CY_SOCKET_TLS_VERIFY_REQUIRED. To override the default authentication mode, use cy_socket_setsockopt with the CY_SOCKET_SO_TLS_AUTH_MODE socket option.

  4. The default mbed TLS configuration provided by the Wi-Fi Middleware Core Library disables the validity period verification of the certificates. To perform this verification, enable MBEDTLS_HAVE_TIME_DATE in the mbedtls_user_config.h file. Ensure that the system time is set prior to the cy_socket_connect() function call. To set the system time, get the time from the NTP server and set the system’s RTC time using cyhal_rtc_init(), cyhal_rtc_write() and cy_set_rtc_instance() functions. See the Time Support Details for reference. See the Code Snippet 12: Get the current time from the NTP server - Send an NTP request packet to the NTP server, and receive an NTP reply packet. to get the time from NTP server.

note

This is applicable if Secure Sockets Library is built for lwIP network stack. If this function returns CY_RSLT_MODULE_SECURE_SOCKETS_CLOSED error, the socket handle cannot be reused to establish the connection. The caller should invoke cy_socket_delete API function to delete the current socket handle, and create a new socket handle using cy_socket_create API function to re-establish the connection. This is required, due to the limitation of lwIP stack.

Return

CY_RSLT_SUCCESS on success; an error code on failure. Important error codes related to this API function are: CY_RSLT_MODULE_SECURE_SOCKETS_INVALID_SOCKET CY_RSLT_MODULE_SECURE_SOCKETS_BADARG CY_RSLT_MODULE_SECURE_SOCKETS_TLS_ERROR CY_RSLT_MODULE_SECURE_SOCKETS_TCPIP_ERROR CY_RSLT_MODULE_SECURE_SOCKETS_TIMEOUT CY_RSLT_MODULE_SECURE_SOCKETS_NOMEM

Parameters

cy_rslt_t cy_socket_disconnect(cy_socket_t handle, uint32_t timeout)

Disconnects a TCP/TLS socket’s remote connection.

Timeout is not supported by all network stacks. If the underlying network stack does not support the timeout option, this function returns after a clean disconnect. lwIP does not support the timeout option.

note

Ensure that this API function is also called when the socket send/receive API fails with the error CY_RSLT_MODULE_SECURE_SOCKETS_CLOSED.

Return

CY_RSLT_SUCCESS on success; an error code on failure. Important error codes related to this API function are: CY_RSLT_MODULE_SECURE_SOCKETS_INVALID_SOCKET CY_RSLT_MODULE_SECURE_SOCKETS_NOT_CONNECTED

Parameters
  • [in] handle: Socket handle returned by either the cy_socket_create API function for client sockets, or by the cy_socket_accept API function for accepted sockets.

  • [in] timeout: Maximum amount of time to wait in milliseconds for a clean disconnect. When the timeout is zero, the function returns after a clean disconnect or when the operation results in an error.

cy_rslt_t cy_socket_bind(cy_socket_t handle, cy_socket_sockaddr_t *address, uint32_t address_length)

Binds the socket to the given socket address.

Return

CY_RSLT_SUCCESS on success; an error code on failure. Important error codes related to this API function are: CY_RSLT_MODULE_SECURE_SOCKETS_INVALID_SOCKET CY_RSLT_MODULE_SECURE_SOCKETS_BADARG CY_RSLT_MODULE_SECURE_SOCKETS_TCPIP_ERROR CY_RSLT_MODULE_SECURE_SOCKETS_NOMEM CY_RSLT_MODULE_SECURE_SOCKETS_PROTOCOL_NOT_SUPPORTED

Parameters

cy_rslt_t cy_socket_listen(cy_socket_t handle, int backlog)

Listens for TCP/TLS socket connections and limits the queue of incoming connections.

If the socket has been configured with a connection request callback, the registered callback will be invoked when the new client connection request is received. Invoke the cy_socket_accept API function from the callback function to accept the client connection.

Return

CY_RSLT_SUCCESS on success; an error code on failure. Important error codes related to this API function are: CY_RSLT_MODULE_SECURE_SOCKETS_INVALID_SOCKET CY_RSLT_MODULE_SECURE_SOCKETS_BADARG CY_RSLT_MODULE_SECURE_SOCKETS_TCPIP_ERROR

Parameters
  • [in] handle: Socket handle returned by the cy_socket_create API function.

  • [in] backlog: Maximum pending connections allowed.

cy_rslt_t cy_socket_accept(cy_socket_t handle, cy_socket_sockaddr_t *address, uint32_t *address_length, cy_socket_t *socket)

Accepts a new TCP/TLS connection on a socket.

This is a blocking API function that returns when there is an incoming connection request from a client.

However, when the CY_SOCKET_SO_RCVTIMEO socket option is set on the listening socket (input socket handle param), this API function returns with a CY_RSLT_MODULE_SECURE_SOCKETS_TIMEOUT error if there is no connection request from a client within the timeout period.

CY_SOCKET_SO_RCVTIMEO can be set using the cy_socket_setsockopt API function.

Return

CY_RSLT_SUCCESS on success; an error code on failure. Important error codes related to this API function are: CY_RSLT_MODULE_SECURE_SOCKETS_INVALID_SOCKET CY_RSLT_MODULE_SECURE_SOCKETS_TLS_ERROR CY_RSLT_MODULE_SECURE_SOCKETS_TIMEOUT CY_RSLT_MODULE_SECURE_SOCKETS_NOMEM CY_RSLT_MODULE_SECURE_SOCKETS_BADARG CY_RSLT_MODULE_SECURE_SOCKETS_NOT_LISTENING

Parameters
  • [in] handle: Socket handle that has been created with cy_socket_create, bound to a local address with cy_socket_bind, and is listening for connections after a call to cy_socket_listen. This is the server-side socket that is reused to establish connections across clients.

  • [out] address: Address of the peer socket in the cy_socket_sockaddr_t structure. Refer cy_socket_ip_address_t for IP address endienness.

  • [out] address_length: Contains the actual size of the peer socket address.

  • [out] socket: Socket handle for the accepted connection with a client. This is the socket that should be used for further communication over a new client connection.

cy_rslt_t cy_socket_send(cy_socket_t handle, const void *buffer, uint32_t length, int flags, uint32_t *bytes_sent)

Sends data over a connected TCP/TLS socket.

note

Ensure that the cy_socket_disconnect API function is called when this API function fails with the CY_RSLT_MODULE_SECURE_SOCKETS_CLOSED error. lwIP doesn't allow the socket to be reused after disconnection. Therefore, the caller should call cy_socket_disconnect and cy_socket_delete API functions to delete the closed socket. This is applicable if Secure Sockets Library is built for lwIP network stack.

Return

CY_RSLT_SUCCESS on success; an error code on failure. On success, it also returns the number of bytes sent. Important error codes related to this API function are: CY_RSLT_MODULE_SECURE_SOCKETS_INVALID_SOCKET CY_RSLT_MODULE_SECURE_SOCKETS_TLS_ERROR CY_RSLT_MODULE_SECURE_SOCKETS_TCPIP_ERROR CY_RSLT_MODULE_SECURE_SOCKETS_TIMEOUT CY_RSLT_MODULE_SECURE_SOCKETS_NOT_CONNECTED CY_RSLT_MODULE_SECURE_SOCKETS_CLOSED

Parameters
  • [in] handle: Socket handle returned by either the cy_socket_create API function for client sockets, or by the cy_socket_accept API function for accepted sockets.

  • [in] buffer: Buffer containing the data to be sent.

  • [in] length: Length of the data to be sent.

  • [in] flags: Flags to indicate the send options: CY_SOCKET_FLAGS_NONE and CY_SOCKET_FLAGS_MORE

  • [out] bytes_sent: Number of bytes sent.

cy_rslt_t cy_socket_sendto(cy_socket_t handle, const void *buffer, uint32_t length, int flags, const cy_socket_sockaddr_t *dest_addr, uint32_t address_length, uint32_t *bytes_sent)

Sends a UDP datagram over a specified socket.

note

If an ARP entry for the specified destination address is not present in the ARP cache, this function sends an ARP request and waits for ARP_WAIT_TIME_IN_MSEC time for MAC address resolution. If the MAC address is not resolved within the timeout, this function returns the error code CY_RSLT_MODULE_SECURE_SOCKETS_ARP_TIMEOUT. Upon receiving this error, the caller can retry this API again after a brief delay.

Return

CY_RSLT_SUCCESS on success; an error code on failure. On success, it also returns the number of bytes sent. Important error code related to this API function is: CY_RSLT_MODULE_SECURE_SOCKETS_INVALID_SOCKET CY_RSLT_MODULE_SECURE_SOCKETS_NETIF_DOES_NOT_EXIST CY_RSLT_MODULE_SECURE_SOCKETS_ARP_TIMEOUT CY_RSLT_MODULE_SECURE_SOCKETS_ERROR_ROUTING

Parameters
  • [in] handle: Socket handle returned by the cy_socket_create API function for UDP sockets.

  • [in] buffer: Buffer containing the data to be sent.

  • [in] length: Length of the data to be sent.

  • [in] flags: Flags to indicate send options. Currently, this argument is not used; this is reserved for the future.

  • [in] dest_addr: Pointer to the cy_socket_sockaddr_t structure that contains the destination address to send the data to. Refer cy_socket_ip_address_t for IP address endienness.

  • [in] address_length: Length of the cy_socket_sockaddr_t structure.

  • [out] bytes_sent: Number of bytes sent.

cy_rslt_t cy_socket_recv(cy_socket_t handle, void *buffer, uint32_t length, int flags, uint32_t *bytes_received)

Receives the data from a connected TCP/TLS socket.

note

Ensure that the cy_socket_disconnect API function is called when this API function fails with the CY_RSLT_MODULE_SECURE_SOCKETS_CLOSED error. lwIP doesn't allow the socket to be reused after disconnection. Therefore, the caller should call cy_socket_disconnect and cy_socket_delete API functions to delete the closed socket. This is applicable if Secure Sockets Library is built for lwIP network stack.

Return

CY_RSLT_SUCCESS on success; an error code on failure. On success, it also returns number of bytes received. Important error codes related to this API function are: CY_RSLT_MODULE_SECURE_SOCKETS_INVALID_SOCKET CY_RSLT_MODULE_SECURE_SOCKETS_TLS_ERROR CY_RSLT_MODULE_SECURE_SOCKETS_TCPIP_ERROR CY_RSLT_MODULE_SECURE_SOCKETS_TIMEOUT CY_RSLT_MODULE_SECURE_SOCKETS_CLOSED

Parameters
  • [in] handle: Socket handle returned by either the cy_socket_create API function for client sockets, or by cy_socket_accept API function for accepted sockets.

  • [out] buffer: Buffer into which received data will be placed.

  • [in] length: Size of the data buffer.

  • [in] flags: Not currently used. Should be set to CY_SOCKET_FLAGS_NONE.

  • [out] bytes_received: Number of bytes received.

cy_rslt_t cy_socket_recvfrom(cy_socket_t handle, void *buffer, uint32_t length, int flags, cy_socket_sockaddr_t *src_addr, uint32_t *src_addr_length, uint32_t *bytes_received)

Receives a UDP datagram for the specified socket.

note

  1. If the datagram is larger than the supplied buffer, excess bytes in the datagram is discarded.

  2. To receive data from a specific source address, the caller should set CY_SOCKET_FLAGS_RECVFROM_SRC_FILTER flag in the 'flags' parameter, and assign the source address through the 'src_addr' parameter. If CY_SOCKET_FLAGS_RECVFROM_SRC_FILTER flag is set and src_addr is NULL, this function returns with the error code CY_RSLT_MODULE_SECURE_SOCKETS_BADARG.

Return

CY_RSLT_SUCCESS on success; an error code on failure. On success, it returns the number of bytes received. If src_addr is not NULL it also returns sender address. Important error code related to this API function is: CY_RSLT_MODULE_SECURE_SOCKETS_INVALID_SOCKET CY_RSLT_MODULE_SECURE_SOCKETS_BADARG

Parameters
  • [in] handle: Socket handle returned by either the cy_socket_create API function for client sockets, or by cy_socket_accept API function for accepted sockets.

  • [out] buffer: Buffer into which the received data will be placed.

  • [in] length: Size of the data buffer.

  • [in] flags: Flags to control the datagram to be received. Refer CY_SOCKET_FLAGS_RECVFROM_NONE and CY_SOCKET_FLAGS_RECVFROM_SRC_FILTER.

  • [inout] src_addr: Pointer to the cy_socket_sockaddr_t structure to store the sender’s address. If passed as NULL, the sender’s address is not returned to the caller. If the CY_SOCKET_FLAGS_RECVFROM_SRC_FILTER flag is set, it contains the source address from which the datagram to be received. Refer cy_socket_ip_address_t for IP address endienness.

  • [in] src_addr_length: Pointer containing source address length. Currently, this argument is not used; this is reserved for the future.

  • [out] bytes_received: Number of bytes received.

cy_rslt_t cy_socket_setsockopt(cy_socket_t handle, int level, int optname, const void *optval, uint32_t optlen)

Sets a particular socket option.

This API function can be called multiple times for the same socket to set various socket options.

Return

CY_RSLT_SUCCESS on success; an error code on failure. Important error codes related to this API function are: CY_RSLT_MODULE_SECURE_SOCKETS_BADARG CY_RSLT_MODULE_SECURE_SOCKETS_INVALID_SOCKET CY_RSLT_MODULE_SECURE_SOCKETS_ALREADY_CONNECTED CY_RSLT_MODULE_SECURE_SOCKETS_INVALID_OPTION CY_RSLT_MODULE_SECURE_SOCKETS_ADDRESS_IN_USE CY_RSLT_MODULE_SECURE_SOCKETS_MAX_MEMBERSHIP_ERROR CY_RSLT_MODULE_SECURE_SOCKETS_MULTICAST_ADDRESS_NOT_REGISTERED CY_RSLT_MODULE_SECURE_SOCKETS_OPTION_NOT_SUPPORTED

Parameters

cy_rslt_t cy_socket_getsockopt(cy_socket_t handle, int level, int optname, void *optval, uint32_t *optlen)

Gets the value of a particular socket option.

Return

CY_RSLT_SUCCESS on success; an error code on failure. Important error codes related to this API function are: CY_RSLT_MODULE_SECURE_SOCKETS_BADARG CY_RSLT_MODULE_SECURE_SOCKETS_INVALID_SOCKET CY_RSLT_MODULE_SECURE_SOCKETS_INVALID_OPTION CY_RSLT_MODULE_SECURE_SOCKETS_PROTOCOL_NOT_SUPPORTED CY_RSLT_MODULE_SECURE_SOCKETS_OPTION_NOT_SUPPORTED

Parameters

cy_rslt_t cy_socket_gethostbyname(const char *hostname, cy_socket_ip_version_t ip_ver, cy_socket_ip_address_t *addr)

Resolves a host name using Domain Name Service.

Return

On success it returns CY_RSLT_SUCCESS and the IP address of the specified host. Returns an error code on failure. Important error codes related to this API function are: CY_RSLT_MODULE_SECURE_SOCKETS_BADARG CY_RSLT_MODULE_SECURE_SOCKETS_HOST_NOT_FOUND

Parameters
  • [in] hostname: Hostname to resolve. It should be a null-terminated string containing ASCII characters.

  • [in] ip_ver: IP version type cy_socket_ip_version_t for which the hostname has to be resolved.

  • [out] addr: IP address of the specified host. Refer cy_socket_ip_address_t for IP address endienness.

cy_rslt_t cy_socket_poll(cy_socket_t handle, uint32_t *rwflags, uint32_t timeout)

Checks whether data is available on the socket.

Return

On success, it returns CY_RSLT_SUCCESS. The CY_SOCKET_POLL_READ flag is set in the rwflags parameter if data is available for read. The CY_SOCKET_POLL_WRITE flag is set if the socket is ready for write operations. Returns an error code on failure. Important error codes related to this API function are: CY_RSLT_MODULE_SECURE_SOCKETS_INVALID_SOCKET CY_RSLT_MODULE_SECURE_SOCKETS_NOT_CONNECTED

Parameters
  • [in] handle: Socket handle returned by either the cy_socket_create API function for client sockets, or by cy_socket_accept API function for accepted sockets.

  • [inout] rwflags: On input, the flags indicate whether the socket needs to be polled for read/write/read-write operation. On return, the flags are updated to indicate the status of the socket readiness for a read/write/read-write operation.

  • [in] timeout: Maximum amount of time in milliseconds to wait before returning. If timeout is zero, the function returns immediately. If timeout is CY_SOCKET_NEVER_TIMEOUT, the function waits indefinitely.

cy_rslt_t cy_socket_shutdown(cy_socket_t handle, int how)

Shuts down the send and/or receive operation on the given TCP socket.

note

This API is not applicable for UDP.

Return

CY_RSLT_SUCCESS on success; an error code on failure. Important error code related to this API function is: CY_RSLT_MODULE_SECURE_SOCKETS_INVALID_SOCKET CY_RSLT_MODULE_SECURE_SOCKETS_BADARG

Parameters

cy_rslt_t cy_socket_delete(cy_socket_t handle)

Releases the resources allocated for the socket by the cy_socket_create function.

Return

CY_RSLT_SUCCESS on success; an error code on failure. Important error code related to this API function is: CY_RSLT_MODULE_SECURE_SOCKETS_INVALID_SOCKET

Parameters