Modules#

POSIX-compliant Socket#

The Socket component offers a POSIX-compliant alternative to the Wi-SUN stack native socket API. The Portable Operating System Interface (POSIX) is a family of standards specified by the IEEE Computer Society. It promotes compatibility and portability of software solutions. It becomes extremly valuable in the IP world to leverage the various application protocols available. In this sense, the socket component can accelerate the integration of existing software libraries on top of the Wi-SUN stack.

The component allows the application to create/destroy sockets, set socket options, and send or receive IP packets using the APIs defined in the POSIX standard. The APIs exposed by the component are thread-safe. The graphical configuration interface gives access to a number of configurations like the maximum count of available sockets and the FIFO buffer size. The component includes the socket-related event handler implementations.

To use the component in your application, add it to your project.

Variables#

const in6_addr_t

in6addr_any

Definition of any address for IPv6.

Functions#

int32_t

socket(sock_domain_t domain, sock_type_t type, proto_type_t protocol)

Create an endpoint for communication and return a socket ID.

int32_t

close(int32_t sockid)

Close socket.

int32_t

bind(int32_t sockid, const struct sockaddr *addr, socklen_t addrlen)

Bind a name to a socket.

int32_t

listen(int32_t sockid, int32_t backlog)

Listen for connections on a socket.

int32_t

accept(int32_t sockid, struct sockaddr *addr, socklen_t *addrlen)

Accept a connection on a socket.

int32_t

connect(int32_t sockid, const struct sockaddr *addr, socklen_t addrlen)

Initiate a connection on a socket.

int32_t

send(int32_t sockid, const void *buff, uint32_t len, int32_t flags)

Send a message on a socket,.

int32_t

sendto(int32_t sockid, const void *buff, uint32_t len, int32_t flags, const struct sockaddr *dest_addr, socklen_t addr_len)

Send a message on a socket.

int32_t

recv(int32_t sockid, void *buf, uint32_t len, int32_t flags)

Receive a message from a socket.

int32_t

recvfrom(int32_t sockid, void *buf, uint32_t len, int32_t flags, struct sockaddr *src_addr, socklen_t *addrlen)

Receive messages from a socket.

int32_t

setsockopt(int32_t sockid, int32_t level, int32_t optname, const void *optval, socklen_t optlen)

Set socket option.

int32_t

getsockopt(int32_t sockid, int32_t level, int32_t optname, void *optval, socklen_t *optlen)

Get socket option.

uint32_t

htonl(uint32_t hostlong)

Long host byte order to network order.

uint16_t

htons(uint16_t hostshort)

Short host byte order to network order.

uint32_t

ntohl(uint32_t netlong)

Long network byte order to host byte order.

uint16_t

ntohs(uint16_t netshort)

Short network byte order to host byte order.

int32_t

inet_pton(sock_domain_t af, const char *src, void *dst)

Convert IPv4 and IPv6 addresses from text to binary form.

const char *

inet_ntop(sock_domain_t af, const void *src, char *dst, socklen_t size)

Convert IPv4 and IPv6 addresses from binary to text form.

Macros#

#define

SOCKADDR_WISUN_FAMILY_OFFSET (offsetof(wisun_addr_t, sin6_family))

Wi-SUN address structure offsets.

#define

SOCKADDR_WISUN_PORT_OFFSET (offsetof(wisun_addr_t, sin6_port))

#define

SOCKADDR_WISUN_FLOWINFO_OFFSET (offsetof(wisun_addr_t, sin6_flowinfo))

#define

SOCKADDR_WISUN_ADDRESS_OFFSET (offsetof(wisun_addr_t, sin6_addr))

#define

SOCKADDR_WISUN_SCOPEID_OFFSET (offsetof(wisun_addr_t, sin6_scope_id))

#define

INADDR_ANY (0UL)

Definition of any address for IPv4.

Variable Documentation#

in6addr_any#

const in6_addr_t in6addr_any

Definition of any address for IPv6.

Function Documentation#

socket#

int32_t socket (sock_domain_t domain, sock_type_t type, proto_type_t protocol)

Create an endpoint for communication and return a socket ID.

Parameters

Type	Direction	Argument Name	Description
sock_domain_t	[in]	domain	The communication domain, this selects the protocol family. It can be: AF_WISUN - Wi-SUN FAN AF_INET6 - External IPv6 network socket (future implementation) AF_INET - External IPv4 network address (future implementation)
sock_type_t	[in]	type	The communication semantics It can be: SOCK_STREAM - Stream Socket type (TCP) SOCK_DGRAM - Datagram Socket type (UDP) SOCK_RAW - Raw Socket type (ICMP)
proto_type_t	[in]	protocol	Specifies the particular protocol to be used. It can be: IPPROTO_AUTO - Auto selection SOCK_STREAM -> TCP, SOCK_DGRAM -> UDP IPPROTO_IP - Same then IPPROTO_AUTO IPPROTO_ICMP - Ping IPPROTO_TCP - TCP protocol IPPROTO_UDP - UDP protocol

