IoT Socket Functions

List of IoT Socket API functions. More...

Functions
int32_t	iotSocketCreate (int32_t af, int32_t type, int32_t protocol)
	Create a communication socket. More...
int32_t	iotSocketBind (int32_t socket, const uint8_t *ip, uint32_t ip_len, uint16_t port)
	Assign a local address to a socket. More...
int32_t	iotSocketListen (int32_t socket, int32_t backlog)
	Listen for socket connections. More...
int32_t	iotSocketAccept (int32_t socket, uint8_t *ip, uint32_t *ip_len, uint16_t *port)
	Accept a new connection on a socket. More...
int32_t	iotSocketConnect (int32_t socket, const uint8_t *ip, uint32_t ip_len, uint16_t port)
	Connect a socket to a remote host. More...
int32_t	iotSocketRecv (int32_t socket, void *buf, uint32_t len)
	Receive data or check if data is available on a connected socket. More...
int32_t	iotSocketRecvFrom (int32_t socket, void *buf, uint32_t len, uint8_t *ip, uint32_t *ip_len, uint16_t *port)
	Receive data or check if data is available on a socket. More...
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. More...
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. More...
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. More...
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. More...
int32_t	iotSocketGetOpt (int32_t socket, int32_t opt_id, void *opt_val, uint32_t *opt_len)
	Get socket option. More...
int32_t	iotSocketSetOpt (int32_t socket, int32_t opt_id, const void *opt_val, uint32_t opt_len)
	Set socket option. More...
int32_t	iotSocketClose (int32_t socket)
	Close and release a socket. More...
int32_t	iotSocketGetHostByName (const char *name, int32_t af, uint8_t *ip, uint32_t *ip_len)
	Retrieve host IP address from host name. More...

Description

List of IoT Socket API functions.

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.

The function iotSocketCreate creates a communication endpoint called a socket.

The argument af specifies the address family. The following values are supported:

Family	Description
IOT_SOCKET_AF_INET	Address Family Internet
IOT_SOCKET_AF_INET6	Address Family Internet version 6

The argument type specifies the communication semantics. The following are the currently supported types:

Type	Description
IOT_SOCKET_SOCK_STREAM	Provides a reliable connection based data stream that is full-duplex
IOT_SOCKET_SOCK_DGRAM	Provides connectionless communication that is unreliable

The argument protocol specifies the protocol that must be used with the socket type:

Protocol	Description
IOT_SOCKET_IPPROTO_TCP	Must be used with IOT_SOCKET_SOCK_STREAM socket type
IOT_SOCKET_IPPROTO_UDP	Must be used with IOT_SOCKET_SOCK_DGRAM socket type

Example:

• see iotSocketListen, iotSocketConnect

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.

The function iotSocketBind assigns a name to an unnamed socket. The name represents the local address and port of the communication endpoint.

The argument socket specifies a socket identification number returned from a previous call to iotSocketCreate.

The argument ip is a pointer to the buffer containing the IP address octets of the local IP address.

The argument ip_len specifies the length of the local IP address. The length is 4 bytes for the IPv4 address and 16 bytes for the IPv6 address.

The argument port specifies the local port. If the argument port is 0, the function returns error, because this port is reserved.

Example:

• see iotSocketListen

iotSocketListen()

int32_t iotSocketListen	(	int32_t	socket,
		int32_t	backlog
	)

Listen for socket connections.

Parameters

[in]	socket	socket identification number.
[in]	backlog	number of connection requests that can be queued.

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.

The function iotSocketListen sets the specified socket to listening mode, that is to the server mode of operation. Before calling the iotSocketListen function, the iotSocketBind function must be called.

The argument socket specifies a socket identification number returned from a previous call to iotSocketCreate.

The argument backlog specifies a maximum number of connection requests that can be queued.

Example:

