AxlNet – Networking

TCP sockets, UDP sockets, URL parsing, HTTP server, HTTP client, TLS, and network utilities (IPv4 address helpers, interface enumeration, ping).

Individual headers can be included separately or use the umbrella <axl/axl-net.h>.

Headers:

  • <axl/axl-net.h> – Umbrella + network utilities

  • <axl/axl-tcp.h> – TCP sockets

  • <axl/axl-udp.h> – UDP sockets

  • <axl/axl-url.h> – URL parsing

  • <axl/axl-http-server.h> – HTTP server

  • <axl/axl-http-client.h> – HTTP client

  • <axl/axl-tls.h> – TLS support (optional, requires AXL_TLS=1)

Overview

AXL networking is built on UEFI’s TCP4/UDP4 protocol stack. The stack must be initialized before use – either by the UEFI Shell (ifconfig) or by calling axl_net_auto_init.

Application
├─ axl_http_server / axl_http_client
├─ axl_tcp / axl_udp
├─ axl_tls (optional, wraps TCP)
└─ UEFI TCP4 / UDP4 protocols
    └─ IP4 → ARP → SNP (NIC driver)

Network Initialization

// Auto-init: load drivers, run DHCP, wait for IP
if (axl_net_auto_init(SIZE_MAX, 10) != 0) {
    axl_printf("Network not available\n");
    return -1;
}

// Or configure static IP
uint8_t ip[]      = {192, 168, 1, 100};
uint8_t netmask[] = {255, 255, 255, 0};
uint8_t gateway[] = {192, 168, 1, 1};
axl_net_set_static_ip(0, ip, netmask, gateway);

TCP Sockets

Blocking and async TCP sockets. The blocking API is simpler; the async API integrates with the event loop for non-blocking I/O.

Client (blocking):

AxlTcp *sock;
if (axl_tcp_connect("192.168.1.1", 8080, &sock) == 0) {
    axl_tcp_send(sock, "GET / HTTP/1.0\r\n\r\n", 18, 5000);

    char buf[4096];
    size_t len = sizeof(buf);
    axl_tcp_recv(sock, buf, &len, 5000);

    axl_tcp_close(sock);
}

Server (async with event loop):

void on_client(AxlTcp *client, int status, void *data) {
    if (status != 0) return;
    // handle client connection...
    axl_tcp_close(client);
}

AxlTcp *listener;
axl_tcp_listen(8080, &listener);
axl_tcp_accept_async(listener, loop, on_client, NULL);
axl_loop_run(loop);

UDP Sockets

Fire-and-forget datagram sending and request-response patterns.

AXL_AUTOPTR(AxlUdpSocket) sock = NULL;
axl_udp_open(&sock, 0);  // ephemeral port

AxlIPv4Address dest;
axl_ipv4_parse("192.168.1.100", dest.addr);

// Fire-and-forget
axl_udp_send(sock, &dest, 514, msg, msg_len);

// Request-response (e.g., DNS query)
char reply[512];
size_t reply_len;
axl_udp_sendrecv(sock, &dest, 53, query, query_len,
                 reply, sizeof(reply), &reply_len, 3000);

HTTP Server

Create an HTTP server with route handlers:

void on_hello(AxlHttpRequest *req, AxlHttpResponse *resp, void *data) {
    axl_http_respond_text(resp, 200, "Hello from AXL!\n");
}

AXL_AUTOPTR(AxlHttpServer) s = axl_http_server_new(8080);
axl_http_server_add_route(s, "GET", "/hello", on_hello, NULL);
axl_http_server_run(s);  // blocks, serving requests

The server supports middleware, WebSocket endpoints, authentication, response caching, and streaming uploads. See the API reference below for details.

HTTP Client

AXL_AUTOPTR(AxlHttpClient) c = axl_http_client_new();
AXL_AUTOPTR(AxlHttpClientResponse) resp = NULL;

if (axl_http_get(c, "http://192.168.1.1:8080/api/status", &resp) == 0) {
    axl_printf("HTTP %zu\n", resp->status_code);
    if (resp->body != NULL) {
        axl_printf("%.*s\n", (int)resp->body_size, (char *)resp->body);
    }
}

