lwip.h

lwip.h is the root-level application header. It exposes stack lifecycle, socket creation, socket I/O, service requests, event callbacks, and memory accounting.

Defines

LWIP_HDR_LWIP_APP_H

LWIP_SOCKET_EVENTF_ERROR

LWIP_SOCKET_EVENTF_STATE_CHANGE

LWIP_SOCKET_EVENTF_IO

LWIP_SOCKET_EVENTF_ALL

LWIP_SOCKET_SVC_DHCP: Service wait flags.

LWIP_SOCKET_SVC_SNTP

LWIP_SOCKET_SVC_DNS

LWIP_SOCKET_SERVICES_TIMEOUT_MS: Timing constants.

LWIP_SOCKET_RX_RING_INIT_SIZE

LWIP_SOCKET_RX_RING_STEP_SIZE

LWIP_SOCKET_RX_RING_MAX_SIZE

lwip_init_runtime()

Typedefs

typedef void (*lwip_socket_event_cb)(struct lwip_socket *sock, lwip_socket_event_type_t type, const void *ev_data, void *arg)

Single typed event callback.

sock — the socket that generated the event. type — LWIP_SOCKET_EV_ERROR / STATE_CHANGE / IO. ev_data — typed payload (cast to the matching _data_t* for the event type). Valid only for the duration of the callback. arg — user pointer supplied to lwip_socket_on_event().

typedef void (*lwip_netif_service_cb)(struct netif *netif, void *arg, uint8_t service_id, lwip_netif_service_status_t status)

Enums

enum lwip_error_t

API result codes.

Values:

enumerator LWIP_OK

enumerator LWIP_ERR_ARG: NULL / out-of-range argument.

enumerator LWIP_ERR_STATE: called in wrong lifecycle state

enumerator LWIP_ERR_MEM: allocation failed

enumerator LWIP_ERR_NETIF: no netif available / not up

enumerator LWIP_ERR_DNS: DNS resolution failed / unavailable.

enumerator LWIP_ERR_CONNECT: connect() failed at transport layer

enumerator LWIP_ERR_PROTO: unsupported protocol for this op

enumerator LWIP_ERR_CLOSED: peer has closed (or local close pending)

enumerator LWIP_ERR_INTERNAL: lwIP returned an unexpected err_t

enum lwip_socket_type_t

Transport selector for lwip_socket_create.

Values:

enumerator LWIP_SOCKET_TCP: raw TCP via tcp_*

enumerator LWIP_SOCKET_UDP: UDP via udp_*

enumerator LWIP_SOCKET_ALTCP: altcp (default TCP allocator)

enumerator LWIP_SOCKET_ALTCP_TLS: altcp wrapped in TLS 1.3 (altcp_tls_ce)

enum lwip_socket_bind_descriptor_t

Which netif a socket attaches to at create().

Values:

enumerator LWIP_NETIF_ANY: first usable netif (loopback or external)

enumerator LWIP_NETIF_LOOP: loopback only

enumerator LWIP_NETIF_EXT: external Ethernet only

enum lwip_status_t

Socket lifecycle status.

Poll via socket->status or STATE_CHANGE events.

Values:

enumerator LWIP_STATUS_INIT: handle created, not connecting yet

enumerator LWIP_STATUS_WAITING_SERVICES: deferred: netif/link/DHCP/DNS not ready

enumerator LWIP_STATUS_RESOLVING: DNS lookup in flight.

enumerator LWIP_STATUS_CONNECTING: TCP / TLS handshake in flight.

enumerator LWIP_STATUS_CONNECTED: ready for write/read

enumerator LWIP_STATUS_CLOSING: local shutdown / close issued

enumerator LWIP_STATUS_CLOSED: peer sent FIN, clean close

enumerator LWIP_STATUS_RESET: peer sent RST, connection immediately gone

enumerator LWIP_STATUS_ERROR: stack error (timeout, OOM, abort)

enum lwip_socket_event_type_t

Socket event types delivered to the event callback.

ERROR is always delivered if a callback is registered, regardless of flags. For STATE_CHANGE, ev_data is lwip_socket_state_data_t* (previous + current status). For IO, ev_data is lwip_socket_io_data_t*. For ERROR, ev_data is lwip_socket_error_data_t* with the full component/operation/raw breakdown. All ev_data pointers are valid only for the duration of the callback.

Values:

enumerator LWIP_SOCKET_EV_ERROR

enumerator LWIP_SOCKET_EV_STATE_CHANGE

