Socket API#

Modules#

Protocol levels used for socket_setsockopt.#

#define

SOL_SOCKET 0

Socket option level.

#define

SOL_APPLICATION 1

Application socket option level.

#define

IPPROTO_IPV6 41

IPV6 socket option level.

application level socket options#

application level socket options summaryopt_name data type set/get sendmsg recvmsg SO_EVENT_MODE int16_t Set only No Yes SO_NONBLOCK int16_t Set only Yes Yes

#define

SO_EVENT_MODE 10

#define

SOCKET_EVENT_MODE SO_EVENT_MODE

#define

SO_NONBLOCK 11

Enable/disable nonblocking mode.

socket level options#

socket level options summaryopt_name data type set/get sendmsg recvmsg SO_RCVBUF int32_t Set/Get No Yes SO_SNDBUF int32_t Set/Get Yes No SO_SNDLOWAT int32_t Set/Get Yes No

#define

SO_RCVBUF 1

#define

SO_SNDBUF 2

Specify send buffer size in payload bytes.

#define

SO_SNDLOWAT 4

Specify send low water mark in payload bytes.

IPv6 socket options#

IPv6 socket options summaryopt_name Data type set/getsockopt sendmsg recvmsg IPV6_UNICAST_HOPS int16_t Set/Get Yes No IPV6_MULTICAST_HOPS int16_t Set/Get Yes No IPV6_JOIN_GROUP ns_ipv6_mreq_t Set only Yes Yes IPV6_LEAVE_GROUP ns_ipv6_mreq_t Set only Yes Yes SO_EDFE_MODE uint32_t Set only Yes No

#define

IPV6_UNICAST_HOPS 2

#define

IPV6_MULTICAST_HOPS 3

Set the multicast hop limit for the socket.

#define

IPV6_JOIN_GROUP 15

Join a multicast group.

#define

IPV6_LEAVE_GROUP 16

Leave a multicast group.

#define

SO_EDFE_MODE 0xfb

Experimental: Enable Extended Directed Frame Exchange mode.

#define

SOCKET_EDFE_MODE SO_EDFE_MODE

Enumerations#

enum

sl_wisun_socket_event_mode_t {

SL_WISUN_SOCKET_EVENT_MODE_INDICATION = 0

SL_WISUN_SOCKET_EVENT_MODE_POLLING = 1

}

Enumerations for socket event mode.

enum

socket_domain {

AF_INET6 = 0

}

Supported address families.

enum

socket_type {

SOCK_STREAM = 1

SOCK_DGRAM = 2

SOCK_RAW = 3

}

Socket types.

enum

socket_protocol {

IPPROTO_IP = 0

IPPROTO_ICMP = 1

IPPROTO_TCP = 2

IPPROTO_UDP = 3

}

IP protocols.

Typedefs#

typedef uint32_t

socklen_t

Socket address length type definition.

typedef int32_t

sl_wisun_socket_id_t

Socket id.

typedef enum socket_domain

sl_socket_domain_t

Supported address families.

typedef enum socket_type

sl_socket_type_t

Socket types.

typedef enum socket_protocol

sl_socket_protocol_t

IP protocols.

typedef struct in6_addr

in6_addr_t

IPv6 Internet address.

typedef struct sockaddr_in6

sockaddr_in6_t

IPv6 address format.

Variables#

const in6_addr_t

in6addr_any

IPv6 wildcard address.

Functions#

int32_t

socket(int32_t domain, int32_t type, int32_t protocol)

Creates an endpoint for communication and returns an Id that refers to that endpoint.

int32_t

close(int32_t sockid)

Close a socket.

int32_t

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

Bind a name to 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 to a given address.

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

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

Receive a message from 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

listen(int32_t sockid, int32_t backlog)

Listen for connections on a socket.

int32_t

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

Set socket option designated by optname at a given protocol level to the value pointed by optval.

int32_t

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

Get socket option.

__STATIC_INLINE uint32_t

htonl(uint32_t hostlong)

Convert the long host byte order to network order.

__STATIC_INLINE uint16_t

htons(uint16_t hostshort)

Convert the short host byte order to network order.

__STATIC_INLINE uint32_t

ntohl(uint32_t netlong)

Convert the long network byte order to host byte order.

__STATIC_INLINE uint16_t

ntohs(uint16_t netshort)

Convert the short network byte order to host byte order.

int32_t

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

Convert the IPv4 and IPv6 addresses from text to binary form.

const char *

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

Convert IPv6 addresses from binary to text form.

Macros#

#define

APP_LEVEL_SOCKET SOL_APPLICATION

#define

IPV6_ADDR_SIZE 16

Size of an IPv6 address.

#define

SOCK_NONBLOCK 0X00010000

When bitwise ored with socket's type, it sets the O_NONBLOCK status flag on the opened socket file description.

Protocol levels used for socket_setsockopt. Documentation#

