IOT Sockets#

iotSocketCreate#

int32_t iotSocketCreate (int32_t af, int32_t type, int32_t protocol)

Create a communication socket.

The iotSocketCreate() function creates a new socket that is used for communication. The socket is created with the specified address family, socket type, and protocol.

• Pre-conditions:

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

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

• Post-conditions:

  • On success a new IoT socket descriptor is allocated and can be passed to iotSocketBind(), iotSocketConnect(), iotSocketListen(), etc.

  • On failure no descriptor is allocated and a negative IOT_SOCKET_E* error code is returned.

Returns

• Returns the socket identification number (>=0) on success. On failure, returns one of the following error codes:

  • IOT_SOCKET_EINVAL : Invalid argument.

  • IOT_SOCKET_ENOTSUP : Operation not supported.

  • IOT_SOCKET_ENOMEM : Not enough memory.

  • IOT_SOCKET_ERROR : Unspecified error.

Return values

• >=0: Valid IoT socket descriptor.

• IOT_SOCKET_EINVAL: Invalid combination of

• IOT_SOCKET_ENOTSUP: Requested family/type/protocol is not supported.

• IOT_SOCKET_ENOMEM: Not enough memory to allocate the socket.

Note

• Thread safety:

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

• Side effects:

  • Allocates an entry in the internal socket pool.

See Also

• iotSocketBind(), iotSocketConnect(), iotSocketListen(), iotSocketClose(), sl_si91x_config_socket()

// Create an IPv4 TCP socket.
int32_t sock = iotSocketCreate(IOT_SOCKET_AF_INET,
                               IOT_SOCKET_SOCK_STREAM,
                               IOT_SOCKET_IPPROTO_TCP);
if (sock < 0) {
  printf("iotSocketCreate() failed, rc = %ld\r\n", (long)sock);
  return sock;
}
// Create an IPv4 TCP socket.
int32_t sock = iotSocketCreate(IOT_SOCKET_AF_INET,
                               IOT_SOCKET_SOCK_STREAM,
                               IOT_SOCKET_IPPROTO_TCP);
if (sock < 0) {
  printf("iotSocketCreate() failed, rc = %ld\r\n", (long)sock);
  return sock;
}

iotSocketBind#

int32_t iotSocketBind (int32_t socket, const uint8_t * ip, uint32_t ip_len, uint16_t port)

Assign a local address to a socket.

The iotSocketBind() function assigns a local IP address and port number to a socket identified by socket. This function is typically used on the server side to bind a socket to a specific IP address and port number, so that the socket can listen for incoming connections or datagrams.

• Pre-conditions:

  • socket must be a valid descriptor returned by iotSocketCreate().

  • Must be called before iotSocketListen() on a TCP server socket and before send/receive on a UDP socket that needs a fixed local port.

• Post-conditions:

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

  • On failure the socket remains unbound.

Returns

• Returns 0 on success. On failure, returns one of the following error codes:

  • IOT_SOCKET_ESOCK : Invalid socket.

  • IOT_SOCKET_EINVAL : Invalid argument (address or socket already bound).

  • IOT_SOCKET_EADDRINUSE : Address already in use.

  • IOT_SOCKET_ERROR : Unspecified error.

Return values

• 0: Success.

• IOT_SOCKET_ESOCK: socket

• IOT_SOCKET_EINVAL: ip

• IOT_SOCKET_EADDRINUSE: The requested address/port is already in use.

• IOT_SOCKET_ERROR: Unspecified stack error.

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

• iotSocketCreate(), iotSocketListen(), iotSocketConnect(), iotSocketGetSockName()

// Bind to any local IPv4 address (0.0.0.0) on TCP port 5000.
const uint8_t any_addr[4] = { 0, 0, 0, 0 };
int32_t       rc          = iotSocketBind(sock, any_addr, sizeof(any_addr), 5000);
if (rc < 0) {
  printf("iotSocketBind() failed, rc = %ld\r\n", (long)rc);
  iotSocketClose(sock);
  return rc;
}
// Bind to any local IPv4 address (0.0.0.0) on TCP port 5000.
const uint8_t any_addr[4] = { 0, 0, 0, 0 };
int32_t       rc          = iotSocketBind(sock, any_addr, sizeof(any_addr), 5000);
if (rc < 0) {
  printf("iotSocketBind() failed, rc = %ld\r\n", (long)rc);
  iotSocketClose(sock);
  return rc;
}

iotSocketListen#

int32_t iotSocketListen (int32_t socket, int32_t backlog)

Listen for socket connections.

The iotSocketListen() function marks the socket referred to by socket as a passive socket, that is, as a socket that will be used to accept incoming connection requests using iotSocketAccept(). The backlog parameter defines the maximum length to which the queue of pending connections for socket may grow.

• Pre-conditions:

  • socket must be a TCP (IOT_SOCKET_SOCK_STREAM) socket created using iotSocketCreate() and bound using iotSocketBind().

• Post-conditions:

  • On success the socket transitions into the listening state and can be passed to iotSocketAccept().

Returns

• Returns 0 on success. On failure, returns one of the following error codes:

  • IOT_SOCKET_ESOCK : Invalid socket.

  • IOT_SOCKET_EINVAL : Invalid argument (socket not bound).

  • IOT_SOCKET_ENOTSUP : Operation not supported.

  • IOT_SOCKET_EISCONN : Socket is already connected.

  • IOT_SOCKET_ERROR : Unspecified error.