HTTPS URLs are automatically detected when built with AXL_TLS=1.

TLS (HTTPS)

Optional TLS support using mbedTLS 3.6. Build with AXL_TLS=1 to enable. See AxlTls – TLS Support for details.

Network Utilities

Functions

int axl_net_get_ip_address(AxlIPv4Address *addr)

Get the local IPv4 address of the first configured NIC.

Parameters:

  • addr – receives the IPv4 address

Returns:

0 on success, -1 on failure.

int axl_net_ping(AxlIPv4Address *target, size_t timeout_ms, size_t *out_rtt_ms)

Send an ICMP echo request and measure round-trip time.

Parameters:

  • target – target IPv4 address

  • timeout_ms – timeout in milliseconds

  • out_rtt_ms – receives round-trip time in milliseconds

Returns:

0 on success, -1 on failure or timeout.

int axl_net_resolve(const char *hostname, AxlIPv4Address *addr)

Resolve a hostname to an IPv4 address via DNS4. Falls back to parsing the hostname as a dotted-decimal IP.

Parameters:

  • hostname – hostname or IP string

  • addr – receives the resolved address

Returns:

0 on success, -1 on failure.

bool axl_net_is_available(void)

Check whether any IPv4 network is available.

Returns:

true if at least one NIC has an IP address.

int axl_net_auto_init(size_t nic_index, size_t dhcp_timeout_sec)

Bring up networking: load drivers, run DHCP, wait for IP.

Performs a best-effort network initialization sequence:

  1. If no SNP handles exist, attempts to load NIC drivers from the “drivers” subdirectory next to the running application.

  2. Connects all SNP handles to trigger protocol stack creation.

  3. Selects a NIC (by nic_index, or first available if SIZE_MAX).

  4. Waits up to dhcp_timeout_sec for an IPv4 address via DHCP.

Parameters:

  • nic_index – NIC index (SIZE_MAX = auto-select first)

  • dhcp_timeout_sec – DHCP timeout in seconds (0 = 10s default)

Returns:

0 on success (IP address acquired), -1 on failure.

int axl_net_set_static_ip(size_t nic_index, const uint8_t ip[4], const uint8_t netmask[4], const uint8_t *gateway)

Configure a static IPv4 address on a NIC.

Sets the IP4Config2 policy to static and assigns the given address, subnet mask, and optional gateway. Pass NULL for gateway to leave it unconfigured.

Parameters:

  • nic_index – NIC index (from axl_net_list_interfaces)

  • ip – IPv4 address

  • netmask – subnet mask (e.g. {255,255,255,0})

  • gateway – gateway address (NULL = none)

Returns:

0 on success, -1 on failure.

int axl_ipv4_parse(const char *str, uint8_t octets[4])

Parse a dotted-decimal IPv4 address string.

Accepts strings like “192.168.1.1”. Each octet must be 0-255. No leading zeros validation — “01.02.03.04” is accepted.

Parameters:

  • str – IPv4 string (e.g. “192.168.1.1”)

  • octets – receives the four octets

Returns:

0 on success, -1 on invalid input.

int axl_ipv4_format(const uint8_t octets[4], char *buf, size_t size)

Format an IPv4 address as a dotted-decimal string.

Writes at most size bytes (including NUL). 16 bytes is always sufficient (“255.255.255.255” + NUL).

Parameters:

  • octets – four octets

  • buf – output buffer

  • size – buffer size (16 bytes sufficient)

Returns:

0 on success, -1 if buffer is too small or args are NULL.

int axl_net_list_interfaces(AxlNetInterface *out, size_t *count)

List available network interfaces.

Fills out with up to *count interface descriptors. On return, *count is set to the number of entries filled. Call with out=NULL to query the number of interfaces.

Parameters:

  • out – output array (NULL to query count)

  • count – [in/out] capacity / entries filled

Returns:

0 on success, -1 on error.

struct AxlIPv4Address
#include <axl-net.h>

IPv4 address (4 bytes).