application level socket options Documentation#

socket level options Documentation#

IPv6 socket options Documentation#

Enumeration Documentation#

sl_wisun_socket_event_mode_t#

sl_wisun_socket_event_mode_t

Enumerations for socket event mode.

Enumerator
SL_WISUN_SOCKET_EVENT_MODE_INDICATION	SL_WISUN_MSG_SOCKET_DATA_IND_ID is sent to the app with the packet contained in the indication.
SL_WISUN_SOCKET_EVENT_MODE_POLLING	SL_WISUN_MSG_SOCKET_DATA_AVAILABLE_IND_ID is sent to the app indicating the amount of data received recv() or recvfrom() should be invoked after indication reception to retrieve data This is the default socket event mode option.

socket_domain#

socket_domain

Supported address families.

Enumerator
AF_INET6	IP version 6.

socket_type#

socket_type

Socket types.

Enumerator
SOCK_STREAM	stream (connection) socket (TCP)
SOCK_DGRAM	datagram (connectionless ) socket (UDP)
SOCK_RAW	raw socket

socket_protocol#

socket_protocol

IP protocols.

Enumerator
IPPROTO_IP	Dummy protocol.
IPPROTO_ICMP	Internet Control Message Protocol.
IPPROTO_TCP	Transmission Control Protocol.
IPPROTO_UDP	User Datagram Protocol.

Typedef Documentation#

socklen_t#

typedef uint32_t socklen_t

Socket address length type definition.

sl_wisun_socket_id_t#

typedef int32_t sl_wisun_socket_id_t

Socket id.

sl_socket_domain_t#

typedef enum socket_domain sl_socket_domain_t

Supported address families.

sl_socket_type_t#

typedef enum socket_type sl_socket_type_t

Socket types.

sl_socket_protocol_t#

typedef enum socket_protocol sl_socket_protocol_t

IP protocols.

in6_addr_t#

typedef struct in6_addr in6_addr_t

IPv6 Internet address.

sockaddr_in6_t#

typedef struct sockaddr_in6 sockaddr_in6_t

IPv6 address format.

Variable Documentation#

in6addr_any#

const in6_addr_t in6addr_any

IPv6 wildcard address.

Function Documentation#

socket#

int32_t socket (int32_t domain, int32_t type, int32_t protocol)

Creates an endpoint for communication and returns an Id that refers to that endpoint.

Parameters

Type Direction Argument Name Description

int32_t

[in]

domain

Type	Direction	Argument Name	Description
int32_t	[in]	domain	Specifies a communication domain. It selects the protocol family which will be used for communication. Must be set to AF_INET6 (IPv6 network socket)
int32_t	[in]	type	The communication semantics It can be: SOCK_STREAM - TCP stream socket type SOCK_DGRAM - UDP datagram socket type SOCK_RAW - Raw Socket type (ICMP)
int32_t	[in]	protocol	Specifies the particular protocol to be used. It can be: IPPROTO_ICMP - Ping IPPROTO_IP and IPPROTO_TCP - TCP stream sockets IPPROTO_IP and IPPROTO_UDP - UDP datagram sockets

Specifies a communication domain. It selects the protocol family which will be used for communication. Must be set to AF_INET6 (IPv6 network socket)

int32_t

[in]

type

The communication semantics It can be:

SOCK_STREAM - TCP stream socket type
SOCK_DGRAM - UDP datagram socket type
SOCK_RAW - Raw Socket type (ICMP)

int32_t

[in]

protocol

Specifies the particular protocol to be used. It can be:

IPPROTO_ICMP - Ping
IPPROTO_IP and IPPROTO_TCP - TCP stream sockets
IPPROTO_IP and IPPROTO_UDP - UDP datagram sockets

Returns

The socket's id on success, (-1) on failure.

close#

int32_t close (int32_t sockid)

Close a socket.

Parameters

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

Returns

0 on success, -1 on failure.

Close a socket and remove from the socket handler storage.

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

Returns

0 on success, -1 on failure.

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

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 descriptor.
const void *	[in]	buff	pointer to data buffer to send.
uint32_t	[in]	len	length of data buffer to send.
int32_t	[in]	flags	flags to select send options. Ignored in our implementation.

Returns

The number of bytes sent on success, -1 if an error occurred.

Preferred with connection-oriented sockets (TCP).

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 to a given address.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	sockid	socket descriptor.
const void *	[in]	buff	pointer to data buffer to send.
uint32_t	[in]	len	length of data buffer to send.
int32_t	[in]	flags	flags to select send options. Ignored in our implementation.
const struct sockaddr *	[in]	dest_addr	pointer to destination address buffer; Required for datagram sockets.
socklen_t	[in]	addr_len	length of destination address buffer.

Returns

The number of bytes sent on success, -1 if an error occurred.