void Echo_Server_Thread (void *arg) {
  uint8_t ip[4] = { 0U, 0U, 0U, 0U };
  int32_t sock, sd, res;
  char dbuf[120];
 
  while (1) {
    sock = iotSocketCreate (IOT_SOCKET_AF_INET, IOT_SOCKET_SOCK_STREAM, IOT_SOCKET_IPPROTO_TCP);
 
    iotSocketBind (sock, (uint8_t *)ip, sizeof(ip), 7U);
    iotSocketListen (sock, 1);
    sd = iotSocketAccept (sock, NULL, NULL, NULL);
    iotSocketClose (sock);
    sock = sd;
 
    while (1) {
      res = iotSocketRecv (sock, dbuf, sizeof(dbuf));
      if (res < 0) {
        break;                                      // Error occurred
      }
      if (res > 0) {
        iotSocketSend (sock, dbuf, res);            // Echo the data
      }
    }
    iotSocketClose (sock);
  }
}

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).
[in,out]	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.

The function iotSocketAccept accepts a connection request queued for a listening socket.

If a connection request is pending, iotSocketAccept removes the request from the queue, and creates a new socket for the connection. The original listening socket remains open and continues to queue new connection requests. The socket must be a socket of type IOT_SOCKET_SOCK_STREAM.

In blocking mode, which is enabled by default, this function waits for a connection request. In non blocking mode, you must call the iotSocketAccept function again if the error code IOT_SOCKET_EAGAIN is returned.

The argument socket specifies a socket identification number returned from a previous call to iotSocketCreate.

The argument ip is a pointer to the buffer that will receive the IP address of the connection node. If the ip is NULL, the IP address is not returned.

The argument ip_len is a pointer to the IP address length. It should initially contain the amount of space pointed to by ip. On return it contains the actual length of the address returned in bytes.

The argument port is a pointer to the buffer, that will receive the port number of the connection node. If the port is NULL, the port number is not returned.

Example:

• see iotSocketListen

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.

The function iotSocketConnect assigns the address of the peer communication endpoint. The function behaves differently according to the type of socket:

• IOT_SOCKET_SOCK_STREAM : A connection is established between the endpoints.

  In blocking mode, which is enabled by default, this function waits for a connection to be established.

  In non blocking mode, the function returns the error code IOT_SOCKET_EINPROGRESS and the connection is established asynchronously. Subsequent calls to iotSocketConnect for the same socket, before the connection is established, return the error code IOT_SOCKET_EALREADY. When the connection is established, the call to iotSocketConnect returns the error code IOT_SOCKET_EISCONN.

• IOT_SOCKET_SOCK_DGRAM : An address filter is established between the endpoints.

  The address filter is changed with another iotSocketConnect function call. If the socket is not yet bound, the system implicitly binds to a random dynamic port.

The argument socket specifies a socket identification number returned from a previous call to iotSocketCreate.

The argument ip is a pointer to the buffer containing the IP address octets of the endpoint node.

The argument ip_len specifies the length of the IP address. The length is 4 bytes for the IPv4 address and 16 bytes for the IPv6 address.

The argument port specifies the port of the endpoint node. If the argument port is 0, the function returns error, because this port is reserved.

Example:

static const char message[] = { "The quick brown fox jumps over the lazy dog." };
 
void Echo_Client_Thread (void *arg) {
  uint8_t ip[4] = { 192U, 168U, 0U, 100U };
  int32_t sock, res;
  char dbuf[120];
 
  while (1) {
    sock = iotSocketCreate (IOT_SOCKET_AF_INET, IOT_SOCKET_SOCK_STREAM, IOT_SOCKET_IPPROTO_TCP);
 
    res = iotSocketConnect (sock, (uint8_t *)ip, sizeof(ip), 7U);
    if (res == 0) {
      while (1) {
        iotSocketSend (sock, message, sizeof(message));
        res = iotSocketRecv (sock, dbuf, sizeof(dbuf));
        if (res < 0) {
          break;               // Receive error
        }
        if (res > 0) {
          if (memcmp (dbuf, message, res) != 0) {
            break;             // Message error, echoed message is not the same
          }
        }
        osDelay (1000U);
      }
    }
    iotSocketClose (sock);
  }
}