Public Members

uint8_t addr[4]
struct AxlNetInterface
#include <axl-net.h>

Network interface descriptor.

Public Members

char name[32]

interface name (“eth0”, “eth1”, …)

uint8_t mac[6]

MAC address.

true if link is up

uint32_t mtu

maximum transmission unit

bool has_ipv4

true if IPv4 is configured

uint8_t ipv4[4]

IPv4 address (valid if has_ipv4)

uint8_t netmask[4]

subnet mask (valid if has_ipv4)

uint8_t gateway[4]

default gateway (valid if has_ipv4)

AxlTcp

Typedefs

typedef struct AxlLoop AxlLoop
typedef struct AxlTcp AxlTcp
typedef void (*AxlTcpCallback)(AxlTcp *sock, int status, void *data)

AxlTcpCallback:

Callback for async TCP operations. sock is the resulting socket (new connection for accept/connect, or the data socket for recv/send). NULL on error. status is 0 on success, -1 on error.

Functions

int axl_tcp_connect(const char *host, uint16_t port, AxlTcp **out_sock)

Connect to a remote host via TCP4.

Parameters:

  • host – IPv4 address string or hostname (DNS resolved)

  • port – remote port number

  • out_sock – receives the connected socket handle

Returns:

0 on success, -1 on failure.

int axl_tcp_listen(uint16_t port, AxlTcp **out_listener)

Create a TCP4 listener on the given port.

Parameters:

  • port – local port to listen on

  • out_listener – receives the listener handle

Returns:

0 on success, -1 on failure.

int axl_tcp_accept(AxlTcp *listener, AxlTcp **out_client)

Accept one pending connection on a listener.

Parameters:

  • listener – listener from axl_tcp_listen

  • out_client – receives the accepted client socket

Returns:

0 on success, -1 on failure.

int axl_tcp_send(AxlTcp *sock, const void *data, size_t size, size_t timeout_ms)

Send data over a connected TCP socket.

Parameters:

  • sock – connected socket

  • data – buffer to send

  • size – number of bytes to send

  • timeout_ms – timeout in ms (0 = default 10s)

Returns:

0 on success, -1 on failure or timeout.

int axl_tcp_recv(AxlTcp *sock, void *buf, size_t *size, size_t timeout_ms)

Receive data from a connected TCP socket.

Parameters:

  • sock – connected socket

  • buf – receive buffer

  • size – on entry, buffer size; on return, bytes received

  • timeout_ms – timeout in ms (0 = default 10s)

Returns:

0 on success, -1 on failure or timeout.

int axl_tcp_poll(AxlTcp *sock)

Poll a TCP socket to drive its internal state machine.

Parameters:

  • sock – socket to poll

Returns:

0 on success, -1 on failure.

void axl_tcp_close(AxlTcp *sock)

Close and free a TCP socket (listener or connected).

Parameters:

  • sock – socket to close (NULL-safe)

int axl_tcp_get_local_addr(AxlTcp *sock, char *addr, size_t size, uint16_t *out_port)

Query the local address of a connected or listening socket.

Parameters:

  • sock – socket

  • addr – buffer for dotted-decimal address (min 16 bytes)

  • size – size of addr buffer

  • out_port – receives local port number

Returns:

0 on success, -1 on failure.

int axl_tcp_get_remote_addr(AxlTcp *sock, char *addr, size_t size, uint16_t *out_port)

Query the remote address of a connected socket.

Parameters:

  • sock – connected socket

  • addr – buffer for dotted-decimal address (min 16 bytes)

  • size – size of addr buffer

  • out_port – receives remote port number

Returns:

0 on success, -1 on failure.

int axl_tcp_connect_async(const char *host, uint16_t port, AxlLoop *loop, AxlTcpCallback cb, void *data)

Async connect — initiates TCP connection, returns immediately.

The callback fires from the event loop when the connection completes (or fails). The newly connected socket is passed to the callback.

Parameters:

  • host – IPv4 address or hostname

  • port – remote port

  • loop – event loop to register with

  • cb – callback on completion

  • data – opaque context

