blob: f42b27ed47868b97641d62bb56e9ec51fdaa5214 [file] [log] [blame]
/**
* @file xml.h
* @author Radek Krejci <rkrejci@cesnet.cz>
* @brief Generic XML parser routines.
*
* Copyright (c) 2015 - 2018 CESNET, z.s.p.o.
*
* This source code is licensed under BSD 3-Clause License (the "License").
* You may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://opensource.org/licenses/BSD-3-Clause
*/
#ifndef LY_XML_H_
#define LY_XML_H_
#include <stdint.h>
#include "context.h"
#include "set.h"
struct lyxml_ns {
const char *element; /* element where the namespace is defined */
char *prefix; /* prefix of the namespace, NULL for the default namespace */
char *uri; /* namespace URI */
};
/* element tag identifier for matching opening and closing tags */
struct lyxml_elem {
const char *prefix;
const char *name;
size_t prefix_len;
size_t name_len;
};
enum LYXML_PARSER_STATUS {
LYXML_ELEMENT, /* expecting XML element, call lyxml_get_element() */
LYXML_ELEM_CONTENT, /* expecting content of an element, call lyxml_get_string */
LYXML_ATTRIBUTE, /* expecting XML attribute, call lyxml_get_attribute() */
LYXML_ATTR_CONTENT, /* expecting value of an attribute, call lyxml_get_string */
LYXML_END /* end of input data */
};
struct lyxml_context {
struct ly_ctx *ctx;
uint64_t line;
enum LYXML_PARSER_STATUS status; /* status providing information about the next expected object in input data */
struct ly_set elements; /* list of not-yet-closed elements */
struct ly_set ns; /* handled with LY_SET_OPT_USEASLIST */
};
/**
* @brief Parse input expecting an XML element.
*
* Able to silently skip comments, PIs and CData. DOCTYPE is not parsable, so it is reported as LY_EVALID error.
* If '<' is not found in input, LY_EINVAL is returned (but no error is logged), so it is possible to continue
* with parsing input as text content.
*
* Input string is not being modified, so the returned values are not NULL-terminated, instead their length
* is returned.
*
* @param[in] context XML context to track lines or store errors into libyang context.
* @param[in,out] input Input string to process, updated according to the processed/read data.
* @param[in] options Currently unused options to modify input processing.
* @param[out] prefix Pointer to prefix if present in the element name, NULL otherwise.
* @param[out] prefix_len Length of the prefix if any.
* @param[out] name Element name. When LY_SUCCESS is returned but name is NULL, check context's status field:
* - LYXML_END - end of input was reached
* - LYXML_ELEMENT - closing element found, expecting sibling element so call lyxml_get_element() again
* @param[out] name_len Length of the element name.
* @return LY_ERR values.
*/
LY_ERR lyxml_get_element(struct lyxml_context *context, const char **input,
const char **prefix, size_t *prefix_len, const char **name, size_t *name_len);
/**
* @brief Parse input expecting an XML attribute (including XML namespace).
*
* Input string is not being modified, so the returned values are not NULL-terminated, instead their length
* is returned.
*
* In case of a namespace definition, prefix just contains xmlns string. In case of the default namespace,
* prefix is NULL and the attribute name is xmlns.
*
* @param[in] context XML context to track lines or store errors into libyang context.
* @param[in,out] input Input string to process, updated according to the processed/read data so,
* when succeeded, it points to the opening quote of the attribute's value.
* @param[out] prefix Pointer to prefix if present in the attribute name, NULL otherwise.
* @param[out] prefix_len Length of the prefix if any.
* @param[out] name Attribute name. LY_SUCCESS can be returned with NULL name only in case the
* end of the element tag was reached. According to the context's status field, the opening tag was read
* (LYXML_CONTENT) or empty element was closed (LYXML_ELEMENT).
* @param[out] name_len Length of the element name.
* @return LY_ERR values.
*/
LY_ERR lyxml_get_attribute(struct lyxml_context *context, const char **input,
const char **prefix, size_t *prefix_len, const char **name, size_t *name_len);
/**
* @brief Parse input as XML text (attribute's values and element's content).
*
* Mixed content of XML elements is not allowed. Formating whitespaces before child element are ignored,
* LY_EINVAL is returned in such a case (output is not set, no error is printed) and input is moved
* to the beginning of a child definition.
*
* In the case of attribute's values, the input string is expected to start on a quotation mark to
* select which delimiter (single or double quote) is used. Otherwise, the element content is being
* parsed expected to be terminated by '<' character.
*
* If function succeeds, the string in a dynamically allocated output buffer is always NULL-terminated.
*
* The dynamically allocated buffer is used only when necessary because of a character or the supported entity
* reference which modify the input data. These constructs are replaced by their real value, so in case the output
* string will be again printed as an XML data, it may be necessary to correctly encode such characters.
*
* @param[in] context XML context to track lines or store errors into libyang context.
* @param[in,out] input Input string to process, updated according to the processed/read data.
* @param[in, out] buffer Storage for the output string. If the parameter points to NULL, the buffer is allocated if needed.
* Otherwise, when needed, the buffer is used and enlarged when necessary. Whenever the buffer is used, the string is NULL-terminated.
* @param[in, out] buffer_size Allocated size of the returned buffer. If a buffer is provided by a caller, it
* is not being reduced even if the string is shorter. On the other hand, it can be enlarged if needed.
* @param[out] output Returns pointer to the resulting string - to the provided/allocated buffer if it was necessary to modify
* the input string or directly into the input string (see the \p dynamic parameter).
* @param[out] length Length of the \p output string.
* @param[out] dynamic Flag if a dynamically allocated memory (\p buffer) was used and caller is supposed to free it at the end.
* In case the value is zero, the \p output points directly into the \p input string.
* @return LY_ERR value.
*/
LY_ERR lyxml_get_string(struct lyxml_context *context, const char **input, char **buffer, size_t *buffer_size, char **output, size_t *length, int *dynamic);
/**
* @brief Add namespace definition into XML context.
*
* Namespaces from a single element are supposed to be added sequentially together (not interleaved by a namespace from other
* element). This mimic namespace visibility, since the namespace defined in element E is not visible from its parents or
* siblings. On the other hand, namespace from a parent element can be redefined in a child element. This is also reflected
* by lyxml_ns_get() which returns the most recent namespace definition for the given prefix.
*
* When leaving processing of a subtree of some element, caller is supposed to call lyxml_ns_rm() to remove all the namespaces
* defined in such an element from the context.
*
* @param[in] context XML context to work with.
* @param[in] element_name Pointer to the element name where the namespace is defined. Serve as an identifier to select
* which namespaces are supposed to be removed via lyxml_ns_rm() when leaving the element's subtree.
* @param[in] prefix Pointer to the namespace prefix as taken from lyxml_get_attribute(). Can be NULL for default namespace.
* @param[in] prefix_len Length of the prefix string (since it is not NULL-terminated when returned from lyxml_get_attribute()).
* @param[in] uri Namespace URI (value) to store. Value can be obtained via lyxml_get_string() and caller is not supposed to
* work with the pointer when the function succeeds.
* @return LY_ERR values.
*/
LY_ERR lyxml_ns_add(struct lyxml_context *context, const char *element_name, const char *prefix, size_t prefix_len, char *uri);
/**
* @brief Get a namespace record for the given prefix in the current context.
*
* @param[in] context XML context to work with.
* @param[in] prefix Pointer to the namespace prefix as taken from lyxml_get_attribute() or lyxml_get_element().
* Can be NULL for default namespace.
* @param[in] prefix_len Length of the prefix string (since it is not NULL-terminated when returned from lyxml_get_attribute() or
* lyxml_get_element()).
* @return The namespace record or NULL if the record for the specified prefix not found.
*/
const struct lyxml_ns *lyxml_ns_get(struct lyxml_context *context, const char *prefix, size_t prefix_len);
/**
* @brief Remove all the namespaces defined in the given element.
*
* @param[in] context XML context to work with.
* @param[in] element_name Pointer to the element name where the namespaces are defined. Serve as an identifier previously provided
* by lyxml_get_element()
* @return LY_ERR values.
*/
LY_ERR lyxml_ns_rm(struct lyxml_context *context, const char *element_name);
/**
* @brief Remove the allocated working memory of the context.
*
* @param[in] context XML context to clear.
*/
void lyxml_context_clear(struct lyxml_context *context);
#endif /* LY_XML_H_ */