File espos_httpd.h¶

FileList > espos_httpd > include > espos_httpd.h

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "esp_err.h"
#include "esp_http_server.h"

Public Types¶

Type	Name
enum	espos_httpd_flags_t

Public Functions¶

Type	Name
esp_err_t	espos_httpd_auth_recovery_open (uint32_t seconds) Exempt requests arriving on the setup access point from the API key for `seconds` , as proof that somebody is at the device.
uint32_t	espos_httpd_auth_recovery_s_left (void) Seconds left of an open recovery window; 0 when none is open.
httpd_handle_t	espos_httpd_handle (void)
esp_err_t	espos_httpd_read_body (httpd_req_t * req, char ** out, size_t * out_len) Read the whole request body into a malloc'ed, NUL-terminated buffer.
esp_err_t	espos_httpd_register (const httpd_uri_t * uri) Register an additional URI handler (server must be started).
esp_err_t	espos_httpd_register_ex (const httpd_uri_t * uri, uint32_t flags) Register a URI handler with flags.
bool	espos_httpd_request_authenticated (httpd_req_t * req) Would this request pass the check a protected endpoint applies? True on an open device (no key configured, unless the build requires one), for a request from the setup portal's network, and for a valid Bearer key or session cookie — a cookie on a state-changing request also needs a matching Origin.
bool	espos_httpd_require_json (httpd_req_t * req) CSRF guard for state-changing endpoints: require `Content-Type: application/json` .
esp_err_t	espos_httpd_send_error (httpd_req_t * req, const char * status, const char * code, const char * msg) Send {"error": code, "message": msg} with the given status.
esp_err_t	espos_httpd_send_json (httpd_req_t * req, const char * status, const char * json) Send `json` (NUL-terminated) with application/json and the given HTTP status ("200 OK" etc.; NULL = 200).
esp_err_t	espos_httpd_start (void) Start the server on the configured port (httpd.port).
esp_err_t	espos_httpd_stop (void)

Public Types Documentation¶

enum espos_httpd_flags_t¶

enum espos_httpd_flags_t {
    ESPOS_HTTPD_PROTECTED = 0,
    ESPOS_HTTPD_PUBLIC = 1u << 0
};

Public Functions Documentation¶

function espos_httpd_auth_recovery_open¶

Exempt requests arriving on the setup access point from the API key for seconds , as proof that somebody is at the device.

esp_err_t espos_httpd_auth_recovery_open (
    uint32_t seconds
)

0 closes the window.

For a consumer with a way to establish that itself a recessed button, a jumper, a key switch. espOS opens the same window by itself after a run of power cycles when CONFIG_ESPOS_HTTPD_PORTAL_RECOVERY is set, which is the path for a device with no such hardware.

The window relaxes nothing on the station or Ethernet side, and it is held in RAM, so a reboot ends it. Call it only from a hardware event a person has to cause; an app that opens it on a schedule or on a network request has given its API key away. ESP_ERR_INVALID_STATE before espos_httpd_start().

function espos_httpd_auth_recovery_s_left¶

Seconds left of an open recovery window; 0 when none is open.

uint32_t espos_httpd_auth_recovery_s_left (
    void
)

function espos_httpd_handle¶

httpd_handle_t espos_httpd_handle (
    void
)

function espos_httpd_read_body¶

Read the whole request body into a malloc'ed, NUL-terminated buffer.

esp_err_t espos_httpd_read_body (
    httpd_req_t * req,
    char ** out,
    size_t * out_len
)

Bounded by CONFIG_ESPOS_HTTPD_MAX_BODY: on overflow sends 413 itself and returns ESP_ERR_INVALID_SIZE (caller must return ESP_FAIL without responding again). On socket error returns ESP_FAIL (no response sent).

function espos_httpd_register¶

Register an additional URI handler (server must be started).

esp_err_t espos_httpd_register (
    const httpd_uri_t * uri
)

The handler is protected: see espos_httpd_register_ex().

function espos_httpd_register_ex¶

Register a URI handler with flags.

esp_err_t espos_httpd_register_ex (
    const httpd_uri_t * uri,
    uint32_t flags
)

The httpd_uri_t is copied; the handler is called with the user_ctx it registered. Protected handlers run only after the request passed the authentication check (a 401/403/429 has been sent otherwise); public ones always run and may ask espos_httpd_request_authenticated() themselves. ESP_ERR_INVALID_STATE before espos_httpd_start(), ESP_ERR_HTTPD_HANDLERS_FULL beyond CONFIG_ESPOS_HTTPD_MAX_URI_HANDLERS.

function espos_httpd_request_authenticated¶

Would this request pass the check a protected endpoint applies? True on an open device (no key configured, unless the build requires one), for a request from the setup portal's network, and for a valid Bearer key or session cookie — a cookie on a state-changing request also needs a matching Origin.

bool espos_httpd_request_authenticated (
    httpd_req_t * req
)

Sends nothing. For public handlers that behave differently for the operator.

function espos_httpd_require_json¶

CSRF guard for state-changing endpoints: require Content-Type: application/json .

bool espos_httpd_require_json (
    httpd_req_t * req
)

Browsers cannot send that cross-origin without a CORS preflight (which we never answer), so a hostile web page cannot drive PUT/POST endpoints through a user's browser. On failure sends 415 and returns false (handler must return ESP_OK without responding again).

function espos_httpd_send_error¶

Send {"error": code, "message": msg} with the given status.

esp_err_t espos_httpd_send_error (
    httpd_req_t * req,
    const char * status,
    const char * code,
    const char * msg
)

function espos_httpd_send_json¶

Send json (NUL-terminated) with application/json and the given HTTP status ("200 OK" etc.; NULL = 200).

esp_err_t espos_httpd_send_json (
    httpd_req_t * req,
    const char * status,
    const char * json
)

function espos_httpd_start¶

Start the server on the configured port (httpd.port).

esp_err_t espos_httpd_start (
    void
)

Registers the built-in endpoints (config, schema, system, static UI). Idempotent.

function espos_httpd_stop¶

esp_err_t espos_httpd_stop (
    void
)

The documentation for this class was generated from the following file espos_httpd/include/espos_httpd.h