sl_si91x_socket_receive_data_callback_t#

sl_si91x_socket_receive_data_callback_t )(uint32_t socket, uint8_t *buffer, uint32_t length, const sl_si91x_socket_metadata_t *firmware_socket_response)

Callback function reads asynchronous data from the socket.

The callback function reads asynchronous data from the socket when the sl_si91x_socket_async API is registered and called. The callback provides the following details: socket ID, pointer to the buffer which contains receiver data, size of the buffer, and metadata of the receiver packet (such as IP address, and port number).

Returns

• N/A

sl_si91x_socket_accept_callback_t#

sl_si91x_socket_accept_callback_t )(int32_t socket, struct sockaddr *addr, uint8_t ip_version)

Callback functions for new asynchronous accepted connection.

The callback provides paramenters for new accepted connection when the sl_si91x_accept_async API is registered and called. The callback provides the following details: socket ID of the accepted connection, address of remoter peer, and IP version of connection.

Returns

• N/A

sl_si91x_socket_data_transfer_complete_handler_t#

sl_si91x_socket_data_transfer_complete_handler_t )(int32_t socket, uint16_t length)

Callback function indicates data transfer status.

The callback indicates the data transfer completion status when either of the sl_si91x_send_async or sl_si91x_sendto_async API is registered and called. The callback provides the socket ID, and the number of bytes that are successfully transfer.

Returns

• N/A

sl_si91x_socket_select_callback_t#

sl_si91x_socket_select_callback_t )(fd_set *fd_read, fd_set *fd_write, fd_set *fd_except, int32_t status)

Callback function indicates asynchronous select request result.

The callback indicates asynchronous response reaches the select request when the sl_si91x_select API is registered and called. The callback provides the following details: file descriptor sets for read, write, and exception conditions, and status of the selected request.

Returns

• N/A

sl_si91x_socket_remote_termination_callback_t#

sl_si91x_socket_remote_termination_callback_t )(int socket, uint16_t port, uint32_t bytes_sent)

Callback function indicates termination of the remote socket.

The callback function notifies on the termination of the remote socket when the sl_si91x_set_remote_termination_callback API is registered and called. The callback provides the following details: socket ID, remote socket port number, and number of bytes sent before termination of the remote socket.

Returns

• The callback does not returns value.

sl_si91x_socket#

int sl_si91x_socket (int family, int type, int protocol)

Creates a new socket.

The function creates a new socket and returns a file descriptor for the respective socket. The socket is used for communication within the specified protocol family, type, and protocol. The created socket is used for various network operations such as, connecting to a remote host, sending and receiving data, and so on.

• Pre-conditions:

  • The Wi-Fi/Net stack must be initialized and a network profile must be up.

  • If socket resources are configured via sl_si91x_config_socket(), that call must be made before sl_si91x_socket().

• Post-conditions:

  • On success a new socket descriptor is allocated and can be passed to sl_si91x_bind(), sl_si91x_connect(), sl_si91x_listen(), sl_si91x_send(), sl_si91x_recv(), etc.

  • On failure no descriptor is allocated and errno is set.

Returns

• Returns the socket ID or file descriptor for the newly created socket on success, or -1 on failure with errno set.

Return values

• >=0: Valid socket descriptor.

• -1/EAFNOSUPPORT: family

• -1/EPROTONOSUPPORT: protocol

• -1/EINVAL: Invalid combination of

• -1/EMFILE: No free socket descriptor available.

• -1/ENOMEM: Not enough memory to allocate the socket.

Note

• Thread safety:

  • Thread-safe: multiple threads may call sl_si91x_socket() concurrently to obtain distinct descriptors.

• Side effects:

  • Allocates an entry in the internal SiWx91x socket pool. Updates errno on failure.

See Also

• sl_si91x_bind(), sl_si91x_connect(), sl_si91x_listen(), sl_si91x_socket_async(), sl_si91x_config_socket()

• Example#

  Create a synchronous SiWx91x TCP socket:

  int sock = sl_si91x_socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
  if (sock < 0) {
    printf("sl_si91x_socket() failed, errno = %d\r\n", errno);
    return -1;
  }
  int sock = sl_si91x_socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
  if (sock < 0) {
    printf("sl_si91x_socket() failed, errno = %d\r\n", errno);
    return -1;
  }
  

sl_si91x_socket_async#

int sl_si91x_socket_async (int family, int type, int protocol, sl_si91x_socket_receive_data_callback_t callback)

Creates an asynchronous socket and registers the provided callback.

This function creates a new asynchronous socket and registers a callback function that is called whenever data is received on the socket. The socket can be used for communication within the specified protocol family, type, and protocol.

• Pre-conditions:

  • The Wi-Fi/Net stack must be initialized and a network profile must be up.

  • callback must be non-NULL and remain valid for the lifetime of the socket.

• Post-conditions:

  • On success the socket is created and callback is registered to be invoked from the stack context whenever data is received.

Returns

• Returns the socket ID or file descriptor for the newly created socket on success, or -1 on failure with errno set.

Return values

• >=0: Valid asynchronous socket descriptor.

• -1/EINVAL: callback

• -1/EAFNOSUPPORT: family

• -1/EPROTONOSUPPORT: protocol

• -1/EMFILE: No free socket descriptor available.

• -1/ENOMEM: Not enough memory to allocate the socket.

Note

• Thread safety:

  • Thread-safe for creation. The registered callback is invoked from an internal stack thread; user logic inside the callback must be thread-safe with the rest of the application.

• Side effects:

  • Allocates an entry in the internal socket pool and registers the RX callback.

See Also

• sl_si91x_socket(), sl_si91x_accept_async(), sl_si91x_send_async(), sl_si91x_set_remote_termination_callback()

