Socket API#

CMSG_ALIGN#

#define CMSG_ALIGN

(len)

Returns the length of the data with the required alignment.

Returns

• The aligned length of the data, rounded up to the nearest multiple of uint32_t

CMSG_SPACE#

#define CMSG_SPACE

(len)

Returns the number of bytes an ancillary element with payload of the passed data length occupies.

Returns

• The size of the control message structure plus the aligned data length

CMSG_LEN#

#define CMSG_LEN

(len)

Returns the value to store in the cmsg_len member of the cmsghdr structure.

Returns

• The size of the control message structure plus the data length

CMSG_FIRSTHDR#

#define CMSG_FIRSTHDR

Returns a pointer to the first control message header in the given msghdr structure.

Returns

• A pointer to the first cmsghdr structure, or NULL if the buffer is empty or invalid

CMSG_NXTHDR#

#define CMSG_NXTHDR

(mhdr, cmsg)

Returns a pointer to the next control message header in the ancillary data buffer.

Returns

• A pointer to the next cmsghdr structure, or NULL if there is no more space left in the buffer

CMSG_DATA#

#define CMSG_DATA

(cmsg)

Returns a pointer to the data portion of a cmsghdr.

Returns

• A pointer to the data following the cmsghdr, casted to uint8_t *

MSG_TRUNC#

#define MSG_TRUNC

0x0001

Normal data truncated, to be used as msg_flags field in the msghdr structure.

MSG_CTRUNC#

#define MSG_CTRUNC

0x0002

Control data truncated, to be used as msg_flags field in the msghdr structure.

MSG_PEEK#

#define MSG_PEEK

0x0004

Leave received data in queue, to be used as the flags parameter.

SOL_SOCKET#

#define SOL_SOCKET

0

Socket option level.

SOL_APPLICATION#

#define SOL_APPLICATION

1

Application socket option level.

IPPROTO_IPV6#

#define IPPROTO_IPV6

41

IPV6 socket option level.

SO_EVENT_MODE#

#define SO_EVENT_MODE

10

Specify event mode of a socket. When set, optval must point to an uint32_t.

Possible values are:

• SL_WISUN_SOCKET_EVENT_MODE_INDICATION: received data is included in SL_WISUN_MSG_SOCKET_DATA_IND_ID indication

• SL_WISUN_SOCKET_EVENT_MODE_POLLING: only the amount of received data is included SL_WISUN_MSG_SOCKET_DATA_AVAILABLE_IND_ID indication. recv() or recvfrom() shouldbe invoked after indication reception to retrieve data

SOCKET_EVENT_MODE#

#define SOCKET_EVENT_MODE

SO_EVENT_MODE

Specify event mode of a socket. When set, optval must point to an uint32_t.

Possible values are:

• SL_WISUN_SOCKET_EVENT_MODE_INDICATION: received data is included in SL_WISUN_MSG_SOCKET_DATA_IND_ID indication

• SL_WISUN_SOCKET_EVENT_MODE_POLLING: only the amount of received data is included SL_WISUN_MSG_SOCKET_DATA_AVAILABLE_IND_ID indication. recv() or recvfrom() shouldbe invoked after indication reception to retrieve data

SO_NONBLOCK#

#define SO_NONBLOCK

11

Enable/disable nonblocking mode.

This option takes an uint32_t value.

Possible values are:

• (1) enables nonblocking mode

• (0) disables nonblocking mode

SO_RCVBUF#

#define SO_RCVBUF

1

Specify receive buffer size in payload bytes. When set, optval must point to an int32_t.

0 means unread data are dropped, unless read in data callback.

SO_SNDBUF#

#define SO_SNDBUF

2

Specify send buffer size in payload bytes.

When set, optval must point to an int32_t.

Used only for stream sockets.

SO_SNDLOWAT#

#define SO_SNDLOWAT

4

Specify send low water mark in payload bytes.

When set, optval must point to an int32_t.

SO_WRITABLE#

#define SO_WRITABLE

5

Non-standard POSIX option SO_WRITABLE.

This option returns a non-zero value (amount of free space in bytes) if the socket is writable.

A socket is considered writable if: The number of bytes of available space in the socket send buffer is greater than or equal the current size of the send low-water mark and either: The socket is connected (TCP). The socket does not require a connection (e.g., UDP).

Returns

• Non-zero value (amount of free space in bytes) if the socket is readable, 0 otherwise.

SO_READABLE#

#define SO_READABLE

6

Non-standard POSIX option SO_READABLE.

This option returns a non-zero value (amount of available bytes) if the socket is readable. A socket is considered readable under the following conditions:

The number of bytes of data in the socket receive buffer is greater than or equal to the current size of the recv low-water mark. The default is 1 for TCP and UDP. The read half of the connection is closed (i.e., a TCP connection that has received a FIN). The socket is a listening socket and the number of completed connections is nonzero.

Returns