Return values

• 0: Success.

• IOT_SOCKET_ESOCK: socket

• IOT_SOCKET_EINVAL: Socket is not bound or

• IOT_SOCKET_ENOTSUP: Socket type does not support listening (e.g. UDP).

• IOT_SOCKET_EISCONN: Socket is already connected.

• IOT_SOCKET_ERROR: Unspecified stack error.

Note

• Thread safety:

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

• Side effects:

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

See Also

• iotSocketCreate(), iotSocketBind(), iotSocketAccept()

// Put the bound TCP server socket into listening mode with 1 pending connection.
int32_t rc = iotSocketListen(sock, 1);
if (rc < 0) {
  printf("iotSocketListen() failed, rc = %ld\r\n", (long)rc);
  iotSocketClose(sock);
  return rc;
}
// Put the bound TCP server socket into listening mode with 1 pending connection.
int32_t rc = iotSocketListen(sock, 1);
if (rc < 0) {
  printf("iotSocketListen() failed, rc = %ld\r\n", (long)rc);
  iotSocketClose(sock);
  return rc;
}

iotSocketAccept#

int32_t iotSocketAccept (int32_t socket, uint8_t * ip, uint32_t * ip_len, uint16_t * port)

Accept a new connection on a socket.

The iotSocketAccept() function is used to accept a new incoming connection on a socket that is in listening mode. It extracts the first connection request on the queue of pending connections for the listening socket, socket, creates a new connected socket, and returns a new file descriptor referring to that socket. The newly created socket is not in the listening state. The original socket remains open and can continue to accept new connections.

• Pre-conditions:

  • socket must be a TCP socket placed in the listening state using iotSocketListen().

• Post-conditions:

  • On success a new connected socket descriptor is returned. If ip / port are non-NULL they are populated with the peer's address.

  • The original listening descriptor remains open.

Returns

• Returns the socket identification number of the accepted socket (>=0) on success. On failure, returns one of the following error codes:

  • IOT_SOCKET_ESOCK : Invalid socket.

  • IOT_SOCKET_EINVAL : Invalid argument (socket not in listen mode).

  • IOT_SOCKET_ENOTSUP : Operation not supported (socket type does not support accepting connections).

  • IOT_SOCKET_ECONNRESET : Connection reset by the peer.

  • IOT_SOCKET_ECONNABORTED : Connection aborted locally.

  • IOT_SOCKET_EAGAIN : Operation would block or timed out (may be called again).

  • IOT_SOCKET_ERROR : Unspecified error.

Return values

• >=0: Descriptor for the accepted connection.

• IOT_SOCKET_ESOCK: socket

• IOT_SOCKET_EINVAL: Socket is not in listen mode or arguments are invalid.

• IOT_SOCKET_ENOTSUP: Socket type does not support accepting.

• IOT_SOCKET_ECONNRESET: Peer reset the incoming connection.

• IOT_SOCKET_ECONNABORTED: The connection has been aborted locally.

• IOT_SOCKET_EAGAIN: Non-blocking socket with no pending connections.

• IOT_SOCKET_ERROR: Unspecified stack error.

Note

• Thread safety:

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

• Side effects:

  • Allocates a new socket slot for the accepted connection.

See Also

• iotSocketCreate(), iotSocketBind(), iotSocketListen(), iotSocketClose()

// Accept a new TCP client and log the peer's IPv4 address and port.
uint8_t  peer_ip[4]  = { 0 };
uint32_t peer_ip_len = sizeof(peer_ip);
uint16_t peer_port   = 0;

int32_t client_sock = iotSocketAccept(sock, peer_ip, &peer_ip_len, &peer_port);
if (client_sock < 0) {
  printf("iotSocketAccept() failed, rc = %ld\r\n", (long)client_sock);
} else {
  printf("Client %u.%u.%u.%u:%u connected\r\n",
         peer_ip[0], peer_ip[1], peer_ip[2], peer_ip[3], peer_port);
}
// Accept a new TCP client and log the peer's IPv4 address and port.
uint8_t  peer_ip[4]  = { 0 };
uint32_t peer_ip_len = sizeof(peer_ip);
uint16_t peer_port   = 0;

int32_t client_sock = iotSocketAccept(sock, peer_ip, &peer_ip_len, &peer_port);
if (client_sock < 0) {
  printf("iotSocketAccept() failed, rc = %ld\r\n", (long)client_sock);
} else {
  printf("Client %u.%u.%u.%u:%u connected\r\n",
         peer_ip[0], peer_ip[1], peer_ip[2], peer_ip[3], peer_port);
}

iotSocketConnect#

int32_t iotSocketConnect (int32_t socket, const uint8_t * ip, uint32_t ip_len, uint16_t port)

Connect a socket to a remote host.

The iotSocketConnect() function establishes a connection to a remote host specified by the IP address and port number. This function is used for connection-oriented protocols such as TCP. The socket identified by socket must be created and optionally bound to a local address before calling this function.

• Pre-conditions:

  • socket must be a descriptor created using iotSocketCreate().

  • Network must be up and the destination must be reachable.

• Post-conditions:

  • On success a TCP socket enters the connected state and can be used with iotSocketSend() / iotSocketRecv().

  • For UDP, the peer is cached so subsequent iotSocketSend() / iotSocketRecv() can be used without specifying the peer.