enumerator LWIP_SOCKET_EV_IO

enum lwip_socket_io_flags_t

IO event flags within lwip_socket_io_data_t.flags.

Values:

enumerator LWIP_SOCKET_IO_READABLE: data in ring; call lwip_socket_read

enumerator LWIP_SOCKET_IO_WRITABLE: peer ACKed sent data

enumerator LWIP_SOCKET_IO_POLL: periodic poll tick

enum lwip_socket_error_component_t

Error component — which subsystem reported the error.

Values:

enumerator LWIP_SOCKET_ERR_COMP_SOCKET

enumerator LWIP_SOCKET_ERR_COMP_NETIF

enumerator LWIP_SOCKET_ERR_COMP_SERVICES

enumerator LWIP_SOCKET_ERR_COMP_DNS

enumerator LWIP_SOCKET_ERR_COMP_TCP

enumerator LWIP_SOCKET_ERR_COMP_UDP

enumerator LWIP_SOCKET_ERR_COMP_ALTCP

enumerator LWIP_SOCKET_ERR_COMP_TLS

enumerator LWIP_SOCKET_ERR_COMP_MEM

enum lwip_socket_error_operation_t

Error operation — what was being attempted when the error occurred.

Values:

enumerator LWIP_SOCKET_ERR_OP_NONE

enumerator LWIP_SOCKET_ERR_OP_CREATE

enumerator LWIP_SOCKET_ERR_OP_CONNECT

enumerator LWIP_SOCKET_ERR_OP_DNS_LOOKUP

enumerator LWIP_SOCKET_ERR_OP_SERVICE_WAIT

enumerator LWIP_SOCKET_ERR_OP_SERVICE_START

enumerator LWIP_SOCKET_ERR_OP_RECV

enumerator LWIP_SOCKET_ERR_OP_SEND

enumerator LWIP_SOCKET_ERR_OP_WRITE

enumerator LWIP_SOCKET_ERR_OP_CLOSE

enumerator LWIP_SOCKET_ERR_OP_SHUTDOWN

enumerator LWIP_SOCKET_ERR_OP_TLS_INIT

enumerator LWIP_SOCKET_ERR_OP_TLS_CONFIG

enumerator LWIP_SOCKET_ERR_OP_ALLOC

enum lwip_netif_service_status_t

Values:

enumerator LWIP_NETIF_SERVICE_UP

enumerator LWIP_NETIF_SERVICE_FAILED

enumerator LWIP_NETIF_SERVICE_TIMEOUT

Functions

bool lwip_start(void)

uint8_t lwip_start_last_error(void)

void lwip_stop(void)

void lwip_poll_network_events(void)

uint32_t lwip_now_ms(void)

bool lwip_default_netif_info(lwip_netif_info_t *info)

lwip_error_t lwip_request_services(uint8_t flags)

lwip_error_t lwip_netif_request_services(struct netif *netif, uint8_t flags, lwip_netif_service_cb cb, void *cb_data)

lwip_error_t lwip_socket_create(struct lwip_socket *socket, lwip_socket_type_t type, lwip_socket_bind_descriptor_t bind, const lwip_socket_addrinfo_t *addrinfo, uint32_t timeout_ms)

Create a socket handle.

Non-blocking: returns immediately after binding the netif preference and kicking DHCP/static-IP. Readiness is awaited asynchronously by lwip_socket_connect.

Parameters:

socket – Caller-allocated handle. Zeroed by this call.
type – Transport selector (lwip_socket_type_t).
bind – Netif preference (lwip_socket_bind_descriptor_t).
addrinfo – NULL for DHCP; non-NULL for static IPv4.
timeout_ms – Inactivity watchdog window for connect/handshake (ms); 0 = default (LWIP_SOCKET_SERVICES_TIMEOUT_MS).

lwip_error_t lwip_socket_create_ex(struct lwip_socket *socket, lwip_socket_type_t type, lwip_socket_bind_descriptor_t bind, const lwip_socket_addrinfo_t *addrinfo, uint32_t timeout_ms, size_t rx_ring_max)

Like lwip_socket_create but with an explicit RX ring maximum.

rx_ring_max == 0 uses LWIP_SOCKET_RX_RING_MAX_SIZE.

lwip_error_t lwip_socket_destroy(struct lwip_socket *socket)

lwip_error_t lwip_socket_connect(struct lwip_socket *socket, const char *host, uint16_t port)

void lwip_socket_on_event(struct lwip_socket *socket, uint8_t event_flags, lwip_socket_event_cb cb, void *arg)

