Network

Data streams over TCP or UDP, to IPv4 and/or IPv6 peers - net_open() connects out to a remote host, net_listener_init() accepts incoming connections or datagrams. More...

Collaboration diagram for Network:

Modules
	MQTT
	A client for MQTT brokers.
	NTP
	NTP (Network Time Protocol) is how a device gets the current wall-clock time from a server over the network, rather than relying on a battery-backed RTC it may not have.

Data Structures
struct	net_addr_t
	An IPv4 or IPv6 address. More...

Macros
#define	NET_LISTENER_CAPACITY   4
	Maximum number of listeners open at once (see net_listener_init()).

Typedefs
typedef struct net_listener_t	net_listener_t
	Opaque listening socket, from net_listener_init().
typedef void(*	net_accept_callback_t) (net_listener_t *listener, sys_iostream_t *conn, const net_addr_t *remote, uint16_t remote_port, void *userdata)
	Called for each accepted TCP connection or received UDP datagram on a listener. More...

Enumerations
enum	net_proto_t { net_proto_tcp, net_proto_udp }
	Transport protocol for a socket. More...
enum	net_addr_family_t { net_addr_family_v4, net_addr_family_v6 }
	Address family for a net_addr_t. More...

Addresses
net_addr_t	net_addr_v4 (uint8_t a, uint8_t b, uint8_t c, uint8_t d)
	Build an IPv4 address from four octets.
net_addr_t	net_addr_v4_any (void)
	The IPv4 "any" address (0.0.0.0), for binding to all interfaces.
net_addr_t	net_addr_v6 (const uint8_t bytes[16])
	Build an IPv6 address from sixteen bytes. More...
net_addr_t	net_addr_v6_any (void)
	The IPv6 "any" address (::), for binding to all interfaces.
size_t	net_addr_to_string (const net_addr_t *addr, char *buf, size_t buf_size)
	Format an address as a human-readable string. More...

Lifecycle
sys_iostream_t *	net_open (net_proto_t proto, const net_addr_t *addr, uint16_t port, uint32_t timeout_ms)
	Open a connection to a remote host. More...
net_listener_t *	net_listener_init (net_proto_t proto, const net_addr_t *addr, uint16_t port, net_accept_callback_t callback, void *userdata)
	Start listening for incoming connections or datagrams. More...
void	net_listener_deinit (net_listener_t *listener)
	Stop listening and release a listener. More...
#define	NET_OPEN_DEFAULT_TIMEOUT_MS   (30 * 1000)
	Default connection timeout used by net_open() when its own timeout_ms is 0.

Polling
bool	net_poll (void)
	Service every network subsystem that needs periodic attention. More...

Detailed Description

Data streams over TCP or UDP, to IPv4 and/or IPv6 peers - net_open() connects out to a remote host, net_listener_init() accepts incoming connections or datagrams.

Every socket, in either direction, is a plain sys_iostream_t (System): reading, writing, closing, and readiness notification all go through the same generic sys_iostream_read()/_write()/_close()/_set_callback() API every other stream in picofuse uses, not socket-specific calls.

Connecting out to a remote host:

net_addr_t addr = net_addr_v4(93, 184, 215, 14); // example.com
sys_iostream_t *conn = net_open(net_proto_tcp, &addr, 80, 0);
if (conn != NULL) {
  const char *req = "GET / HTTP/1.0\r\n\r\n";
  sys_iostream_write(conn, req, strlen(req));
  char buf[512];
  size_t n = sys_iostream_read(conn, buf, sizeof(buf));
  // ... use buf/n ...
  sys_iostream_close(conn);
}