• Non-zero value (amount of data in bytes) if the socket is readable, 0 otherwise.

DSCP_DEFAULT#

#define DSCP_DEFAULT

0

Standard priority and it is socket default.

DSCP_AF11#

#define DSCP_AF11

10

Application high priority service: Stack priorities these messages over the default priority messages.

DSCP_EF#

#define DSCP_EF

46

Expedited Forwarding (EF) QoS level enable high priority state: low loss, low delay, and low jitter services.

IPV6_TCLASS#

#define IPV6_TCLASS

1

IPv6 header has a field traffic class that contains a 6-bit Differentiated Services Code Point (DSCP) field that is used for packet classification.

By default the packet class level is set to 0 DSCP_DEFAULT. Specify traffic class for outgoing packets, as int; valid values:

IPV6_UNICAST_HOPS#

#define IPV6_UNICAST_HOPS

2

Set the unicast hop limit for the socket, as int.

Valid values 0 and 255, -1 for using the route default.

IPV6_MULTICAST_HOPS#

#define IPV6_MULTICAST_HOPS

3

Set the multicast hop limit for the socket, as int.

Valid values 0 and 255, -1 for using the route default.

IPV6_USE_MIN_MTU#

#define IPV6_USE_MIN_MTU

5

Specify PMTU preference, as int; Valid values -1 (PMTUD for unicast, default), 0 (PMTUD always), 1 (PMTUD off).

IPV6_HOPLIMIT#

#define IPV6_HOPLIMIT

8

Ancillary data option on sendmsg()/recvmsg(), value to be used for single ongoing packet, as int; Valid values 0-255, -1 for default.

IPV6_RECVHOPLIMIT#

#define IPV6_RECVHOPLIMIT

11

Ancillary data option on recvmsg(), specifies hop-limit for the single received ongoing packet, as int; A nonzero value enables the option; a value of 0 disables the option.

IPV6_MULTICAST_LOOP#

#define IPV6_MULTICAST_LOOP

14

Specify whether outgoing multicast packets are looped back, as int.

A nonzero value enables the option; a value of 0 disables the option.

IPV6_ADD_MEMBERSHIP#

#define IPV6_ADD_MEMBERSHIP

15

Join a multicast group.

Only valid for SOCK_DGRAM or SOCK_RAW sockets. When set, optval is a pointer to a struct ipv6_mreq.

IPV6_JOIN_GROUP#

#define IPV6_JOIN_GROUP

IPV6_ADD_MEMBERSHIP

IPv6 header has a field traffic class that contains a 6-bit Differentiated Services Code Point (DSCP) field that is used for packet classification.

By default the packet class level is set to 0 DSCP_DEFAULT. Specify traffic class for outgoing packets, as int; valid values:

IPV6_DROP_MEMBERSHIP#

#define IPV6_DROP_MEMBERSHIP

16

Leave a multicast group.

Only valid for SOCK_DGRAM or SOCK_RAW sockets. When set, optval is a pointer to a struct ipv6_mreq.

IPV6_LEAVE_GROUP#

#define IPV6_LEAVE_GROUP

IPV6_DROP_MEMBERSHIP

IPv6 header has a field traffic class that contains a 6-bit Differentiated Services Code Point (DSCP) field that is used for packet classification.

By default the packet class level is set to 0 DSCP_DEFAULT. Specify traffic class for outgoing packets, as int; valid values:

IPV6_PKTINFO#

#define IPV6_PKTINFO

9

Specify control messages packet info for recvmsg() as struct in6_pktinfo.

IPV6_RECVPKTINFO#

#define IPV6_RECVPKTINFO

10

Set delivery of the IPV6_PKTINFO control message on incoming datagrams, as int.

Such control messages contain a struct in6_pktinfo, as per RFC 3542. Allowed only for SOCK_DGRAM or SOCK_RAW sockets.

IPV6_RECVTCLASS#

#define IPV6_RECVTCLASS

12

Enables the application to receive the value of the traffic class field from the IPv6 header, as int; A nonzero value enables the option; a value of 0 disables the option.

IPV6_DONTFRAG#

#define IPV6_DONTFRAG

6

Specify not to fragment datagrams, as int; For Wi-SUN, direct neighbors can receive frames up to 1504 bytes, while the other nodes can receive frames up to 1280 bytes.

0 (fragment to path MTU). 1 (no fragmentation, TX fails if bigger than PMTU).

SO_EDFE_MODE#

#define SO_EDFE_MODE

0xfb

Experimental: Enable Extended Directed Frame Exchange mode.

When set, optval must point to an uint32_t.

SOCKET_EDFE_MODE#

#define SOCKET_EDFE_MODE

SO_EDFE_MODE

IPv6 header has a field traffic class that contains a 6-bit Differentiated Services Code Point (DSCP) field that is used for packet classification.

By default the packet class level is set to 0 DSCP_DEFAULT. Specify traffic class for outgoing packets, as int; valid values:

