Sockets#

Wi-SUN socket API is loosely modeled after the well-known BSD socket API, also known as POSIX socket API. Each socket represents a handle for the local endpoint of a communication circuit.

API overview#


BSD function	Wi-SUN API function	Description
socket()	sl_wisun_open_socket()
bind()	sl_wisun_bind_socket()
listen()	sl_wisun_listen_on_socket()
connect()	sl_wisun_connect_socket()
accept()	sl_wisun_accept_on_socket()
send()	sl_wisun_send_on_socket()
recv()	sl_wisun_receive_on_socket()
sendto()	sl_wisun_sendto_on_socket()
recvfrom()	Not supported
close()	sl_wisun_close_socket()
gethostbyname()	Not supported
gethostbyaddr()	Not supported
select()	Not supported
poll()	Not supported
getsockopt()	sl_wisun_get_socket_option()
setsockopt()	sl_wisun_set_socket_option()

Socket Life Cycle#

In general, a socket is created by explicitly calling sl_wisun_open_socket() and must be explicitly closed by calling sl_wisun_close_socket(). This will both close the communication circuit as well as free any resources allocated to the socket.

In certain protocols, the communication circuit may be closed by the remote peer. This is indicated with a SL_WISUN_MSG_SOCKET_CLOSING_IND_ID event. Although the socket connection has been closed, the system resources will not be freed until the application calls sl_wisun_close_socket().

Exchanging Data#

Certain protocols require a socket in a connected state, meaning the underlying protocol must first establish a session with the remote peer before data can be exchanged. It is also optionally possible on certain connectionless protocols. In either case, connecting a socket creates a direct communication link with a remote peer, allowing the socket to be used only with that particular peer.

To switch a socket into connected state, sl_wisun_connect_socket() is used. See the table below for protocol details.


Protocol	Unconnected	Connected
SL_WISUN_SOCKET_PROTOCOL_UDP	MAY	MAY
SL_WISUN_SOCKET_PROTOCOL_TCP	MUST NOT	MUST
SL_WISUN_SOCKET_PROTOCOL_ICMP	MUST	MUST NOT

Transmit#

When a socket is in unconnected state, sl_wisun_sendto_on_socket() is used to transmit data. The function requires the application to specify the remote peer address and port number on each call. When a socket is connected, sl_wisun_send_on_socket() is used instead. Because the socket is "locked" into a single remote peer, address and port number are not needed.

Both functions are asynchronous, a successful return code indicates the socket has buffered the provided data and the application may free the data resources. The application receives a SL_WISUN_MSG_SOCKET_DATA_SENT_IND_ID event when part or all of the buffered data has been sent.

Receive#

The application has indication mode and polling mode for managing received socket data. All sockets default to indication mode. In this mode, the received data is sent as a SL_WISUN_MSG_SOCKET_DATA_IND_ID event as soon as it is received. The application must either handle the data immediately or store it for later processing. Either way, the socket will not keep the data once the event handler returns. In polling mode, the application will receive a SL_WISUN_MSG_SOCKET_DATA_AVAILABLE_IND_ID event on data reception. The received data is stored in the socket buffer until the application reads it using sl_wisun_receive_on_socket().

Client#

TCP Example#

Open a SL_WISUN_SOCKET_PROTOCOL_TCP type socket using sl_wisun_open_socket().
Initiate connection to the remote server using sl_wisun_connect_socket().
Wait for SL_WISUN_MSG_SOCKET_CONNECTED_IND_ID event.
... Exchange data with the remote server ...
Close the socket using sl_wisun_close_socket().

UDP Example#

Open a SL_WISUN_SOCKET_PROTOCOL_UDP type socket using sl_wisun_open_socket().
... Exchange data with the remote server ...
Close the socket using sl_wisun_close_socket().

Server#

TCP Example#

Open a SL_WISUN_SOCKET_PROTOCOL_TCP type server socket using sl_wisun_open_socket().
Set the server socket port number using sl_wisun_bind_socket().
Set the server socket into listening state using sl_wisun_listen_on_socket().
Wait for SL_WISUN_MSG_SOCKET_CONNECTION_AVAILABLE_IND_ID event.
Accept the client connection using sl_wisun_accept_on_socket() on the server socket.
... Exchange data with the remote client using the newly created client socket ...
Close the client socket using sl_wisun_close_socket().
Go to 4.

UDP Example#

Open a SL_WISUN_SOCKET_PROTOCOL_UDP type socket using sl_wisun_open_socket().
Set the socket port number using sl_wisun_bind_socket().
... Exchange data with the remote client ...