Returns

• Returns 0 on success. On failure, returns one of the following error codes:

  • IOT_SOCKET_ESOCK : Invalid socket.

  • IOT_SOCKET_EINVAL : Invalid argument.

  • IOT_SOCKET_EALREADY : Connection already in progress.

  • IOT_SOCKET_EINPROGRESS : Operation in progress.

  • IOT_SOCKET_EISCONN : Socket is already connected.

  • IOT_SOCKET_ECONNREFUSED : Connection rejected by the peer.

  • IOT_SOCKET_ECONNABORTED : Connection aborted locally.

  • IOT_SOCKET_EADDRINUSE : Address already in use.

  • IOT_SOCKET_ETIMEDOUT : Operation timed out.

  • IOT_SOCKET_ERROR : Unspecified error.

Return values

• 0: Success.

• IOT_SOCKET_ESOCK: socket

• IOT_SOCKET_EINVAL: Invalid

• IOT_SOCKET_EALREADY: A previous connect attempt is still in progress.

• IOT_SOCKET_EINPROGRESS: Non-blocking connect in progress.

• IOT_SOCKET_EISCONN: Socket is already connected.

• IOT_SOCKET_ECONNREFUSED: Remote peer refused the connection.

• IOT_SOCKET_ECONNABORTED: Connection aborted locally.

• IOT_SOCKET_EADDRINUSE: Local address is already in use.

• IOT_SOCKET_ETIMEDOUT: Connection attempt timed out.

• IOT_SOCKET_ERROR: Unspecified stack error.

Note

• Thread safety:

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

• Side effects:

  • Allocates internal TCP state. For TLS-enabled sockets the handshake runs synchronously.

See Also

• iotSocketCreate(), iotSocketBind(), iotSocketSend(), iotSocketRecv(), iotSocketClose()

// Connect a TCP client socket to 192.168.0.100 on port 5001.
const uint8_t server_ip[4] = { 192, 168, 0, 100 };
int32_t       rc           = iotSocketConnect(sock, server_ip, sizeof(server_ip), 5001);
if (rc < 0) {
  printf("iotSocketConnect() failed, rc = %ld\r\n", (long)rc);
  iotSocketClose(sock);
  return rc;
}
// Connect a TCP client socket to 192.168.0.100 on port 5001.
const uint8_t server_ip[4] = { 192, 168, 0, 100 };
int32_t       rc           = iotSocketConnect(sock, server_ip, sizeof(server_ip), 5001);
if (rc < 0) {
  printf("iotSocketConnect() failed, rc = %ld\r\n", (long)rc);
  iotSocketClose(sock);
  return rc;
}

iotSocketRecv#

int32_t iotSocketRecv (int32_t socket, void * buf, uint32_t len)

Receive data from a socket.

The iotSocketRecv() function receives data from a connected socket identified by socket. The received data is stored in the buffer pointed to by buf, which has a length of len bytes.

• Pre-conditions:

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

• Post-conditions:

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

Returns

• Returns the number of bytes received (>=0) on success. On failure, returns one of the following error codes:

  • 0: Data is available (when len is 0).

  • IOT_SOCKET_ESOCK : Invalid socket.

  • IOT_SOCKET_EINVAL : Invalid argument (pointer to buffer or length).

  • IOT_SOCKET_ENOTCONN : Socket is not connected.

  • IOT_SOCKET_ECONNRESET : Connection reset by the peer.

  • IOT_SOCKET_ECONNABORTED : Connection aborted locally.

  • IOT_SOCKET_EAGAIN : Operation would block or timed out (may be called again).

  • IOT_SOCKET_ERROR : Unspecified error.

Return values

• >0: Number of bytes read into

