Radek Krejci | d91dbaf | 2018-09-21 15:51:39 +0200 | [diff] [blame] | 1 | /** |
| 2 | * @file xml.h |
| 3 | * @author Radek Krejci <rkrejci@cesnet.cz> |
| 4 | * @brief Generic XML parser routines. |
| 5 | * |
| 6 | * Copyright (c) 2015 - 2018 CESNET, z.s.p.o. |
| 7 | * |
| 8 | * This source code is licensed under BSD 3-Clause License (the "License"). |
| 9 | * You may not use this file except in compliance with the License. |
| 10 | * You may obtain a copy of the License at |
| 11 | * |
| 12 | * https://opensource.org/licenses/BSD-3-Clause |
| 13 | */ |
| 14 | |
| 15 | #ifndef LY_XML_H_ |
| 16 | #define LY_XML_H_ |
| 17 | |
| 18 | #include <stdint.h> |
| 19 | |
| 20 | #include "context.h" |
| 21 | #include "set.h" |
| 22 | |
| 23 | struct lyxml_ns { |
Radek Krejci | 4b74d5e | 2018-09-26 14:30:55 +0200 | [diff] [blame] | 24 | const char *element; /* element where the namespace is defined */ |
| 25 | char *prefix; /* prefix of the namespace, NULL for the default namespace */ |
| 26 | char *uri; /* namespace URI */ |
Radek Krejci | d91dbaf | 2018-09-21 15:51:39 +0200 | [diff] [blame] | 27 | }; |
| 28 | |
| 29 | enum LYXML_PARSER_STATUS { |
| 30 | LYXML_STATUS_CDSECT, /* CDATA section */ |
| 31 | LYXML_STATUS_COMMENT, /* XML comment */ |
| 32 | }; |
| 33 | |
| 34 | struct lyxml_context { |
| 35 | struct ly_ctx *ctx; |
| 36 | uint64_t line; |
Radek Krejci | 4b74d5e | 2018-09-26 14:30:55 +0200 | [diff] [blame] | 37 | struct ly_set ns; /* handled with LY_SET_OPT_USEASLIST */ |
Radek Krejci | d91dbaf | 2018-09-21 15:51:39 +0200 | [diff] [blame] | 38 | }; |
| 39 | |
Radek Krejci | 4b74d5e | 2018-09-26 14:30:55 +0200 | [diff] [blame] | 40 | /** |
| 41 | * @brief Parse input expecting an XML element. |
| 42 | * |
| 43 | * Able to silently skip comments, PIs and CData. DOCTYPE is not parsable, so it is reported as LY_EVALID error. |
| 44 | * If '<' is not found in input, LY_EINVAL is returned (but no error is logged), so it is possible to continue |
| 45 | * with parsing input as text content. |
| 46 | * |
| 47 | * Input string is not being modified, so the returned values are not NULL-terminated, instead their length |
| 48 | * is returned. |
| 49 | * |
| 50 | * @param[in] context XML context to track lines or store errors into libyang context. |
| 51 | * @param[in,out] input Input string to process, updated according to the processed/read data. |
| 52 | * @param[in] options Currently unused options to modify input processing. |
| 53 | * @param[out] prefix Pointer to prefix if present in the element name, NULL otherwise. |
| 54 | * @param[out] prefix_len Length of the prefix if any. |
| 55 | * @param[out] name Element name. LY_SUCCESS can be returned with NULL name only in case the |
| 56 | * end of the input string was reached (EOF). |
| 57 | * @param[out] name_len Length of the element name. |
| 58 | * @return LY_ERR values. |
| 59 | */ |
| 60 | LY_ERR lyxml_get_element(struct lyxml_context *context, const char **input, |
| 61 | const char **prefix, size_t *prefix_len, const char **name, size_t *name_len); |
| 62 | |
| 63 | /** |
| 64 | * @brief Parse input expecting an XML attribute (including XML namespace). |
| 65 | * |
| 66 | * Input string is not being modified, so the returned values are not NULL-terminated, instead their length |
| 67 | * is returned. |
| 68 | * |
| 69 | * In case of a namespace definition, prefix just contains xmlns string. In case of the default namespace, |
| 70 | * prefix is NULL and the attribute name is xmlns. |
| 71 | * |
| 72 | * @param[in] context XML context to track lines or store errors into libyang context. |
| 73 | * @param[in,out] input Input string to process, updated according to the processed/read data so, |
| 74 | * when succeeded, it points to the opening quote of the attribute's value. |
| 75 | * @param[out] prefix Pointer to prefix if present in the attribute name, NULL otherwise. |
| 76 | * @param[out] prefix_len Length of the prefix if any. |
| 77 | * @param[out] name Attribute name. LY_SUCCESS can be returned with NULL name only in case the |
| 78 | * end of the element tag was reached. |
| 79 | * @param[out] name_len Length of the element name. |
| 80 | * @return LY_ERR values. |
| 81 | */ |
| 82 | LY_ERR lyxml_get_attribute(struct lyxml_context *context, const char **input, |
| 83 | const char **prefix, size_t *prefix_len, const char **name, size_t *name_len); |
| 84 | |
| 85 | /** |
| 86 | * @brief Parse input as XML text (attribute's values and element's content). |
| 87 | * |
| 88 | * Mixed content of XML elements is not allowed. Formating whitespaces before child element are ignored, |
| 89 | * LY_EINVAL is returned in such a case (buffer is not filled, no error is printed) and input is moved |
| 90 | * to the beginning of a child definition. |
| 91 | * |
| 92 | * In the case of attribute's values, the input string is expected to start on a quotation mark to |
| 93 | * select which delimiter (single or double quote) is used. Otherwise, the element content is being |
| 94 | * parsed expected to be terminated by '<' character. |
| 95 | * |
| 96 | * If function succeeds, the string in output buffer is always NULL-terminated. |
| 97 | * |
| 98 | * @param[in] context XML context to track lines or store errors into libyang context. |
| 99 | * @param[in,out] input Input string to process, updated according to the processed/read data. |
| 100 | * @param[out] buffer Storage of the output string. If NULL, the buffer is allocated. Otherwise, the buffer |
| 101 | * is used and enlarged when necessary. |
| 102 | * @param[out] buffer_size Allocated size of the returned buffer. If a buffer is provided by a caller, it |
| 103 | * is not being reduced even if the string is shorter. On the other hand, it can be enlarged if needed. |
| 104 | * @return LY_ERR value. |
| 105 | */ |
| 106 | LY_ERR lyxml_get_string(struct lyxml_context *context, const char **input, char **buffer, size_t *buffer_size); |
| 107 | |
| 108 | /** |
| 109 | * @brief Add namespace definition into XML context. |
| 110 | * |
| 111 | * Namespaces from a single element are supposed to be added sequentially together (not interleaved by a namespace from other |
| 112 | * element). This mimic namespace visibility, since the namespace defined in element E is not visible from its parents or |
| 113 | * siblings. On the other hand, namespace from a parent element can be redefined in a child element. This is also reflected |
| 114 | * by lyxml_ns_get() which returns the most recent namespace definition for the given prefix. |
| 115 | * |
| 116 | * When leaving processing of a subtree of some element, caller is supposed to call lyxml_ns_rm() to remove all the namespaces |
| 117 | * defined in such an element from the context. |
| 118 | * |
| 119 | * @param[in] context XML context to work with. |
| 120 | * @param[in] element_name Pointer to the element name where the namespace is defined. Serve as an identifier to select |
| 121 | * which namespaces are supposed to be removed via lyxml_ns_rm() when leaving the element's subtree. |
| 122 | * @param[in] prefix Pointer to the namespace prefix as taken from lyxml_get_attribute(). Can be NULL for default namespace. |
| 123 | * @param[in] prefix_len Length of the prefix string (since it is not NULL-terminated when returned from lyxml_get_attribute()). |
| 124 | * @param[in] uri Namespace URI (value) to store. Value can be obtained via lyxml_get_string() and caller is not supposed to |
| 125 | * work with the pointer when the function succeeds. |
| 126 | * @return LY_ERR values. |
| 127 | */ |
| 128 | LY_ERR lyxml_ns_add(struct lyxml_context *context, const char *element_name, const char *prefix, size_t prefix_len, char *uri); |
| 129 | |
| 130 | /** |
| 131 | * @brief Get a namespace record for the given prefix in the current context. |
| 132 | * |
| 133 | * @param[in] context XML context to work with. |
| 134 | * @param[in] prefix Pointer to the namespace prefix as taken from lyxml_get_attribute() or lyxml_get_element(). |
| 135 | * Can be NULL for default namespace. |
| 136 | * @param[in] prefix_len Length of the prefix string (since it is not NULL-terminated when returned from lyxml_get_attribute() or |
| 137 | * lyxml_get_element()). |
| 138 | * @return The namespace record or NULL if the record for the specified prefix not found. |
| 139 | */ |
| 140 | const struct lyxml_ns *lyxml_ns_get(struct lyxml_context *context, const char *prefix, size_t prefix_len); |
| 141 | |
| 142 | /** |
| 143 | * @brief Remove all the namespaces defined in the given element. |
| 144 | * |
| 145 | * @param[in] context XML context to work with. |
| 146 | * @param[in] element_name Pointer to the element name where the namespaces are defined. Serve as an identifier previously provided |
| 147 | * by lyxml_get_element() |
| 148 | * @return LY_ERR values. |
| 149 | */ |
| 150 | LY_ERR lyxml_ns_rm(struct lyxml_context *context, const char *element_name); |
Radek Krejci | b416be6 | 2018-10-01 14:51:45 +0200 | [diff] [blame] | 151 | |
| 152 | #endif /* LY_XML_H_ */ |