BSD Socket interface

Nordic socket interface for IoT. More...

Data Structures
struct	sockaddr
	Generic socket address. More...
struct	in6_addr
	IPv6 address. More...
struct	sockaddr_in6
	Address record for IPv6 addresses. More...

Macros
#define	htons(x)   HTONS(x)
#define	FD_ZERO(set)   (*(set) = 0)
#define	FD_SET(fd, set)   (*(set) |= (1u << (fd)))
#define	FD_CLR(fd, set)   (*(set) &= ~(1u << (fd)))
#define	FD_ISSET(fd, set)   (*(set) & (1u << (fd)))
#define	FD_SETSIZE   sizeof(fd_set)
#define	AF_INET6   2
#define	AF_BLUETOOTH   3
#define	SOCK_STREAM   1
#define	SOCK_DGRAM   2
#define	IPPROTO_TCP   1
#define	IPPROTO_UDP   2
#define	MSG_DONTROUTE   0x01
	Socket send/recv flags.
#define	MSG_DONTWAIT   0x02
#define	MSG_OOB   0x04
#define	MSG_PEEK   0x08
#define	MSG_WAITALL   0x10
#define	F_SETFL   1
#define	O_NONBLOCK   0x01

Typedefs
typedef uint32_t	socklen_t
typedef int32_t	ssize_t
typedef uint32_t	fd_set
	API for filedescriptor set. More...
typedef uint16_t	in_port_t
typedef int	socket_family_t
	Socket families.
typedef socket_family_t	sa_family_t
typedef int	socket_type_t
	Socket types.
typedef int	socket_protocol_t
	Socket protocols. More...
typedef struct sockaddr	sockaddr_t
typedef struct sockaddr_in6	sockaddr_in6_t
typedef struct in6_addr	in6_addr_t

Enumerations
enum	socket_opt_lvl_t {   SOL_SOCKET = 1,   NRF_BLE = 2,   NRF_CRYPTO = 3,   NRF_RF = 4 }
	Socket option levels. More...

Functions
int	socket (socket_family_t family, socket_type_t type, socket_protocol_t protocol)
	Create a socket. More...
int	close (int sock)
	Close a socket and free any resources held by it. More...
int	fcntl (int fd, int cmd, int flags)
	Control file descriptor options. More...
int	connect (int sock, const void *p_servaddr, socklen_t addrlen)
	Connect to an endpoint with a given address. More...
ssize_t	send (int sock, const void *p_buff, size_t nbytes, int flags)
	Send data through a socket. More...
ssize_t	write (int sock, const void *p_buff, size_t nbytes)
	Write data to a socket. See send() for details.
ssize_t	recv (int sock, void *p_buff, size_t nbytes, int flags)
	Receive data on a socket. More...
ssize_t	read (int sock, void *p_buff, size_t nbytes)
	Read data from a socket. See recv() for details.
int	select (int nfds, fd_set *p_readset, fd_set *p_writeset, fd_set *p_exceptset, const struct timeval *timeout)
	Wait for read, write or exception events on a socket. More...
int	setsockopt (int sock, socket_opt_lvl_t level, int optname, const void *optval, socklen_t optlen)
	Set socket options for a given socket. More...
int	getsockopt (int sock, socket_opt_lvl_t level, int optname, void *optval, socklen_t *optlen)
	Get socket options for a given socket. More...
int	bind (int sock, const void *p_myaddr, socklen_t addrlen)
	Bind a socket to an address and prot. More...
int	listen (int sock, int backlog)
	Mark a socket as listenable. More...
int	accept (int sock, void *p_cliaddr, socklen_t *p_addrlen)
	Wait for next client to connect. More...
int	inet_pton (socket_family_t af, const char *src, void *dst)
	Convert human readable ip address to a form usable by the socket api. More...

Detailed Description

Nordic socket interface for IoT.

This module provides the socket interface for writing IoT applications. The API is designed to be compatible with the POSIX/BSD socket interface for the purpose of making porting easy. The socket options API has been extended to support configuring Nordic BLE stack, tuning of RF parameters as well as security options.

