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()

Open a socket. .

bind()

sl_wisun_bind_socket()

Bind a socket to a specific local address and/or a port number. .

listen()

sl_wisun_listen_on_socket()

Set a TCP socket to listening state. .

connect()

sl_wisun_connect_socket()

Initiate a connection from a socket to a remote peer socket. .

accept()

sl_wisun_accept_on_socket()

Accept a pending connection request on a TCP socket. .

send()

sl_wisun_send_on_socket()

Write data to a connected socket. .

recv()

sl_wisun_receive_on_socket()

Read data from a socket. .

sendto()

sl_wisun_sendto_on_socket()

Write data to an unconnected socket. .

recvfrom()

Not supported

close()

sl_wisun_close_socket()

Close a socket. .

gethostbyname()

Not supported

gethostbyaddr()

Not supported

select()

Not supported

poll()

Not supported

getsockopt()

sl_wisun_get_socket_option()

Get a socket option. .

setsockopt()

sl_wisun_set_socket_option()

Set a 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#

  1. Open a SL_WISUN_SOCKET_PROTOCOL_TCP type socket using sl_wisun_open_socket().

  2. Initiate connection to the remote server using sl_wisun_connect_socket().

  3. Wait for SL_WISUN_MSG_SOCKET_CONNECTED_IND_ID event.

  4. ... Exchange data with the remote server ...

  5. Close the socket using sl_wisun_close_socket().

UDP Example#

  1. Open a SL_WISUN_SOCKET_PROTOCOL_UDP type socket using sl_wisun_open_socket().

  2. ... Exchange data with the remote server ...

  3. Close the socket using sl_wisun_close_socket().

Server#

TCP Example#

  1. Open a SL_WISUN_SOCKET_PROTOCOL_TCP type server socket using sl_wisun_open_socket().

  2. Set the server socket port number using sl_wisun_bind_socket().

  3. Set the server socket into listening state using sl_wisun_listen_on_socket().

  4. Wait for SL_WISUN_MSG_SOCKET_CONNECTION_AVAILABLE_IND_ID event.

  5. Accept the client connection using sl_wisun_accept_on_socket() on the server socket.

  6. ... Exchange data with the remote client using the newly created client socket ...

  7. Close the client socket using sl_wisun_close_socket().

  8. Go to 4.

UDP Example#

  1. Open a SL_WISUN_SOCKET_PROTOCOL_UDP type socket using sl_wisun_open_socket().

  2. Set the socket port number using sl_wisun_bind_socket().

  3. ... Exchange data with the remote client ...