• Example#

  Define an asynchronous RX handler that the stack invokes when data arrives:

  static void on_data_rx(uint32_t sock_id,
                         uint8_t *buffer,
                         uint32_t length,
                         const sl_si91x_socket_metadata_t *metadata)
  {
    UNUSED_PARAMETER(buffer);
    UNUSED_PARAMETER(metadata);
    printf("Socket %u received %u bytes\r\n", sock_id, length);
  }
  static void on_data_rx(uint32_t sock_id,
                         uint8_t *buffer,
                         uint32_t length,
                         const sl_si91x_socket_metadata_t *metadata)
  {
    UNUSED_PARAMETER(buffer);
    UNUSED_PARAMETER(metadata);
    printf("Socket %u received %u bytes\r\n", sock_id, length);
  }
  

Create an asynchronous TCP socket and register the RX callback:

int sock = sl_si91x_socket_async(AF_INET, SOCK_STREAM, IPPROTO_TCP, on_data_rx);
if (sock < 0) {
  printf("sl_si91x_socket_async() failed, errno = %d\r\n", errno);
  return -1;
}
int sock = sl_si91x_socket_async(AF_INET, SOCK_STREAM, IPPROTO_TCP, on_data_rx);
if (sock < 0) {
  printf("sl_si91x_socket_async() failed, errno = %d\r\n", errno);
  return -1;
}

sl_si91x_setsockopt#

int sl_si91x_setsockopt (int32_t socket, int level, int option_name, const void * option_value, socklen_t option_len)

Sets a specified socket option on the identified socket asynchronously.

This function sets a specified option for a given socket asynchronously. The options can be set at various levels and include parameters such as receive timeout, maximum retries, maximum segment size, TCP keepalive, SSL options, and so on.

• Pre-conditions:

  • socket must be a valid descriptor returned by sl_si91x_socket() or sl_si91x_socket_async().

  • Must be called before sl_si91x_connect() / sl_si91x_listen() (TCP) or before sl_si91x_sendto() / sl_si91x_recvfrom() / sl_si91x_connect() (UDP).

• Post-conditions:

  • On success the option is applied to the socket.

Returns

• Returns 0 on success, or -1 on failure with errno set.

Return values

• 0: Success.

• -1/EBADF: socket

• -1/ENOTSOCK: socket

• -1/EINVAL: option_value

• -1/ENOPROTOOPT: option_name

Note

• Thread safety:

  • Not thread-safe on the same descriptor; serialize concurrent access.

• Side effects:

  • Changes internal SiWx91x socket state; TLS-related options change the next handshake.

See Also

• sl_si91x_socket(), sl_si91x_connect(), sl_si91x_listen()

Note

• This function is used only for the SiWx91x socket API. The options set in this function will not be effective if called after sl_si91x_connect() or sl_si91x_listen() for TCP, or after sl_si91x_sendto(), sl_si91x_recvfrom(), or sl_si91x_connect() for UDP. The value of the option SL_SI91X_SO_MAX_RETRANSMISSION_TIMEOUT_VALUE should be a power of 2 between 1 and 128.

• Example#

  1. Mark the socket as a high-performance RX socket (must be done before connect/listen):

     uint32_t high_performance = BIT(7);
     if (sl_si91x_setsockopt(sock,
                             SOL_SOCKET,
                             SL_SI91X_SO_HIGH_PERFORMANCE_SOCKET,
                             &high_performance,
                             sizeof(high_performance)) < 0) {
       printf("setsockopt(SL_SI91X_SO_HIGH_PERFORMANCE_SOCKET) failed, errno = %d\r\n", errno);
     }
     uint32_t high_performance = BIT(7);
     if (sl_si91x_setsockopt(sock,
                             SOL_SOCKET,
                             SL_SI91X_SO_HIGH_PERFORMANCE_SOCKET,
                             &high_performance,
                             sizeof(high_performance)) < 0) {
       printf("setsockopt(SL_SI91X_SO_HIGH_PERFORMANCE_SOCKET) failed, errno = %d\r\n", errno);
     }
     

  2. Enable TLS 1.2 on the socket:

     uint8_t ssl_version = SL_SI91X_ENABLE_TLS | SL_SI91X_TLS_V_1_2;
     if(sl_si91x_setsockopt(sock, SOL_SOCKET, SL_SI91X_SO_SSL_V_1_2_ENABLE,
                               &ssl_version, sizeof(ssl_version)) < 0) {
      printf("setsockopt(SL_SI91X_SO_SSL_V_1_2_ENABLE) failed, errno = %d\r\n", errno);
     }
     uint8_t ssl_version = SL_SI91X_ENABLE_TLS | SL_SI91X_TLS_V_1_2;
     if(sl_si91x_setsockopt(sock, SOL_SOCKET, SL_SI91X_SO_SSL_V_1_2_ENABLE,
                               &ssl_version, sizeof(ssl_version)) < 0) {
      printf("setsockopt(SL_SI91X_SO_SSL_V_1_2_ENABLE) failed, errno = %d\r\n", errno);
     }
     

  3. Select the TLS certificate index (0-3) to use:

     uint8_t cert_index = 0;
     if(sl_si91x_setsockopt(sock, SOL_SOCKET, SL_SI91X_SO_CERT_INDEX,
                               &cert_index, sizeof(cert_index)) < 0) {
      printf("setsockopt(SL_SI91X_SO_CERT_INDEX) failed, errno = %d\r\n", errno);
     }
     uint8_t cert_index = 0;
     if(sl_si91x_setsockopt(sock, SOL_SOCKET, SL_SI91X_SO_CERT_INDEX,
                               &cert_index, sizeof(cert_index)) < 0) {
      printf("setsockopt(SL_SI91X_SO_CERT_INDEX) failed, errno = %d\r\n", errno);
     }
     

sl_si91x_bind#

int sl_si91x_bind (int socket, const struct sockaddr * addr, socklen_t addr_len)

Assigns a local protocol address to a socket.

The function binds a socket to a specific local address and port number. It is typically used on the server side to specify the port on which the server will listen for incoming connections.

