DeterministicESPAsyncWebServer v6.28.0
Zero-allocation, bounded-execution async HTTP server for ESP32
Loading...
Searching...
No Matches
xmpp.h
Go to the documentation of this file.
1// Copyright (C) 2026 Douglas Quigg (dstroy0) <dquigg123@gmail.com>
2// SPDX-License-Identifier: AGPL-3.0-or-later
3
4/**
5 * @file xmpp.h
6 * @brief XMPP (RFC 6120) stanza codec (DETWS_ENABLE_XMPP).
7 *
8 * XMPP (Jabber) is an XML streaming protocol: after a `<stream:stream>` open, peers exchange three
9 * stanza kinds - `<message>`, `<presence>`, and `<iq>` (info/query). This is the stanza codec: builders
10 * that emit correctly XML-escaped stanzas into a caller buffer (so a device can publish sensor data or
11 * receive commands as an IoT XMPP client), plus minimal readers to pull the stanza element name and an
12 * attribute value out of a received stanza.
13 *
14 * Pure text framing, zero heap, no stdlib, host-testable. TLS (`starttls`) + SASL auth ride the existing
15 * client TLS path; the IoT XEPs (0323 sensor-data, 0325 control) layer their payloads inside `<iq>`.
16 */
17
18#ifndef DETERMINISTICESPASYNCWEBSERVER_XMPP_H
19#define DETERMINISTICESPASYNCWEBSERVER_XMPP_H
20
21#include "ServerConfig.h"
22#include <stddef.h>
23#include <stdint.h>
24
25#if DETWS_ENABLE_XMPP
26
27/**
28 * @brief XML-escape @p in into @p out (& < > ' " -> entities). @return bytes written (excl NUL), or 0 if
29 * it would overflow @p cap (a NUL terminator is written when there is room).
30 */
31size_t detws_xmpp_escape(const char *in, size_t in_len, char *out, size_t cap);
32
33/**
34 * @brief Build the initial `<stream:stream ...>` open tag (jabber:client). @return length, or 0 on overflow.
35 */
36size_t detws_xmpp_stream_open(const char *from, const char *to, char *out, size_t cap);
37
38/**
39 * @brief Build a `<message to=.. from=.. type=..><body>..</body></message>` stanza.
40 * @param type e.g. "chat"; null omits the type attribute. from may be null (server stamps it).
41 * @return length, or 0 on overflow.
42 */
43size_t detws_xmpp_message(const char *to, const char *from, const char *type, const char *body, char *out, size_t cap);
44
45/** @brief Build a `<presence/>` (type null) or `<presence type=".."/>` stanza. @return length, or 0. */
46size_t detws_xmpp_presence(const char *type, char *out, size_t cap);
47
48/**
49 * @brief Build an `<iq type=.. id=..>child</iq>` stanza (child is inserted verbatim; may be null/empty).
50 * @return length, or 0 on overflow.
51 */
52size_t detws_xmpp_iq(const char *type, const char *id, const char *child_xml, char *out, size_t cap);
53
54/**
55 * @brief Read the stanza's top-level element name (message / presence / iq / ...) into @p out.
56 * @return the name length, or 0 if no start tag is found.
57 */
58size_t detws_xmpp_stanza_name(const char *xml, size_t len, char *out, size_t cap);
59
60/**
61 * @brief Extract the value of attribute @p attr from the stanza's start tag into @p out (unescaped copy
62 * is NOT performed - the raw attribute text is returned). @return value length, or 0 if absent.
63 */
64size_t detws_xmpp_attr(const char *xml, size_t len, const char *attr, char *out, size_t cap);
65
66#endif // DETWS_ENABLE_XMPP
67#endif // DETERMINISTICESPASYNCWEBSERVER_XMPP_H
ServerConfig.h
User-facing configuration for DeterministicESPAsyncWebServer.