Macro Definition Documentation

#define AF_BLUETOOTH   3

Bluetooth Low Energy socket family.

#define AF_INET6   2

IPv6 socket family.

#define FD_CLR	(		fd,
			set
	)		(*(set) &= ~(1u << (fd)))

Clear a bit in the set.

#define FD_ISSET	(		fd,
			set
	)		(*(set) & (1u << (fd)))

Check if a bit in the set is set.

#define FD_SET	(		fd,
			set
	)		(*(set) |= (1u << (fd)))

Set a bit in the set.

#define FD_SETSIZE   sizeof(fd_set)

The max size of a set.

#define FD_ZERO

(

set

)

(*(set) = 0)

Clear entire set.

#define IPPROTO_TCP   1

Use TCP as transport protocol.

#define IPPROTO_UDP   2

Use UDP as transport protocol.

#define SOCK_DGRAM   2

UDP socket type.

#define SOCK_STREAM   1

TCP socket type.

Typedef Documentation

typedef uint32_t fd_set

API for filedescriptor set.

File descriptor sets are used as input to the select() function for doing I/O multiplexing. The max number of descriptors contained in a set is defined by FD_SETSIZE.

typedef int socket_protocol_t

Socket protocols.

Using 0 should be sufficient for most users. Other values are only provided for socket API compatibility.

Enumeration Type Documentation

enum socket_opt_lvl_t

Socket option levels.

Enumerator
SOL_SOCKET	Standard socket options.
NRF_BLE	Nordic BLE socket options. Use this to control BLE paramters.
NRF_CRYPTO	Nordic crypto socket options. Use this to enable TLS/DTLS.
NRF_RF	Nordic radio socket options. Use this to control radio behavior.

Function Documentation

int accept	(	int	sock,
		void *	p_cliaddr,
		socklen_t *	p_addrlen
	)

Wait for next client to connect.

This function will block if there are no clients attempting to connect.

Parameters

[in]	sock	The socket descriptor to use for waiting on client connections.
[out]	p_cliaddr	Socket address that will be set to the clients address.
[out]	p_addrlen	The size of the p_cliaddr passed. Might be modified by the function.

Return values

A	non-negative client desciptor on success, or -1 on error.

int bind	(	int	sock,
		const void *	p_myaddr,
		socklen_t	addrlen
	)

Bind a socket to an address and prot.

The provided address must be supported by the socket protocol family.

Parameters

[in]	sock	The socket descriptor to bind.
[in]	p_myaddr	The address to bind this socket to.
[in]	addrlen	The size of p_myaddr.

Return values

0	on success, or -1 on error.

int close

(

int

sock

)

Close a socket and free any resources held by it.

If the socket is already closed, this function is a noop.

Parameters

[in]

sock

The socket to close.

Return values

0	on success, or -1 on error.

int connect	(	int	sock,
		const void *	p_servaddr,
		socklen_t	addrlen
	)

Connect to an endpoint with a given address.

The socket handle must be a valid handle that has not already been connected. Running connect on an connected handle will return error.

Parameters

[in]	sock	The socket to use for connection.
[in]	p_servaddr	The address of the server to connect to. Currently, only sockaddr_in6 is the only supported type.
[in]	addrlen	The size of the p_servaddr argument.

Return values

0	on success, or -1 on error.

int fcntl	(	int	fd,
		int	cmd,
		int	flags
	)

Control file descriptor options.

Set or get file descriptor options or flags. Only supports command F_SETFL and arg O_NONBLOCK.

Parameters

[in]	fd	The descriptor to set options on.
[in]	cmd	The command class for options.
[in]	flags	The flags to set.

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

Get socket options for a given socket.

The options are grouped by level, and the option value is the value described by the option name.

Parameters

[in]	sock	The socket for which to set option.
[in]	level	The level, or group to which the option belongs.
[in]	optname	The name of the socket option.
[out]	optval	Pointer to the storage for the option value.
[in,out]	optlen	The size of optval. Can be modified to the actual size of optval.

Return values