Returns:

0 if initiated, -1 on immediate failure.

int axl_tcp_accept_async(AxlTcp *listener, AxlLoop *loop, AxlTcpCallback cb, void *data)

Async accept — waits for incoming connection via the event loop.

The callback fires each time a client connects. After the callback, accept is automatically re-armed for the next connection. Call axl_tcp_close on the listener to stop accepting.

Parameters:

  • listener – listener from axl_tcp_listen

  • loop – event loop

  • cb – callback per accepted client

  • data – opaque context

Returns:

0 if initiated, -1 on immediate failure.

int axl_tcp_recv_start(AxlTcp *sock, void *buf, size_t size, AxlLoop *loop, AxlTcpCallback cb, void *data)

Async receive — waits for data via the event loop.

The callback fires when data arrives in the caller’s buffer. Not automatically re-armed — call again to receive more data.

Parameters:

  • sock – connected socket

  • buf – receive buffer (must stay valid until callback)

  • size – buffer size

  • loop – event loop

  • cb – callback when data received

  • data – opaque context

Returns:

0 if initiated, -1 on immediate failure.

size_t axl_tcp_recv_get_size(AxlTcp *sock)

Get the number of bytes received by the last axl_tcp_recv_start.

Call from inside the recv callback to get the actual byte count.

Parameters:

  • sock – socket from recv callback

Returns:

bytes received, or 0 if no recv has completed.

int axl_tcp_send_start(AxlTcp *sock, const void *buf, size_t size, AxlLoop *loop, AxlTcpCallback cb, void *data)

Async send — initiates send, callback on completion.

The buffer must stay valid until the callback fires.

Parameters:

  • sock – connected socket

  • buf – send buffer (must stay valid until callback)

  • size – bytes to send

  • loop – event loop

  • cb – callback when send completes

  • data – opaque context

Returns:

0 if initiated, -1 on immediate failure.

AxlUdp

Typedefs

typedef struct AxlUdpSocket AxlUdpSocket
typedef AxlLoop AxlLoop
typedef void (*AxlUdpRecvCallback)(AxlUdpSocket *sock, const void *data, size_t len, const AxlIPv4Address *from, uint16_t from_port, void *user_data)

AxlUdpRecvCallback:

Called when a datagram is received on an async-monitored socket.

Functions

int axl_udp_open(AxlUdpSocket **sock, uint16_t local_port)

Open a UDP socket bound to a local port.

Uses the NIC’s DHCP-assigned or static IP address. Pass 0 for local_port to use an ephemeral port.

Parameters:

  • sock – [out] receives socket handle

  • local_port – local port (0 = ephemeral)

Returns:

0 on success, -1 if UDP4 stack is not available.

void axl_udp_close(AxlUdpSocket *sock)

Close a UDP socket and release resources. NULL-safe.

Parameters:

  • sock – socket to close

int axl_udp_send(AxlUdpSocket *sock, const AxlIPv4Address *dest, uint16_t port, const void *data, size_t len)

Send a UDP datagram. Blocking with 2-second timeout.

Fire-and-forget — no response expected.

Parameters:

  • sock – socket

  • dest – destination IPv4 address

  • port – destination port

  • data – payload

  • len – payload length

Returns:

0 on success, -1 on error or timeout.

int axl_udp_sendrecv(AxlUdpSocket *sock, const AxlIPv4Address *dest, uint16_t port, const void *tx_data, size_t tx_len, void *rx_buf, size_t rx_size, size_t *rx_len, size_t timeout_ms)

Send a datagram and wait for a response.

Sends tx_data, then polls for an incoming datagram up to timeout_ms milliseconds. Useful for DNS queries, NTP, etc.

Parameters:

  • sock – socket

  • dest – destination IPv4 address

  • port – destination port

  • tx_data – request payload

  • tx_len – request length

  • rx_buf – [out] response buffer

  • rx_size – response buffer capacity

  • rx_len – [out] bytes received

  • timeout_ms – receive timeout in ms

Returns:

0 on success, -1 on error or timeout.