Preferred in datagram mode (UDP).

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	descriptor of socket to receive the message from.
void *	[out]	buf	pointer to destination data buffer.
uint32_t	[in]	len	length of destination data buffer.
int32_t	[in]	flags	flags to select type of message reception. Ignored in our implementation.
struct sockaddr *	[in]	src_addr	pointer to a sockaddr structure in which the sending address is to be stored.
socklen_t *	[in]	addrlen	length of the supplied sockaddr structure.

Returns

The number of bytes received on success, -1 if an error occurred.

Receives data on a socket whether or not it is connection-oriented.

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	descriptor of socket to receive the message from.
void *	[out]	buf	pointer to destination data buffer.
uint32_t	[in]	len	length of destination data buffer.
int32_t	[in]	flags	flags to select type of message reception. Ignored in our implementation.

Returns

The number of bytes received on success, -1 if an error occurred.

Should be used for connection-oriented protocol (TCP)

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 descriptor
struct sockaddr *	[inout]	addr	A pointer to sockaddr structure filled in with the address of the peer (remote) socket. When addr is NULL, nothing is filled in; in this case, addrlen is not used, and should also be NULL.
socklen_t *	[inout]	addrlen	The caller must initialize it to contain the size (in bytes) of the structure pointed to by addr. On return it will contain the actual size of the peer address.

Returns

The socket id of the accepted socket on success, -1 if an error occurred.

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

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 descriptor.
const struct sockaddr *	[in]	addr	If the socket sockid is of type SOCK_DGRAM, 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	[in]	addrlen	length of the supplied sockaddr structure.

Returns

0 on connection or binding success, -1 if an error occurred.

Connects the socket referred to by the sockid to the address specified by address.

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

Returns

0 on success, -1 if an error occurred.

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.

setsockopt#

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

Set socket option designated by optname at a given protocol level to the value pointed by optval.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	sockid	socket ID
int32_t	[in]	level	protocol level at which the option resides. it could be: SOL_SOCKET IPPROTO_IPV6 SOL_APPLICATION
int32_t	[in]	optname	option name. it could be: for SOL_SOCKET level: SO_RCVBUF SO_SNDBUF SO_SNDLOWAT for IPPROTO_IPV6 level: IPV6_UNICAST_HOPS IPV6_MULTICAST_HOPS IPV6_JOIN_GROUP IPV6_LEAVE_GROUP SO_EDFE_MODE for SOL_APPLICATION: SO_EVENT_MODE SO_NONBLOCK
const void *	[in]	optval	Pointer to the socket option new value. The type of variable pointed by optval depends level and optname values.
socklen_t	[in]	optlen	Must be the size of the symbol pointed by optval.

Returns

0 on success, -1 if an error occurred.

This function can set socket properties.

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 descriptor.
int32_t	[in]	level	socket protocol level.
int32_t	[in]	optname	Option name. Supported options: for SOL_SOCKET level: SO_RCVBUF SO_SNDBUF SO_SNDLOWAT for IPPROTO_IPV6 level: IPV6_UNICAST_HOPS IPV6_MULTICAST_HOPS
void *	[out]	optval	option value structure pointer.
socklen_t *	[in]	optlen	size of the option value structure.

Returns

0 on success, -1 if an error occurred.

The function gets socket option by optname, and copies option data to optval ptr.

htonl#

__STATIC_INLINE uint32_t htonl (uint32_t hostlong)

Convert the long host byte order to network order.

Parameters

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

Returns

Long network integer

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

htons#

__STATIC_INLINE uint16_t htons (uint16_t hostshort)

Convert the short host byte order to network order.

Parameters

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

Returns

Short network integer

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

ntohl#

__STATIC_INLINE uint32_t ntohl (uint32_t netlong)

Convert the long network byte order to host byte order.

Parameters

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

Returns

Long host integer

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

ntohs#

__STATIC_INLINE uint16_t ntohs (uint16_t netshort)

Convert the short network byte order to host byte order.

Parameters

Type	Direction	Argument Name	Description
uint16_t	[in]	netshort

Returns

Short host integer

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

inet_pton#

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

Convert the IPv4 and IPv6 addresses from text to binary form.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	af	The address family. Only AF_INET6 is supported by our implementation.
const char *	[in]	src	Source string
void *	[out]	dst	Destination address pointer

Returns

1 on succes, -1 if an error occurred. (POSIX described the 0 value too)

This function converts the character string src into a network address structure in the af address family, then copies the network address structure to dst. AF_INET (IPv4) case not supported.

inet_ntop#

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

Convert IPv6 addresses from binary to text form.

Parameters

Type	Direction	Argument Name	Description
int32_t	[in]	af	- Address family. Only AF_INET6 is supported
const void *	[in]	src	Source address in byte form
char *	[out]	dst	Destination buffer ptr
socklen_t	[in]	size	Size of the destination buffer.

Returns

It returns a non-null pointer to dst. NULL if an error occurred.

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. AF_INET (IPv4) case not supported.