Socket API support Wi-SUN FAN and external IP network communications. External handlers can be implemented, the default implementations are weak functions. Created sockets added to socket handler automatically Returns

if any error occurred, return with -1, otherwise return with the socket id

close#

int32_t close (int32_t sockid)

Close socket.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	sockid	socket id

Close socket and remove from the socket handler storage Returns

if any error occurred, return with -1, otherwise return with the socket id

bind#

int32_t bind (int32_t sockid, const struct sockaddr * addr, socklen_t addrlen)

Bind a name to a socket.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	sockid	socket id
const struct sockaddr *	[in]	addr	address structure ptr
socklen_t	[in]	addrlen	address structure size

Assigns the address specified by addr to the socket referred to by the socket id. It is normally necessary to assign a local address using bind() before a SOCK_STREAM socket may receive connections Returns

On success, zero is returned. On error, -1 is returned

listen#

int32_t listen (int32_t sockid, int32_t backlog)

Listen for connections on a socket.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	sockid	socket id
int32_t	[in]	backlog	Argument defines the maximum length to which the queue of pending connections for sockid may grow. Not implemented for Wi-SUN, the connection queue size is always 1

Marks the socket referred to by sockid as a passive socket, that is, as a socket that will be used to accept incoming connection requests using accept Returns

On success, zero is returned. On error, -1 is returned

accept#

int32_t accept (int32_t sockid, struct sockaddr * addr, socklen_t * addrlen)

Accept a connection on a socket.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	sockid	socket id
struct sockaddr *	[inout]	addr	Is filled in with the address of the peer (remote) socket In Wi-SUN case, it shouldn't be NULL ptr, but for external sockets should be.
socklen_t *	[inout]	addrlen	It is the byte size of the address. In Wi-SUN, it won't be set to the actual size on return.

It is used with connection-based socket types (TCP). It extracts the first connection request on the queue of pending connections for the listening socket. Returns

On success, return with the socket id for accepted socket, on error -1 is returned.

connect#

int32_t connect (int32_t sockid, const struct sockaddr * addr, socklen_t addrlen)

Initiate a connection on a socket.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	sockid	socket id
const struct sockaddr *	[inout]	addr	If the socket sockid is of type SOCK_DGRAM, then addr is the address to which datagrams are sent by default, and the only address from which datagrams are received. If the socket is of type SOCK_STREAM, this call attempts to make a connection to the socket that is bound to the address specified by addr.
socklen_t	[inout]	addrlen	It is the byte size of the address. In Wi-SUN, it won't be set to the actual size on return.

Connects the socket referred to by the socketid to the address specified by addr. Returns

If the connection or binding succeeds, zero is returned. On error, -1 is returned.

send#

int32_t send (int32_t sockid, const void * buff, uint32_t len, int32_t flags)

Send a message on a socket,.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	sockid	socket id
const void *	[in]	buff	buffer pointer to send
uint32_t	[in]	len	length of buffer to send
int32_t	[in]	flags	In Wi-SUN domain, the flags is not used.

It is preferred with connection-oriented sockets (TCP). Returns

On success, these calls return the number of bytes sent. On error, -1 is returned

sendto#

int32_t sendto (int32_t sockid, const void * buff, uint32_t len, int32_t flags, const struct sockaddr * dest_addr, socklen_t addr_len)

Send a message on a socket.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	sockid	socket id
const void *	[in]	buff	buffer pointer to send
uint32_t	[in]	len	length of buffer to send
int32_t	[in]	flags	In Wi-SUN domain, the flags is not used.
const struct sockaddr *	[in]	dest_addr	destination address ptr, the structure must be prepared for UDP sockets
socklen_t	[in]	addr_len	destination address length

It is preferred in datagram mode (UDP). Returns

On success, these calls return the number of bytes sent. On error, -1 is returned

recv#

int32_t recv (int32_t sockid, void * buf, uint32_t len, int32_t flags)

Receive a message from a socket.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	sockid	socket id
void *	[out]	buf	destination buffer ptr
uint32_t	[in]	len	length of data to read
int32_t	[in]	flags	In Wi-SUN domain, the flags is not used.

It should be used for connection-oriented protocol (TCP) Returns

return the number of bytes received, or -1 if an error occurred

recvfrom#

int32_t recvfrom (int32_t sockid, void * buf, uint32_t len, int32_t flags, struct sockaddr * src_addr, socklen_t * addrlen)

Receive messages from a socket.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	sockid	socket id
void *	[out]	buf	destination buffer ptr
uint32_t	[in]	len	length of data to read
int32_t	[in]	flags	In Wi-SUN domain, the flags is not used.
struct sockaddr *	[in]	src_addr	Source address
socklen_t *	[in]	addrlen	length of the source address

It can be used to receive data on a socket whether or not it is connection-oriented. Returns

return the number of bytes received, or -1 if an error occurred

setsockopt#