• Pre-conditions:

  • socket must be a valid descriptor returned by sl_si91x_socket() / sl_si91x_socket_async().

• Post-conditions:

  • On success the socket is associated with the supplied local address/port.

Returns

• Returns 0 on success, or -1 on failure with errno set.

Return values

• 0: Success.

• -1/EBADF: socket

• -1/ENOTSOCK: socket

• -1/EINVAL: addr

• -1/EADDRINUSE: The requested address/port is already in use.

• -1/EAFNOSUPPORT: addr->sa_family

Note

• Thread safety:

  • Not thread-safe on the same descriptor; serialize concurrent access.

• Side effects:

  • Reserves the local address/port in the stack.

See Also

• sl_si91x_socket(), sl_si91x_listen(), sl_si91x_connect()

• Example#

  Bind the SiWx91x server socket to any local interface on port 5000:

  struct sockaddr_in server_addr = { 0 };
  server_addr.sin_family         = AF_INET;
  server_addr.sin_port           = 5000;
  server_addr.sin_addr.s_addr    = INADDR_ANY;
  
  if (sl_si91x_bind(sock, (struct sockaddr *)&server_addr, sizeof(server_addr)) < 0) {
    printf("sl_si91x_bind() failed, errno = %d\r\n", errno);
    close(sock);
    return -1;
  }
  struct sockaddr_in server_addr = { 0 };
  server_addr.sin_family         = AF_INET;
  server_addr.sin_port           = 5000;
  server_addr.sin_addr.s_addr    = INADDR_ANY;
  
  if (sl_si91x_bind(sock, (struct sockaddr *)&server_addr, sizeof(server_addr)) < 0) {
    printf("sl_si91x_bind() failed, errno = %d\r\n", errno);
    close(sock);
    return -1;
  }
  

sl_si91x_listen#

int sl_si91x_listen (int socket, int max_number_of_clients)

Enables a socket to listen for remote connection requests in passive mode.

The function configures a socket to listen for incoming connection requests. It is typically used on the server side after the socket has been bound to a local address using the sl_si91x_bind function. The socket enters passive mode, where it waits for remote clients to connect.

• Pre-conditions:

  • socket must be a TCP socket bound via sl_si91x_bind().

• Post-conditions:

  • On success the socket transitions into the listening state.

Returns

• Returns 0 on success, or -1 on failure with errno set.

Return values

• 0: Success.

• -1/EBADF: socket

• -1/ENOTSOCK: socket

• -1/EOPNOTSUPP: The socket type does not support listening (e.g. UDP).

• -1/EINVAL: Socket is not bound or

Note

• Thread safety:

  • Not thread-safe on the same descriptor; serialize concurrent access.

• Side effects:

  • Allocates a pending-connection queue of size max_number_of_clients in the stack.

See Also

• sl_si91x_socket(), sl_si91x_bind(), sl_si91x_accept(), sl_si91x_accept_async(), sl_si91x_config_socket()

• Example#

  Place the SiWx91x server socket into passive/listen mode (1 pending client):

  if (sl_si91x_listen(sock, 1) < 0) {
    printf("sl_si91x_listen() failed, errno = %d\r\n", errno);
    close(sock);
    return -1;
  }
  if (sl_si91x_listen(sock, 1) < 0) {
    printf("sl_si91x_listen() failed, errno = %d\r\n", errno);
    close(sock);
    return -1;
  }
  

sl_si91x_accept#

int sl_si91x_accept (int socket, const struct sockaddr * addr, socklen_t addr_len)

Accepts a connection request from a remote peer.

The function blocks until a client attempts to connect to the server socket. After receiving a connection request, it proceeds.

• Pre-conditions:

  • socket must be a listening TCP socket placed in passive mode via sl_si91x_listen().

• Post-conditions:

  • On success a new connected socket descriptor is returned. addr is populated with the peer's address when non-NULL.

  • The original listening descriptor remains open and usable for further sl_si91x_accept() calls.

Returns

• Returns a non-negative socket descriptor for the accepted connection on success, or -1 on failure with errno set.

Return values

• >=0: Descriptor for the accepted connection.

• -1/EBADF: socket

• -1/ENOTSOCK: socket

• -1/EINVAL: Socket is not listening or arguments are invalid.

• -1/EMFILE: No free descriptor to allocate for the accepted connection.

• -1/ECONNABORTED: A connection has been aborted before

Note

• Thread safety:

  • Not thread-safe on the same listening descriptor; serialize concurrent sl_si91x_accept() calls.

• Side effects:

  • Blocks the calling thread until a client connects. Allocates a new socket slot for the accepted connection.

See Also

• sl_si91x_socket(), sl_si91x_bind(), sl_si91x_listen(), sl_si91x_accept_async()

• Example#

  Synchronously accept an incoming TCP client on a listening server socket:

  struct sockaddr_in client_addr = { 0 };
  
  int client_sock = sl_si91x_accept(sock,
                                    (struct sockaddr *)&client_addr,
                                    sizeof(client_addr));
  if (client_sock < 0) {
    printf("sl_si91x_accept() failed, errno = %d\r\n", errno);
    close(sock);
    return -1;
  }
  struct sockaddr_in client_addr = { 0 };
  
  int client_sock = sl_si91x_accept(sock,
                                    (struct sockaddr *)&client_addr,
                                    sizeof(client_addr));
  if (client_sock < 0) {
    printf("sl_si91x_accept() failed, errno = %d\r\n", errno);
    close(sock);
    return -1;
  }
  

sl_si91x_accept_async#

int sl_si91x_accept_async (int socket, sl_si91x_socket_accept_callback_t callback)

Accepts a connection request from the remote peer and registers a callback.

The function sets up the server socket to listen for incoming connections, and immediately returns without blocking the main program's execution.

• Pre-conditions:

  • socket must be a listening TCP socket placed in passive mode via sl_si91x_listen().

  • callback must be non-NULL.

