IOT Sockets#

This section provides a reference to IoT Socket API functions.

The IOT socket implementation aims to emulate the standards library to the extent possible for embedded offerings from Silabs. There are substantial limitation/exceptions however, and those are mentioned in the subsequent documentation of IOT sockets.

Modules#

Functions#

int32_t

iotSocketCreate(int32_t af, int32_t type, int32_t protocol)

Create a communication socket.

int32_t

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

Assign a local address to a socket.

int32_t

iotSocketListen(int32_t socket, int32_t backlog)

Listen for socket connections.

int32_t

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

Accept a new connection on a socket.

int32_t

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

Connect a socket to a remote host.

int32_t

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

Receives data from the socket.

int32_t

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

Receives data from the socket.

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.

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.

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.

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.

int32_t

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

Get socket option.

int32_t

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

Set socket option.

int32_t

iotSocketClose(int32_t socket)

Close and release a socket.

int32_t

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

Retrieve host IP address from host name.

Function Documentation#

iotSocketCreate#

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

Create a communication socket.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	af	Address family. One of the values from Address Family.
int32_t	[in]	type	Socket type. One of the values from Socket Type.
int32_t	[in]	protocol	Socket protocol. One of the values from Socket Protocol.

Returns

int32_t. Status information:
- Socket identification number (>=0).
- 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.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	socket	Socket identification number.
const uint8_t *	[in]	ip	Pointer to local IP address.
uint32_t	[in]	ip_len	Length of 'ip' address in bytes.
uint16_t	[in]	port	Local port number.

Returns

int32_t. Status information:
- 0 = Operation successful.
- 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.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	socket	Socket identification number.
int32_t	[in]	backlog	Maximum number of the clients supported.

Returns

int32_t. Status information:
- 0 = Operation successful.
- 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.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	socket	Socket identification number.
uint8_t *	[out]	ip	Pointer to buffer where address of connecting socket shall be returned (NULL for none).
uint32_t *	[inout]	ip_len	pointer to length of 'ip' (or NULL if 'ip' is NULL): Length of supplied 'ip' on input. Length of stored 'ip' on output.
uint16_t *	[out]	port	Pointer to buffer where port of connecting socket shall be returned (NULL for none).

Returns

int32_t. Status information:
- socket identification number of accepted socket (>=0).
- 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.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	socket	Socket identification number.
const uint8_t *	[in]	ip	Pointer to remote IP address.
uint32_t	[in]	ip_len	Length of 'ip' address in bytes.
uint16_t	[in]	port	Remote port number.

Returns

int32_t. Status information:
- 0 = Operation successful.
- 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 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)

Receives data from the socket.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	socket	Socket identification number.
void *	[out]	buf	Pointer to buffer where data should be stored.
uint32_t	[in]	len	Length of buffer (in bytes).

Returns

int32_t. Status information:
- Number of bytes received (>=0), if len != 0.
- 0 = Data is available (len = 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)

Receives data from the socket.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	socket	Socket identification number.
void *	[out]	buf	Pointer to buffer where data should be stored.
uint32_t	[in]	len	Length of buffer (in bytes).
uint8_t *	[out]	ip	Pointer to buffer where remote source address shall be returned (NULL for none).
uint32_t *	[inout]	ip_len	Pointer to length of 'ip' (or NULL if 'ip' is NULL): Length of supplied 'ip' on input. Length of stored 'ip' on output.
uint16_t *	[out]	port	Pointer to buffer where remote source port shall be returned (NULL for none).

Returns