int32_t setsockopt (int32_t sockid, int32_t level, int32_t optname, const void * optval, socklen_t optlen)

Set socket option.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	sockid	socket id
int32_t	[in]	level	Not used in Wi-SUN domain.
int32_t	[in]	optname	Option name. For Wi-SUN: SL_WISUN_SOCKET_OPTION_EVENT_MODE - Option for socket event mode SL_WISUN_SOCKET_OPTION_MULTICAST_GROUP - Option for multicast group SL_WISUN_SOCKET_OPTION_SEND_BUFFER_LIMIT - Option for send buffer limit
const void *	[in]	optval	Option value structure pointer. For Wi-SUN it is casted to sl_wisun_socket_option_t
socklen_t	[in]	optlen	Must be the size of sl_wisun_socket_option_data_t union

This function can set socket properties. There are some limitation in Wi-SUN domain: optlen and level args are not used. optname and optval are casted to the corresponding Wi-SUN types: sl_wisun_socket_option_t and sl_wisun_socket_option_data_t. sl_wisun_socket_option_data_t is a union type to include all of implemented Wi-SUN socket options Returns

Return 0 on succes, other wise -1

getsockopt#

int32_t getsockopt (int32_t sockid, int32_t level, int32_t optname, void * optval, socklen_t * optlen)

Get socket option.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	sockid	socket id
int32_t	[in]	level	Not used in Wi-SUN domain.
int32_t	[in]	optname	Option name. For Wi-SUN: SL_WISUN_SOCKET_OPTION_EVENT_MODE - Option for socket event mode SL_WISUN_SOCKET_OPTION_MULTICAST_GROUP - Option for multicast group SL_WISUN_SOCKET_OPTION_SEND_BUFFER_LIMIT - Option for send buffer limit
void *	[out]	optval	Destination structure pointer. For Wi-SUN it is casted to sl_wisun_socket_option_t
socklen_t *	[in]	optlen	Must be the size of sl_wisun_socket_option_data_t union

The function gets socket option by optname, and copy option data to optval ptr Returns

Return 0 on success, other wise -1

htonl#

static uint32_t htonl (uint32_t hostlong)

Long host byte order to network order.

Parameters

Type	Direction	Argument Name	Description
uint32_t	[in]	hostlong	Long host integer

It converts the unsigned integer hostlong from host byte order to network byte order. For Wi-SUN, conversion is not needed. Dummy implementation Returns

Long network integer

htons#

static uint16_t htons (uint16_t hostshort)

Short host byte order to network order.

Parameters

Type	Direction	Argument Name	Description
uint16_t	[in]	hostshort	Short host integer

It converts the unsigned short integer hostshort from host byte order to network byte order. For Wi-SUN, conversion is not needed. Dummy implementation Returns

Short network integer

ntohl#

static uint32_t ntohl (uint32_t netlong)

Long network byte order to host byte order.

Parameters

Type	Direction	Argument Name	Description
uint32_t	[in]	netlong	Long network integer

It converts the unsigned integer netlong from network byte order to host byte order. For Wi-SUN, conversion is not needed. Dummy implementation Returns

Long host integer

ntohs#

static uint16_t ntohs (uint16_t netshort)

Short network byte order to host byte order.

Parameters

Type	Direction	Argument Name	Description
uint16_t	[in]	netshort

It converts the unsigned short integer netshort from network byte order to host byte order. For Wi-SUN, conversion is not needed. Dummy implementation Returns

Short host integer

inet_pton#

int32_t inet_pton (sock_domain_t af, const char * src, void * dst)

Convert IPv4 and IPv6 addresses from text to binary form.

Parameters

Type	Direction	Argument Name	Description
sock_domain_t	[in]	af	Address family. The af argument must be either AF_WISUN, AF_INET6 or AF_INET
const char *	[in]	src	Source string
void *	[out]	dst	Destination address pointer

It converts the character string src into a network address structure in the af address family, then copies the network address structure to dst For AF_WISUN or AF_INET6, stoip6(src, len, dst) called within the implementation AF_INET (IPv4) case not implemented. Returns

1 on succes, -1 on error (POSIX described the 0 value too)

inet_ntop#

const char* inet_ntop (sock_domain_t af, const void * src, char * dst, socklen_t size)

Convert IPv4 and IPv6 addresses from binary to text form.

Parameters

Type	Direction	Argument Name	Description
sock_domain_t	[in]	af	Address family. The af argument must be either AF_WISUN, AF_INET6 or AF_INET
const void *	[in]	src	Source address in byte form
char *	[out]	dst	Destination buffer ptr
socklen_t	[in]	size	Size of the destination buffer.

Converts the network address structure src in the af address family into a character string. The resulting string is copied to the buffer pointed to by dst, which must be a non-null pointer. The caller specifies the number of bytes available in this buffer in the argument size. For AF_WISUN or AF_INET6, stoip6(src, len, dst) called within the implementation AF_INET (IPv4) case not implemented. Returns

It returns a non-null pointer to dst. NULL is returned if there was an error