• Post-conditions:

  • On success, the registration is complete and callback is invoked from the stack context whenever a new client connects.

  • The original descriptor remains open.

Returns

• Returns 0 on success, or -1 on failure with errno set.

Return values

• 0: Registration complete; accepted clients are delivered via

• -1/EBADF: socket

• -1/ENOTSOCK: socket

• -1/EINVAL: callback

Note

• Thread safety:

  • Thread-safe for registration. The registered callback is invoked from an internal stack thread; user logic inside the callback must be thread-safe with the rest of the application.

• Side effects:

  • Registers the async-accept handler in the SiWx91x stack.

See Also

• sl_si91x_listen(), sl_si91x_accept(), sl_si91x_socket_async(), sl_si91x_set_remote_termination_callback()

• Example#

  Define a callback that the stack invokes when a new client connects:

  static void on_client_connected(int32_t sock_id,
                                  struct sockaddr *addr,
                                  uint8_t ip_version)
  {
    (void)addr;
    (void)ip_version;
    printf("New client on socket %ld\r\n", (long)sock_id);
  }
  static void on_client_connected(int32_t sock_id,
                                  struct sockaddr *addr,
                                  uint8_t ip_version)
  {
    (void)addr;
    (void)ip_version;
    printf("New client on socket %ld\r\n", (long)sock_id);
  }
  

Non-blocking accept: returns immediately and the callback is invoked later:

if (sl_si91x_accept_async(sock, on_client_connected) < 0) {
  printf("sl_si91x_accept_async() failed, errno = %d\r\n", errno);
  close(sock);
  return -1;
}
if (sl_si91x_accept_async(sock, on_client_connected) < 0) {
  printf("sl_si91x_accept_async() failed, errno = %d\r\n", errno);
  close(sock);
  return -1;
}

sl_si91x_connect#

int sl_si91x_connect (int socket, const struct sockaddr * addr, socklen_t addr_len)

Initiates a connection to a remote socket specified by the addr parameter.

The function initiates a connection to a remote socket specified by the addr parameter. It is typically used on the client side to establish a connection to a server.

• Pre-conditions:

  • socket must be a descriptor returned by sl_si91x_socket() / sl_si91x_socket_async().

  • For TLS: sl_si91x_setsockopt() must have been called for the relevant SSL options before sl_si91x_connect().

• Post-conditions:

  • On success a TCP socket enters the connected state. For UDP, the peer is cached for subsequent send/recv.

Returns

• Returns 0 on success, or -1 on failure with errno set.

Return values

• 0: Success.

• -1/EBADF: socket

• -1/ENOTSOCK: socket

• -1/EINVAL: Invalid

• -1/EAFNOSUPPORT: Address family does not match the socket family.

• -1/ECONNREFUSED: Remote peer refused the connection.

• -1/ETIMEDOUT: Connection attempt timed out.

• -1/ENETUNREACH: No route to the remote peer.

• -1/EISCONN: Socket is already connected.

Note

• Thread safety:

  • Not thread-safe on the same descriptor; serialize concurrent access.

• Side effects:

  • Allocates internal TCP/TLS state. For TLS, the handshake runs synchronously.

See Also

• sl_si91x_socket(), sl_si91x_bind(), sl_si91x_setsockopt(), sl_si91x_send(), sl_si91x_recv()

• Example#

  Connect a SiWx91x client socket to a remote TCP server:

  struct sockaddr_in server_addr = { 0 };
  server_addr.sin_family         = AF_INET;
  server_addr.sin_port           = 5001;
  sl_net_inet_addr("192.168.0.100", &server_addr.sin_addr.s_addr);
  
  if (sl_si91x_connect(sock,
                       (const struct sockaddr *)&server_addr,
                       sizeof(server_addr)) < 0) {
    printf("sl_si91x_connect() failed, errno = %d\r\n", errno);
    close(sock);
    return -1;
  }
  struct sockaddr_in server_addr = { 0 };
  server_addr.sin_family         = AF_INET;
  server_addr.sin_port           = 5001;
  sl_net_inet_addr("192.168.0.100", &server_addr.sin_addr.s_addr);
  
  if (sl_si91x_connect(sock,
                       (const struct sockaddr *)&server_addr,
                       sizeof(server_addr)) < 0) {
    printf("sl_si91x_connect() failed, errno = %d\r\n", errno);
    close(sock);
    return -1;
  }
  

sl_si91x_send#

int sl_si91x_send (int socket, const uint8_t * buffer, size_t buffer_length, int32_t flags)

Sends the data to the remote peer on the given socket.

This should be used only when the socket is in a connected state.

• Pre-conditions:

  • socket must be connected (TCP) or have a cached peer (UDP via sl_si91x_connect()).

• Post-conditions:

  • On success the bytes have been handed to the stack for transmission.

Returns

• Returns the number of bytes sent on success, or -1 on failure with errno set.

Return values

• >=0: Number of bytes accepted by the stack for transmission.

• -1/EBADF: socket

• -1/ENOTSOCK: socket

• -1/ENOTCONN: Socket is not connected.

• -1/EINVAL: buffer

• -1/EMSGSIZE: Buffer exceeds the MSS limit for the protocol.

• -1/EPIPE: Peer has closed the connection.

• -1/ECONNRESET: Peer resets the connection.

• -1/ENOBUFS: Not enough buffer space in the stack; try again later.

Note

• Thread safety:

  • Not thread-safe on the same descriptor; serialize concurrent access.

• Side effects:

  • Enqueues the payload in the firmware send queue.

See Also

• sl_si91x_send_async(), sl_si91x_sendto(), sl_si91x_send_large_data(), sl_si91x_recv()

Note

• The flags parameter is not currently supported.

• For TCP, the maximum buffer length should not exceed the MSS.

• The following table lists the maximum buffer length which could be sent over each supported protocol.