iotSocketRecv()

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

Receive data or check if data is available on a connected socket.

Parameters

[in]	socket	socket identification number.
[out]	buf	pointer to buffer where data should be stored.
[in]	len	length of buffer (in bytes), set len = 0 to check if data is available.

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.

The function iotSocketRecv receives incoming data that has been queued for the socket.

You can use this function with both, the stream and the datagram socket. It reads as much information as currently available up to the size of the buffer specified.

In blocking mode, which is enabled by default, this function waits for received data. In non blocking mode, you must call the iotSocketRecv function again if the error code IOT_SOCKET_EAGAIN is returned.

The argument socket specifies a socket identification number returned from a previous call to iotSocketCreate.

The argument buf is a pointer to the application data buffer for storing the data to. If the available data is too large to fit in the supplied application buffer buf, excess bytes are discarded in case of a datagram sockets. For stream sockets, the data is buffered internally so the application can retrieve all data by multiple calls of iotSocketRecv function.

The argument len specifies the size of the application data buffer.

Note

The function can also be used to check if the socket has data available to read by specifying 0 for argument len (argument buf is ignored). The function returns 0 if data is available or error code otherwise. In blocking mode, the function waits until data is available, in non blocking mode the function returns instantly.

Example:

• see iotSocketListen

iotSocketRecvFrom()

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

Receive data or check if data is available on a socket.

Parameters

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

The function iotSocketRecvFrom is used to receive data that has been queued for a socket.

It is normally used to receive messages on datagram sockets, but can also be used to receive a reliable, ordered stream of data on a connected stream sockets. It reads as much information as currently available up to the size of the buffer specified.

In blocking mode, which is enabled by default, this function waits for received data. In non blocking mode, you must call the iotSocketRecv function again if the error code IOT_SOCKET_EAGAIN is returned.

The argument socket specifies a socket identification number returned from a previous call to iotSocketCreate.

The argument buf is a pointer to the application data buffer for storing the data to. If the available data is too large to fit in the supplied application buffer buf, excess bytes are discarded in case of a datagram sockets. For stream sockets, the data is buffered internally so the application can retrieve all data by multiple calls of iotSocketRecv function.

The argument len specifies the size of the application data buffer.

The argument ip is a pointer to the buffer that will receive the IP address of the sender. If the ip is NULL, the IP address is not returned.

The argument ip_len is a pointer to the IP address length. It should initially contain the amount of space pointed to by ip. On return it contains the actual length of the address returned in bytes.

The argument port is a pointer to the buffer, that will receive the port number of the sender. If the port is NULL, the port number is not returned.

Note

The function can also be used to check if the socket has data available to read by specifying 0 for argument len (arguments buf, ip, ip_len and port are ignored). The function returns 0 if data is available or error code otherwise. In blocking mode, the function waits until data is available, in non blocking mode the function returns instantly.

Example:

void Echo_Server_Thread (void *arg) {
  uint8_t ip[4];
  uint16_t port;
  int32_t sock, res;
  uint32_t ip_len;
  char dbuf[120];
 
  while (1) {
    sock = iotSocketCreate (IOT_SOCKET_AF_INET, IOT_SOCKET_SOCK_DGRAM, IOT_SOCKET_IPPROTO_UDP);
 
    ip[0] = 0U;                 // Unspecified address
    ip[1] = 0U;
    ip[2] = 0U;
    ip[3] = 0U;
    port  = 7U;                 // Standard port for Echo service
 
    iotSocketBind (sock, (uint8_t *)ip, sizeof(ip), port);
 
    while (1) {
      ip_len = sizeof(ip);
      res = iotSocketRecvFrom (sock, dbuf, sizeof(dbuf), (uint8_t *)ip, &ip_len, &port);
      if (res < 0) {
        break;                  // Error occurred
      }
      if (res > 0) {            // Echo the data
        iotSocketSendTo (sock, dbuf, res, (uint8_t *)ip, ip_len, port);
      }
    }
    iotSocketClose (sock);
  }
}

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), set len = 0 to check if data can be sent.

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.

