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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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

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.

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.

Note

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

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.

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.