• Example#

  Send a buffer on a connected SiWx91x TCP socket (respecting the 1460 B MSS):

  const uint8_t payload[1460] = { 0 };
  int           sent          = sl_si91x_send(sock, payload, sizeof(payload), 0);
  if (sent < 0) {
    printf("sl_si91x_send() failed, errno = %d\r\n", errno);
  }
  const uint8_t payload[1460] = { 0 };
  int           sent          = sl_si91x_send(sock, payload, sizeof(payload), 0);
  if (sent < 0) {
    printf("sl_si91x_send() failed, errno = %d\r\n", errno);
  }
  

sl_si91x_send_async#

int sl_si91x_send_async (int socket, const uint8_t * buffer, size_t buffer_length, int32_t flags, sl_si91x_socket_data_transfer_complete_handler_t callback)

Transmits one or more messages to a socket asynchronously.

This should be used only when the socket is in a connected state.

• Pre-conditions:

  • socket must be connected (TCP) or have a cached peer (UDP).

  • callback, if non-NULL, must remain valid until the TX-complete notification is delivered.

• Post-conditions:

  • On success, the request is queued. callback is invoked from the stack context once the transmission completes.

Returns

• Returns 0 on successful submission, or -1 on failure with errno set.

Return values

• 0: Request accepted;

• -1/EBADF: socket

• -1/ENOTSOCK: socket

• -1/ENOTCONN: Socket is not connected.

• -1/EINVAL: buffer

• -1/EMSGSIZE: Buffer exceeds the MSS limit for the protocol.

• -1/ENOBUFS: Not enough buffer space in the stack; try again later.

Note

• Thread safety:

  • Not thread-safe on the same descriptor; serialize concurrent access.

  • The registered callback is invoked from an internal stack thread.

• Side effects:

  • Enqueues the payload in the firmware send queue.

See Also

• sl_si91x_send(), sl_si91x_sendto_async(), sl_si91x_socket_async()

Note

• The flags parameter is not currently supported.

• For TCP, the maximum buffer length should not exceed the MSS.

• The following table lists the maximum buffer length which could be sent over each supported protocol.

• Example#

  Define a callback that the stack invokes once the TX completes, then issue a non-blocking send:

  static void on_tx_complete(int32_t sock_id, uint16_t bytes_sent)
  {
    printf("socket %ld: %u bytes transmitted\r\n", (long)sock_id, bytes_sent);
  }
  
  const uint8_t payload[] = "hello";
  if (sl_si91x_send_async(sock, payload, sizeof(payload) - 1, 0, on_tx_complete) < 0) {
    printf("sl_si91x_send_async() failed, errno = %d\r\n", errno);
  }
  static void on_tx_complete(int32_t sock_id, uint16_t bytes_sent)
  {
    printf("socket %ld: %u bytes transmitted\r\n", (long)sock_id, bytes_sent);
  }
  
  const uint8_t payload[] = "hello";
  if (sl_si91x_send_async(sock, payload, sizeof(payload) - 1, 0, on_tx_complete) < 0) {
    printf("sl_si91x_send_async() failed, errno = %d\r\n", errno);
  }
  

sl_si91x_sendto#

int sl_si91x_sendto (int socket, const uint8_t * buffer, size_t buffer_length, int32_t flags, const struct sockaddr * addr, socklen_t addr_len)

Transmits one or more messages to another socket.

The function is called from an unconnected socket, typically like a UDP socket.

• Pre-conditions:

  • socket must be a descriptor returned by sl_si91x_socket() (typically UDP).

• Post-conditions:

  • On success the datagram has been handed to the stack for transmission.

Returns

• Returns the number of bytes sent on success, or -1 on failure with errno set.

Return values

• >=0: Number of bytes accepted by the stack for transmission.

• -1/EBADF: socket

• -1/ENOTSOCK: socket

• -1/EINVAL: Invalid

• -1/EAFNOSUPPORT: addr

• -1/EMSGSIZE: Buffer exceeds the MSS limit for the protocol.

• -1/ENOBUFS: Not enough buffer space in the stack; try again later.

Note

• Thread safety:

  • Not thread-safe on the same descriptor; serialize concurrent access.

• Side effects:

  • Enqueues the datagram in the firmware send queue.

See Also

• sl_si91x_send(), sl_si91x_sendto_async(), sl_si91x_recvfrom()

Note

• The flags parameter is not currently supported.

• For TCP, the maximum buffer length should not exceed the MSS.

• The following table lists the maximum buffer length which could be sent over each supported protocol.

• Example#

  Send a UDP datagram to a specific remote address using the SiWx91x API:

  struct sockaddr_in dest_addr  = { 0 };
  dest_addr.sin_family          = AF_INET;
  dest_addr.sin_port            = 5002;
  sl_net_inet_addr("192.168.0.100", &dest_addr.sin_addr.s_addr);
  
  const uint8_t payload[] = "ping";
  int sent = sl_si91x_sendto(udp_sock,
                             payload,
                             sizeof(payload) - 1,
                             0,
                             (const struct sockaddr *)&dest_addr,
                             sizeof(dest_addr));
  if (sent < 0) {
    printf("sl_si91x_sendto() failed, errno = %d\r\n", errno);
  }
  struct sockaddr_in dest_addr  = { 0 };
  dest_addr.sin_family          = AF_INET;
  dest_addr.sin_port            = 5002;
  sl_net_inet_addr("192.168.0.100", &dest_addr.sin_addr.s_addr);
  
  const uint8_t payload[] = "ping";
  int sent = sl_si91x_sendto(udp_sock,
                             payload,
                             sizeof(payload) - 1,
                             0,
                             (const struct sockaddr *)&dest_addr,
                             sizeof(dest_addr));
  if (sent < 0) {
    printf("sl_si91x_sendto() failed, errno = %d\r\n", errno);
  }
  

sl_si91x_sendto_async#

int sl_si91x_sendto_async (int socket, const uint8_t * buffer, size_t buffer_length, int32_t flags, const struct sockaddr * to_addr, socklen_t to_addr_len, sl_si91x_socket_data_transfer_complete_handler_t callback)

