HTTP Server

Lightweight embedded HTTP server with REST API routing. More...

Data Structures
struct	ove_httpd_config_t
	HTTP server configuration. More...

Macros
#define	OVE_HTTPD_MAX_ROUTES   16
	Maximum number of registered routes.
#define	OVE_HTTPD_MAX_SEGMENTS   8
	Maximum path segments for parsing (e.g. /api/leds/0 = 3).

Typedefs
typedef struct ove_httpd_req	ove_httpd_req_t
	Opaque HTTP request.
typedef struct ove_httpd_resp	ove_httpd_resp_t
	Opaque HTTP response.
typedef int(*	ove_httpd_handler_t) (ove_httpd_req_t *req, ove_httpd_resp_t *resp)
	Route handler callback.
typedef struct ove_httpd_ws_conn	ove_httpd_ws_conn_t
	Opaque WebSocket connection handle.
typedef void(*	ove_httpd_ws_handler_t) (ove_httpd_ws_conn_t *conn, const void *data, size_t len)
	WebSocket message callback.
typedef void(*	ove_httpd_ws_close_handler_t) (ove_httpd_ws_conn_t *conn)
	WebSocket close callback.

Functions
int	ove_httpd_start (const ove_httpd_config_t *cfg)
	Start the HTTP server.
void	ove_httpd_stop (void)
	Stop the HTTP server and close the listening socket.
int	ove_httpd_route (const char *method, const char *path, ove_httpd_handler_t handler)
	Register a route handler.
void	ove_httpd_register_builtin_routes (void)
	Register built-in dashboard routes (/api/info, /api/leds, etc.).
void	ove_httpd_set_netif (ove_netif_t netif)
	Set the network interface used by built-in dashboard routes.
void	ove_httpd_set_audio_graph (struct ove_audio_graph *g)
	Set the audio graph for /api/audio/stats.
void	ove_httpd_set_model (ove_model_t model)
	Set the ML model for /api/infer/stats.
const char *	ove_httpd_req_method (ove_httpd_req_t *req)
	Get the HTTP method string ("GET" or "POST").
const char *	ove_httpd_req_path (ove_httpd_req_t *req)
	Get the full request path (e.g. "/api/leds/0").
const char *	ove_httpd_req_query (ove_httpd_req_t *req)
	Get the query string after '?' (or NULL).
const char *	ove_httpd_req_body (ove_httpd_req_t *req)
	Get the request body (or NULL).
size_t	ove_httpd_req_body_len (ove_httpd_req_t *req)
	Get the request body length.
const char *	ove_httpd_req_segment (ove_httpd_req_t *req, int idx)
	Get a path segment by index.
int	ove_httpd_resp_json (ove_httpd_resp_t *resp, int status, const char *json)
	Send a JSON response.
int	ove_httpd_resp_html (ove_httpd_resp_t *resp, int status, const char *html, size_t len)
	Send an HTML response.
int	ove_httpd_resp_send (ove_httpd_resp_t *resp, int status, const char *content_type, const void *body, size_t len)
	Send a response with arbitrary content type.
int	ove_httpd_resp_send_gz (ove_httpd_resp_t *resp, int status, const char *content_type, const void *body, size_t len)
	Send a pre-gzipped response (adds Content-Encoding: gzip).
int	ove_httpd_resp_error (ove_httpd_resp_t *resp, int status, const char *message)
	Send a JSON error response.
int	ove_httpd_ws_route (const char *path, ove_httpd_ws_handler_t on_message, ove_httpd_ws_close_handler_t on_close)
	Register a WebSocket route.
int	ove_httpd_ws_send (ove_httpd_ws_conn_t *conn, const void *data, size_t len)
	Send a text message to a WebSocket connection.
int	ove_httpd_ws_broadcast (const char *path, const void *data, size_t len)
	Broadcast a text message to all WebSocket connections on a path.
int	ove_httpd_ws_active_count (void)
	Return the number of active WebSocket connections.
int	ove_httpd_ws_is_upgrade (const char *headers)
	Return non-zero if the HTTP headers request a WebSocket upgrade.
int	ove_httpd_ws_handshake (const char *headers, size_t headers_len, const char *path, ove_socket_t sock, ove_socket_storage_t *storage)
	Complete the WebSocket upgrade handshake on sock.
void	ove_httpd_ws_poll (void)
	Drive the WS subsystem from the httpd task's poll loop.
void	ove_httpd_log_append (const char *line)
	Feed a log line into the httpd log ring buffer.

Detailed Description

Lightweight embedded HTTP server with REST API routing.

Provides a single-threaded HTTP/1.1 server with path-based route registration, JSON response helpers, and an optional built-in web dashboard for device management.

