diff options
Diffstat (limited to 'src/parser_data.h')
| -rw-r--r-- | src/parser_data.h | 108 |
1 files changed, 89 insertions, 19 deletions
diff --git a/src/parser_data.h b/src/parser_data.h index 050ced3..feedb14 100644 --- a/src/parser_data.h +++ b/src/parser_data.h @@ -1,9 +1,10 @@ /** * @file parser_data.h * @author Radek Krejci <rkrejci@cesnet.cz> + * @author Michal Vasko <mvasko@cesnet.cz> * @brief Data parsers for libyang * - * Copyright (c) 2015-2020 CESNET, z.s.p.o. + * Copyright (c) 2015-2023 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. @@ -156,9 +157,14 @@ struct ly_in; modified manually. If this flag is used incorrectly (for unordered data), the behavior is undefined and most functions executed with these data will not work correctly. */ -#define LYD_PARSE_SUBTREE 0x400000 /**< Parse only the current data subtree with any descendants, no siblings. +#define LYD_PARSE_SUBTREE 0x400000 /**< Parse only the first child item along with any descendants, but no + siblings. This flag is not required when parsing data which do not + start at the schema root; for that purpose, use lyd_parse_data's parent + argument. Also, a new return value ::LY_ENOT is returned if there is a sibling - subtree following in the input data. */ + subtree following in the input data. Note that if validation is requested, + only the newly parsed subtree is validated. This might result in + an invalid datastore content. */ #define LYD_PARSE_WHEN_TRUE 0x800000 /**< Mark all the parsed nodes dependend on a when condition with the flag that means the condition was satisifed before. This allows for auto-deletion of these nodes during validation. */ @@ -196,6 +202,15 @@ struct ly_in; #define LYD_VALIDATE_NO_STATE 0x0001 /**< Consider state data not allowed and raise an error if they are found. Also, no implicit state data are added. */ #define LYD_VALIDATE_PRESENT 0x0002 /**< Validate only modules whose data actually exist. */ +#define LYD_VALIDATE_MULTI_ERROR 0x0004 /**< Do not stop validation on the first error but generate all the detected errors. */ +#define LYD_VALIDATE_OPERATIONAL 0x0008 /**< Semantic constraint violations are reported only as warnings instead of + errors (see [RFC 8342 sec. 5.3](https://datatracker.ietf.org/doc/html/rfc8342#section-5.3)). */ +#define LYD_VALIDATE_NO_DEFAULTS 0x0010 /**< Do not add any default nodes during validation, other implicit nodes + (such as NP containers) are still added. Validation will fail if a + default node is required for it to pass. */ +#define LYD_VALIDATE_NOT_FINAL 0x0020 /**< Skip final validation tasks that require for all the data nodes to + either exist or not, based on the YANG constraints. Once the data + satisfy this requirement, the final validation should be performed. */ #define LYD_VALIDATE_OPTS_MASK 0x0000FFFF /**< Mask for all the LYD_VALIDATE_* options. */ @@ -205,7 +220,8 @@ struct ly_in; * @brief Parse (and validate) data from the input handler as a YANG data tree. * * @param[in] ctx Context to connect with the tree being built here. - * @param[in] parent Optional parent to connect the parsed nodes to. + * @param[in] parent Optional parent to connect the parsed nodes to. If provided, the data are expected to describe + * a subtree of the YANG model instead of starting at the schema root. * @param[in] in The input handle to provide the dumped data in the specified @p format to parse (and validate). * @param[in] format Format of the input data to be parsed. Can be 0 to try to detect format from the input handler. * @param[in] parse_options Options for parser, see @ref dataparseroptions. @@ -213,6 +229,11 @@ struct ly_in; * @param[out] tree Full parsed data tree, note that NULL can be a valid tree. If @p parent is set, set to NULL. * @return LY_SUCCESS in case of successful parsing (and validation). * @return LY_ERR value in case of error. Additional error information can be obtained from the context using ly_err* functions. + * + * When parsing subtrees (i.e., when @p parent is non-NULL), validation is only performed on the newly parsed data. + * This might result in allowing invalid datastore content when the schema contains cross-branch constraints, + * complicated `must` statements, etc. When a full-datastore validation is desirable, parse all subtrees + * first, and then request validation of the complete datastore content. */ LIBYANG_API_DECL LY_ERR lyd_parse_data(const struct ly_ctx *ctx, struct lyd_node *parent, struct ly_in *in, LYD_FORMAT format, uint32_t parse_options, uint32_t validate_options, struct lyd_node **tree); @@ -303,26 +324,35 @@ LIBYANG_API_DECL LY_ERR lyd_parse_ext_data(const struct lysc_ext_instance *ext, * @{ */ enum lyd_type { - LYD_TYPE_DATA_YANG = 0, /* generic YANG instance data */ - LYD_TYPE_RPC_YANG, /* instance of a YANG RPC/action request with only "input" data children, - including all parents in case of an action */ - LYD_TYPE_NOTIF_YANG, /* instance of a YANG notification, including all parents in case of a nested one */ - LYD_TYPE_REPLY_YANG, /* instance of a YANG RPC/action reply with only "output" data children, - including all parents in case of an action */ + LYD_TYPE_DATA_YANG = 0, /* generic YANG instance data */ + LYD_TYPE_RPC_YANG, /* instance of a YANG RPC/action request with only "input" data children, + including all parents and optional top-level "action" element in case of an action */ + LYD_TYPE_NOTIF_YANG, /* instance of a YANG notification, including all parents in case of a nested one */ + LYD_TYPE_REPLY_YANG, /* instance of a YANG RPC/action reply with only "output" data children, + including all parents in case of an action */ + + LYD_TYPE_RPC_NETCONF, /* complete NETCONF RPC invocation as defined for + [RPC](https://tools.ietf.org/html/rfc7950#section-7.14.4) and + [action](https://tools.ietf.org/html/rfc7950#section-7.15.2) */ + LYD_TYPE_NOTIF_NETCONF, /* complete NETCONF notification message as defined for + [notification](https://tools.ietf.org/html/rfc7950#section-7.16.2) */ + LYD_TYPE_REPLY_NETCONF, /* complete NETCONF RPC reply as defined for + [RPC](https://tools.ietf.org/html/rfc7950#section-7.14.4) and + [action](https://tools.ietf.org/html/rfc7950#section-7.15.2) */ - LYD_TYPE_RPC_NETCONF, /* complete NETCONF RPC invocation as defined for - [RPC](https://tools.ietf.org/html/rfc7950#section-7.14.4) and - [action](https://tools.ietf.org/html/rfc7950#section-7.15.2) */ - LYD_TYPE_NOTIF_NETCONF, /* complete NETCONF notification message as defined for - [notification](https://tools.ietf.org/html/rfc7950#section-7.16.2) */ - LYD_TYPE_REPLY_NETCONF /* complete NETCONF RPC reply as defined for - [RPC](https://tools.ietf.org/html/rfc7950#section-7.14.4) and - [action](https://tools.ietf.org/html/rfc7950#section-7.15.2) */ + LYD_TYPE_RPC_RESTCONF, /* message-body of a RESTCONF operation input parameters + ([ref](https://www.rfc-editor.org/rfc/rfc8040.html#section-3.6.1)) */ + LYD_TYPE_NOTIF_RESTCONF, /* RESTCONF JSON notification data + ([ref](https://www.rfc-editor.org/rfc/rfc8040.html#section-6.4)), to parse + a notification in XML, use ::LYD_TYPE_NOTIF_NETCONF */ + LYD_TYPE_REPLY_RESTCONF /* message-body of a RESTCONF operation output parameters + ([ref](https://www.rfc-editor.org/rfc/rfc8040.html#section-3.6.2)) */ }; /** @} datatype */ /** - * @brief Parse YANG data into an operation data tree. + * @brief Parse YANG data into an operation data tree. Specific parsing flags ::LYD_PARSE_ONLY, ::LYD_PARSE_STRICT and + * no validation flags are used. * * At least one of @p parent, @p tree, or @p op must always be set. * @@ -349,6 +379,28 @@ enum lyd_type { * - @p op - must be NULL, the reply is appended to the RPC; * Note that there are 3 kinds of NETCONF replies - ok, error, and data. Only data reply appends any nodes to the RPC. * + * - ::LYD_TYPE_RPC_RESTCONF: + * - @p parent - must be set, pointing to the invoked RPC operation (RPC or action) node; + * - @p format - can be both ::LYD_JSON and ::LYD_XML; + * - @p tree - must be provided, all the RESTCONF-specific JSON objects will be returned here as + * a separate opaque data tree, even if the function fails, this may be returned; + * - @p op - must be NULL, @p parent points to the operation; + * + * - ::LYD_TYPE_NOTIF_RESTCONF: + * - @p parent - must be NULL, the whole notification is expected; + * - @p format - must be ::LYD_JSON, XML-formatted notifications are parsed using ::LYD_TYPE_NOTIF_NETCONF; + * - @p tree - must be provided, all the RESTCONF-specific JSON objects will be returned here as + * a separate opaque data tree, even if the function fails, this may be returned; + * - @p op - must be provided, the notification data tree itself will be returned here, pointing to the operation; + * + * - ::LYD_TYPE_REPLY_RESTCONF: + * - @p parent - must be set, pointing to the invoked RPC operation (RPC or action) node; + * - @p format - can be both ::LYD_JSON and ::LYD_XML; + * - @p tree - must be provided, all the RESTCONF-specific JSON objects will be returned here as + * a separate opaque data tree, even if the function fails, this may be returned; + * - @p op - must be NULL, @p parent points to the operation; + * Note that error reply should be parsed as 'yang-data' extension data. + * * @param[in] ctx libyang context. * @param[in] parent Optional parent to connect the parsed nodes to. * @param[in] in Input handle to read the input from. @@ -427,6 +479,10 @@ LIBYANG_API_DECL LY_ERR lyd_validate_all(struct lyd_node **tree, const struct ly * The data tree is modified in-place. As a result of the validation, some data might be removed * from the tree. In that case, the removed items are freed, not just unlinked. * + * If several modules need to be validated, the flag ::LYD_VALIDATE_NOT_FINAL should be used first for validation + * of each module and then ::lyd_validate_module_final() should be called also for each module. Otherwise, + * false-positive validation errors for foreign dependencies may occur. + * * @param[in,out] tree Data tree to recursively validate. May be changed by validation, might become NULL. * @param[in] module Module whose data (and schema restrictions) to validate. * @param[in] val_opts Validation options (@ref datavalidationoptions). @@ -438,6 +494,20 @@ LIBYANG_API_DECL LY_ERR lyd_validate_module(struct lyd_node **tree, const struct struct lyd_node **diff); /** + * @brief Finish validation of a module data that have previously been validated with ::LYD_VALIDATE_NOT_FINAL flag. + * + * This final validation will not add or remove any nodes. + * + * @param[in] tree Data tree to recursively validate. + * @param[in] module Module whose data (and schema restrictions) to validate. + * @param[in] val_opts Validation options (@ref datavalidationoptions). + * @return LY_SUCCESS on success. + * @return LY_ERR error on error. + */ +LIBYANG_API_DECL LY_ERR lyd_validate_module_final(struct lyd_node *tree, const struct lys_module *module, + uint32_t val_opts); + +/** * @brief Validate an RPC/action request, reply, or notification. Only the operation data tree (input/output/notif) * is validate, any parents are ignored. * |