Register the single event callback.

flags — bitwise OR of LWIP_SOCKET_EVENTF_* to subscribe to; ERROR is always delivered regardless. cb — callback: void cb(sock, type, ev_data, arg) arg — user pointer passed as the last argument to cb.

Call before lwip_socket_connect. Only one callback is supported per socket; calling again replaces the previous registration.

bool lwip_socket_is_active(const struct lwip_socket *socket)

True while the socket is in a pre-terminal lifecycle state (INIT / WAITING / RESOLVING / CONNECTING / CONNECTED / CLOSING).

Returns false once the socket reaches CLOSED, RESET, or ERROR — use this as the main-loop exit condition.

lwip_error_t lwip_socket_set_connect_timeout(struct lwip_socket *socket, uint32_t timeout_ms)

lwip_error_t lwip_socket_write(struct lwip_socket *socket, const uint8_t *buf, size_t len)

size_t lwip_socket_available(const struct lwip_socket *socket)

size_t lwip_socket_read(struct lwip_socket *socket, uint8_t *buf, size_t len)

Read up to len bytes from the socket ring.

Returns bytes actually read (clamped to available); never blocks.

lwip_status_t lwip_socket_status(const struct lwip_socket *socket)

lwip_error_t lwip_socket_shutdown(struct lwip_socket *socket)

lwip_error_t lwip_socket_close(struct lwip_socket *socket)

lwip_error_t lwip_socket_abort(struct lwip_socket *socket)

lwip_error_t lwip_socket_set_rx_limits(struct lwip_socket *socket, size_t initial_size, size_t max_size)

uint8_t lwip_init_runtime_opaque(void *malloc_fn, void *free_fn, void *realloc_fn)

struct lwip_socket_addrinfo_t

#include <lwip.h>

Optional static IPv4 configuration.

Pass NULL for DHCP.

Public Members

ip4_addr_t ip

ip4_addr_t netmask

ip4_addr_t gateway

struct lwip_socket_error_data_t

#include <lwip.h>

ev_data for LWIP_SOCKET_EV_ERROR events.

Public Members

uint16_t component: lwip_socket_error_component_t

uint16_t operation: lwip_socket_error_operation_t

int raw_error: raw err_t / module code

lwip_error_t err: mapped app-facing result

lwip_status_t status: socket status at time of error

struct lwip_socket_state_data_t

#include <lwip.h>

ev_data for LWIP_SOCKET_EV_STATE_CHANGE events.

Public Members

lwip_status_t previous

lwip_status_t current

struct lwip_socket_io_data_t

#include <lwip.h>

ev_data for LWIP_SOCKET_EV_IO events.

Public Members

uint8_t flags: lwip_socket_io_flags_t bitmap

size_t readable: bytes in ring for lwip_socket_read

uint16_t written: bytes peer ACKed (WRITABLE flag set)

struct lwip_netif_info_t

#include <lwip.h>

Snapshot of the default lwIP netif.

Public Members

bool has_netif

bool up

bool link_up

bool dhcp_running

uint8_t dhcp_state

bool has_ipv4

bool has_ipv4_gateway

uint8_t ipv4_addr[4]

uint8_t ipv4_netmask[4]

uint8_t ipv4_gateway[4]

struct lwip_socket

#include <lwip.h>

Socket handle.

status and last_error are app-readable; all other fields are managed by the implementation — do not write them.

Public Members

lwip_status_t status

lwip_error_t last_error

void *user_arg

lwip_socket_event_cb on_event

uint8_t event_flags

uint8_t protocol: lwip_socket_type_t

uint8_t flags: service flags

uint8_t aborting

uint16_t remote_port

ip_addr_t remote_ip

struct netif *netif

uint8_t bind_descriptor

bool has_addrinfo

bool static_applied

lwip_socket_addrinfo_t addrinfo

struct tcp_pcb *tcp

struct udp_pcb *udp

struct altcp_pcb *altcp

union lwip_socket pcb

struct altcp_tls_ce_config *tls_conf

struct mem_buffer *rx_ring

size_t rx_ring_init

size_t rx_ring_max

uint16_t last_sent_len

uint16_t pending_events

lwip_error_t pending_error

int pending_raw_error

uint16_t pending_error_component

uint16_t pending_error_operation

lwip_status_t pending_state_previous

const char *pending_host

uint32_t services_deadline

uint32_t connect_timeout_ms

uint32_t activity_seen

struct lwip_socket *services_next

struct lwip_socket *registry_next