int32_t. Status information:
- Number of bytes received (>=0), if len != 0.
- 0 = Data is available (len = 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.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	socket	Socket identification number.
const void *	[in]	buf	Pointer to buffer containing data to send.
uint32_t	[in]	len	Length of data (in bytes).

Returns

int32_t. Status information:
- Number of bytes sent (>=0), if len != 0.
- 0 = Data can be sent (len = 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.

Note

The function doesn't guarantees the packets are transmitted to remote note, which are enqueued in the queue.
The function can only send max of 1460 bytes in case of plain TCP and UDP. For TLS, the max buffer length is 1370.

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.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	socket	Socket identification number.
const void *	[in]	buf	Pointer to buffer containing data to send.
uint32_t	[in]	len	Length of data (in bytes).
const uint8_t *	[in]	ip	Pointer to remote destination IP address.
uint32_t	[in]	ip_len	Length of 'ip' address in bytes.
uint16_t	[in]	port	Remote destination port number.

Returns

int32_t. Status information:
- Number of bytes sent (>=0), if len != 0.
- 0 = Data can be sent (len = 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.

Note

If number of bytes to be send exceeds the MSS size specified by remote node, the API will return IOT_SOCKET_ERROR. To know the MSS size for the socket, use sl_si91x_get_socket_mss() utility, In the case of TCP, this should be called after iotSocketConnect().
The function doesn't guarantees the packets are transmitted to remote note, which are enqueued in the queue.
The function can only send max of 1460 bytes in case of plain TCP or UDP. For TLS, the max buffer length is 1370.

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.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	socket	Socket identification number.
uint8_t *	[out]	ip	Pointer to buffer where local address shall be returned (NULL for none).
uint32_t *	[inout]	ip_len	Pointer to length of 'ip' (or NULL if 'ip' is NULL): Length of supplied 'ip' on input. Length of stored 'ip' on output.
uint16_t *	[out]	port	Pointer to buffer where local port shall be returned (NULL for none).

Returns

int32_t. Status information:
- 0 = Operation successful.
- 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.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	socket	Socket identification number.
uint8_t *	[out]	ip	Pointer to buffer where remote address shall be returned (NULL for none).
uint32_t *	[inout]	ip_len	Pointer to length of 'ip' (or NULL if 'ip' is NULL): Length of supplied 'ip' on input. Length of stored 'ip' on output.
uint16_t *	[out]	port	Pointer to buffer where remote port shall be returned (NULL for none).

Returns

int32_t. Status information:
- 0 = Operation successful.
- 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)

Get socket option.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	socket	Socket identification number.
int32_t	[in]	opt_id	Option identifier. One of the values from Socket Option Id
void *	[out]	opt_val	Pointer to the buffer that will receive the option value.
uint32_t *	[inout]	opt_len	Pointer to length of the option value: Length of buffer on input. Length of data on output.

Returns

int32_t. Satus information:
- 0 = Operation successful.
- IOT_SOCKET_ESOCK = Invalid socket.
- IOT_SOCKET_EINVAL = Invalid argument.
- IOT_SOCKET_ENOTSUP = Operation not supported.
- IOT_SOCKET_ERROR = Unspecified error.

Note

The following are the options, which are supported currently.

iotSocketSetOpt#

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

Set socket option.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	socket	Socket identification number.
int32_t	[in]	opt_id	Option identifier. One of the values from Socket Option Id.
const void *	[in]	opt_val	Pointer to the option value.
uint32_t	[in]	opt_len	Length of the option value in bytes.

Returns

int32_t. Status information:
- 0 = Operation successful.
- IOT_SOCKET_ESOCK = Invalid socket.
- IOT_SOCKET_EINVAL = Invalid argument.
- IOT_SOCKET_ENOTSUP = Operation not supported.
- IOT_SOCKET_ERROR = Unspecified error.

Note

The following are the options, which are supported currently.

iotSocketClose#

int32_t iotSocketClose (int32_t socket)

Close and release a socket.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	socket	Socket identification number.

Returns

int32_t. Status information:
- 0 = Operation successful.
- IOT_SOCKET_ESOCK = Invalid socket.
- IOT_SOCKET_EAGAIN = Operation would block (may be called again).
- IOT_SOCKET_ERROR = Unspecified error.

Note

Calling close on server or first client socket would end up closing other socket 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.

Parameters

Type	Direction	Argument Name	Description
const char *	[in]	name	Host name.
int32_t	[in]	af	Address family. One of value from IOT_SOCKET_ADDRESS_FAMILY
uint8_t *	[out]	ip	Pointer to buffer where resolved IP address shall be returned.
uint32_t *	[inout]	ip_len	Pointer to length of 'ip': length of supplied 'ip' on input. length of stored 'ip' on output.

Returns

int32_t. Status information:
- 0 = Operation successful.
- 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.