sl_wisun_socket_event_mode_t#

sl_wisun_socket_event_mode_t

Enumerations for socket event mode.

socket_domain#

socket_domain

Supported address families.

socket_protocol#

socket_protocol

IP protocols.

socket_type#

socket_type

Socket types.

cmsghdr_t#

typedef struct cmsghdr cmsghdr_t

Control messages.

in6_addr_t#

typedef struct in6_addr in6_addr_t

IPv6 Internet address.

in6_pktinfo_t#

typedef struct in6_pktinfo in6_pktinfo_t

Structure to store the IPv6 packet information.

iovec_t#

typedef struct iovec iovec_t

Structure to store scatter/gather array elements.

ip6_mtuinfo_t#

typedef struct ip6_mtuinfo ip6_mtuinfo_t

Structure to store the IPv6 MTU (Maximum Transmission Unit) information.

ipv6_mreq_t#

typedef struct ipv6_mreq ipv6_mreq_t

Structure to specify the multicast group and the interface.

msghdr_t#

typedef struct msghdr msghdr_t

The msghdr structure is used by the recvmsg() and sendmsg() functions.

sa_family_t#

typedef uint32_t sa_family_t

Address family.

sl_socket_domain_t#

typedef enum socket_domain sl_socket_domain_t

Supported address families.

sl_socket_protocol_t#

typedef enum socket_protocol sl_socket_protocol_t

IP protocols.

sl_socket_type_t#

typedef enum socket_type sl_socket_type_t

Socket types.

sl_wisun_socket_id_t#

typedef int sl_wisun_socket_id_t

Socket id.

sockaddr_in6_t#

typedef struct sockaddr_in6 sockaddr_in6_t

IPv6 address format.

socklen_t#

typedef uint32_t socklen_t

Socket address length type definition.

in6addr_any#

const in6_addr_t in6addr_any

IPv6 wildcard address.

accept#

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

Accept a connection on a socket.

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.

bind#

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

Bind a name to a socket.

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.

close#

int close (int sockid)

Close a socket.

Returns

• 0 on success, -1 on failure.

Close a socket and remove from the socket handler storage.

connect#

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

Initiate a connection on a socket.

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.

getpeername#

int getpeername (int socket, struct sockaddr *restrict address, socklen_t *restrict address_len)

Get the address of the peer connected to the socket.

This function retrieves the address of the peer connected to the specified socket. The peer's address is stored in the provided 'address' structure, and the length of the address is stored in 'address_len'.

Returns

• 0 on success, -1 on failure and sets errno appropriately.

getsockname#

int getsockname (int socket, struct sockaddr *restrict address, socklen_t *restrict address_len)

Retrieves the local address of a socket.

Returns

• On success, returns zero. On failure, returns -1 and sets errno appropriately.

This function retrieves the local address associated with a socket. It populates the provided address structure with the local address information.

getsockopt#

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

Get socket option.

Returns

• 0 on success, -1 if an error occurred.

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

listen#

int listen (int sockid, int backlog)

Listen for connections on a socket.

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.

recv#

ssize_t recv (int sockid, void * buf, size_t len, int flags)

Receive a message from a socket.

Returns

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

Should be used for connection-oriented protocol (TCP)

recvfrom#

ssize_t recvfrom (int sockid, void * buf, size_t len, int flags, struct sockaddr * src_addr, socklen_t * addrlen)

Receive messages from a socket.

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.

recvmsg#

ssize_t recvmsg (int socket, struct msghdr * message, int flags)

Receive a message from a socket.

Returns

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

This function is typically used with connectionless-mode sockets because it permits the application to retrieve the source address of received data.

send#

ssize_t send (int sockid, const void * buff, size_t len, int flags)

Send a message on a socket.

Returns

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

Preferred with connection-oriented sockets (TCP).

sendmsg#

ssize_t sendmsg (int socket, const struct msghdr * message, int flags)

Send a message through a connection-mode or connectionless-mode socket.

Returns

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

sendto#

ssize_t sendto (int sockid, const void * buff, size_t len, int flags, const struct sockaddr * dest_addr, socklen_t addr_len)

Send a message to a given address.

Returns

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

Preferred in datagram mode (UDP).

setsockopt#

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

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

Returns

• 0 on success, -1 if an error occurred.

This function can set socket properties.

socket#

int socket (int domain, int type, int protocol)

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

Returns

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

APP_LEVEL_SOCKET#

#define APP_LEVEL_SOCKET

SOL_APPLICATION

For backward compatibility.

IPV6_ADDR_SIZE#

#define IPV6_ADDR_SIZE

16

Size of an IPv6 address.

IPV6_PREFIX_SIZE#

#define IPV6_PREFIX_SIZE

8

Size of 64 bit IPv6 prefix byte array.

SOCK_NONBLOCK#

#define SOCK_NONBLOCK

0X00010000

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