0	on success, or -1 on error.

int inet_pton	(	socket_family_t	af,
		const char *	src,
		void *	dst
	)

Convert human readable ip address to a form usable by the socket api.

This function will convert a string form of addresses and encode it into a byte array.

Parameters

[in]	af	Address family. Only AF_INET6 supported.
[in]	src	Null-terminated string containing the address to convert.
[out]	dst	Pointer to a struct in6_addr where address will be stored.

Return values

1	on success, 0 if src does not contain a valid address, -1 if af is not a valid address family.

int listen	(	int	sock,
		int	backlog
	)

Mark a socket as listenable.

Once a socket is marked as listenable, it cannot be unmarked. It is important to consider the backlog paramter, as it will affect how much memory your application will use in the worst case.

Parameters

[in]	sock	The socket descriptor on which to set listening options.
[in]	backlog	The max length of the queue of pending connections. A value of 0 means infinite.

Return values

0	on success, or -1 on error.

ssize_t recv	(	int	sock,
		void *	p_buff,
		size_t	nbytes,
		int	flags
	)

Receive data on a socket.

API for receiving data from a socket. By default, this function will block, UNLESS O_NONBLOCK socket option has been set, or MSG_DONTWAIT is passed as a flag.

Parameters

[in]	sock	The socket to receive data from.
[out]	p_buff	Buffer to hold data to be read.
[in]	nbytes	Number of bytes to read. Should NOT BE larger than the size of p_buff.
[in]	flags	Flags to control send behavior.

Return values

The	amount of bytes that was read, or -1 on error.

int select	(	int	nfds,
		fd_set *	p_readset,
		fd_set *	p_writeset,
		fd_set *	p_exceptset,
		const struct timeval *	timeout
	)

Wait for read, write or exception events on a socket.

Wait for a set of socket descriptors to be ready for reading, writing or having exceptions. The set of socket descriptors are configured before calling this function. This function will block until any of the descriptors in the set has any of the required events. This function is mostly useful when using O_NONBLOCK or MSG_DONTWAIT options to enable async operation.

Parameters

[in]	nfds	The highest socket descriptor value contained in the sets.
[in,out]	p_readset	The set of descriptors for which to wait for read events. Set to NULL if not used.
[in,out]	p_writeset	The set of descriptors for which to wait for write events. Set to NULL if not used.
[in,out]	p_exceptset	The set of descriptors for which to wait for exception events. Set to NULL if not used.
[in]	timeout	The timeout to use for select call. Set to NULL if waiting forever.

Return values

The	number of ready descriptors contained in the descriptor sets, or -1 on error.

ssize_t send	(	int	sock,
		const void *	p_buff,
		size_t	nbytes,
		int	flags
	)

Send data through a socket.

By default, this function will block, UNLESS O_NONBLOCK socket option has been set, OR MSG_DONTWAIT is passed as a flag. In that case, the method will return immediately.

Parameters

[in]	sock	The socket to write data to.
[in]	p_buff	Buffer containing data to send.
[in]	nbytes	Size of data contained on p_buff.
[in]	flags	Flags to control send behavior.

Return values

The	amount of bytes that was sent on success, or -1 on error.

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

Set socket options for a given socket.

The options are grouped by level, and the option value should be the expected for the given option, and the lifetime must be longer than that of the socket.

Parameters

[in]	sock	The socket for which to set option.
[in]	level	The level, or group to which the option belongs.
[in]	optname	The name of the socket option.
[in]	optval	The value to be stored for this option.
[in]	optlen	The size of optval.

Return values

0	on success, or -1 on error.

int socket	(	socket_family_t	family,
		socket_type_t	type,
		socket_protocol_t	protocol
	)

Create a socket.

API to create a socket that can be used for network communication independently of lower protocol layers.

Parameters

[in]	family	The protocol family of the network protocol to use. Currently only AF_INET6 is supported.
[in]	type	The protocol type to use for this socket.
[in]	protocol	The transport protocol to use for this socket.

Return values

A	non-negative socket descriptor if successful if OK, or -1 on error.