• 0: Data is available (when

• IOT_SOCKET_ESOCK: socket

• IOT_SOCKET_EINVAL: buf

• IOT_SOCKET_ENOTCONN: Socket is not connected.

• IOT_SOCKET_ECONNRESET: Peer reset the connection.

• IOT_SOCKET_ECONNABORTED: Connection aborted locally.

• IOT_SOCKET_EAGAIN: Non-blocking socket has no data available, or timeout elapsed.

• IOT_SOCKET_ERROR: Unspecified stack error.

Note

• Thread safety:

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

• Side effects:

  • Blocks the calling thread unless IOT_SOCKET_SO_RCVTIMEO or IOT_SOCKET_IO_FIONBIO is set.

See Also

• iotSocketRecvFrom(), iotSocketSend(), iotSocketConnect(), iotSocketSetOpt()

// Read up to 1460 bytes from a connected socket, looping until peer closes.
uint8_t buffer[1460];
int32_t n;

while ((n = iotSocketRecv(sock, buffer, sizeof(buffer))) > 0) {
  // Process buffer[0 .. n - 1].
}
if (n == IOT_SOCKET_EAGAIN) {
  // Receive timed out - retry later.
} else if (n < 0) {
  printf("iotSocketRecv() failed, rc = %ld\r\n", (long)n);
}
// Read up to 1460 bytes from a connected socket, looping until peer closes.
uint8_t buffer[1460];
int32_t n;

while ((n = iotSocketRecv(sock, buffer, sizeof(buffer))) > 0) {
  // Process buffer[0 .. n - 1].
}
if (n == IOT_SOCKET_EAGAIN) {
  // Receive timed out - retry later.
} else if (n < 0) {
  printf("iotSocketRecv() failed, rc = %ld\r\n", (long)n);
}

iotSocketRecvFrom#

int32_t iotSocketRecvFrom (int32_t socket, void * buf, uint32_t len, uint8_t * ip, uint32_t * ip_len, uint16_t * port)

Receive data from a socket.

The iotSocketRecvFrom() function receives data from a socket identified by socket. The received data is stored in the buffer pointed to by buf, which has a length of len bytes. If the ip and port parameters are provided, the function also returns the source address and port of the received data.

• Pre-conditions:

  • socket must be bound using iotSocketBind() (for UDP) or connected using iotSocketConnect() (for TCP).

• Post-conditions:

  • On success buf contains the received bytes and ip / port (when non-NULL) are populated with the source address.

Returns

• Returns the number of bytes received (>=0) on success. On failure, returns one of the following error codes:

  • 0: Data is available (when len is 0).

  • IOT_SOCKET_ESOCK : Invalid socket.

  • IOT_SOCKET_EINVAL : Invalid argument (pointer to buffer or length).

  • IOT_SOCKET_ENOTCONN : Socket is not connected.

  • IOT_SOCKET_ECONNRESET : Connection reset by the peer.

  • IOT_SOCKET_ECONNABORTED : Connection aborted locally.

  • IOT_SOCKET_EAGAIN : Operation would block or timed out (may be called again).

  • IOT_SOCKET_ERROR : Unspecified error.

Return values

• >=0: Number of bytes received.

• IOT_SOCKET_ESOCK: socket

• IOT_SOCKET_EINVAL: Invalid

• IOT_SOCKET_ENOTCONN: Socket is not connected (TCP only).

• IOT_SOCKET_ECONNRESET: Peer reset the connection.

• IOT_SOCKET_ECONNABORTED: Connection aborted locally.

• IOT_SOCKET_EAGAIN: Non-blocking socket has no data available, or timeout elapsed.

• IOT_SOCKET_ERROR: Unspecified stack error.

Note

• Thread safety:

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

• Side effects:

  • Blocks the calling thread unless IOT_SOCKET_SO_RCVTIMEO or IOT_SOCKET_IO_FIONBIO is set.

  • Truncated UDP datagrams are silently discarded beyond len bytes.

See Also

• iotSocketRecv(), iotSocketSendTo(), iotSocketBind(), iotSocketSetOpt()

// Receive a UDP datagram and capture the sender's IPv4 address/port.
uint8_t  buffer[1472];
uint8_t  src_ip[4]    = { 0 };
uint32_t src_ip_len   = sizeof(src_ip);
uint16_t src_port     = 0;

int32_t n = iotSocketRecvFrom(sock, buffer, sizeof(buffer),
                              src_ip, &src_ip_len, &src_port);
if (n > 0) {
  printf("Received %ld bytes from %u.%u.%u.%u:%u\r\n",
         (long)n, src_ip[0], src_ip[1], src_ip[2], src_ip[3], src_port);
} else if (n < 0) {
  printf("iotSocketRecvFrom() failed, rc = %ld\r\n", (long)n);
}
// Receive a UDP datagram and capture the sender's IPv4 address/port.
uint8_t  buffer[1472];
uint8_t  src_ip[4]    = { 0 };
uint32_t src_ip_len   = sizeof(src_ip);
uint16_t src_port     = 0;

int32_t n = iotSocketRecvFrom(sock, buffer, sizeof(buffer),
                              src_ip, &src_ip_len, &src_port);
if (n > 0) {
  printf("Received %ld bytes from %u.%u.%u.%u:%u\r\n",
         (long)n, src_ip[0], src_ip[1], src_ip[2], src_ip[3], src_port);
} else if (n < 0) {
  printf("iotSocketRecvFrom() failed, rc = %ld\r\n", (long)n);
}

iotSocketSend#

int32_t iotSocketSend (int32_t socket, const void * buf, uint32_t len)

Send data or check if data can be sent on a connected socket.

The iotSocketSend() function sends data from the buffer pointed to by buf through the socket identified by socket. If len is 0, the function checks if data can be sent on the socket without blocking.

• Pre-conditions:

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

• Post-conditions:

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

Returns

• Returns the number of bytes sent (>=0) on success if len is not 0. If len is 0, returns 0 if data can be sent. On failure, returns one of the following error codes:

  • IOT_SOCKET_ESOCK : Invalid socket.

  • IOT_SOCKET_EINVAL : Invalid argument (pointer to buffer or length).

  • IOT_SOCKET_ENOTCONN : Socket is not connected.

  • IOT_SOCKET_ECONNRESET : Connection reset by the peer.

  • IOT_SOCKET_ECONNABORTED : Connection aborted locally.

  • IOT_SOCKET_EAGAIN : Operation would block or timed out (may be called again).

  • IOT_SOCKET_ERROR : Unspecified error.

Return values

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

• IOT_SOCKET_ESOCK: socket

• IOT_SOCKET_EINVAL: buf

• IOT_SOCKET_ENOTCONN: Socket is not connected.

• IOT_SOCKET_ECONNRESET: Peer reset the connection.

• IOT_SOCKET_ECONNABORTED: Connection aborted locally.

• IOT_SOCKET_EAGAIN: Non-blocking socket cannot accept the data now, or timeout elapsed.

• IOT_SOCKET_ERROR: Unspecified stack error.

Note

• Thread safety:

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

• Side effects:

  • Enqueues the payload in the firmware send queue; transmission happens asynchronously.

See Also

• iotSocketSendTo(), iotSocketRecv(), iotSocketConnect(), iotSocketSetOpt()

Note

• • The function does not guarantee that the packets are transmitted to the remote node; they are enqueued in the queue.

  • The function can only send a maximum of 1460 bytes in the case of plain TCP and UDP. For TLS, the maximum buffer length is 1370 bytes.

// Send a payload on a connected TCP socket, handling partial sends.
const uint8_t payload[] = "GET / HTTP/1.0\r\n\r\n";
uint32_t      remaining = (uint32_t)(sizeof(payload) - 1);
uint32_t      offset    = 0;

while (remaining > 0) {
  int32_t sent = iotSocketSend(sock, payload + offset, remaining);
  if (sent < 0) {
    printf("iotSocketSend() failed, rc = %ld\r\n", (long)sent);
    break;
  }
  offset    += (uint32_t)sent;
  remaining -= (uint32_t)sent;
}
// Send a payload on a connected TCP socket, handling partial sends.
const uint8_t payload[] = "GET / HTTP/1.0\r\n\r\n";
uint32_t      remaining = (uint32_t)(sizeof(payload) - 1);
uint32_t      offset    = 0;

while (remaining > 0) {
  int32_t sent = iotSocketSend(sock, payload + offset, remaining);
  if (sent < 0) {
    printf("iotSocketSend() failed, rc = %ld\r\n", (long)sent);
    break;
  }
  offset    += (uint32_t)sent;
  remaining -= (uint32_t)sent;
}

iotSocketSendTo#

int32_t iotSocketSendTo (int32_t socket, const void * buf, uint32_t len, const uint8_t * ip, uint32_t ip_len, uint16_t port)

Send data or check if data can be sent on a socket.

The iotSocketSendTo() function sends data from the buffer pointed to by buf through the socket identified by socket to the specified remote destination IP address and port. If len is 0, the function checks if data can be sent on the socket without blocking.

• Pre-conditions:

  • socket must have been created using iotSocketCreate().

  • For a connected socket, ip / port are ignored.

• Post-conditions:

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

Returns

• Returns the number of bytes sent (>=0) on success if len is not 0. If len is 0, returns 0 if data can be sent. On failure, returns one of the following error codes:

  • IOT_SOCKET_ESOCK : Invalid socket.

  • IOT_SOCKET_EINVAL : Invalid argument (pointer to buffer or length).

  • IOT_SOCKET_ENOTCONN : Socket is not connected.

  • IOT_SOCKET_ECONNRESET : Connection reset by the peer.

  • IOT_SOCKET_ECONNABORTED : Connection aborted locally.

  • IOT_SOCKET_EAGAIN : Operation would block or timed out (may be called again).

  • IOT_SOCKET_ERROR : Unspecified error.

Return values

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

• IOT_SOCKET_ESOCK: socket

• IOT_SOCKET_EINVAL: buf

• IOT_SOCKET_ECONNRESET: Peer reset the connection.

• IOT_SOCKET_ECONNABORTED: Connection aborted locally.

• IOT_SOCKET_EAGAIN: Non-blocking socket cannot accept the data now, or timeout elapsed.

• IOT_SOCKET_ERROR: Unspecified stack error (e.g.

Note

• Thread safety:

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

• Side effects:

  • Enqueues the datagram in the firmware send queue; transmission happens asynchronously.

See Also

• iotSocketSend(), iotSocketRecvFrom(), iotSocketBind(), iotSocketConnect()

Note

• • If the number of bytes to be sent exceeds the Maximum Segment Size (MSS) specified by the remote node, the API will return IOT_SOCKET_ERROR. To know the MSS size for the socket, use the sl_si91x_get_socket_mss() utility. In the case of TCP, is should be called after iotSocketConnect().

  • The function does not guarantee that the packets are transmitted to the remote node; they are enqueued in the queue.

  • The function can only send a maximum of 1460 bytes in the case of plain TCP or UDP. For TLS, the maximum buffer length is 1370 bytes.

// Send a UDP datagram to a specific remote IPv4 host.
const uint8_t dst_ip[4]    = { 192, 168, 0, 100 };
const uint8_t payload[]    = "ping";

int32_t sent = iotSocketSendTo(sock,
                               payload,
                               (uint32_t)(sizeof(payload) - 1),
                               dst_ip,
                               sizeof(dst_ip),
                               5002);
if (sent < 0) {
  printf("iotSocketSendTo() failed, rc = %ld\r\n", (long)sent);
}
// Send a UDP datagram to a specific remote IPv4 host.
const uint8_t dst_ip[4]    = { 192, 168, 0, 100 };
const uint8_t payload[]    = "ping";

int32_t sent = iotSocketSendTo(sock,
                               payload,
                               (uint32_t)(sizeof(payload) - 1),
                               dst_ip,
                               sizeof(dst_ip),
                               5002);
if (sent < 0) {
  printf("iotSocketSendTo() failed, rc = %ld\r\n", (long)sent);
}

iotSocketGetSockName#

int32_t iotSocketGetSockName (int32_t socket, uint8_t * ip, uint32_t * ip_len, uint16_t * port)

Retrieve local IP address and port of a socket.

The iotSocketGetSockName() function retrieves the local IP address and port number associated with the socket identified by socket. This function is typically used to obtain the local address and port assigned to a socket after it has been bound or connected.

• Pre-conditions:

  • socket must be a descriptor returned by iotSocketCreate() and should be bound or connected.

• Post-conditions:

  • On success ip / port (when non-NULL) are populated with the local endpoint.

Returns

• Returns 0 on success. On failure, returns one of the following error codes:

  • IOT_SOCKET_ESOCK : Invalid socket.

  • IOT_SOCKET_EINVAL : Invalid argument (pointer to buffer or length).

  • IOT_SOCKET_ERROR : Unspecified error.

Return values

• 0: Success.

• IOT_SOCKET_ESOCK: socket

• IOT_SOCKET_EINVAL: ip_len

• IOT_SOCKET_ERROR: Unspecified stack error.

Note

• Thread safety:

  • Safe to call concurrently with I/O on the same descriptor; read-only access to socket state.

• Side effects:

  • None. Does not modify socket behavior.

See Also

• iotSocketGetPeerName(), iotSocketBind(), iotSocketCreate()

// Retrieve the local address/port bound to the socket.
uint8_t  local_ip[4]  = { 0 };
uint32_t local_ip_len = sizeof(local_ip);
uint16_t local_port   = 0;

int32_t rc = iotSocketGetSockName(sock, local_ip, &local_ip_len, &local_port);
if (rc == 0) {
  printf("Local endpoint %u.%u.%u.%u:%u\r\n",
         local_ip[0], local_ip[1], local_ip[2], local_ip[3], local_port);
}
// Retrieve the local address/port bound to the socket.
uint8_t  local_ip[4]  = { 0 };
uint32_t local_ip_len = sizeof(local_ip);
uint16_t local_port   = 0;

int32_t rc = iotSocketGetSockName(sock, local_ip, &local_ip_len, &local_port);
if (rc == 0) {
  printf("Local endpoint %u.%u.%u.%u:%u\r\n",
         local_ip[0], local_ip[1], local_ip[2], local_ip[3], local_port);
}

iotSocketGetPeerName#

int32_t iotSocketGetPeerName (int32_t socket, uint8_t * ip, uint32_t * ip_len, uint16_t * port)

Retrieve remote IP address and port of a socket.

The iotSocketGetPeerName() function retrieves the remote IP address and port number associated with the socket identified by socket. This function is typically used to obtain the address and port of the peer to which the socket is connected.

• Pre-conditions:

  • socket must be a connected descriptor returned by iotSocketConnect() or iotSocketAccept().

• Post-conditions:

  • On success ip / port (when non-NULL) are populated with the peer's endpoint.

Returns

• Returns 0 on success. On failure, returns one of the following error codes:

  • IOT_SOCKET_ESOCK : Invalid socket.

  • IOT_SOCKET_EINVAL : Invalid argument (pointer to buffer or length).

  • IOT_SOCKET_ENOTCONN : Socket is not connected.

  • IOT_SOCKET_ERROR : Unspecified error.

Return values

• 0: Success.

• IOT_SOCKET_ESOCK: socket

• IOT_SOCKET_EINVAL: ip_len

• IOT_SOCKET_ENOTCONN: Socket is not connected.

• IOT_SOCKET_ERROR: Unspecified stack error.

Note

• Thread safety:

  • Safe to call concurrently with I/O on the same descriptor; read-only access to socket state.

• Side effects:

  • None. Does not modify socket behavior.

See Also

• iotSocketGetSockName(), iotSocketConnect(), iotSocketAccept()

// Fetch the connected peer's IPv4 address and port.
uint8_t  peer_ip[4]  = { 0 };
uint32_t peer_ip_len = sizeof(peer_ip);
uint16_t peer_port   = 0;

if (iotSocketGetPeerName(sock, peer_ip, &peer_ip_len, &peer_port) == 0) {
  printf("Connected to %u.%u.%u.%u:%u\r\n",
         peer_ip[0], peer_ip[1], peer_ip[2], peer_ip[3], peer_port);
}
// Fetch the connected peer's IPv4 address and port.
uint8_t  peer_ip[4]  = { 0 };
uint32_t peer_ip_len = sizeof(peer_ip);
uint16_t peer_port   = 0;

if (iotSocketGetPeerName(sock, peer_ip, &peer_ip_len, &peer_port) == 0) {
  printf("Connected to %u.%u.%u.%u:%u\r\n",
         peer_ip[0], peer_ip[1], peer_ip[2], peer_ip[3], peer_port);
}

iotSocketGetOpt#

int32_t iotSocketGetOpt (int32_t socket, int32_t opt_id, void * opt_val, uint32_t * opt_len)

Retrieve socket option.

The iotSocketGetOpt() function retrieves the value of a socket option specified by opt_id for the socket identified by socket. The option value is stored in the buffer pointed to by opt_val, and the length of the option value is specified by opt_len.

• Pre-conditions:

  • socket must be a descriptor returned by iotSocketCreate().

• Post-conditions:

  • On success opt_val is populated and opt_len is updated with the number of bytes written.

Returns

• Returns 0 on success. On failure, returns one of the following error codes:

  • IOT_SOCKET_ESOCK : Invalid socket.

  • IOT_SOCKET_EINVAL : Invalid argument.

  • IOT_SOCKET_ENOTSUP : Operation not supported.

  • IOT_SOCKET_ERROR : Unspecified error.

Return values

• 0: Success.

• IOT_SOCKET_ESOCK: socket

• IOT_SOCKET_EINVAL: opt_val

• IOT_SOCKET_ENOTSUP: opt_id

• IOT_SOCKET_ERROR: Unspecified stack error.

Note

• Thread safety:

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

• Side effects:

  • None. Does not modify socket behavior.

See Also

• iotSocketSetOpt()

Note

• The following options are currently supported:

  • IOT_SOCKET_IO_FIONBIO

  • IOT_SOCKET_SO_RCVTIMEO

  • IOT_SOCKET_SO_SNDTIMEO

  • IOT_SOCKET_SO_KEEPALIVE

  • IOT_SOCKET_SO_TYPE

  • IOT_SOCKET_SO_SSL_ENABLE (Silicon Labs vendor extension; non-portable)

// Query the current receive timeout of a socket.
uint32_t timeout_ms = 0;
uint32_t opt_len    = sizeof(timeout_ms);

if (iotSocketGetOpt(sock, IOT_SOCKET_SO_RCVTIMEO, &timeout_ms, &opt_len) == 0) {
  printf("Current RX timeout: %lu ms\r\n", (unsigned long)timeout_ms);
}
// Query the current receive timeout of a socket.
uint32_t timeout_ms = 0;
uint32_t opt_len    = sizeof(timeout_ms);

if (iotSocketGetOpt(sock, IOT_SOCKET_SO_RCVTIMEO, &timeout_ms, &opt_len) == 0) {
  printf("Current RX timeout: %lu ms\r\n", (unsigned long)timeout_ms);
}

iotSocketSetOpt#

int32_t iotSocketSetOpt (int32_t socket, int32_t opt_id, const void * opt_val, uint32_t opt_len)

Set socket option.

The iotSocketSetOpt() function sets the value of a socket option specified by opt_id for the socket identified by socket. The option value is provided in the buffer pointed to by opt_val, and the length of the option value is specified by opt_len.

• Pre-conditions:

  • socket must be a descriptor returned by iotSocketCreate().

• Post-conditions:

  • On success the option has been applied. Subsequent calls on the socket observe the new behavior.

Returns

• Returns 0 on success. On failure, returns one of the following error codes:

  • IOT_SOCKET_ESOCK : Invalid socket.

  • IOT_SOCKET_EINVAL : Invalid argument.

  • IOT_SOCKET_ENOTSUP : Operation not supported.

  • IOT_SOCKET_ERROR : Unspecified error.

Return values

• 0: Success.

• IOT_SOCKET_ESOCK: socket

• IOT_SOCKET_EINVAL: opt_val

• IOT_SOCKET_ENOTSUP: opt_id

• IOT_SOCKET_ERROR: Unspecified stack error.

Note

• Thread safety:

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

• Side effects:

  • Changes internal state of the socket (non-blocking mode, timeouts, keepalive).

See Also

• iotSocketGetOpt()

Note

• The following options are currently supported:

  • IOT_SOCKET_IO_FIONBIO

  • IOT_SOCKET_SO_RCVTIMEO

  • IOT_SOCKET_SO_SNDTIMEO

  • IOT_SOCKET_SO_KEEPALIVE

  • IOT_SOCKET_SO_TYPE

  • IOT_SOCKET_SO_SSL_ENABLE (Silicon Labs vendor extension; non-portable)

// 1. Enable non-blocking mode on the socket.
uint32_t nbio = 1;
(void)iotSocketSetOpt(sock, IOT_SOCKET_IO_FIONBIO, &nbio, sizeof(nbio));

// 2. Set a 2-second receive timeout (value is in milliseconds).
uint32_t rx_timeout_ms = 2000;
if (iotSocketSetOpt(sock, IOT_SOCKET_SO_RCVTIMEO,
                    &rx_timeout_ms, sizeof(rx_timeout_ms)) < 0) {
  printf("iotSocketSetOpt(RCVTIMEO) failed\r\n");
}

// 3. Turn on TCP keepalive.
uint32_t keepalive = 1;
(void)iotSocketSetOpt(sock, IOT_SOCKET_SO_KEEPALIVE,
                      &keepalive, sizeof(keepalive));

// 4. (Silicon Labs vendor extension) Enable TLS 1.2 on a stream socket
//    BEFORE iotSocketConnect(). See IOT_SOCKET_SO_SSL_ENABLE for details.
#ifdef IOT_SOCKET_VENDOR_SILABS
const char tls_version[] = "tls_1_2";
(void)iotSocketSetOpt(sock, IOT_SOCKET_SO_SSL_ENABLE,
                      tls_version, sizeof(tls_version));
#endif
// 1. Enable non-blocking mode on the socket.
uint32_t nbio = 1;
(void)iotSocketSetOpt(sock, IOT_SOCKET_IO_FIONBIO, &nbio, sizeof(nbio));

// 2. Set a 2-second receive timeout (value is in milliseconds).
uint32_t rx_timeout_ms = 2000;
if (iotSocketSetOpt(sock, IOT_SOCKET_SO_RCVTIMEO,
                    &rx_timeout_ms, sizeof(rx_timeout_ms)) < 0) {
  printf("iotSocketSetOpt(RCVTIMEO) failed\r\n");
}

// 3. Turn on TCP keepalive.
uint32_t keepalive = 1;
(void)iotSocketSetOpt(sock, IOT_SOCKET_SO_KEEPALIVE,
                      &keepalive, sizeof(keepalive));

// 4. (Silicon Labs vendor extension) Enable TLS 1.2 on a stream socket
//    BEFORE iotSocketConnect(). See IOT_SOCKET_SO_SSL_ENABLE for details.
#ifdef IOT_SOCKET_VENDOR_SILABS
const char tls_version[] = "tls_1_2";
(void)iotSocketSetOpt(sock, IOT_SOCKET_SO_SSL_ENABLE,
                      tls_version, sizeof(tls_version));
#endif

iotSocketClose#

int32_t iotSocketClose (int32_t socket)

Close and release a socket.

The iotSocketClose() function closes the socket identified by socket and releases any resources associated with it. If the socket is a server socket or the first client socket, closing it may also close other related sockets.

• Pre-conditions:

  • socket must be a descriptor returned by iotSocketCreate() or iotSocketAccept().

• Post-conditions:

  • The descriptor is released back to the pool and must not be used for further operations.

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

Returns

• Returns 0 on success. On failure, returns one of the following error codes:

  • IOT_SOCKET_ESOCK : Invalid socket.

  • IOT_SOCKET_EAGAIN : Operation would block (may be called again).

  • IOT_SOCKET_ERROR : Unspecified error.

Return values

• 0: Success.

• IOT_SOCKET_ESOCK: socket

• IOT_SOCKET_EAGAIN: Close would block; retry later.

• IOT_SOCKET_ERROR: Unspecified stack error.

Note

• Thread safety:

  • Not thread-safe on the same descriptor. Caller must ensure no other thread is operating on socket when iotSocketClose() is invoked.

• Side effects:

  • Releases stack resources (TCP state, internal buffers, pending timers).

  • Closing a server or first client socket may close related sockets (see note).

See Also

• iotSocketCreate(), iotSocketAccept()

Note

• Calling close on a server or the first client socket may result in closing other related sockets as well.

// Always close a socket in every exit path (including errors) to avoid leaks.
int32_t rc = iotSocketClose(sock);
if (rc < 0) {
  printf("iotSocketClose() failed, rc = %ld\r\n", (long)rc);
}
sock = -1;
// Always close a socket in every exit path (including errors) to avoid leaks.
int32_t rc = iotSocketClose(sock);
if (rc < 0) {
  printf("iotSocketClose() failed, rc = %ld\r\n", (long)rc);
}
sock = -1;

iotSocketGetHostByName#

int32_t iotSocketGetHostByName (const char * name, int32_t af, uint8_t * ip, uint32_t * ip_len)

Retrieve host IP address from host name.

The iotSocketGetHostByName() function resolves a host name to an IP address. The resolved IP address is stored in the buffer pointed to by ip, and the length of the IP address is specified by ip_len. The address family is specified by af.

• Pre-conditions:

  • The network stack must be initialized and a network profile must be up.

  • A reachable DNS server must be configured.

• Post-conditions:

  • On success ip is populated with the resolved address and ip_len is updated to reflect the returned length.

Returns

• Returns 0 on success. On failure, returns one of the following error codes:

  • IOT_SOCKET_EINVAL : Invalid argument.

  • IOT_SOCKET_ENOTSUP : Operation not supported.

  • IOT_SOCKET_ETIMEDOUT : Operation timed out.

  • IOT_SOCKET_EHOSTNOTFOUND : Host not found.

  • IOT_SOCKET_ERROR : Unspecified error.

Return values

• 0: Success.

• IOT_SOCKET_EINVAL: name

• IOT_SOCKET_ENOTSUP: af

• IOT_SOCKET_ETIMEDOUT: DNS lookup timed out.

• IOT_SOCKET_EHOSTNOTFOUND: No record exists for

• IOT_SOCKET_ERROR: Unspecified stack error.

Note

• Thread safety:

  • Thread-safe; may be called concurrently from multiple threads.

• Side effects:

  • Blocks the caller for the duration of the DNS transaction (subject to the stack's DNS timeout).

See Also

• iotSocketConnect(), iotSocketSendTo()

// Resolve an IPv4 host name (requires an active network).
uint8_t  resolved_ip[4] = { 0 };
uint32_t ip_len         = sizeof(resolved_ip);

int32_t rc = iotSocketGetHostByName("example.com",
                                    IOT_SOCKET_AF_INET,
                                    resolved_ip,
                                    &ip_len);
if (rc == 0) {
  printf("example.com -> %u.%u.%u.%u\r\n",
         resolved_ip[0], resolved_ip[1], resolved_ip[2], resolved_ip[3]);
} else {
  printf("DNS resolve failed, rc = %ld\r\n", (long)rc);
}
// Resolve an IPv4 host name (requires an active network).
uint8_t  resolved_ip[4] = { 0 };
uint32_t ip_len         = sizeof(resolved_ip);

int32_t rc = iotSocketGetHostByName("example.com",
                                    IOT_SOCKET_AF_INET,
                                    resolved_ip,
                                    &ip_len);
if (rc == 0) {
  printf("example.com -> %u.%u.%u.%u\r\n",
         resolved_ip[0], resolved_ip[1], resolved_ip[2], resolved_ip[3]);
} else {
  printf("DNS resolve failed, rc = %ld\r\n", (long)rc);
}