RapidXML

This is a port of https://github.com/dwd/rapidxml with minimal patch, and additional support code for Sming.

API Documentation

namespace XML

Unnamed Group

bool deserialize(Document &doc, char *content)

De-serialise XML text into a document.

Note

Document maintains references to content so MUST stay in scope for lifetime of doc, or until doc.clear() is called

Return values:

bool – false on parse error

static inline bool deserialize(Document &doc, String &content)
bool deserialize(Document &doc, const FlashString &content)

Unnamed Group

size_t serialize(const Node &node, String &buffer, bool pretty = false)

Serialize XML text and append to string buffer.

Return values:

size_t – number of characters written

String serialize(const Node &node, bool pretty = false)
size_t serialize(const Node &node, Print &out, bool pretty = false)
static inline size_t serialize(const Node &node, Print *out, bool pretty = false)

Unnamed Group

Node *appendNode(Node *parent, const char *name, const char *value = nullptr, size_t name_size = 0, size_t value_size = 0)

Append a child element with optional value.

Note

If provide, sizes do not include nul-terminator Node MUST already be added to the document tree

Parameters:

  • parent – Node to append child to

  • name – Name of child node (copy taken)

  • value – Optional node value (copy taken)

Return values:

Node* – Child node

static inline Node *appendNode(Node *parent, const String &name, const String &value = nullptr)
Node *appendNode(Node *parent, const String &name, const FlashString &value)
template<typename TString, typename TValue>
Node *appendNode(Node *parent, const TString &name, const TValue &value)

Unnamed Group

Attribute *appendAttribute(Node *node, const char *name, const char *value, size_t name_size = 0, size_t value_size = 0)

Append an attribute.

Parameters:

  • parent – Node to append child to

  • name – Name of attribute (copy taken)

  • value – Value string (copy taken)

  • Attribute* – New attribute

static inline Attribute *appendAttribute(Node *node, const String &name, const String &value)
template<typename TString, typename TValue>
Attribute *appendAttribute(Node *node, const TString &name, const TValue &value)

Gets child node by relative path

Leading/trailing separators are not permitted.

param doc:

param path:

Node path using slash as separator

param ns:

Optional namespace

retval Node*:

nullptr if none is found

Node *getNode(Node *node, const char *path, const char *ns, size_t ns_len = 0)
inline Node *getNode(Node *node, const String &path, const String &ns = nullptr)

Gets node from a document by path

Leading separator is important: if present, search starts at root node. If omitted, first element must match the root node name.

param doc:

param path:

Node path using slash as separator

param ns:

Optional namespace

retval Node*:

nullptr if none is found

Trailing separator is not allowed.

Example 1: /s:Body/u:GetContentResponse Will search for s:Body node that is a child of the root node. The node u:GetContentResponse should be child of the s:Body node

Example 2: s:Envelope/s:Body/u:GetContentResponse Will search for s:Body node that is a child of the root node named s:Envelope. The node u:GetContentResponse should be child of the s:Body node

Node *getNode(const Document &doc, const char *path, const char *ns = nullptr, size_t ns_len = 0)
inline Node *getNode(const Document &doc, const String &path, const String &ns = nullptr)

Get node value

param node:

param name:

param name_size:

retval String:

invalid if node or name not found

String getValue(const Node *node, const char *name, size_t name_size, const char *ns = nullptr, size_t ns_size = 0)
inline String getValue(const Node *node, const char *name, const char *ns = nullptr)
inline String getValue(const Node *node, const String &name, const String &ns = nullptr)

Get attribute value

param node:

param name:

param name_size:

retval String:

invalid if node or name not found

String getAttribute(const Node *node, const char *name, size_t name_size)
inline String getAttribute(const Node *node, const char *name)
inline String getAttribute(const Node *node, const String &name)

Typedefs

using Document = rapidxml::xml_document<char>
using Node = rapidxml::xml_node<char>
using NodeType = rapidxml::node_type
using Attribute = rapidxml::xml_attribute<char>

Functions

Node *insertDeclaration(Document &doc)

Add a declaration to the document if there isn’t one already.

Note

By default, declarations are included when parsed during de-serialisation. If you need one in the output serialisation, call this function. (We’re talking about the “<?xml version=”1.0” ?>” at the start)

References

Used by

SoC support

  • esp32

  • esp32c2

  • esp32c3

  • esp32s2

  • esp32s3

  • esp8266

  • host

  • rp2040

  • rp2350