IOT Sockets#

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.

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

[in]	af	address family.
[in]	type	socket type.
[in]	protocol	socket protocol.

Returns

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.

Definition at line 105 of file third_party/iot_socket/include/iot_socket.h

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

[in]	socket	socket identification number.
[in]	ip	pointer to local IP address.
[in]	ip_len	length of 'ip' address in bytes.
[in]	port	local port number.

Returns

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.

Definition at line 121 of file third_party/iot_socket/include/iot_socket.h

iotSocketListen#

int32_t iotSocketListen (int32_t socket, int32_t backlog)

Listen for socket connections.

Parameters

[in]	socket	socket identification number.
[in]	backlog	maximum number of the clients supported.

Returns

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.

Definition at line 136 of file third_party/iot_socket/include/iot_socket.h

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

[in]	socket	socket identification number.
[out]	ip	pointer to buffer where address of connecting socket shall be returned (NULL for none).
[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.
[out]	port	pointer to buffer where port of connecting socket shall be returned (NULL for none).

Returns

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.

Definition at line 157 of file third_party/iot_socket/include/iot_socket.h

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

[in]	socket	socket identification number.
[in]	ip	pointer to remote IP address.
[in]	ip_len	length of 'ip' address in bytes.
[in]	port	remote port number.

Returns

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.

Definition at line 179 of file third_party/iot_socket/include/iot_socket.h

iotSocketRecv#

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

Receives data from the socket.

Parameters

[in]	socket	socket identification number.
[out]	buf	pointer to buffer where data should be stored.
[in]	len	length of buffer (in bytes).

Returns

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.

Definition at line 198 of file third_party/iot_socket/include/iot_socket.h

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

[in]	socket	socket identification number.
[out]	buf	pointer to buffer where data should be stored.
[in]	len	length of buffer (in bytes).
[out]	ip	pointer to buffer where remote source address shall be returned (NULL for none).
[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.
[out]	port	pointer to buffer where remote source port shall be returned (NULL for none).

Returns

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.

Definition at line 222 of file third_party/iot_socket/include/iot_socket.h

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

[in]	socket	socket identification number.
[in]	buf	pointer to buffer containing data to send.
[in]	len	length of data (in bytes).

Returns

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 iotSocketSend() system call doesn't guarantees the packets are transmitted to remote note, which are enqueued in the queue. The iotSocketSend() system call can only send max of 1460 bytes incase of plain TCP, UDP. Whereas incase of TLS, the max buffer length is 1370.

Definition at line 244 of file third_party/iot_socket/include/iot_socket.h

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

[in]	socket	socket identification number.
[in]	buf	pointer to buffer containing data to send.
[in]	len	length of data (in bytes).
[in]	ip	pointer to remote destination IP address.
[in]	ip_len	length of 'ip' address in bytes.
[in]	port	remote destination port number.

Note

If number of bytes to be send exceeds the MSS size specified by remote node then API will return IOT_SOCKET_ERROR. To know the MSS size for the socket use si91x_get_socket_mss() utility, In case of TCP this should be called after the connect()

Returns

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 iotSocketSendTo() system call doesn't guarantees the packets are transmitted to remote note, which are enqueued in the queue. The iotSocketSendTo() system call can only send max of 1460 bytes incase of plain TCP, UDP. Whereas incase of TLS, the max buffer length is 1370.

Definition at line 271 of file third_party/iot_socket/include/iot_socket.h

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

[in]	socket	socket identification number.
[out]	ip	pointer to buffer where local address shall be returned (NULL for none).
[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.
[out]	port	pointer to buffer where local port shall be returned (NULL for none).

Returns

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.

Definition at line 288 of file third_party/iot_socket/include/iot_socket.h

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

[in]	socket	socket identification number.
[out]	ip	pointer to buffer where remote address shall be returned (NULL for none).
[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.
[out]	port	pointer to buffer where remote port shall be returned (NULL for none).

Returns

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.

Definition at line 306 of file third_party/iot_socket/include/iot_socket.h

iotSocketGetOpt#

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

Get socket option.

Parameters

[in]	socket	socket identification number.
[in]	opt_id	option identifier.
[out]	opt_val	pointer to the buffer that will receive the option value.
[inout]	opt_len	pointer to length of the option value: length of buffer on input. length of data on output.

Returns

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.
- IOT_SOCKET_IO_FIONBIO
- IOT_SOCKET_SO_RCVTIMEO
- IOT_SOCKET_SO_SNDTIMEO
- IOT_SOCKET_SO_KEEPALIVE
- IOT_SOCKET_SO_TYPE.

Definition at line 331 of file third_party/iot_socket/include/iot_socket.h

iotSocketSetOpt#

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

Set socket option.

Parameters

[in]	socket	socket identification number.
[in]	opt_id	option identifier.
[in]	opt_val	pointer to the option value.
[in]	opt_len	length of the option value in bytes.

Returns

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.
- IOT_SOCKET_IO_FIONBIO
- IOT_SOCKET_SO_RCVTIMEO
- IOT_SOCKET_SO_SNDTIMEO
- IOT_SOCKET_SO_KEEPALIVE
- IOT_SOCKET_SO_TYPE.

Definition at line 354 of file third_party/iot_socket/include/iot_socket.h

iotSocketClose#

int32_t iotSocketClose (int32_t socket)

Close and release a socket.

Parameters

[in]

socket

socket identification number.

Returns

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 othet socket as well.

Definition at line 368 of file third_party/iot_socket/include/iot_socket.h

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

[in]	name	host name.
[in]	af	address family.
[out]	ip	pointer to buffer where resolved IP address shall be returned.
[inout]	ip_len	pointer to length of 'ip': length of supplied 'ip' on input. length of stored 'ip' on output.

Returns

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.

Definition at line 387 of file third_party/iot_socket/include/iot_socket.h