The function iotSocketSend is used to send data on an already connected socket.

This function is normally used to send a reliable, ordered stream of data bytes on a stream sockets. It can also be used to send messages on datagram sockets.

The argument socket specifies a socket identification number returned from a previous call to iotSocketCreate.

The argument buf is a pointer to the application data buffer containing data to transmit. The buffer data length is not limited in size. If the data length is too large for one packet, the iotSocketSend function will fragment the data and send it in several successive data packets:

• In blocking mode, which is enabled by default, this function returns after the data has been successfully queued for transmission.
• In non blocking mode, the function returns immediately without blocking the system.

The argument len specifies the length of data in bytes.

Return value, when positive, represents the number of bytes sent, which can be less than len.

Note

The function can also be used to check if the socket is ready to send data by specifying 0 for argument len (argument buf is ignored). The function returns 0 if the socket is writable or error code otherwise.

Example:

• see iotSocketListen

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), set len = 0 to check if data can be sent.
[in]	ip	pointer to remote destination IP address.
[in]	ip_len	length of 'ip' address in bytes.
[in]	port	remote destination port number.

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.

The function iotSocketSendTo is used to send data.

It is normally used to send messages on a datagram sockets, but can also be used to send data on a connected stream sockets.

If the datagram socket is not yet bound, the system implicitly binds to a random dynamic port.

The argument socket specifies a socket identification number returned from a previous call to iotSocketCreate.

The argument buf is a pointer to the application data buffer containing data to transmit. The buffer data length is not limited in size. If the data length is too large for one packet, the iotSocketSend function will fragment the data and send it in several successive data packets:

• In blocking mode, which is enabled by default, this function returns after the data has been successfully queued for transmission.
• In non blocking mode, the function returns immediately without blocking the system.

The argument len specifies the length of data in bytes.

The argument ip is a pointer to the buffer containing the IP address octets of the endpoint node.

The argument ip_len specifies the length of the IP address. The length is 4 bytes for the IPv4 address and 16 bytes for the IPv6 address.

The argument port specifies the port of the endpoint node. If the argument port is 0, the function returns error, because this port is reserved.

For the stream sockets, arguments ip, ip_len and port are ignored.

Return value, when positive, represents the number of bytes sent, which can be less than len.

Note

The function can also be used to check if the socket is ready to send data by specifying 0 for argument len (arguments buf, ip, ip_len and port are ignored). The function returns 0 if the socket is writable or error code otherwise.

Example:

• see iotSocketRecvFrom

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).
[in,out]	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.

The function iotSocketGetSockName retrieves the local IP address and port for a socket.

The argument socket specifies a socket identification number returned from a previous call to iotSocketCreate.

The argument ip is a pointer to the buffer that will receive the local IP address. If the ip is NULL, the local IP address is not returned.

The argument ip_len is a pointer to the IP address length. It should initially contain the amount of space pointed to by ip. On return it contains the actual length of the address returned in bytes.

The argument port is a pointer to the buffer, that will receive the local port number. If the port is NULL, the local port number is not returned.

Example:

static uint8_t  local_ip[4];    // Socket address and port
static uint16_t local_port;
 