Transmits one or more messages to another socket asynchronously, and receives acknowledgement through the registered callback.

The function can also be called from an unconnected socket, typically like a UDP socket.

• Pre-conditions:

  • socket must be a descriptor returned by sl_si91x_socket_async() (typically UDP).

  • callback, if non-NULL, must remain valid until the TX-complete notification is delivered.

• Post-conditions:

  • On success, the request is queued. callback is invoked from the stack context once the transmission completes.

Returns

• Returns 0 on successful submission, or -1 on failure with errno set.

Return values

• 0: Request accepted;

• -1/EBADF: socket

• -1/ENOTSOCK: socket

• -1/EINVAL: Invalid

• -1/EAFNOSUPPORT: to_addr

• -1/EMSGSIZE: Buffer exceeds the MSS limit for the protocol.

• -1/ENOBUFS: Not enough buffer space in the stack; try again later.

Note

• Thread safety:

  • Not thread-safe on the same descriptor; serialize concurrent access.

  • The registered callback is invoked from an internal stack thread.

• Side effects:

  • Enqueues the datagram in the firmware send queue.

See Also

• sl_si91x_sendto(), sl_si91x_send_async(), sl_si91x_socket_async()

Note

• The flags parameter is not currently supported.

• For TCP, the maximum buffer length should not exceed the MSS.

• The following table lists the maximum buffer length which could be sent over each supported protocol.

sl_si91x_send_large_data#

int sl_si91x_send_large_data (int socket, const uint8_t * buffer, size_t buffer_length, int32_t flags)

Sends data that is larger than the Maximum Segment Size (MSS).

This function sends data that exceeds the MSS size to a remote peer. It handles the segmentation of the data into smaller chunks that fit within the MSS limit. This API can even be used when the buffer length is less than the MSS.

• Pre-conditions:

  • socket must be a connected TCP socket.

• Post-conditions:

  • On success, the requested number of bytes are segmented and queued by the stack for transmission.

Returns

• Returns the number of bytes sent on success, or -1 on failure with errno set.

Return values