Note

Requires CONFIG_OVE_NET_HTTPD (implies CONFIG_OVE_NET).

Typedef Documentation

ove_httpd_handler_t

typedef int(* ove_httpd_handler_t) (ove_httpd_req_t *req, ove_httpd_resp_t *resp)

Route handler callback.

Returns

OVE_OK on success (response sent), negative error code on failure.

ove_httpd_ws_handler_t

typedef void(* ove_httpd_ws_handler_t) (ove_httpd_ws_conn_t *conn, const void *data, size_t len)

WebSocket message callback.

Parameters

[in]	conn	Connection that sent the message.
[in]	data	Message payload (text or binary).
[in]	len	Payload length in bytes.

ove_httpd_ws_close_handler_t

typedef void(* ove_httpd_ws_close_handler_t) (ove_httpd_ws_conn_t *conn)

WebSocket close callback.

Parameters

[in]

conn

Connection that was closed.

Function Documentation

ove_httpd_start()

int ove_httpd_start

(

const ove_httpd_config_t *

cfg

)

Start the HTTP server.

Spawns a background task that accepts connections on the configured port. Register routes with ove_httpd_route() before or after starting.

Parameters

[in]

cfg

Server configuration (NULL for defaults).

Returns

OVE_OK on success, negative error code on failure.

ove_httpd_route()

int ove_httpd_route	(	const char *	method,
		const char *	path,
		ove_httpd_handler_t	handler
	)

Register a route handler.

Parameters

[in]	method	HTTP method ("GET" or "POST").
[in]	path	URL path prefix (e.g. "/api/leds").
[in]	handler	Callback function.

Returns

OVE_OK on success, OVE_ERR_NO_MEMORY if route table full.

ove_httpd_register_builtin_routes()

void ove_httpd_register_builtin_routes

(

void

)

Register built-in dashboard routes (/api/info, /api/leds, etc.).

Call after ove_httpd_start() to add the standard device management API.

ove_httpd_set_netif()

void ove_httpd_set_netif

(

ove_netif_t

netif

)

Set the network interface used by built-in dashboard routes.

When set, /api/info and /api/network return the real interface addresses instead of placeholder values.

Parameters

[in]

netif

Network interface handle.

ove_httpd_req_segment()

const char * ove_httpd_req_segment	(	ove_httpd_req_t *	req,
		int	idx
	)

Get a path segment by index.

For path "/api/leds/0": segment 0="api", 1="leds", 2="0".

Parameters

[in]	req	Request.
[in]	idx	Segment index (0-based).

Returns

Segment string or NULL if out of range.

ove_httpd_ws_route()

int ove_httpd_ws_route	(	const char *	path,
		ove_httpd_ws_handler_t	on_message,
		ove_httpd_ws_close_handler_t	on_close
	)

Register a WebSocket route.

When a client sends an HTTP upgrade request matching path, the connection is upgraded to WebSocket. Incoming messages are dispatched to on_message.

Parameters

[in]	path	URL path prefix (e.g. "/ws/log").
[in]	on_message	Callback for incoming messages (may be NULL).
[in]	on_close	Callback when connection closes (may be NULL).

Returns

OVE_OK on success, OVE_ERR_NO_MEMORY if route table full.

ove_httpd_ws_send()

int ove_httpd_ws_send	(	ove_httpd_ws_conn_t *	conn,
		const void *	data,
		size_t	len
	)

Send a text message to a WebSocket connection.

Parameters

[in]	conn	Target connection.
[in]	data	Message payload.
[in]	len	Payload length in bytes.

Returns

OVE_OK on success, negative error code on failure.

ove_httpd_ws_broadcast()

int ove_httpd_ws_broadcast	(	const char *	path,
		const void *	data,
		size_t	len
	)

Broadcast a text message to all WebSocket connections on a path.

Parameters

[in]	path	Path filter (NULL for all connections).
[in]	data	Message payload.
[in]	len	Payload length in bytes.

Returns

Number of connections the message was sent to.

ove_httpd_ws_handshake()

int ove_httpd_ws_handshake	(	const char *	headers,
		size_t	headers_len,
		const char *	path,
		ove_socket_t	sock,
		ove_socket_storage_t *	storage
	)

Complete the WebSocket upgrade handshake on sock.

Invoked by the httpd accept loop after ove_httpd_ws_is_upgrade() returns true. On success the connection is handed off to the WS subsystem.

ove_httpd_log_append()

void ove_httpd_log_append

(

const char *

line

)

Feed a log line into the httpd log ring buffer.

Call from the log output hook to capture lines for GET /api/log.