static void get_socket_local_info (void) {
  uint32_t ip_len;
 
  ip_len = sizeof(local_ip);
  iotSocketGetSockName (sock, (uint8_t *)local_ip, &ip_len, &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.

Parameters

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

The function iotSocketGetPeerName retrieves the IP address and port of the peer to which a socket is connected.

The argument socket specifies a socket identification number returned from a previous call to iotSocketCreate.

The argument ip is a pointer to the buffer that will receive the IP address of the peer. If the ip is NULL, the IP address is not returned.

The argument ip_len is a pointer to the IP address length. It should initially contain the amount of space pointed to by ip. On return it contains the actual length of the address returned in bytes.

The argument port is a pointer to the buffer, that will receive the port number of the peer. If the port is NULL, the port number is not returned.

Example:

static uint8_t  peer_ip[4];    // Socket address and port
static uint16_t peer_port;
 
static void get_socket_peer_info (void) {
  uint32_t ip_len;
 
  ip_len = sizeof(peer_ip);
  iotSocketGetPeerName (sock, (uint8_t *)peer_ip, &ip_len, &peer_port);
}

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.
[in,out]	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.

The function iotSocketGetOpt retrieves options for a socket.

The argument socket specifies a socket identification number returned from a previous call to iotSocketCreate.

The argument opt_id is the socket option for which the value is to be retrieved. The following socket options are supported:

Option	Description
IOT_SOCKET_SO_RCVTIMEO	Timeout for receiving in blocking mode
IOT_SOCKET_SO_SNDTIMEO	Timeout for sending in blocking mode
IOT_SOCKET_SO_KEEPALIVE	Keep-alive mode for the stream socket
IOT_SOCKET_SO_TYPE	Type of the socket (stream or datagram)

The argument opt_val points to the buffer that will receive the value of the opt_id.

The argument opt_len contains the length of the buffer at the input and returns the length of the option information on the output.

Example:

uint32_t type;
 
iotSocketGetOpt (sock, IOT_SOCKET_SO_TYPE, &type, sizeof(type));
if (type == IOT_SOCKET_SOCK_STREAM) {
  // Stream socket
}
if (type == IOT_SOCKET_SOCK_DGRAM) {
  // Datagram socket
}

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.

The function iotSocketSetOpt sets options for a socket.

The argument socket specifies a socket identification number returned from a previous call to iotSocketCreate.

The argument opt_id is the socket option for which the value is to be set. The following socket options are supported:

Option	Description
IOT_SOCKET_IO_FIONBIO	Non-blocking mode for the socket
IOT_SOCKET_SO_RCVTIMEO	Timeout for receiving in blocking mode
IOT_SOCKET_SO_SNDTIMEO	Timeout for sending in blocking mode
IOT_SOCKET_SO_KEEPALIVE	Keep-alive mode for the stream socket

The argument opt_val points to the buffer containing the value of the opt_id.

The argument opt_len tells the exact length of the option.

Example:

uint32_t nonblocking = 0U;    // Blocking mode
uint32_t timeout = 10000U;    // Timeout 10 seconds
 
iotSocketSetOpt (sock, IOT_SOCKET_IO_FIONBIO, &nonblocking, sizeof(nonblocking));
iotSocketSetOpt (sock, IOT_SOCKET_SO_RCVTIMEO, &timeout, sizeof(timeout));
iotSocketSetOpt (sock, IOT_SOCKET_SO_SNDTIMEO, &timeout, sizeof(timeout));

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.

The function iotSocketClose closes an existing socket and releases the socket descriptor. Further references to socket fail with IOT_SOCKET_EINVAL error code.

The argument socket specifies a socket identification number returned from a previous call to iotSocketCreate.

In blocking mode, which is enabled by default, this function will wait until a socket is closed. In non blocking mode, you must call the iotSocketClose function again if the error code IOT_SOCKET_EAGAIN is returned.

Example:

• see iotSocketListen

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.
[in,out]	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.

The function iotSocketGetHostByName retrieves host information corresponding to a host name from a host database.

It does this by sending DNS requests to the DNS server. The IP address of the DNS server is specified in the network interface configuration or can be obtained from the DHCP server for the local area network.

The argument name is a pointer to the null-terminated name of the host to resolve.

The argument af specifies the address family, that is, which type of IP address you want to resolve. The following values are supported:

Family	Description
IOT_SOCKET_AF_INET	Resolve the IPv4 address
IOT_SOCKET_AF_INET6	Resolve the IPv6 address

The argument ip is a pointer to the buffer that will receive the resolved IP address of the host. If the argument ip is NULL, the function returns error.

The argument ip_len is a pointer to the IP address length. It should initially contain the amount of space pointed to by ip. On return it contains the actual length of the address returned in bytes.