int axl_udp_recv_start(AxlUdpSocket *sock, AxlLoop *loop, AxlUdpRecvCallback cb, void *data)

Start receiving datagrams asynchronously via the event loop.

cb fires on each received datagram. Receiving continues until axl_udp_recv_stop() is called or the socket is closed.

Parameters:

  • sock – socket

  • loop – event loop

  • cb – receive callback

  • data – user data for callback

Returns:

0 on success, -1 on error.

void axl_udp_recv_stop(AxlUdpSocket *sock)

Stop async receive. No more callbacks after this returns.

Parameters:

  • sock – socket

AxlUrl

Functions

int axl_url_parse(const char *url, AxlUrl **out_parsed)

Parse a URL string into components.

Parameters:

  • url – URL string (e.g. “http://host:8080/path?q=1”)

  • out_parsed – receives allocated AxlUrl; free with axl_url_free()

Returns:

0 on success, -1 on failure.

void axl_url_free(AxlUrl *url)

Free an AxlUrl returned by axl_url_parse.

Parameters:

  • url – URL to free (NULL-safe)

char *axl_url_build(const char *scheme, const char *host, uint16_t port, const char *path)

Build a URL string from components.

Parameters:

  • scheme – “http” or “https”

  • host – hostname or IP

  • port – port number (0 = use default for scheme)

  • path – path starting with “/” (NULL = “/”)

Returns:

allocated URL string, or NULL on failure. Caller frees.

int axl_url_encode(const char *src, char *out, size_t size)

Percent-encode a string for use in a URL.

Encodes all characters except unreserved characters (A-Z, a-z, 0-9, ‘-’, ‘.’, ‘_’, ‘~’) and optionally ‘/’ (preserved by default for path encoding). Each encoded byte becomes XX.

Parameters:

  • src – input string (UTF-8)

  • out – output buffer

  • size – output buffer size

Returns:

number of bytes written (excluding NUL), or -1 on error or truncation.

int axl_url_decode(const char *src, char *out, size_t size)

Decode a percent-encoded URL string.

Replaces XX sequences with the corresponding byte. Passes through characters that are not percent-encoded.

Parameters:

  • src – percent-encoded string

  • out – output buffer

  • size – output buffer size

Returns:

number of bytes written (excluding NUL), or -1 on error or truncation.

struct AxlUrl

Public Members

char *scheme
char *host
char *path
char *query
uint16_t port

AxlHttpServer

Defines

AXL_WS_CONNECT
AXL_WS_TEXT
AXL_WS_BINARY
AXL_WS_DISCONNECT
AXL_ROUTE_NO_AUTH
AXL_ROUTE_AUTH
AXL_ROUTE_ADMIN
AXL_CACHE_FOREVER

Typedefs

typedef struct AxlLoop AxlLoop
typedef int (*AxlHttpHandler)(AxlHttpRequest *req, AxlHttpResponse *resp, void *data)

Route handler callback.

Return:

0 on success, -1 on failure.

typedef int (*AxlHttpMiddleware)(AxlHttpRequest *req, AxlHttpResponse *resp, void *data)

Middleware callback. Return 0 to continue pipeline, -1 to short-circuit.

Return:

0 to continue, -1 to abort.

typedef struct AxlHttpServer AxlHttpServer
typedef int (*AxlWsHandler)(size_t event, const void *frame, size_t frame_size, void *data)

WebSocket event callback.

Return:

0 on success, -1 on failure.

typedef int (*AxlAuthCallback)(AxlHttpRequest *req, AxlAuthInfo *auth_out, void *data)

Authentication callback.

Return:

0 on success (authenticated), -1 on failure.

typedef int (*AxlUploadHandler)(AxlHttpRequest *req, const void *chunk, size_t chunk_size, void *data)

Upload streaming callback, called per chunk.

Return:

0 on success, -1 on failure.

Functions

AxlHttpServer *axl_http_server_new(uint16_t port)

Create a new HTTP server bound to the given port.

Parameters:

  • port – TCP port to listen on

Returns:

server instance, or NULL on failure.

void axl_http_server_free(AxlHttpServer *server)

Free an HTTP server and all resources.

Parameters:

  • server – server to free (NULL-safe)

int axl_http_server_set(AxlHttpServer *s, const char *key, const char *value)

Set a server option by key.

Supported keys: “max.connections”, “max.routes”, “body.limit”, “keep.alive.sec”.

Parameters:

  • s – server

  • key – option key

  • value – option value (string)

Returns:

0 on success, -1 on unknown key or invalid value.

const char *axl_http_server_get(AxlHttpServer *s, const char *key)

Get a server option value as string.

Parameters:

  • s – server

  • key – option key

Returns:

option value, or NULL for unknown keys.

void axl_http_server_set_max_connections(AxlHttpServer *s, size_t max)

Set maximum simultaneous connections.

Parameters:

  • s – server

  • max – maximum simultaneous connections (default 8)

void axl_http_server_set_max_routes(AxlHttpServer *s, size_t max)

Set maximum registered routes.

Parameters:

  • s – server

  • max – maximum registered routes (default 32)

void axl_http_server_set_body_limit(AxlHttpServer *s, size_t max_bytes)

Set maximum request body size.

Parameters:

  • s – server

  • max_bytes – maximum request body size in bytes (default 4 MB)

void axl_http_server_set_keep_alive(AxlHttpServer *s, size_t timeout_sec)

Set keep-alive timeout.

Parameters:

  • s – server

  • timeout_sec – keep-alive timeout in seconds (default 30)

int axl_http_server_use(AxlHttpServer *s, AxlHttpMiddleware mw, void *data)

Register middleware executed in registration order. Return 0 from mw to continue pipeline, -1 to short-circuit.

Parameters:

  • s – server

  • mw – middleware function

  • data – context passed to mw

Returns:

0 on success, -1 on failure.

int axl_http_server_add_route(AxlHttpServer *s, const char *method, const char *path, AxlHttpHandler handler, void *data)

Register a route handler.

Parameters:

  • s – server

  • method – HTTP method (“GET”, “POST”, etc.) or NULL for any

  • path – path pattern; trailing slash-star matches prefix

  • handler – handler function

  • data – context passed to handler

Returns:

0 on success, -1 on failure.

int axl_http_server_add_static(AxlHttpServer *s, const char *prefix, const char *fs_path)

Serve static files from a filesystem path.

Parameters:

  • s – server

  • prefix – URL prefix (e.g. “/”)

  • fs_path – filesystem path (UTF-8)

Returns:

0 on success, -1 on failure.

int axl_http_server_attach(AxlHttpServer *s, AxlLoop *loop)

Attach server to an event loop for cooperative polling.

Parameters:

  • s – server

  • loop – event loop from axl_loop_new

Returns:

0 on success, -1 on failure.

int axl_http_server_run(AxlHttpServer *s)

Run the server in standalone mode (blocks until quit).

Parameters:

  • s – server

Returns:

0 on success, -1 on failure.

void axl_http_response_set_json(AxlHttpResponse *r, const char *json)

Set JSON body and “application/json” content type (default 200).

Parameters:

  • r – response

  • json – JSON string

void axl_http_response_set_text(AxlHttpResponse *r, const char *text)

Set plain text body and “text/plain” content type (default 200).

Parameters:

  • r – response

  • text – plain text string

void axl_http_response_set_status(AxlHttpResponse *r, size_t code)

Set or override the HTTP status code.

Parameters:

  • r – response

  • code – HTTP status code

void axl_http_response_set_file(AxlHttpResponse *r, const char *path)

Set response body from a file, inferring content type from extension.

Parameters:

  • r – response

  • path – filesystem path (UTF-8)

void axl_http_response_set_range(AxlHttpResponse *r, const void *data, size_t offset, size_t length, size_t total_size)

Set a byte-range response (HTTP 206) with Content-Range header.

Parameters:

  • r – response

  • data – full data buffer

  • offset – byte offset into data

  • length – number of bytes to send

  • total_size – total size of the resource

bool axl_http_parse_range(const char *range_header, uint64_t file_size, AxlHttpRange *out)

Parse an HTTP Range request header.

Supports a single “bytes=START-END” range (not multi-range). Handles “bytes=START-”, “bytes=-SUFFIX”, and “bytes=START-END”. Clamps end to file_size - 1. Sets out->valid on success.

Parameters:

  • range_header – Range header value (e.g. “bytes=0-499”)

  • file_size – total file size

  • out – receives the parsed range

Returns:

true if a valid range was parsed, false otherwise.

bool axl_http_accepts(const char *accept_header, const char *media_type)

Check if an HTTP Accept header includes a media type.

Searches the comma-separated Accept header value for media_type (e.g. “application/json”, “text/html”). Matching is case-insensitive and ignores quality parameters. Also matches wildcard types (wildcard accepts everything).

Parameters:

  • accept_header – Accept header value (may be NULL)

  • media_type – media type to check (e.g. “application/json”)

Returns:

true if media_type is acceptable.

int axl_http_server_use_tls(AxlHttpServer *s, const void *cert_der, size_t cert_len, const void *key_der, size_t key_len)

Enable TLS on the server with DER-encoded cert and key.

After this call, all accepted connections use TLS. The cert and key can be generated with axl_tls_generate_self_signed(). Requires AXL_TLS=1 at build time.

Parameters:

  • s – server

  • cert_der – DER-encoded certificate

  • cert_len – certificate length

  • key_der – DER-encoded private key

  • key_len – key length

Returns:

0 on success, -1 if TLS not available or cert/key invalid.

int axl_http_server_add_websocket(AxlHttpServer *s, const char *path, AxlWsHandler handler, void *data)

Register a WebSocket endpoint.

Parameters:

  • s – server

  • path – WebSocket endpoint path

  • handler – WebSocket event handler

  • data – opaque caller data

Returns:

0 on success, -1 on failure.

int axl_http_server_ws_broadcast(AxlHttpServer *s, const char *path, const void *data, size_t size)

Broadcast data to all connected WebSocket clients on a path.

Parameters:

  • s – server

  • path – WebSocket endpoint path

  • data – data to broadcast

  • size – data size in bytes

Returns:

0 on success, -1 on failure.

int axl_http_server_use_auth(AxlHttpServer *s, AxlAuthCallback cb, void *data)

Register an authentication handler for the server.

Parameters:

  • s – server

  • cb – authentication callback

  • data – opaque caller data

Returns:

0 on success, -1 on failure.

int axl_http_server_add_route_auth(AxlHttpServer *s, const char *method, const char *path, AxlHttpHandler handler, void *data, uint32_t auth_flags)

Register a route handler with authentication requirements.

Parameters:

  • s – server

  • method – HTTP method or NULL for any

  • path – path pattern

  • handler – handler function

  • data – context passed to handler

  • auth_flags – AXL_ROUTE_* flags

Returns:

0 on success, -1 on failure.

int axl_http_server_use_cache(AxlHttpServer *s, size_t max_entries)

Enable response caching on the server.

Parameters:

  • s – server

  • max_entries – maximum cache entries

Returns:

0 on success, -1 on failure.

int axl_http_server_set_route_ttl(AxlHttpServer *s, const char *path, size_t ttl_ms)

Set cache TTL for a specific route.

Parameters:

  • s – server

  • path – route path

  • ttl_ms – time-to-live in milliseconds, or AXL_CACHE_FOREVER

Returns:

0 on success, -1 on failure.

void axl_http_server_cache_invalidate(AxlHttpServer *s, const char *prefix)

Invalidate cached responses matching the prefix.

Parameters:

  • s – server

  • prefix – path prefix to invalidate (NULL for all)

int axl_http_server_add_upload_route(AxlHttpServer *s, const char *method, const char *path, AxlUploadHandler handler, void *data)

Register a streaming upload route.

Parameters:

  • s – server

  • method – HTTP method

  • path – path pattern

  • handler – upload handler

  • data – opaque caller data

Returns:

0 on success, -1 on failure.

struct AxlHttpRequest

Public Members

const char *method
const char *path
const char *query
AxlHashTable *headers
const void *body
size_t body_size
char client_addr[46]
void *middleware_data
struct AxlHttpResponse

Public Members

size_t status_code
AxlHashTable *headers
void *body
size_t body_size
const char *content_type
struct AxlHttpRange
#include <axl-http-server.h>

Parsed byte range from an HTTP Range request header.

Public Members

uint64_t start

first byte position (inclusive)

uint64_t end

last byte position (inclusive)

uint64_t total

total file size (from file_size parameter)

bool valid

true if parsing succeeded

struct AxlAuthInfo

Public Members

const char *username
size_t role

AxlHttpClient

Typedefs

typedef struct AxlHttpClient AxlHttpClient

Functions

AxlHttpClient *axl_http_client_new(void)

Create a new HTTP client with default options.

Returns:

client instance, or NULL on failure.

void axl_http_client_free(AxlHttpClient *c)

Free an HTTP client and close any open connection.

Parameters:

  • c – client to free (NULL-safe)

int axl_http_client_set(AxlHttpClient *c, const char *key, const char *value)

Set a client option.

All values are strings, parsed internally. See header comment for the list of supported options.

Parameters:

  • c – client

  • key – option name

  • value – option value (string)

Returns:

0 on success, -1 on unknown option.

const char *axl_http_client_get(AxlHttpClient *c, const char *key)

Get a client option value.

Returns a pointer to the internally stored string. The pointer remains valid until the option is changed or the client is freed.

Parameters:

  • c – client

  • key – option name

Returns:

option value string, or NULL for unknown options.

int axl_http_get(AxlHttpClient *c, const char *url, AxlHttpClientResponse **out_resp)

HTTP GET request.

Parameters:

  • c – client

  • url – full URL string

  • out_resp – receives response; free with axl_http_client_response_free()

Returns:

0 on success, -1 on failure.

int axl_http_post(AxlHttpClient *c, const char *url, const void *body, size_t size, const char *content_type, AxlHttpClientResponse **out_resp)

HTTP POST request.

Parameters:

  • c – client

  • url – full URL string

  • body – request body

  • size – body size in bytes

  • content_type – MIME type (e.g. “application/json”)

  • out_resp – receives response

Returns:

0 on success, -1 on failure.

int axl_http_put(AxlHttpClient *c, const char *url, const void *body, size_t size, const char *content_type, AxlHttpClientResponse **out_resp)

HTTP PUT request.

Parameters:

  • c – client

  • url – full URL string

  • body – request body

  • size – body size in bytes

  • content_type – MIME type

  • out_resp – receives response

Returns:

0 on success, -1 on failure.

int axl_http_delete(AxlHttpClient *c, const char *url, AxlHttpClientResponse **out_resp)

HTTP DELETE request.

Parameters:

  • c – client

  • url – full URL string

  • out_resp – receives response

Returns:

0 on success, -1 on failure.

int axl_http_request(AxlHttpClient *c, const char *method, const char *url, const void *body, size_t body_size, const char *content_type, AxlHashTable *extra_headers, AxlHttpClientResponse **out_resp)

Generic HTTP request with optional per-request headers.

Parameters:

  • c – client

  • method – HTTP method (“GET”, “POST”, “PUT”, “DELETE”, etc.)

  • url – full URL string

  • body – request body, or NULL

  • body_size – body size in bytes

  • content_type – MIME type, or NULL

  • extra_headers – optional hash table of additional headers (NULL for none)

  • out_resp – receives response

Returns:

0 on success, -1 on failure.

void axl_http_client_response_free(AxlHttpClientResponse *resp)

Free a client response.

Parameters:

  • resp – response to free (NULL-safe)

int axl_http_download(AxlHttpClient *c, const char *url, const char *local_path)

Download a URL to a local file.

Parameters:

  • c – client

  • url – full URL string

  • local_path – filesystem path to write (UTF-8)

Returns:

0 on success, -1 on failure.

struct AxlHttpClientResponse

Public Members

size_t status_code
AxlHashTable *headers
void *body
size_t body_size