Accepting incoming connections - net_listener_init() returns immediately, and callback fires from then on for as long as the listener stays open (once per accepted connection for net_proto_tcp, once per received datagram for net_proto_udp - see net_listener_init()'s own doc):

static void on_accept(net_listener_t *listener, sys_iostream_t *conn,
                      const net_addr_t *remote, uint16_t remote_port,
                      void *userdata) {
  char buf[512];
  size_t n = sys_iostream_read(conn, buf, sizeof(buf));
  sys_iostream_write(conn, buf, n); // echo back
  sys_iostream_close(conn);
}

net_addr_t any = net_addr_v4_any();
net_listener_t *echo =
    net_listener_init(net_proto_tcp, &any, 7, on_accept, NULL);

Typedef Documentation

net_accept_callback_t

typedef void(* net_accept_callback_t) (net_listener_t *listener, sys_iostream_t *conn, const net_addr_t *remote, uint16_t remote_port, void *userdata)

Called for each accepted TCP connection or received UDP datagram on a listener.

Parameters

listener	The listener this arrived on.
conn	Stream to read/write. Caller-owned - close with sys_iostream_close() when done with it; net_listener_deinit() on listener does not affect streams already handed out this way. For net_proto_udp this is good for exactly one read and, if replying, one write - see net.h's own doc for why.
remote	Address of the remote peer.
remote_port	Port of the remote peer.
userdata	Opaque pointer, as passed to net_listener_init().

Definition at line 76 of file types.h.

Enumeration Type Documentation

net_addr_family_t

enum net_addr_family_t

Address family for a net_addr_t.

Enumerator
net_addr_family_v4	IPv4 - net_addr_t.addr.v4 is valid.
net_addr_family_v6	IPv6 - net_addr_t.addr.v6 is valid.

Definition at line 39 of file types.h.

             {
  net_addr_family_v4, 
  net_addr_family_v6, 
} net_addr_family_t;

net_proto_t

enum net_proto_t

Transport protocol for a socket.

Enumerator
net_proto_tcp	Connection-oriented, reliable, ordered byte stream.
net_proto_udp	Connectionless, unreliable datagrams.

Definition at line 30 of file types.h.

             {
  net_proto_tcp, 
  net_proto_udp, 
} net_proto_t;

Function Documentation

net_addr_to_string()

size_t net_addr_to_string	(	const net_addr_t *	addr,
		char *	buf,
		size_t	buf_size
	)

Format an address as a human-readable string.

Parameters

addr	Address to format.
buf	Destination buffer.
buf_size	Size of buf in bytes.

Returns

Number of characters that would have been written to buf, not counting the null terminator, same truncation semantics as sys_sprintf().

net_addr_v6()

net_addr_t net_addr_v6

(

const uint8_t

bytes[16]

)

Build an IPv6 address from sixteen bytes.

Parameters

bytes

Address bytes, network byte order. Must point to at least 16 bytes.

net_listener_deinit()

void net_listener_deinit

(

net_listener_t *

listener

)

Stop listening and release a listener.

Parameters

listener

The listener to close, or NULL (a no-op). Streams already handed to callback are unaffected - see its own doc.

net_listener_init()

net_listener_t* net_listener_init	(	net_proto_t	proto,
		const net_addr_t *	addr,
		uint16_t	port,
		net_accept_callback_t	callback,
		void *	userdata
	)

Start listening for incoming connections or datagrams.

Parameters

proto	Transport protocol.
addr	Local address to bind to (see net_addr_v4_any()/ net_addr_v6_any() to bind to all interfaces).
port	Local port to bind to.
callback	Called for each accepted connection or received datagram (see net_proto_t), for as long as the listener stays open.
userdata	Opaque pointer passed through to callback.

Returns

A listener handle, or NULL on failure (for example, the port is already in use, or NET_LISTENER_CAPACITY listeners are already open).

net_open()

sys_iostream_t* net_open	(	net_proto_t	proto,
		const net_addr_t *	addr,
		uint16_t	port,
		uint32_t	timeout_ms
	)

Open a connection to a remote host.

Parameters

proto	Transport protocol.
addr	Remote address to connect to.
port	Remote port to connect to.
timeout_ms	How long to wait for the connection to establish, or 0 to default to NET_OPEN_DEFAULT_TIMEOUT_MS. Not consulted for net_proto_udp - "connecting" a UDP socket just records a default peer locally, with no handshake to wait for.

Returns

An open stream, or NULL on failure (connection refused, timed out, or no route). Blocks until connected or the attempt fails.

For net_proto_udp this "connects" the socket to a single remote address: every subsequent sys_iostream_write() sends to it, and sys_iostream_read() only ever returns datagrams from it. Use net_listener_init() instead for a UDP socket that receives from arbitrary, not-yet-known peers.

net_poll()

bool net_poll

(

void

)

Service every network subsystem that needs periodic attention.

Returns

true if anything was actually serviced this call.

Call this regularly from the application's own main loop, alongside pix_poll()/HID polling - one call point for the whole network module, rather than a separate poll per subsystem. Currently drives the active MQTT connection, if any (see net_mqtt_init()) - including actually sending whatever net_mqtt_publish() has staged (see its own doc on why sending happens here rather than synchronously in that call). net_mqtt_t and friends have no public poll of their own; net_open()/ net_listener_init() need none, being callback-driven already (see this file's own doc).