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

Returns

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.

Returns

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)

Returns

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

returns 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

returns 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

returns 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

returns 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

  • esp32c3

  • esp32s2

  • esp32s3

  • esp8266

  • host

  • rp2040