• >=0: Total number of bytes sent (may be less than

• -1/EBADF: socket

• -1/ENOTSOCK: socket

• -1/ENOTCONN: Socket is not connected.

• -1/EINVAL: buffer

• -1/EPIPE: Peer has closed the connection.

• -1/ECONNRESET: Peer resets the connection.

• -1/ENOBUFS: Not enough buffer space in the stack.

Note

• Thread safety:

  • Not thread-safe on the same descriptor; serialize concurrent access.

• Side effects:

  • Internally segments buffer into MSS-sized chunks and enqueues them for transmission.

See Also

• sl_si91x_send(), sl_si91x_send_async()

• Example#

  Send a payload larger than the MSS; the API handles internal segmentation:

  uint8_t big_buffer[8192];
  memset(big_buffer, 'A', sizeof(big_buffer));
  
  int sent = sl_si91x_send_large_data(sock, big_buffer, sizeof(big_buffer), 0);
  if (sent < 0) {
    printf("sl_si91x_send_large_data() failed, errno = %d\r\n", errno);
  } else {
    printf("Transmitted %d bytes of %u\r\n", sent, (unsigned)sizeof(big_buffer));
  }
  uint8_t big_buffer[8192];
  memset(big_buffer, 'A', sizeof(big_buffer));
  
  int sent = sl_si91x_send_large_data(sock, big_buffer, sizeof(big_buffer), 0);
  if (sent < 0) {
    printf("sl_si91x_send_large_data() failed, errno = %d\r\n", errno);
  } else {
    printf("Transmitted %d bytes of %u\r\n", sent, (unsigned)sizeof(big_buffer));
  }
  

sl_si91x_recv#

int sl_si91x_recv (int socket, uint8_t * buffer, size_t bufferLength, int32_t flags)

Receives data from a connected socket.

This function receives data from a connected socket and stores it in the specified buffer. It is typically used on the client or server side to read incoming data from a remote peer.

If the incoming TCP payload exceeds the provided buffer, only the first bufferLength bytes are returned. Any remaining bytes will be delivered by subsequent calls to sl_si91x_recv(). The max buffer length for each supported protocol is as follows:

• IPv4: 1460 bytes

• IPv6: 1440 bytes

• Pre-conditions:

  • socket must be a connected descriptor (TCP) or an accepted socket.

• Post-conditions:

  • On success buffer contains the received bytes and the return value is the number of bytes read.

  • A return value of 0 indicates orderly shutdown by the peer (TCP).

Returns

• Returns the number of bytes received on success, or -1 on failure with errno set.

Return values

• >0: Number of bytes read into

• 0: Orderly shutdown by the peer (TCP).

• -1/EBADF: socket

• -1/ENOTSOCK: socket

• -1/ENOTCONN: Socket is not connected.

• -1/EINVAL: buffer

• -1/EWOULDBLOCK: Non-blocking socket has no data available.

• -1/ETIMEDOUT

• -1/ECONNRESET: Peer resets the connection.

Note

• Thread safety:

  • Not thread-safe on the same descriptor; serialize concurrent access.

• Side effects:

  • Blocks the calling thread unless SL_SI91X_SO_RCVTIME is set.

See Also

• sl_si91x_recvfrom(), sl_si91x_send(), sl_si91x_setsockopt()

• Example#

  Read up to 1460 bytes on a connected SiWx91x TCP socket and process the received data when the call succeeds:

  uint8_t rx_buffer[1460];
  int     received_bytes = sl_si91x_recv(sock, rx_buffer, sizeof(rx_buffer), 0);
  if (received_bytes < 0) {
    printf("sl_si91x_recv() failed, errno = %d\r\n", errno);
  } else if (received_bytes == 0) {
    printf("Peer closed the connection\r\n");
  } else {
    ...
  }
  uint8_t rx_buffer[1460];
  int     received_bytes = sl_si91x_recv(sock, rx_buffer, sizeof(rx_buffer), 0);
  if (received_bytes < 0) {
    printf("sl_si91x_recv() failed, errno = %d\r\n", errno);
  } else if (received_bytes == 0) {
    printf("Peer closed the connection\r\n");
  } else {
    ...
  }
  

sl_si91x_recvfrom#

int sl_si91x_recvfrom (int socket, uint8_t * buffer, size_t buffersize, int32_t flags, struct sockaddr * fromAddr, socklen_t * fromAddrLen)

Receives data from an unconnected socket, typically a UDP socket.

This function receives data from an unconnected socket and stores it in the specified buffer. It is typically used to receive data from a remote peer without establishing a connection.

If the payload of an incoming UDP datagram exceeds the size of the user-provided buffer, the sl_si91x_recvfrom() function returns only the first buffersize bytes. The remaining portion of the same datagram is delivered in subsequent calls, effectively splitting the datagram into chunks. To ensure the entire datagram is received in a single call, the buffer should be sized as follows:

• IPv4: 1472 bytes

• IPv6: 1452 bytes

• Pre-conditions:

  • socket must be bound via sl_si91x_bind() (for UDP) or connected (for TCP).

• Post-conditions:

  • On success buffer contains the received bytes and, when fromAddr is non-NULL, the source address is populated.

Returns

• Returns the number of bytes received on success, or -1 on failure with errno set.

Return values

• >=0: Number of bytes received.

• -1/EBADF: socket

• -1/ENOTSOCK: socket

• -1/EINVAL: buffer

• -1/EWOULDBLOCK: Non-blocking socket has no data available.

• -1/ETIMEDOUT

• -1/ECONNRESET: Peer resets the connection.

Note

• Thread safety:

  • Not thread-safe on the same descriptor; serialize concurrent access.

• Side effects:

  • Blocks the calling thread unless SL_SI91X_SO_RCVTIME is set.

  • Truncated UDP datagrams are delivered in pieces across successive calls (no silent loss).

See Also

• sl_si91x_recv(), sl_si91x_sendto(), sl_si91x_setsockopt()

• Example#

  Receive a UDP datagram on a SiWx91x socket and log the sender:

  uint8_t            buffer[1472];
  struct sockaddr_in src_addr = { 0 };
  socklen_t          src_len  = sizeof(src_addr);
  
  int received_bytes = sl_si91x_recvfrom(udp_sock,
                            buffer,
                            sizeof(buffer),
                            0,
                            (struct sockaddr *)&src_addr,
                            &src_len);
  if (received_bytes > 0) {
    printf("Got %d bytes from port %u\r\n", n, ntohs(src_addr.sin_port));
  } else if (received_bytes < 0) {
    printf("sl_si91x_recvfrom() failed, errno = %d\r\n", errno);
  }
  uint8_t            buffer[1472];
  struct sockaddr_in src_addr = { 0 };
  socklen_t          src_len  = sizeof(src_addr);
  
  int received_bytes = sl_si91x_recvfrom(udp_sock,
                            buffer,
                            sizeof(buffer),
                            0,
                            (struct sockaddr *)&src_addr,
                            &src_len);
  if (received_bytes > 0) {
    printf("Got %d bytes from port %u\r\n", n, ntohs(src_addr.sin_port));
  } else if (received_bytes < 0) {
    printf("sl_si91x_recvfrom() failed, errno = %d\r\n", errno);
  }
  

sl_si91x_shutdown#

int sl_si91x_shutdown (int socket, int how)

Disables send or receive operations on a socket.

This function disables further send or receive operations on a specified socket. It can either close a specific socket or all sockets associated with a given port number.

• Pre-conditions:

  • socket must be a valid descriptor.

• Post-conditions:

  • On success the indicated socket(s) are closed and their descriptors are released.

  • Any pending I/O on the descriptor(s) is aborted; queued unsent data may be discarded.

Returns

• Returns 0 on success, or -1 on failure with errno set.

Return values

• 0: Success.

• -1/EBADF: socket

• -1/ENOTSOCK: socket

• -1/EINVAL: how

Note

• Thread safety:

  • Not thread-safe on the same descriptor. The caller must ensure no other thread is using the descriptor.

• Side effects:

  • Releases stack resources (TCP state, TLS context, internal buffers) for the targeted socket(s).

See Also

• sl_si91x_socket(), sl_si91x_socket_async()

Note

• If the socket is a server socket, the how parameter is ignored, and the socket is always closed based on the port number.

• Example#

  Close only the specified socket (how = 0):

  if (sl_si91x_shutdown(sock, 0) < 0) {
    printf("sl_si91x_shutdown() failed, errno = %d\r\n", errno);
  }
  if (sl_si91x_shutdown(sock, 0) < 0) {
    printf("sl_si91x_shutdown() failed, errno = %d\r\n", errno);
  }
  

Close every socket that shares the same source port (how = 1):

(void)sl_si91x_shutdown(sock, 1);
(void)sl_si91x_shutdown(sock, 1);

sl_si91x_select#

int sl_si91x_select (int nfds, fd_set * readfds, fd_set * writefds, fd_set * exceptfds, const struct timeval * timeout, sl_si91x_socket_select_callback_t callback)

The sl_si91x_select() function is used to monitor multiple file descriptors for readiness to perform I/O operations.

The file descriptors in the sets are monitored to see if they are ready for reading, ready for writing, or have an error condition pending.

sl_si91x_select() allows a program to monitor multiple file descriptors, waiting until one or more of the file descriptors become "ready" for some class of I/O operation (e.g., input possible). A file descriptor is considered ready if it is possible to perform a corresponding I/O operation without blocking.

• Pre-conditions:

  • All descriptors placed in the fd sets must be valid sockets created via sl_si91x_socket() / sl_si91x_socket_async().

  • The firmware select capacity must be configured via SL_SI91X_EXT_TCP_IP_TOTAL_SELECTS.

• Post-conditions:

  • In synchronous mode (callback is NULL): the input fd sets are updated in place to indicate ready descriptors.

  • In asynchronous mode (callback is non-NULL): callback is invoked from the stack context when one or more descriptors become ready.

Returns

• If callback is provided, the function will immediately return zero for success, and -1 for failure. If callback is NULL, returns:

  • total number of file descriptors set on success.

  • 0 when no file descriptors are ready within the specified timeout.

  • -1 on failure.

Return values

• >=0: Number of ready descriptors (synchronous mode) or 0 on successful async submission.

• 0: Timeout expired before any descriptor became ready (synchronous mode).

• -1/EBADF: One of the supplied descriptors is invalid.

• -1/EINVAL: nfds

• -1/EPERM: Select capacity is not configured in firmware.

Note

• Thread safety:

  • Not thread-safe on the same fd sets. A single thread should own the select loop for a given set of sockets.

  • The callback is invoked from an internal stack thread.

• Side effects:

  • In synchronous mode, modifies the supplied fd sets in place.

  • Consumes one firmware select-slot for the duration of the call.

See Also

• sl_si91x_socket(), sl_si91x_recv(), sl_si91x_send()

Note

• The select function modifies the sets passed to it, so if the function is to be called again, the sets must be reinitialized. The exceptfds parameter is not currently supported.

• If the number of select requests is not configured, the sl_si91x_select() API will fail and return -1, with the errno being set to EPERM (Operation not permitted).

• The number of select operations the device can handle can be configured using the SL_SI91X_EXT_TCP_IP_TOTAL_SELECTS.

• The sl_si91x_select() function has the following limitations:

  • Supports a maximum of 10 sockets per call.

  • Supports read and write fd_sets only. It does not monitor the exceptfds set.

  • Operates only with connected sockets. Listening sockets are not supported.

  • The select API supports configuring multiple file descriptors in a single call. However, it returns only one read descriptor when an event is pending, and returns none if no events are pending.

• Example#

  Synchronous select: wait up to 2 seconds for data on two sockets, then service whichever sockets are flagged as ready:

  fd_set          read_fds;
  struct timeval  tv = { .tv_sec = 2, .tv_usec = 0 };
  
  FD_ZERO(&read_fds);
  FD_SET(sock_a, &read_fds);
  FD_SET(sock_b, &read_fds);
  
  int max_fd = (sock_a > sock_b ? sock_a : sock_b) + 1;
  int ready  = sl_si91x_select(max_fd, &read_fds, NULL, NULL, &tv, NULL);
  if (ready < 0) {
    printf("sl_si91x_select() failed, errno = %d\r\n", errno);
  } else if (ready == 0) {
    printf("sl_si91x_select() timed out\r\n");
  } else {
    if (FD_ISSET(sock_a, &read_fds)) {
      ...
    }
  }
  fd_set          read_fds;
  struct timeval  tv = { .tv_sec = 2, .tv_usec = 0 };
  
  FD_ZERO(&read_fds);
  FD_SET(sock_a, &read_fds);
  FD_SET(sock_b, &read_fds);
  
  int max_fd = (sock_a > sock_b ? sock_a : sock_b) + 1;
  int ready  = sl_si91x_select(max_fd, &read_fds, NULL, NULL, &tv, NULL);
  if (ready < 0) {
    printf("sl_si91x_select() failed, errno = %d\r\n", errno);
  } else if (ready == 0) {
    printf("sl_si91x_select() timed out\r\n");
  } else {
    if (FD_ISSET(sock_a, &read_fds)) {
      ...
    }
  }
  

sl_si91x_set_remote_termination_callback#

void sl_si91x_set_remote_termination_callback (sl_si91x_socket_remote_termination_callback_t callback)

Registers a callback for remote socket termination events.

This function registers a callback function is called when a remote socket is terminated. The callback function should be of type sl_si91x_socket_remote_termination_callback_t.

• Pre-conditions:

  • The SiWx91x Wi-Fi/Net stack must be initialized.

• Post-conditions:

  • After registration the callback is invoked from the stack context whenever a peer terminates a SiWx91x socket.

  • Only one handler is stored; subsequent calls overwrite the previous registration.

Note

• Thread safety:

  • The stored handler is overwritten atomically. The callback itself runs on an internal stack thread, so user logic must be reentrant/thread-safe relative to the rest of the application.

• Side effects:

  • Replaces any previously-registered remote-termination callback.

See Also

• sl_si91x_socket_async(), sl_si91x_accept_async()

• Example#

  Define a handler that the stack invokes when the remote peer closes its socket, and register it:

  static void on_remote_termination(int socket_id, uint16_t port_number, uint32_t bytes_sent)
  {
    printf("Remote closed socket %d (port %u), %lu bytes sent\r\n",
           socket_id, port_number, (unsigned long)bytes_sent);
  }
  
  sl_si91x_set_remote_termination_callback(on_remote_termination);
  static void on_remote_termination(int socket_id, uint16_t port_number, uint32_t bytes_sent)
  {
    printf("Remote closed socket %d (port %u), %lu bytes sent\r\n",
           socket_id, port_number, (unsigned long)bytes_sent);
  }
  
  sl_si91x_set_remote_termination_callback(on_remote_termination);
  

sl_si91x_get_socket_info#

sl_status_t sl_si91x_get_socket_info (sl_si91x_socket_info_response_t * socket_info_response)

Retrieve information about currently opened sockets from the socket management system.

Returns

• sl_status_t

sl_si91x_get_socket_mss#

int16_t sl_si91x_get_socket_mss (int32_t socketIndex)

Retrieves the Maximum Segment Size (MSS) for a specific socket.

The MSS is the largest amount of data, specified in bytes, that a computer or communications device can handle in a single, unfragmented piece. Returns

• Returns an int16_t value representing the MSS of the specified socket in bytes.