1/** 2 * @file libyang.h 3 * @author Radek Krejci <rkrejci@cesnet.cz> 4 * @brief The main libyang public header. 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_LIBYANG_H_ 16#define LY_LIBYANG_H_ 17 18#include <stdio.h> 19 20/** 21 * @brief Whether to enable schema and data cache. 22 */ 23#cmakedefine LY_ENABLED_CACHE 24 25/** 26 * @brief Whether to allow reusing latest revisions of schemas. 27 */ 28#cmakedefine LY_ENABLED_LATEST_REVISIONS 29 30/** 31 * @brief Whether to add priv pointer to struct lyd_node. 32 */ 33#cmakedefine LY_ENABLED_LYD_PRIV 34 35/** 36 * @brief Compiler flag for packed data types. 37 */ 38#define _PACKED @COMPILER_PACKED_ATTR@ 39 40#include "tree_schema.h" 41#include "tree_data.h" 42#include "xml.h" 43#include "dict.h" 44 45#ifdef __cplusplus 46extern "C" { 47#endif 48 49#define LY_VERSION_MAJOR @LIBYANG_MAJOR_SOVERSION@ /**< libyang major version number */ 50#define LY_VERSION_MINOR @LIBYANG_MINOR_SOVERSION@ /**< libyang minor version number */ 51#define LY_VERSION_MICRO @LIBYANG_MICRO_SOVERSION@ /**< libyang micro version number */ 52#define LY_VERSION "@LIBYANG_SOVERSION_FULL@" /**< libyang version string */ 53 54/** 55 * @mainpage About 56 * 57 * libyang is a library implementing processing of the YANG schemas and data modeled by the YANG language. The 58 * library is implemented in C for GNU/Linux and provides C API. 59 * 60 * @section about-features Main Features 61 * 62 * - [Parsing (and validating) schemas](@ref howtoschemasparsers) in YANG format. 63 * - [Parsing (and validating) schemas](@ref howtoschemasparsers) in YIN format. 64 * - [Parsing, validating and printing instance data](@ref howtodata) in XML format. 65 * - [Parsing, validating and printing instance data](@ref howtodata) in JSON format 66 * ([RFC 7951](https://tools.ietf.org/html/rfc7951)). 67 * - [Manipulation with the instance data](@ref howtodatamanipulators). 68 * - Support for [default values in the instance data](@ref howtodatawd) ([RFC 6243](https://tools.ietf.org/html/rfc6243)). 69 * - Support for [YANG extensions and user types](@ref howtoschemaplugins). 70 * - Support for [YANG Metadata](@ref howtoschemametadata) ([RFC 7952](https://tools.ietf.org/html/rfc6243)). 71 * 72 * The current implementation covers YANG 1.0 ([RFC 6020](https://tools.ietf.org/html/rfc6020)) as well as 73 * YANG 1.1 ([RFC 7950](https://tools.ietf.org/html/rfc7950)). 74 * 75 * @subsection about-features-others Extra (side-effect) Features 76 * 77 * - XML parser. 78 * - Optimized string storage (dictionary). 79 * 80 * @section about-license License 81 * 82 * Copyright (c) 2015-2017 CESNET, z.s.p.o. 83 * 84 * (The BSD 3-Clause License) 85 * 86 * Redistribution and use in source and binary forms, with or without 87 * modification, are permitted provided that the following conditions 88 * are met: 89 * 1. Redistributions of source code must retain the above copyright 90 * notice, this list of conditions and the following disclaimer. 91 * 2. Redistributions in binary form must reproduce the above copyright 92 * notice, this list of conditions and the following disclaimer in 93 * the documentation and/or other materials provided with the 94 * distribution. 95 * 3. Neither the name of the Company nor the names of its contributors 96 * may be used to endorse or promote products derived from this 97 * software without specific prior written permission. 98 */ 99 100/** 101 * @page howto How To ... 102 * 103 * - @subpage howtocontext 104 * - @subpage howtoschemas 105 * - @subpage howtodata 106 * - @subpage howtoxpath 107 * - @subpage howtoxml 108 * - @subpage howtothreads 109 * - @subpage howtologger 110 */ 111 112/** @page howtocontext Context 113 * 114 * The context concept allows callers to work in environments with different sets of YANG schemas. 115 * 116 * The first step in libyang is to create a new context using ly_ctx_new(). It returns a handler 117 * used in the following work. 118 * 119 * When creating a new context, search dir can be specified (NULL is accepted) to provide directory 120 * where libyang will automatically search for schemas being imported or included. The search path 121 * can be later changed via ly_ctx_set_searchdir() and ly_ctx_unset_searchdirs() functions. Before the search dirs, 122 * also the current working directory is (non-recursively) searched. For the case of the explicitly set search 123 * dirs, also all their subdirectories (and symlinks) are taken into account. Searching in the current working 124 * directory can be avoided with context's #LY_CTX_DISABLE_SEARCHDIR_CWD option (or via ly_ctx_set_disable_searchdir_cwd()). 125 * Searching in all the context's search dirs (without removing them) can be avoided with the context's 126 * #LY_CTX_DISABLE_SEARCHDIRS option (or via ly_ctx_set_disable_searchdirs()). This automatic searching can be preceded 127 * by a custom module searching callback (#ly_module_imp_clb) set via ly_ctx_set_module_imp_clb(). The algorithm of 128 * searching in search dirs is also available via API as lys_search_localfile() function. 129 * 130 * Schemas are added into the context using [parser functions](@ref howtoschemasparsers) - \b lys_parse_*(). 131 * In case of schemas, also ly_ctx_load_module() can be used - in that case the #ly_module_imp_clb or automatic 132 * search in search dir and in the current working directory is used. 133 * 134 * Similarly, data trees can be parsed by \b lyd_parse_*() functions. Note, that functions for schemas have \b lys_ 135 * prefix while functions for instance data have \b lyd_ prefix. It can happen during data parsing that a schema is 136 * required and __not found__ in the context or the schema is found, but is __only imported__, not implemented (so the 137 * data cannot actually be instantiated). In these cases, a callback is called, which should add this schema into 138 * the context or change its conformance to implemented. You can set the callback using ly_ctx_set_module_data_clb() 139 * (more in @ref howtodataparsers and @ref howtodatavalidation). 140 * 141 * Context can hold multiple revisions of the same schema, but only one of them can be implemented. The schema is not 142 * implemented in case it is automatically loaded as import for another module and it is not referenced in such 143 * a module (and no other) as target of leafref, augment or deviation. All modules with deviation definition are always 144 * marked as implemented. The imported (not implemented) module can be set implemented by lys_set_implemented(). But 145 * the implemented module cannot be changed back to just imported module. The imported modules are used only as a 146 * source of definitions for types and groupings for uses statements. The data in such modules are ignored - caller 147 * is not allowed to create the data (including instantiating identities) defined in the model via data parsers, 148 * the default nodes are not added into any data tree and mandatory nodes are not checked in the data trees. This 149 * can be changed by ly_ctx_set_allimplemented() function, which causes that all the imported modules are automatically 150 * set to be implemented. 151 * 152 * When loading/importing a module without revision, the latest revision of the required module is supposed to load. 153 * For a context, the first time the latest revision of a module is requested, it is properly searched for and loaded. 154 * However, when this module is requested (without revision) the second time, the one found previously is returned. 155 * This has the advantage of not searching for the module repeatedly but the drawback that if a later revision 156 * of the module is later made available, this context will not use it. If you are aware of a case when this 157 * optimization could cause problems, you can disable it using a cmake(1) build option (variable). 158 * 159 * Context holds all modules and their submodules internally. To get 160 * a specific module or submodule, use ly_ctx_get_module() and ly_ctx_get_submodule(). There are some additional 161 * alternatives to these functions (with different parameters). If you need to do something with all the modules or 162 * submodules in the context, it is advised to iterate over them using ly_ctx_get_module_iter(), it is 163 * the most efficient way. Alternatively, the ly_ctx_info() function can be used to get complex information 164 * about the schemas in the context in the form of data tree defined by 165 * <a href="https://tools.ietf.org/html/draft-ietf-netconf-yang-library-04">ietf-yang-library</a> schema. 166 * To get a specific node defined in a module in the context, ly_ctx_find_path() or ly_ctx_get_node() can be used. 167 * 168 * Modules held by a context can be removed by ly_ctx_remove_module(). Besides removing the module, it is possible 169 * just to disable it with lys_set_disabled(). In this case the module is hidden in the context (disabled modules can 170 * be iterated via ly_ctx_get_disabled_module_iter()) and not used during the common work with the context. The module 171 * is enabled explicitly by calling lys_set_enabled() or implicitly by the request to load the schema (directly or 172 * indirectly via import of another module) into the context. 173 * 174 * To clean the context from all the loaded modules (except the [internal modules](@ref howtoschemasparsers)), the 175 * ly_ctx_clean() function can be used. To remove the context, there is ly_ctx_destroy() function. 176 * 177 * - @subpage howtocontextdict 178 * 179 * \note API for this group of functions is available in the [context module](@ref context). 180 * 181 * Functions List 182 * -------------- 183 * - ly_ctx_new() 184 * - ly_ctx_set_searchdir() 185 * - ly_ctx_unset_searchdirs() 186 * - ly_ctx_get_searchdirs() 187 * - ly_ctx_set_module_imp_clb() 188 * - ly_ctx_get_module_imp_clb() 189 * - ly_ctx_set_module_data_clb() 190 * - ly_ctx_get_module_data_clb() 191 * - ly_ctx_set_allimplemented() 192 * - ly_ctx_unset_allimplemented() 193 * - ly_ctx_set_disable_searchdirs() 194 * - ly_ctx_unset_disable_searchdirs() 195 * - ly_ctx_set_disable_searchdir_cwd() 196 * - ly_ctx_unset_disable_searchdir_cwd() 197 * - ly_ctx_load_module() 198 * - ly_ctx_info() 199 * - ly_ctx_get_module_set_id() 200 * - ly_ctx_get_module_iter() 201 * - ly_ctx_get_disabled_module_iter() 202 * - ly_ctx_get_module() 203 * - ly_ctx_get_module_older() 204 * - ly_ctx_get_module_by_ns() 205 * - ly_ctx_get_submodule() 206 * - ly_ctx_get_submodule2() 207 * - ly_ctx_get_node() 208 * - ly_ctx_find_path() 209 * - ly_ctx_remove_module() 210 * - ly_ctx_clean() 211 * - ly_ctx_destroy() 212 * - lys_set_implemented() 213 * - lys_set_disabled() 214 * - lys_set_enabled() 215 * - lys_search_localfile() 216 */ 217 218/** 219 * @page howtocontextdict Context Dictionary 220 * 221 * Context includes dictionary to store strings more effectively. The most of strings repeats quite often in schema 222 * as well as data trees. Therefore, instead of allocating those strings each time they appear, libyang stores them 223 * as records in the dictionary. The basic API to the context dictionary is public, so even a caller application can 224 * use the dictionary. 225 * 226 * To insert a string into the dictionary, caller can use lydict_insert() (adding a constant string) or 227 * lydict_insert_zc() (for dynamically allocated strings that won't be used by the caller after its insertion into 228 * the dictionary). Both functions return the pointer to the inserted string in the dictionary record. 229 * 230 * To remove (reference of the) string from the context dictionary, lydict_remove() is supposed to be used. 231 * 232 * \note Incorrect usage of the dictionary can break libyang functionality. 233 * 234 * \note API for this group of functions is described in the [XML Parser module](@ref dict). 235 * 236 * Functions List 237 * -------------- 238 * - lydict_insert() 239 * - lydict_insert_zc() 240 * - lydict_remove() 241 */ 242 243/** 244 * @page howtoschemas Schemas 245 * 246 * 247 * Schema is an internal libyang's representation of a YANG data model. Each schema is connected with 248 * its [context](@ref howtocontext) and loaded using [parser functions](@ref howtoschemasparsers). It means, that 249 * the schema cannot be created (nor changed) programmatically. In libyang, schemas are used only to 250 * access data model definitions. 251 * 252 * Schema tree nodes are able to hold private objects (via a pointer to a structure, function, variable, ...) used by 253 * a caller application. Such an object can be assigned to a specific node using lys_set_private() function. 254 * Note that the object is not freed by libyang when the context is being destroyed. So the caller is responsible 255 * for freeing the provided structure after the context is destroyed or the private pointer is set to NULL in 256 * appropriate schema nodes where the object was previously set. This can be automated via destructor function 257 * to free these private objects. The destructor is passed to the ly_ctx_destroy() function. On the other hand, 258 * freeing the object while the schema tree is still in use can lead to a segmentation fault. 259 * 260 * - @subpage howtoschemasparsers 261 * - @subpage howtoschemasfeatures 262 * - @subpage howtoschemaplugins 263 * - @subpage howtoschemasprinters 264 * 265 * \note There are many functions to access information from the schema trees. Details are available in 266 * the [Schema Tree module](@ref schematree). 267 * 268 * For information about difference between implemented and imported modules, see the 269 * [context description](@ref howtocontext). 270 * 271 * Functions List (not assigned to above subsections) 272 * -------------------------------------------------- 273 * - lys_getnext() 274 * - lys_parent() 275 * - lys_module() 276 * - lys_node_module() 277 * - lys_set_private() 278 * - lys_set_implemented() 279 * - lys_set_disabled() 280 * - lys_set_enabled() 281 */ 282 283/** 284 * @page howtoschemasparsers Parsing Schemas 285 * 286 * Schema parser allows to read schema from a specific format. libyang supports the following schema formats: 287 * 288 * - YANG 289 * 290 * Basic YANG schemas format described in [RFC 6020](http://tools.ietf.org/html/rfc6020) and 291 * [RFC 7951](http://tools.ietf.org/html/rfc7951) (so both YANG 1.0 and YANG 1.1 versions are supported). 292 * 293 * - YIN 294 * 295 * Alternative XML-based format to YANG - YANG Independent Notation. The details can be found in 296 * [RFC 6020](http://tools.ietf.org/html/rfc6020#section-11) and 297 * [RFC 7951](http://tools.ietf.org/html/rfc7951#section-13). 298 * 299 * When the [context](@ref howtocontext) is created, it already contains the following schemas, which 300 * are implemented internally by libyang: 301 * - ietf-yang-metadata@2016-08-05 302 * - yang@2017-02-20 303 * - ietf-inet-types@2013-07-15 304 * - ietf-yang-types@2013-07-15 305 * - ietf-yang-library@2016-06-21 306 * 307 * The `yang` schema is the libyang's internal module to provide namespace and definitions of for various YANG 308 * attributes described in [RFC 7951](https://tools.ietf.org/html/rfc6243) (such as `insert` attribute for 309 * edit-config's data). 310 * 311 * Other schemas can be added to the context manually as described in [context page](@ref howtocontext) by the functions 312 * listed below. Besides the schema parser functions, it is also possible to use ly_ctx_load_module() which tries to 313 * find the required schema automatically - using #ly_module_imp_clb or automatic search in working directory and in the 314 * context's searchpath. 315 * 316 * Functions List 317 * -------------- 318 * - lys_parse_mem() 319 * - lys_parse_fd() 320 * - lys_parse_path() 321 * - lys_search_localfile() 322 * - ly_ctx_set_module_imp_clb() 323 * - ly_ctx_load_module() 324 */ 325 326/** 327 * @page howtoschemasfeatures YANG Features Manipulation 328 * 329 * The group of functions prefixed by \b lys_features_ are used to access and manipulate with the schema's 330 * features. 331 * 332 * The first two functions are used to access information about the features in the schema. 333 * lys_features_list() provides list of all features defined in the specific schema and its 334 * submodules. Optionally, it can also provide information about the state of all features. 335 * Alternatively, caller can use lys_features_state() function to get state of one specific 336 * feature. 337 * 338 * The remaining two functions, lys_features_enable() and lys_features_disable(), are used 339 * to enable and disable the specific feature (or all via the '`*`' value). By default, when the module 340 * is loaded by libyang parser, all features are disabled. 341 * 342 * To get know, if a specific schema node is currently disabled or enable, the lys_is_disabled() function can be used. 343 * 344 * Note, that the feature's state can affect some of the output formats (e.g. Tree format). 345 * 346 * Functions List 347 * -------------- 348 * - lys_features_list() 349 * - lys_features_enable() 350 * - lys_features_disable() 351 * - lys_features_state() 352 * - lys_is_disabled() 353 */ 354 355/** 356 * @page howtoschemaplugins YANG Extension and User Type Support 357 * 358 * Extensions and user types are supported in the form of **plugins**. These are loaded from the plugin directory 359 * (`LIBDIR/libyang/`) whenever a context is created. However, the list of plugins can be refreshed manually by ly_load_plugins(). 360 * The extension plugin directory path (default `LIBDIR/libyang/extensions/`) can be change via the 361 * `LIBYANG_EXTENSIONS_PLUGINS_DIR` environment variable and similarly the user type directory (default `LIBDIR/libyang/user_types/`) 362 * via `LIBYANG_USER_TYPES_PLUGINS_DIR`. Note, that unavailable plugins are not removed, only 363 * any new plugins are loaded. Also note that the availability of new plugins does not affect the current schemas in the 364 * contexts, they are applied only to the newly parsed schemas. 365 * 366 * The plugins list can be cleaned by ly_clean_plugins(). However, since various contexts (respectively their 367 * schemas) can link to the plugins, the cleanup is successful only when there is no remaining context. 368 * 369 * For both plugin types, when a specific plugin is being loaded, libyang checks for the API version the plugin was compiled with. 370 * From the plugin side, this is done using `LYEXT_VERSION_CHECK` or `LYTYPE_VERSION_CHECK` which must be defined in the plugin code. 371 * 372 * @section extensions Extensions 373 * 374 * YANG provides extensions as a mechanism how to add new statements into the language. Since they are very generic - 375 * extension instance can appear anywhere, they can contain any other YANG statement including extension instances and 376 * their specification has a form of the description text, it is very challenging for libyang to provide working and 377 * useful implementation. Therefore, you can reach some limitation regarding the extensions support, but the common 378 * use cases should be covered and supported. 379 * 380 * Since libyang does not understand human text, it is not possible to get the complete definition of the extension from 381 * its description statement. Therefore, libyang allows the schema authors to provide @link extplugins extension 382 * plugin@endlink that provides information from the extension description to libyang. 383 * 384 * Here are some notes about the implementation of the particular YANG extensions features 385 * 386 * - Extension instance can appear anywhere 387 * This is completely supported. In addition, the extension plugins are allowed to provide callback function to 388 * check if the extension instance is actually allowed to be instantiated as a substatement of the particular node. 389 * In some case the extension instance is not stored in the libyang structures inside the statement it is 390 * instantiated since some statements (such as description, position and several others listed as #LYEXT_SUBSTMT) are 391 * not stored as a structure, but directly as a value. The extension instances of such statements are then actually 392 * stored besides the extension instances of the parent structure (e.g. in ::lys_type_bit in case of position's 393 * extension instances). These extension instances are indicated by the ::lys_ext_instance#insubstmt value which 394 * refers (sometimes in combination with ::lys_ext_instance#insubstmt_index) to the substatement where the particular 395 * extension is actually instantiated. 396 * 397 * - Extension instance can contain any other YANG statement 398 * This is supported with exceptions - the list of YANG statements is defined as #LY_STMT enumeration with the 399 * description if the specific statement can appear as an extension instance substatement or if there is some 400 * limitation regarding its cardinality. It also specifies how the specific statement is stored in the extension 401 * instance (which data type or structure is used). In some cases, like `include` or `yang-version` statements, it 402 * make no sense to have them inside an extension instance, so they are not supported by libyang. 403 * 404 * The list of allowed substatement for the specific extension instances is provided by the extension plugin. Besides 405 * the list of substatement, the plugin also specifies where the data are stored and the cardinality for each 406 * substatement. Other extension instances as an extension instance substatements are always allowed. Note, that if 407 * there is no extension plugin defined or if the list of the allowed substatements is empty, no substatement (except 408 * extension instances) is allowed. 409 * 410 * There are several extension types (enumerated as #LYEXT_TYPE) according to their purpose and content: 411 * 412 * - #LYEXT_FLAG - simple extension with no content (no substatement is allowed). The extension instance serves just as 413 * a flag with or without an argument and its value. The example of such an extension is NACM's __default-deny-write__ 414 * or __default-deny-all__. This is the default type of extension for the case there is no extension plugin available 415 * for the specific extension. Extension instances of this type are represented as ::lys_ext_instance. 416 * 417 * - #LYEXT_COMPLEX - complex extension with content. The specific rules for the content and how it is stored in the 418 * extension instance structure is specified by the plugin. Extension instances of this type are represented as 419 * ::lys_ext_instance_complex. 420 * 421 * Note that the ::lys_ext_instance structure serves as a generic structure for all extension instances. In case the 422 * ::lys_ext_instance#ext_type is set to a different value than #LYEXT_FLAG, the structure can be cast to the particular 423 * extension instance structure to access the type-specific members. 424 * 425 * @subsection extplugins Extension Plugins 426 * 427 * Extension plugins provide more detailed information about the extension in a understandable form for libyang. These 428 * information is usually provided in a text form in the extension's description statement. libyang provides several 429 * plugins for the common IETF extensions (NACM, Metadata, ...) that can be used as a code examples for other 430 * extensions. 431 * 432 * There are several types of extension plugins which corresponds to the extension types: 433 * 434 * - ::lyext_plugin - the plugin for a simple extensions of type #LYEXT_FLAG. The plugin is supposed to provide 435 * callbacks for: 436 * + @link lyext_check_position_clb checking extension position @endlink (if the extension instance can be instantiated 437 * in a particular parent) 438 * + @link lyext_check_inherit_clb deciding if the extension is supposed to be inherited @endlink 439 * (see #LYEXT_OPT_INHERIT). Note that the inherited extension instances are available in the libyang data 440 * structures, but they are not part of the schema so they are not printed into the schema output formats. 441 * + @link lyext_check_result_clb checking the result @endlink, the callback is called when the schema is completely 442 * parsed and all the data are available for the final (possibly complex) checking (or modification) 443 * - ::lyext_plugin_complex - the plugin for the complex extension instances (#LYEXT_COMPLEX). The structure extends 444 * the ::lyext_plugin structure by: 445 * + instance_size - the overall size of the ::lyext_plugin_complex structure to allocate. 446 * The substatement list is flexible array, so the size of the plugin structure depends on the content of the array. 447 * + substmt - the list of the allowed substatements to the extension instance, besides the substatement id, it 448 * also specifies its cardinality and the specific position in the ::lys_ext_instance_complex where the data are 449 * stored (as offset to the ::lys_ext_instance_complex#content member). The way how the data are stored is 450 * specified descriptions of #LY_STMT values. 451 * 452 * @subsection howtoschemametadata Metadata Support 453 * 454 * YANG Metadata annotations are defined in [RFC 7952](https://tools.ietf.org/html/rfc6243) as YANG extension. In 455 * practice, it allows to have XML attributes (there is also a special encoding for JSON) in YANG modeled data. 456 * libyang does not allow to have any XML attribute without the appropriate annotation definition describing the 457 * data as it is done e.g. for leafs. When an attribute without a matching annotation definition is found in the 458 * input data, it is silently dropped (with warning) or an error is reported in case the #LYD_OPT_STRICT parser 459 * option is provided to the [parser function](@ref howtodataparsers). 460 * 461 * There are some XML attributes, described by [YANG](https://tools.ietf.org/html/rfc7951) and 462 * [NETCONF](https://tools.ietf.org/html/rfc6241) specifications, which are not defined as annotations, but libyang 463 * implements them this way. In case of attributes in the YANG namespace (`insert`, `value` and `key` attributes 464 * for the NETCONF edit-config operation), they are defined in special libyang's internal module `yang`, which is 465 * available in each context and the content of this schema can be printed via 466 * [schema printers](@ref howtoschemasprinters). 467 * 468 * In case of the attributes described in [NETCONF specification](https://tools.ietf.org/html/rfc6241), the libyang's 469 * annotations structures are hidden and cannot be printed despite, internally, they are part of the `ietf-netconf`'s 470 * schema structure. Therefore, these attributes are available only when the `ietf-netconf` schema is loaded in the 471 * context. The definitions of these annotations are as follows: 472 * 473 * md:annotation operation { 474 * type enumeration { 475 * enum merge; 476 * enum replace; 477 * enum create; 478 * enum delete; 479 * enum remove; 480 * } 481 * } 482 * 483 * md:annotation type { 484 * type enumeration { 485 * enum subtree; 486 * enum xpath { 487 * if-feature "nc:xpath"; 488 * } 489 * } 490 * } 491 * 492 * md:annotation select { 493 * type string; 494 * } 495 * 496 * Note, that, following the specification, 497 * - the `type` and `select` XML attributes are supposed to be unqualified (without namespace) and that 498 * - the `select`'s content is XPath and it is internally transformed by libyang into the format where the 499 * XML namespace prefixes are replaced by the YANG module names. 500 * 501 * @section usertypes User Types 502 * 503 * Using this plugin mechanism, it is also possible to define what can be called **user types**. Values are 504 * always stored as a string in addition to being in a #lyd_val union. It is possible to customize how 505 * the value is stored in the union using a #lytype_store_clb callback. 506 * 507 * Generally, it is meant for storing certain types more effectively. For instance, when working with **ipv4-address** 508 * from the *ietf-inet-types* model, an application will most likely use the address in a binary form, not as a string. 509 * So, in the callback the value is simply transformed into the desired format and saved into #lyd_val value. However, 510 * the callback is allowed to store anything in the union. Another example, if there are many strings being created and 511 * handled, is to store the string length instead having 2 pointers to the same string. 512 * 513 * Also, it is possible to perform some additional validation of the value except for the standard YANG one. Even if 514 * the value should only be validated, this callback can be defined and used, it will just keep the #lyd_val value 515 * unchanged. 516 * 517 * @subsection typeplugins User Type Plugins 518 * 519 * There are simple example user type plugins in `src/user_types`. 520 * 521 * - ::lytype_plugin_list - plugin is supposed to provide callbacks for: 522 * + @link lytype_store_clb storing the value itself @endlink 523 * + freeing the stored value (optionally, if the store callback allocates memory) 524 * 525 * Functions List 526 * -------------- 527 * - lys_ext_instance_presence() 528 * - lys_ext_instance_substmt() 529 * - ly_load_plugins() 530 * - ly_clean_plugins() 531 */ 532 533/** 534 * @page howtoschemasprinters Printing Schemas 535 * 536 * Schema printers allows to serialize internal representation of a schema module in a specific format. libyang 537 * supports the following schema formats for printing: 538 * 539 * - YANG 540 * 541 * Basic YANG schemas format described in [RFC 6020](http://tools.ietf.org/html/rfc6020) and 542 * [RFC 7951](http://tools.ietf.org/html/rfc7951) (so both YANG 1.0 and YANG 1.1 versions are supported). 543 * 544 * - YIN 545 * 546 * Alternative XML-based format to YANG - YANG Independent Notation. The details can be found in 547 * [RFC 6020](http://tools.ietf.org/html/rfc6020#section-11) and 548 * [RFC 7951](http://tools.ietf.org/html/rfc7951#section-13). 549 * 550 * - Tree 551 * 552 * Simple tree structure of the module where each node is printed as: 553 * 554 * <status> <flags> <name> <opts> <type> <if-features> 555 * 556 * - `<status>` is one of: 557 * - `+` for current 558 * - `x` for deprecated 559 * - `o` for obsolete 560 * 561 * - `<flags>` is one of: 562 * - `rw` for configuration data 563 * - `ro` for status data 564 * - `-x` for RPCs 565 * - `-n` for Notification 566 * 567 * - `<name>` is the name of the node 568 * - `(<name>)` means that the node is a choice node 569 * - `:(<name>)` means that the node is a case node 570 * - if the node is augmented into the tree from another module, it is printed with the module name as 571 * `<module-name>:<name>`. 572 * 573 * - `<opts>` is one of: 574 * - `?` for an optional leaf or choice 575 * - `!` for a presence container 576 * - `*` for a leaf-list or list 577 * - `[<keys>]` for a list's keys 578 * 579 * - `<type>` is the name of the type for leafs and leaf-lists 580 * - if there is a default value defined, it is printed within angle brackets `<default-value>` 581 * - if the type is a leafref, the type is printed as -> TARGET` 582 * 583 * - `<if-features>` is the list of features this node depends on, printed within curly brackets and 584 * a question mark `{...}?` 585 * 586 * 587 * - Info 588 * 589 * Detailed information about the specific node in the schema tree. 590 * It allows to print information not only about a specific module, but also about its specific part: 591 * 592 * - absolute-schema-nodeid 593 * 594 * e.g. \a `/modules/module-set-id` in \a `ietf-yang-library` module 595 * 596 * - <b>typedef/</b>typedef-name 597 * 598 * e.g. \a `typedef/revision-identifier` in \a `ietf-yang-library` module 599 * 600 * - <b>feature/</b>feature-name 601 * 602 * e.g. \a `feature/ssh` in \a `ietf-netconf-server` module 603 * 604 * - <b>grouping/</b>grouping-name/descendant-schema-nodeid 605 * 606 * e.g. \a `grouping/module` or \a `grouping/module/module/submodules` in \a `ietf-yang-library` module 607 * 608 * - <b>type/</b>leaf-or-leaflist 609 * 610 * e.g. \a `type/modules/module-set-id` in \a `ietf-yang-library` module 611 * 612 * Printer functions allow to print to the different outputs including a callback function which allows caller 613 * to have a full control of the output data - libyang passes to the callback a private argument (some internal 614 * data provided by a caller of lys_print_clb()), string buffer and number of characters to print. Note that the 615 * callback is supposed to be called multiple times during the lys_print_clb() execution. 616 * 617 * Functions List 618 * -------------- 619 * - lys_print_mem() 620 * - lys_print_fd() 621 * - lys_print_file() 622 * - lys_print_path() 623 * - lys_print_clb() 624 */ 625 626/** 627 * @page howtodata Data Instances 628 * 629 * All data nodes in data trees are connected with their schema node - libyang is not able to represent data of an 630 * unknown schema. 631 * 632 * Connected to the aforementioned, it is important to mention that there are several kinds of data trees libyang 633 * can work with. Except for a standard full data tree and configuration data tree, there are trees specific for use 634 * in NETCONF, which are \<get\> or \<get-config\> replies, \<edit-config\> input content, generic RPC/action request, 635 * RPC/action reply, or a notification. 636 * 637 * Special care is needed when working with action input and RPC/action output, because in these cases the libyang data 638 * tree does not match the actual data tree NETCONF expects. 639 * 640 * <b>Action input</b> differentiates from a standard RPC that the child of \<rpc\> element is not the specific RPC 641 * request being sent, but a special \<action\> element in the base YANG namespace. It is expected to be present when 642 * parsing an action input and can optionally be included when the action is printed. 643 * 644 * As for <b>RPC output</b>, NETCONF expects the output parameters as direct children of the \<rpc-reply\> element. 645 * However, libyang encapsulates these parameters in the specific RPC request container. Same as before, it is expected 646 * to be without this container when parsing and can be printed out. 647 * 648 * Lastly, <b>action output</b> is almost similar to RPC output and in NETCONF you actually cannot distinguish them, 649 * but in case of action output, libyang puts all the output parameters under the action container, which is also 650 * just a child to all the schema tree ancestors up to the schema top-level, just like in an action input. Same applies 651 * even in this case, parsed data should be only the output parameters, you can decide how to print it. 652 * 653 * So, you do not have to use any special flag when you want to print the data tree the way libyang internally stores 654 * it, although you will not be able to parse it back, as was mentioned in the paragraphs above. To print data in the 655 * way NETCONF and libyang expects them to be, use #LYP_NETCONF flag for any printing function. 656 * 657 * Please, continue reading a specific subsection or go through all the subsections if you are a new user of libyang. 658 * 659 * - @subpage howtodataparsers 660 * - @subpage howtodatamanipulators 661 * - @subpage howtodatavalidation 662 * - @subpage howtodatawd 663 * - @subpage howtodataprinters 664 * 665 * \note API for this group of functions is described in the [Data Instances module](@ref datatree). 666 * 667 * Functions List (not assigned to above subsections) 668 * -------------------------------------------------- 669 * - lyd_find_instance() 670 * - lyd_find_xpath() 671 * - lyd_leaf_type() 672 */ 673 674/** 675 * @page howtodataparsers Parsing Data 676 * 677 * Data parser allows to read instances from a specific format. libyang supports the following data formats: 678 * 679 * - XML 680 * 681 * Original data format used in NETCONF protocol. XML mapping is part of the YANG specification 682 * ([RFC 6020](http://tools.ietf.org/html/rfc6020)). 683 * 684 * - JSON 685 * 686 * The alternative data format available in RESTCONF protocol. Specification of JSON encoding of data modeled by YANG 687 * can be found in [RFC 7951](http://tools.ietf.org/html/rfc7951). 688 * 689 * Besides the format of input data, the parser functions accepts additional [options](@ref parseroptions) to specify 690 * how the input data should be processed. 691 * 692 * In contrast to the schema parser, data parser also accepts empty input data if such an empty data tree is valid 693 * according to the schemas in the libyang context. 694 * 695 * If a node from a schema, which is not present in the context or is not implemented, is parsed, a callback set by 696 * ly_ctx_set_module_data_clb() is called and this way the application is given the opportunity to add this schema into 697 * the context or change its conformance before the parsing would fail. 698 * 699 * In case of XML input data, there is one additional way to parse input data. Besides parsing the data from a string 700 * in memory or a file, caller is able to build an XML tree using [libyang XML parser](@ref howtoxml) and then use 701 * this tree (or a part of it) as input to the lyd_parse_xml() function. 702 * 703 * Functions List 704 * -------------- 705 * - lyd_parse_mem() 706 * - lyd_parse_fd() 707 * - lyd_parse_path() 708 * - lyd_parse_xml() 709 */ 710 711/** 712 * @page howtodatamanipulators Manipulating Data 713 * 714 * There are many functions to create or modify an existing data tree. You can add new nodes, reconnect nodes from 715 * one tree to another (or e.g. from one list instance to another) or remove nodes. The functions doesn't allow you 716 * to put a node to a wrong place (by checking the module), but not all validation checks can be made directly 717 * (or you have to make a valid change by multiple tree modifications) when the tree is being changed. Therefore, 718 * there is lyd_validate() function supposed to be called to make sure that the current data tree is valid. If 719 * working with RPCs, they are invalid also in case the data nodes are not ordered according to the schema, which 720 * you can fix easily with lyd_schema_sort(). Note, that not performing validation after some data tree changes 721 * can cause failure of various libyang functions later. All functions performing data tree changes are marked 722 * with the __PARTIAL CHANGE__ flag in their documentation meaning they leave at least partly non-validated data tree. 723 * 724 * Creating data is generally possible in two ways, they can be combined. You can add nodes one-by-one based on 725 * the node name and/or its parent (lyd_new(), \b lyd_new_anydata_*(), lyd_new_leaf(), and their output variants) or 726 * address the nodes using a simple XPath addressing (lyd_new_path()). The latter enables to create a whole path 727 * of nodes, requires less information about the modified data, and is generally simpler to use. The path format 728 * specifics can be found [here](@ref howtoxpath). 729 * 730 * Working with two data subtrees can also be performed two ways. Usually, you would use lyd_insert*() functions. 731 * They are generally meant for simple inserts of a node into a data tree. For more complicated inserts and when 732 * merging 2 trees use lyd_merge(). It offers additional options and is basically a more powerful insert. 733 * 734 * Also remember, that when you are creating/inserting a node, all the objects in that operation must belong to the 735 * same context. 736 * 737 * Modifying the single data tree in multiple threads is not safe. 738 * 739 * Functions List 740 * -------------- 741 * - lyd_dup() 742 * - lyd_dup_to_ctx() 743 * - lyd_change_leaf() 744 * - lyd_insert() 745 * - lyd_insert_sibling() 746 * - lyd_insert_before() 747 * - lyd_insert_after() 748 * - lyd_insert_attr() 749 * - lyd_merge() 750 * - lyd_merge_to_ctx() 751 * - lyd_new() 752 * - lyd_new_anydata() 753 * - lyd_new_leaf() 754 * - lyd_new_path() 755 * - lyd_new_output() 756 * - lyd_new_output_anydata() 757 * - lyd_new_output_leaf() 758 * - lyd_list_pos() 759 * - lyd_schema_sort() 760 * - lyd_unlink() 761 * - lyd_free() 762 * - lyd_free_attr() 763 * - lyd_free_withsiblings() 764 */ 765 766/** 767 * @page howtodatavalidation Validating Data 768 * 769 * By default, the represented data are supposed to represent a full YANG datastore content. So if a schema declares 770 * some mandatory nodes, despite configuration or status, the data are supposed to be present in the data tree being 771 * loaded or validated. However, it is possible to specify other kinds of data (see @ref parseroptions) allowing some 772 * exceptions to the validation process. 773 * 774 * Data validation is performed implicitly to the input data processed by the parser (\b lyd_parse_*() functions) and 775 * on demand via the lyd_validate() function. The lyd_validate() is supposed to be used when a (complex or simple) 776 * change is done on the data tree (via a combination of \b lyd_change_*(), \b lyd_insert*(), \b lyd_new*(), 777 * lyd_unlink() and lyd_free() functions). 778 * 779 * Part of data validation is resolving leafrefs and instance-identifiers. Leafrefs are resolved only when a change occurred 780 * in the data tree that could have broken the link. However, as instance-identifiers can point to any node whatsoever 781 * without an import, it would not be effective to store metadata as in the case of leafrefs. That is why they are resolved 782 * during every validation. Also, for the same reason, it can easily happen that when parsing/validating data with 783 * an instance-identifier, it will target a remote node, whose schema is not currently present in the context. To handle 784 * this case, a callback should be set using ly_ctx_set_module_data_clb(), which can load the schema when required. 785 * 786 * Must And When Conditions Accessible Tree 787 * ---------------------------------------- 788 * 789 * In YANG 1.1, there can be \b must and/or \b when expressions in RPC/action input or output, or in notifications that 790 * require access to the configuration datastore and/or state data. Normally, when working with any of the aforementioned 791 * data trees, they must contain only the RPC/action/notification itself, without any additional configuration or state 792 * data. So how can then these conditions be verified during validation? 793 * 794 * There is an option to pass this additional data tree to all the functions that perform \b must and \b when condition 795 * checking (\b lyd_parse_*() and lyd_validate()). Also, there are 3 flags of \b struct lys_node that 796 * mark schema nodes that include paths that require foreign nodes (outside their subtree) for their evaluation. 797 * #LYS_XPCONF_DEP marks nodes with such must and/or when expressions that require some configuration data, 798 * #LYS_XPSTATE_DEP that require some state data, and #LYS_LEAFREF_DEP with such a leafref. 799 * The subtree root is always the particular operation data node (for RPC it is the RPC data node and all 800 * the input or output nodes as its children and similarly for action and notification). Note that for action and 801 * not-top-level notification this means that all their parents are not considered as belonging to their subtree even though 802 * they are included in their data tree and must be present for the operation validation to pass. The reason for this is that if 803 * there are any lists in those parents, we cannot know if there are not some other instances of them in the standard 804 * data tree in addition to the one used in the action/notification invocation. 805 * 806 * There were 2 ways of using this mechanism envisioned (explained below), but you can combine or modify them. 807 * 808 * ### Fine-grained Data Retrieval ### 809 * 810 * This approach is recommended when you do not maintain a full configuration data tree with state data at all times. 811 * 812 * Firstly, you should somehow learn that the operation data tree you are currently working with includes some schema 813 * node instances that have conditions that require foreign data. You can either know this about every operation beforehand 814 * or you go through all the schema nodes looking for the flags #LYS_XPCONF_DEP, #LYS_XPSTATE_DEP, and #LYS_LEAFREF_DEP. 815 * Then you should use lys_node_xpath_atomize() 816 * to retrieve all XPath condition dependencies (in the form of schema nodes) outside the operation subtree. You will likely 817 * want to use the flag #LYXP_NO_LOCAL to get rid of all the nodes from inside the subtree (you should already have those). 818 * The last thing to do is to build a data tree that includes at least all the instances of the nodes obtained from lys_node_xpath_atomize() 819 * (it will be expected). Then you pass this tree to the validation and it should now have access to all the nodes that 820 * can potentially affect the XPath evaluation and no other. 821 * 822 * ### Maintaining Configuration And State Data Tree ### 823 * 824 * If you have a full data tree with state data available for the validation process then it is quite simple (compared 825 * to the first approach). You can simply always pass it to validation of these operations and in cases it is not required 826 * (no nodes with conditions traversing foreign nodes) only a negligible amount of redundant work is performed and you can 827 * skip the process of learning whether it is required or not. 828 * 829 * Functions List 830 * -------------- 831 * - lyd_validate() 832 */ 833 834/** 835 * @page howtodatawd Default Values 836 * 837 * libyang provides support for work with default values as defined in [RFC 6243](https://tools.ietf.org/html/rfc6243). 838 * This document defines 4 modes for handling default nodes in a data tree, libyang adds the fifth mode: 839 * - \b explicit - Only the explicitly set configuration data. But in the case of status data, missing default 840 * data are added into the tree. In libyang, this mode is represented by #LYP_WD_EXPLICIT option. 841 * - \b trim - Data nodes containing the schema default value are removed. This mode is applied using #LYP_WD_TRIM option. 842 * - \b report-all - All the missing default data are added into the data tree. This mode is represented by 843 * #LYP_WD_ALL option. 844 * - \b report-all-tagged - In this case, all the missing default data are added as in case of the `report-all` mode, 845 * but additionally all the nodes (existing as well as added) containing the schema default value 846 * are tagged (see the note below). libyang uses #LYP_WD_ALL_TAG option for this mode. 847 * - \b report-implicit-tagged - The last mode is similar to the previous one, except only the added nodes are tagged. 848 * This is the libyang's extension and it is represented by #LYP_WD_IMPL_TAG option. 849 * 850 * libyang automatically adds/maintain the default nodes when a data tree is being parsed or validated. Note, that in a 851 * modified data tree (via e.g. lyd_insert() or lyd_free()), some of the default nodes can be missing or they can be 852 * present by mistake. Such a data tree is again corrected during the next lyd_validate() call. 853 * 854 * The implicit (default) nodes, created by libyang, are marked with the ::lyd_node#dflt flag which applies to the 855 * leafs and leaf-lists. In case of containers, the flag means that the container holds only a default node(s) or it 856 * is an empty container (according to YANG 1.1 spec, all such containers are part of the accessible data tree). 857 * 858 * The presence of the default nodes during the data tree lifetime is affected by the LYD_OPT_ flag used to 859 * parse/validate the tree: 860 * - #LYD_OPT_DATA - all the default nodes are present despite they are configuration or status nodes 861 * - #LYD_OPT_CONFIG - only the configuration data nodes are added into the tree 862 * - #LYD_OPT_GET, #LYD_OPT_GETCONFIG, #LYD_OPT_EDIT - no default nodes are added 863 * - #LYD_OPT_RPC, #LYD_OPT_RPCREPLY, #LYD_OPT_NOTIF - the default nodes from the particular subtree are added 864 * 865 * The with-default modes described above are supported when the data tree is being printed with the 866 * [LYP_WD_ printer flags](@ref printerflags). Note, that in case of #LYP_WD_ALL_TAG and #LYP_WD_IMPL_TAG modes, 867 * the XML/JSON attributes are printed only if the context includes the ietf-netconf-with-defaults schema. Otherwise, 868 * these modes have the same result as #LYP_WD_ALL. The presence of empty containers (despite they were added explicitly 869 * or implicitly as part of accessible data tree) depends on #LYP_KEEPEMPTYCONT option. 870 * 871 * To get know if the particular leaf or leaf-list node contains default value (despite implicit or explicit), you can 872 * use lyd_wd_default() function. 873 * 874 * Functions List 875 * -------------- 876 * - lyd_wd_default() 877 * 878 * - lyd_parse_mem() 879 * - lyd_parse_fd() 880 * - lyd_parse_path() 881 * - lyd_parse_xml() 882 * - lyd_validate() 883 * - lyd_print_mem() 884 * - lyd_print_fd() 885 * - lyd_print_file() 886 * - lyd_print_path() 887 * - lyd_print_clb() 888 */ 889 890/** 891 * @page howtodataprinters Printing Data 892 * 893 * Data printers allows to serialize internal representation of a data tree in a specific format. libyang 894 * supports the following data formats for printing: 895 * 896 * - XML 897 * 898 * Basic format as specified in rules of mapping YANG modeled data to XML in 899 * [RFC 6020](http://tools.ietf.org/html/rfc6020). It is possible to specify if 900 * the indentation (formatting) will be used (by #LYP_FORMAT @ref printerflags "printer option"). 901 * 902 * - JSON 903 * 904 * The alternative data format available in RESTCONF protocol. Specification of JSON encoding of data modeled by YANG 905 * can be found in [this draft](https://tools.ietf.org/html/draft-ietf-netmod-yang-json-05).It is possible to specify 906 * if the indentation (formatting) will be used (by #LYP_FORMAT @ref printerflags "printer option"). 907 * 908 * Printer functions allow to print to the different outputs including a callback function which allows caller 909 * to have a full control of the output data - libyang passes to the callback a private argument (some internal 910 * data provided by a caller of lyd_print_clb()), string buffer and number of characters to print. Note that the 911 * callback is supposed to be called multiple times during the lyd_print_clb() execution. 912 * 913 * To print the data tree with default nodes according to the with-defaults capability defined in 914 * [RFC 6243](https://tools.ietf.org/html/rfc6243), check the [page about the default values](@ref howtodatawd). 915 * 916 * Also, to print the data in NETCONF format, use the #LYP_NETCONF flag. More information can be found on the page 917 * @ref howtodata. 918 * 919 * Functions List 920 * -------------- 921 * - lyd_print_mem() 922 * - lyd_print_fd() 923 * - lyd_print_file() 924 * - lyd_print_clb() 925 */ 926 927/** 928 * @page howtoxpath XPath Addressing 929 * 930 * Internally, XPath evaluation is performed on __when__ and __must__ conditions in the schema. For that almost 931 * a full XPath 1.0 evaluator was implemented. In YANG models you can also find paths identifying __augment__ 932 * targets, __leafref__ targets, and trivial paths in __choice default__ and __unique__ statements argument. 933 * The exact format of all those paths can be found in the relevant RFCs. Further will only be discussed 934 * paths that are used directly in libyang API functions. 935 * 936 * Schema 937 * ====== 938 * 939 * Regarding identifying schema nodes, we use a slightly modified version of YANG __augment__ target path: 940 * - strictly speaking, most XPath expressions are not accepted, only simple paths (no predicates, 941 * numbers, literals, operators, ...), 942 * - whenever a prefix is used for a node, it is not the import prefix, but the __module name__ itself, 943 * - __current module__ is specified separately for _absolute_ paths and is the module of the start 944 * (current) node for _relative_ paths, 945 * - unprefixed nodes all use the prefix of the __current module__ so all nodes from other modules than 946 * the __current module__ _MUST_ have prefixes, 947 * - nodes from the __current module__ _MAY_ have prefixes, 948 * 949 * Examples 950 * -------- 951 * 952 * - get all top-level nodes of the __module-name__ 953 * 954 * /module-name:* 955 * 956 * - get all the descendants of __container__ (excluding __container__) 957 * 958 * /module-name:container//\asterisk 959 * 960 * - get __aug-leaf__, which was added to __module-name__ from an augment module __augment-module__ 961 * 962 * /module-name:container/container2/augment-module:aug-cont/augment-module:aug-leaf 963 * 964 * Functions List 965 * -------------- 966 * - lys_find_path() 967 * - lys_path() 968 * - ly_path_data2schema() 969 * 970 * 971 * Data 972 * ==== 973 * 974 * As for paths evaluated on YANG data, we opted for standardized JSON paths ([RFC 7951](https://tools.ietf.org/html/rfc7951#section-6.11)). Summarized, it follows these conventions: 975 * - generally, you can use almost a full XPath in these paths where it makes sense, but only data nodes (node sets) 976 * will always be returned (except for paths, predicates are mostly used), 977 * - as per the specification, prefixes are actually __module names__, 978 * - also in the specification, for _absolute_ paths, the first (leftmost) node _MUST_ have a prefix, 979 * - for _relative_ paths, you specify the __context node__, which then acts as a parent for the first node in the path, 980 * - nodes always inherit their module (prefix) from their __parent node__ so whenever a node is from a different 981 * module than its parent, it _MUST_ have a prefix, 982 * - nodes from the same module as their __parent__ _MUST NOT_ have a prefix, 983 * - different from schema paths, non-data nodes (choice, case, uses, input, output) are skipped and not included 984 * in the path. 985 * 986 * Examples 987 * -------- 988 * 989 * - get __list__ instance with __key1__ of value __1__ and __key2__ of value __2__ (this can return more __list__ instances if there are more keys than __key1__ and __key2__) 990 * 991 * /module-name:container/list[key1='1'][key2='2'] 992 * 993 * - get __leaf-list__ instance with the value __val__ 994 * 995 * /module-name:container/leaf-list[.='val'] 996 * 997 * - get __aug-list__ with __aug-list-key__, which was added to __module-name__ from an augment module __augment-module__ 998 * 999 * /module-name:container/container2/augment-module:aug-cont/aug-list[aug-list-key='value'] 1000 * 1001 * Functions List 1002 * -------------- 1003 * - lyd_find_path() 1004 * - lyd_new_path() 1005 * - lyd_path() 1006 * - lys_data_path() 1007 * - ly_ctx_get_node() 1008 * - ly_ctx_find_path() 1009 * 1010 */ 1011 1012/** 1013 * @page howtoxml libyang XML Support 1014 * 1015 * libyang XML parser is able to parse XML documents. The main purpose is to load data modeled by YANG. However, it can 1016 * be used as a standalone XML parser with the following limitations in comparison to a full-featured XML parsers: 1017 * - comments are ignored 1018 * - Doctype declaration is ignored 1019 * - CData sections are ignored 1020 * - Process Instructions (PI) are ignored 1021 * 1022 * The API is designed to almost only read-only access. You can simply load XML document, go through the tree as 1023 * you wish and dump the tree to an output. The only "write" functions are lyxml_free() and lyxml_unlink() to remove 1024 * part of the tree or to unlink (separate) a subtree. 1025 * 1026 * XML parser is used internally by libyang for parsing YIN schemas and data instances in XML format. 1027 * 1028 * \note API for this group of functions is described in the [XML Parser module](@ref xmlparser). 1029 * 1030 * Functions List 1031 * -------------- 1032 * - lyxml_parse_mem() 1033 * - lyxml_parse_path() 1034 * - lyxml_get_attr() 1035 * - lyxml_get_ns() 1036 * - lyxml_print_mem() 1037 * - lyxml_print_fd() 1038 * - lyxml_print_file() 1039 * - lyxml_print_clb() 1040 * - lyxml_unlink() 1041 * - lyxml_free() 1042 */ 1043 1044/** 1045 * @page howtothreads libyang in Threads 1046 * 1047 * libyang can be used in multithreaded applications keeping in mind the following rules: 1048 * - libyang context manipulation (adding new schemas, removing schemas or even printing schemas) is not thread safe 1049 * and it is supposed to be done in a main thread before any other work with context, schemas or data instances. 1050 * Destroying the context is supposed to be done when no other thread accesses context, schemas nor data trees, 1051 * - data parser (\b lyd_parse*() functions) can be used simultaneously in multiple threads (also the returned 1052 * #ly_errno is thread safe), 1053 * - data manipulation (lyd_new(), lyd_insert(), lyd_unlink(), lyd_free() and many other 1054 * functions) a single data tree is not thread safe, 1055 * - data printing of a single data tree is thread-safe. 1056 */ 1057 1058/** 1059 * @page howtologger Logger 1060 * 1061 * There are 4 verbosity levels defined as ::LY_LOG_LEVEL. The level can be 1062 * changed by the ly_verb() function. By default, the verbosity level is 1063 * set to #LY_LLERR value. 1064 * 1065 * All the logging operations are tied to the specific **thread** and **context**. 1066 * The default behaviour is that the last message (error or warning, verbose and debug 1067 * messages are never stored) is always stored and can be accessed using ly_errmsg(). On error, 1068 * #ly_errno is set. If that was a validation error (#ly_errno is set to #LY_EVALID), 1069 * also validation error code (via ly_vecode()) and path to the error node (via ly_errpath()) are available. 1070 * 1071 * For some specific cases, a YANG schema can define error message and/or error tag (mainly for 1072 * use in NETCONF). If a message is set, it is provided via ly_errmsg(). If a tag is set in schema, 1073 * it is available via ly_errapptag() (if not set, the returned string is empty). 1074 * 1075 * By default, all libyang messages are printed to `stderr`. However, the caller is able to set their own logging 1076 * callback function. In that case, instead of printing messages, libyang passes error level, message and path 1077 * (if any) to the caller's callback function. In case of error level, the message and path are still 1078 * automatically stored and available via the functions and macros described above. 1079 * 1080 * This is the basic way of working with errors but another, more sophisticated is also available. With ly_log_options() 1081 * you can modify what is done with all the messages. Default flags are #LY_LOLOG and #LY_LOSTORE_LAST so that messages 1082 * are logged and the last one is stored. If you set the flag #LY_LOSTORE, all the messages will be stored. Be careful 1083 * because unless you regularly clean them, the error list will grow indefinitely. With ly_err_first() you can retrieve 1084 * the first generated error structure ly_err_item. It is a linked-list so you can get next errors using the **next** pointer. 1085 * Being processed (for instance printed with ly_err_print()), you can then free them with ly_err_clean(). 1086 * 1087 * \note API for this group of functions is described in the [logger module](@ref logger). 1088 * 1089 * Functions List 1090 * -------------- 1091 * - ly_verb() 1092 * - ly_set_log_clb() 1093 * - ly_get_log_clb() 1094 * - ly_log_options() 1095 * - #ly_errno 1096 * - ly_vecode() 1097 * - ly_errmsg() 1098 * - ly_errpath() 1099 * - ly_errapptag() 1100 * - ly_err_first() 1101 * - ly_err_print() 1102 * - ly_err_clean() 1103 */ 1104 1105/** 1106 * @defgroup context Context 1107 * @{ 1108 * 1109 * Structures and functions to manipulate with the libyang "containers". The \em context concept allows callers 1110 * to work in environments with different sets of YANG schemas. More detailed information can be found at 1111 * @ref howtocontext page. 1112 */ 1113 1114/** 1115 * @struct ly_ctx 1116 * @brief libyang context handler. 1117 */ 1118struct ly_ctx; 1119 1120/** 1121 * @defgroup contextoptions Context options 1122 * @ingroup context 1123 * 1124 * Options to change context behavior. 1125 * @{ 1126 */ 1127 1128#define LY_CTX_ALLIMPLEMENTED 0x01 /**< All the imports of the schema being parsed are treated implemented. */ 1129#define LY_CTX_TRUSTED 0x02 /**< Handle the schema being parsed as trusted and skip its validation 1130 tests. Note that while this option improves performance, it can 1131 lead to an undefined behavior if the schema is not correct. */ 1132#define LY_CTX_NOYANGLIBRARY 0x04 /**< Do not internally implement ietf-yang-library module. The option 1133 causes that function ly_ctx_info() does not work (returns NULL) until 1134 the ietf-yang-library module is loaded manually. While any revision 1135 of this schema can be loaded with this option, note that the only 1136 revisions implemented by ly_ctx_info() are 2016-04-09 and 2018-01-17. 1137 This option cannot be used with ly_ctx_new_yl*() functions. */ 1138#define LY_CTX_DISABLE_SEARCHDIRS 0x08 /**< Do not search for schemas in context's searchdirs neither in current 1139 working directory. It is entirely skipped and the only way to get 1140 schema data for imports or for ly_ctx_load_module() is to use the 1141 callbacks provided by caller via ly_ctx_set_module_imp_clb() */ 1142#define LY_CTX_DISABLE_SEARCHDIR_CWD 0x10 /**< Do not automatically search for schemas in current working 1143 directory, which is by default searched automatically (despite not 1144 recursively). */ 1145#define LY_CTX_PREFER_SEARCHDIRS 0x20 /**< When searching for schema, prefer searchdirs instead of user callback. */ 1146/**@} contextoptions */ 1147 1148/** 1149 * @brief Create libyang context 1150 * 1151 * Context is used to hold all information about schemas. Usually, the application is supposed 1152 * to work with a single context in which libyang is holding all schemas (and other internal 1153 * information) according to which the data trees will be processed and validated. So, the schema 1154 * trees are tightly connected with the specific context and they are held by the context internally 1155 * - caller does not need to keep pointers to the schemas returned by lys_parse(), context knows 1156 * about them. The data trees created with lyd_parse() are still connected with the specific context, 1157 * but they are not internally held by the context. The data tree just points and lean on some data 1158 * held by the context (schema tree, string dictionary, etc.). Therefore, in case of data trees, caller 1159 * is supposed to keep pointers returned by the lyd_parse() and manage the data tree on its own. This 1160 * also affects the number of instances of both tree types. While you can have only one instance of 1161 * specific schema connected with a single context, number of data tree instances is not connected. 1162 * 1163 * @param[in] search_dir Directory where libyang will search for the imported or included modules 1164 * and submodules. If no such directory is available, NULL is accepted. 1165 * @param[in] options Context options, see @ref contextoptions. 1166 * 1167 * @return Pointer to the created libyang context, NULL in case of error. 1168 */ 1169struct ly_ctx *ly_ctx_new(const char *search_dir, int options); 1170 1171/** 1172 * @brief Create libyang context according to the content of the given yang-library data. 1173 * 1174 * This function loads the yang-library data from the file at the given path. If you need 1175 * to pass the data as string, use ly_ctx_new_ylmem(). Both functions extend functionality of 1176 * ly_ctx_new() by loading modules specified in the ietf-yang-library form into the context 1177 * being created. 1178 * 1179 * The preferred tree model revision is 2018-01-17. However, only the first module-set is processed 1180 * and loaded into the context. If there are no matching nodes from this tree, the legacy tree 1181 * (originally from model revision 2016-04-09) is processed. 1182 * 1183 * Note, that the modules are loaded the same way as in case of ly_ctx_load_module(), so the schema 1184 * paths in the yang-library data are ignored and the modules are loaded from the context's search 1185 * locations. On the other hand, YANG features of the modules are set as specified in the yang-library 1186 * data. 1187 * 1188 * To get yang library data from a libyang context, use ly_ctx_info(). 1189 * 1190 * @param[in] search_dir Directory where libyang will search for the imported or included modules 1191 * and submodules. If no such directory is available, NULL is accepted. 1192 * @param[in] path Path to the file containing yang-library data in the specified \p format. 1193 * @param[in] format Format of the data in the provided file. 1194 * @param[in] options Context options, see @ref contextoptions. 1195 * @return Pointer to the created libyang context, NULL in case of error. 1196 */ 1197struct ly_ctx *ly_ctx_new_ylpath(const char *search_dir, const char *path, LYD_FORMAT format, int options); 1198 1199/** 1200 * @brief Create libyang context according to the content of the given yang-library data. 1201 * 1202 * This function loads the yang-library data from the given string. If you need to pass the data 1203 * as path to a file holding the data, use ly_ctx_new_ylpath(). Both functions extend functionality of 1204 * ly_ctx_new() by loading modules specified in the ietf-yang-library form into the context 1205 * being created. 1206 * 1207 * The preferred tree model revision is 2018-01-17. However, only the first module-set is processed 1208 * and loaded into the context. If there are no matching nodes from this tree, the legacy tree 1209 * (originally from model revision 2016-04-09) is processed. 1210 * 1211 * Note, that the modules are loaded the same way as in case of ly_ctx_load_module(), so the schema 1212 * paths in the yang-library data are ignored and the modules are loaded from the context's search 1213 * locations. On the other hand, YANG features of the modules are set as specified in the yang-library 1214 * data. 1215 * 1216 * To get yang library data from a libyang context, use ly_ctx_info(). 1217 * 1218 * @param[in] search_dir Directory where libyang will search for the imported or included modules 1219 * and submodules. If no such directory is available, NULL is accepted. 1220 * @param[in] data String containing yang-library data in the specified \p format. 1221 * @param[in] format Format of the data in the provided file. 1222 * @param[in] options Context options, see @ref contextoptions. 1223 * @return Pointer to the created libyang context, NULL in case of error. 1224 */ 1225struct ly_ctx *ly_ctx_new_ylmem(const char *search_dir, const char *data, LYD_FORMAT format, int options); 1226 1227/** 1228 * @brief Number of internal modules, which are in the context and cannot be removed nor disabled. 1229 * @param[in] ctx Context to investigate. 1230 * @return Number of internal modules, 0 in case of invalid parameter. 1231 */ 1232unsigned int ly_ctx_internal_modules_count(struct ly_ctx *ctx); 1233 1234/** 1235 * @brief Add the search path into libyang context 1236 * 1237 * To reset search paths set in the context, use ly_ctx_unset_searchdirs() and then 1238 * set search paths again. 1239 * 1240 * @param[in] ctx Context to be modified. 1241 * @param[in] search_dir New search path to add to the current paths previously set in ctx. 1242 * @return EXIT_SUCCESS, EXIT_FAILURE. 1243 */ 1244int ly_ctx_set_searchdir(struct ly_ctx *ctx, const char *search_dir); 1245 1246/** 1247 * @brief Clean the search path(s) from the libyang context 1248 * 1249 * @param[in] ctx Context to be modified. 1250 * @param[in] index Index of the search path to be removed, use negative value to remove them all. 1251 * Correct index value can be checked via ly_ctx_get_searchdirs(). 1252 */ 1253void ly_ctx_unset_searchdirs(struct ly_ctx *ctx, int index); 1254 1255/** 1256 * @brief Get the NULL-terminated list of the search paths in libyang context. 1257 * 1258 * @param[in] ctx Context to query. 1259 * @return NULL-terminated list (array) of the search paths, NULL if no searchpath was set. 1260 */ 1261const char * const *ly_ctx_get_searchdirs(const struct ly_ctx *ctx); 1262 1263/** 1264 * @brief Get the currently set context's options. 1265 * 1266 * @param[in] ctx Context to query. 1267 * @return Combination of all the currently set context's options, see @ref contextoptions. 1268 */ 1269int ly_ctx_get_options(struct ly_ctx *ctx); 1270 1271/** 1272 * @brief Make context to stop searching for schemas (imported, included or requested via ly_ctx_load_module()) 1273 * in searchdirs set via ly_ctx_set_searchdir() functions. Searchdirs are still stored in the context, so by 1274 * unsetting the option by ly_ctx_unset_disable_searchdirs() searching in all previously searchdirs is restored. 1275 * 1276 * The same effect is achieved by using #LY_CTX_DISABLE_SEARCHDIRS option when creating new context or parsing 1277 * a specific schema. 1278 * 1279 * @param[in] ctx Context to be modified. 1280 */ 1281void ly_ctx_set_disable_searchdirs(struct ly_ctx *ctx); 1282 1283/** 1284 * @brief Reverse function to ly_ctx_set_disable_searchdirs(). 1285 * 1286 * @param[in] ctx Context to be modified. 1287 */ 1288void ly_ctx_unset_disable_searchdirs(struct ly_ctx *ctx); 1289 1290/** 1291 * @brief Make context to stop implicitly searching for schemas (imported, included or requested via ly_ctx_load_module()) 1292 * in current working directory. This flag can be unset by ly_ctx_unset_disable_searchdir_cwd(). 1293 * 1294 * The same effect is achieved by using #LY_CTX_DISABLE_SEARCHDIR_CWD option when creating new context or parsing 1295 * a specific schema. 1296 * 1297 * @param[in] ctx Context to be modified. 1298 */ 1299void ly_ctx_set_disable_searchdir_cwd(struct ly_ctx *ctx); 1300 1301/** 1302 * @brief Reverse function to ly_ctx_set_disable_searchdir_cwd(). 1303 * 1304 * @param[in] ctx Context to be modified. 1305 */ 1306void ly_ctx_unset_disable_searchdir_cwd(struct ly_ctx *ctx); 1307 1308/** 1309 * @brief Prefer context's searchdirs before the user callback (ly_module_imp_clb) provided via ly_ctx_set_module_imp_clb()). 1310 * 1311 * The same effect is achieved by using #LY_CTX_PREFER_SEARCHDIRS option when creating new context or parsing 1312 * a specific schema. 1313 * 1314 * @param[in] ctx Context to be modified. 1315 */ 1316void ly_ctx_set_prefer_searchdirs(struct ly_ctx *ctx); 1317 1318/** 1319 * @brief Reverse function to ly_ctx_set_prefer_searchdirs(). 1320 * 1321 * @param[in] ctx Context to be modified. 1322 */ 1323void ly_ctx_unset_prefer_searchdirs(struct ly_ctx *ctx); 1324 1325/** 1326 * @brief Make context to set all the imported modules to be implemented. By default, 1327 * if the imported module is not used in leafref's path, augment or deviation, it is 1328 * imported and its data tree is not taken into account. 1329 * 1330 * The same effect is achieved by using #LY_CTX_ALLIMPLEMENTED option when creating new context or parsing 1331 * a specific schema. 1332 * 1333 * Note, that function does not make the currently loaded modules, it just change the 1334 * schema parser behavior for the future parsing. This flag can be unset by ly_ctx_unset_allimplemented(). 1335 * 1336 * @param[in] ctx Context to be modified. 1337 */ 1338void ly_ctx_set_allimplemented(struct ly_ctx *ctx); 1339 1340/** 1341 * @brief Reverse function to ly_ctx_set_allimplemented(). 1342 * 1343 * @param[in] ctx Context to be modified. 1344 */ 1345void ly_ctx_unset_allimplemented(struct ly_ctx *ctx); 1346 1347/** 1348 * @brief Change the schema parser behavior when parsing new schemas forcing it to skip some of the schema 1349 * validation checks to improve performance. Note that parsing invalid schemas this way may lead to an 1350 * undefined behavior later, e.g. when working with data trees. 1351 * 1352 * The same effect is achieved by using #LY_CTX_TRUSTED option when creating new context or parsing 1353 * a specific schema. 1354 * 1355 * This flag can be unset by ly_ctx_unset_trusted(). 1356 * 1357 * @param[in] ctx Context to be modified. 1358 */ 1359void ly_ctx_set_trusted(struct ly_ctx *ctx); 1360 1361/** 1362 * @brief Reverse function to ly_ctx_set_trusted(). 1363 * 1364 * @param[in] ctx Context to be modified. 1365 */ 1366void ly_ctx_unset_trusted(struct ly_ctx *ctx); 1367 1368/** 1369 * @brief Get current ID of the modules set. The value is available also 1370 * as module-set-id in ly_ctx_info() result. 1371 * 1372 * @param[in] ctx Context to be examined. 1373 * @return Numeric identifier of the current context's modules set. 1374 */ 1375uint16_t ly_ctx_get_module_set_id(const struct ly_ctx *ctx); 1376 1377/** 1378 * @brief Get data of an internal ietf-yang-library module. 1379 * 1380 * @param[in] ctx Context with the modules. 1381 * @return Root data node corresponding to the model, NULL on error. 1382 * Caller is responsible for freeing the returned data tree using lyd_free(). 1383 */ 1384struct lyd_node *ly_ctx_info(struct ly_ctx *ctx); 1385 1386/** 1387 * @brief Iterate over all (enabled) modules in a context. 1388 * 1389 * @param[in] ctx Context with the modules. 1390 * @param[in,out] idx Index of the next module to be returned. Value of 0 starts from the beginning. 1391 * @return Next context module, NULL if the last was already returned. 1392 */ 1393const struct lys_module *ly_ctx_get_module_iter(const struct ly_ctx *ctx, uint32_t *idx); 1394 1395/** 1396 * @brief Iterate over the disabled modules in a context. 1397 * 1398 * @param[in] ctx Context with the modules. 1399 * @param[in,out] idx Index of the next module to be returned. Value of 0 starts from the beginning. 1400 * @return Next context module, NULL if the last was already returned. 1401 */ 1402const struct lys_module *ly_ctx_get_disabled_module_iter(const struct ly_ctx *ctx, uint32_t *idx); 1403 1404/** 1405 * @brief Get pointer to the schema tree of the module of the specified name. 1406 * 1407 * @param[in] ctx Context to work in. 1408 * @param[in] name Name of the YANG module to get. 1409 * @param[in] revision Optional revision date of the YANG module to get. If not specified, 1410 * the schema in the newest/implemented revision (see \p implemented parameter) is returned if any. 1411 * @param[in] implemented In case the revision is not specified, require the implemented module 1412 * instead of the newest revision of the module. 1413 * @return Pointer to the data model structure, NULL if no schema following the name and 1414 * revision requirements is present in the context. 1415 */ 1416const struct lys_module *ly_ctx_get_module(const struct ly_ctx *ctx, const char *name, const char *revision, int implemented); 1417 1418/** 1419 * @brief Get pointer to the older schema tree to the specified one in the provided context. 1420 * 1421 * The module is not necessarily from the provided \p ctx. If there are multiple schemas older than the 1422 * provided one, the newest of them is returned. 1423 * 1424 * The function can be used in combination with ly_ctx_get_module() to get all revisions of a module in a context: 1425 * \code{.c} 1426 * for (mod = ly_ctx_get_module(ctx, name, NULL); mod; mod = ly_ctx_get_module_older(ctx, mod)) { 1427 * ... 1428 * } 1429 * \endcode 1430 * 1431 * @param[in] ctx Context to work in. 1432 * @param[in] module YANG module to compare with 1433 * @return Pointer to the data model structure, NULL if no older schema is present in the context. 1434 */ 1435const struct lys_module *ly_ctx_get_module_older(const struct ly_ctx *ctx, const struct lys_module *module); 1436 1437/** 1438 * @brief Try to find the model in the searchpath of \p ctx and load it into it. If custom missing 1439 * module callback is set, it is used instead. 1440 * 1441 * If there is a possibility that the requested module is already in the context, you should call 1442 * the ly_ctx_get_module() first to avoid a lot of work performed by ly_ctx_load_module(). 1443 * 1444 * @param[in] ctx Context to add to. 1445 * @param[in] name Name of the module to load. 1446 * @param[in] revision Optional revision date of the module. If not specified, it is 1447 * assumed that there is only one model revision in the searchpath (the first matching file 1448 * is parsed). 1449 * @return Pointer to the data model structure, NULL if not found or some error occurred. 1450 */ 1451const struct lys_module *ly_ctx_load_module(struct ly_ctx *ctx, const char *name, const char *revision); 1452 1453/** 1454 * @brief Callback for retrieving missing included or imported models in a custom way. 1455 * 1456 * @param[in] mod_name Missing module name. 1457 * @param[in] mod_rev Optional missing module revision. 1458 * @param[in] submod_name Optional missing submodule name. 1459 * @param[in] submod_rev Optional missing submodule revision. 1460 * @param[in] user_data User-supplied callback data. 1461 * @param[out] format Format of the returned module data. 1462 * @param[out] free_module_data Callback for freeing the returned module data. If not set, the data will be left untouched. 1463 * @return Requested module data, NULL if the module is supposed to be loaded 1464 * using standard mechanisms (searched for in the filesystem), NULL and #ly_errno set if 1465 * the callback failed resulting in the module failing to load. 1466 * If an @arg free_module_data callback is provided, it will be used to free the allegedly const data 1467 * which were returned by this callback. 1468 */ 1469typedef const char *(*ly_module_imp_clb)(const char *mod_name, const char *mod_rev, const char *submod_name, const char *sub_rev, 1470 void *user_data, LYS_INFORMAT *format, void (**free_module_data)(void *model_data, void *user_data)); 1471 1472/** 1473 * @brief Set missing include or import module callback. It is meant to be used when the models 1474 * are not locally available (such as when downloading modules from a NETCONF server), it should 1475 * not be required in other cases. 1476 * 1477 * @param[in] ctx Context that will use this callback. 1478 * @param[in] clb Callback responsible for returning the missing model. 1479 * @param[in] user_data Arbitrary data that will always be passed to the callback \p clb. 1480 */ 1481void ly_ctx_set_module_imp_clb(struct ly_ctx *ctx, ly_module_imp_clb clb, void *user_data); 1482 1483/** 1484 * @brief Get the custom callback for missing import/include module retrieval. 1485 * 1486 * @param[in] ctx Context to read from. 1487 * @param[in] user_data Optional pointer for getting the user-supplied callback data. 1488 * @return Callback or NULL if not set. 1489 */ 1490ly_module_imp_clb ly_ctx_get_module_imp_clb(const struct ly_ctx *ctx, void **user_data); 1491 1492/** 1493 * @brief Callback for retrieving missing modules in the context, for which some data was found. 1494 * 1495 * Either \p name or \p ns is ALWAYS set, but both can also be set. 1496 * 1497 * @param[in,out] ctx Context with the missing module. 1498 * @param[in] name Missing module name. 1499 * @param[in] ns Missing module namespace. 1500 * @param[in] options Bitmask of LY_MODCLB_* values or 0. 1501 * @param[in] user_data User-supplied callback data. 1502 * @return Newly added or modified module, NULL on failure. 1503 */ 1504typedef const struct lys_module *(*ly_module_data_clb)(struct ly_ctx *ctx, const char *name, const char *ns, 1505 int options, void *user_data); 1506 1507/* Module is in the context, but is not implemented, so to continue with the data operation, it must be implemented. */ 1508#define LY_MODCLB_NOT_IMPLEMENTED 0x01 1509 1510/** 1511 * @brief Set the missing data module callback. It will be called when some data is parsed or searched for and their module 1512 * is not found in the context or is not implemented. 1513 * 1514 * @param[in] ctx Context that will use this callback. 1515 * @param[in] clb Callback responsible for returning the missing model. 1516 * @param[in] user_data Arbitrary data that will always be passed to the callback \p clb. 1517 */ 1518void ly_ctx_set_module_data_clb(struct ly_ctx *ctx, ly_module_data_clb clb, void *user_data); 1519 1520/** 1521 * @brief Get the missing data module calback. 1522 * 1523 * @param[in] ctx Context to read from. 1524 * @param[in] user_data Optional pointer for getting the user-supplied callback data. 1525 * @return Callback or NULL if not set. 1526 */ 1527ly_module_data_clb ly_ctx_get_module_data_clb(const struct ly_ctx *ctx, void **user_data); 1528 1529#ifdef LY_ENABLED_LYD_PRIV 1530 1531void ly_ctx_set_priv_dup_clb(struct ly_ctx *ctx, void *(*priv_dup_clb)(const void *priv)); 1532 1533#endif 1534 1535/** 1536 * @brief Get pointer to the schema tree of the module of the specified namespace 1537 * 1538 * @param[in] ctx Context to work in. 1539 * @param[in] ns Namespace of the YANG module to get. 1540 * @param[in] revision Optional revision date of the YANG module to get. If not specified, 1541 * the schema in the newest/implemented revision (see \p implemented parameter) is returned if any. 1542 * @param[in] implemented In case the revision is not specified, require the implemented module 1543 * instead of the newest revision of the module. 1544 * @return Pointer to the data model structure, NULL if no schema following the namespace and 1545 * revision requirements is present in the context. 1546 */ 1547const struct lys_module *ly_ctx_get_module_by_ns(const struct ly_ctx *ctx, const char *ns, const char *revision, int implemented); 1548 1549/** 1550 * @brief Get submodule of a main module. 1551 * 1552 * If you already have the pointer to the submodule's main module, use ly_ctx_get_submodule2() instead. 1553 * 1554 * @param[in] ctx Context to work in. 1555 * @param[in] module Name of the main (belongs-to) module. If NULL, all module submodules are searched. 1556 * @param[in] revision Optional revision date of \p module. If NULL, all revisions of \p module 1557 * are searched. If set, \p module must also be set. 1558 * @param[in] submodule Name of the submodule to get. 1559 * @param[in] sub_revision Optional revision date of \p submodule. If NULL, the newest revision of \p submodule 1560 * is returned. 1561 * @return Pointer to the data model structure. 1562 */ 1563const struct lys_submodule *ly_ctx_get_submodule(const struct ly_ctx *ctx, const char *module, const char *revision, 1564 const char *submodule, const char *sub_revision); 1565 1566/** 1567 * @brief Get submodule of a main module. 1568 * 1569 * If you have only the name (and optionally revision) of the submodule's main module, use ly_ctx_get_submodule() 1570 * instead. 1571 * 1572 * @param[in] main_module Main module (belongs to) of the searched submodule. 1573 * @param[in] submodule Name of the submodule to get. 1574 * @return Pointer to the data model structure. 1575 */ 1576const struct lys_submodule *ly_ctx_get_submodule2(const struct lys_module *main_module, const char *submodule); 1577 1578/** 1579 * @brief Get schema node according to the given data path (JSON format, see @ref howtoxpath). 1580 * 1581 * This function is meant as a utility function to ease getting a specific schema node 1582 * directly from context having \p data_path a const immutable string. Generally, 1583 * it is better to use lyd_find_path(), lys_find_path(), or ly_ctx_find_path(). Also, 1584 * it is possible to transform data paths into schema paths using ly_path_data2schema(). 1585 * 1586 * @param[in] ctx Context to work in. Must be set if \p start is NULL. 1587 * @param[in] start Starting node for a relative data node identifier, in which 1588 * case it is mandatory and \p ctx can be NULL. 1589 * @param[in] data_path JSON data path of the node to get. 1590 * @param[in] output Search operation output instead input. 1591 * @return Resolved schema node or NULL. 1592 */ 1593const struct lys_node *ly_ctx_get_node(const struct ly_ctx *ctx, const struct lys_node *start, const char *data_path, int output); 1594 1595/** 1596 * @brief Get schema node according to the given schema path (see @ref howtoxpath). 1597 * 1598 * Note that the given path must be absolute and fully prefixed (which is the default output 1599 * of lys_path() function). To get node specified by a relative path, use lys_find_path() instead. 1600 * 1601 * @param[in] ctx Context to work in. 1602 * @param[in] path Schema path of the node to find. 1603 * @return Set of found schema nodes. If no nodes are matching \p path the returned set is empty. 1604 * In case of an error, NULL is returned. 1605 */ 1606struct ly_set *ly_ctx_find_path(struct ly_ctx *ctx, const char *path); 1607 1608/** 1609 * @brief Remove the specified module from its context. 1610 * 1611 * Beside the selected module, also all other modules depending on all the modules being removed 1612 * will be removed as well. 1613 * 1614 * libyang internal modules (those present when the context is created) cannot be removed. 1615 * 1616 * @param[in] module Module to be removed. 1617 * @param[in] private_destructor Optional destructor function for private objects assigned 1618 * to the nodes via lys_set_private(). If NULL, the private objects are not freed by libyang. 1619 * @return EXIT_SUCCESS or EXIT_FAILURE (in case of invalid parameter). 1620 */ 1621int ly_ctx_remove_module(const struct lys_module *module, 1622 void (*private_destructor)(const struct lys_node *node, void *priv)); 1623 1624/** 1625 * @brief Remove all the modules from the context except the internal modules. Also the addition data in 1626 * dictionary are kept. 1627 * 1628 * @param[in] ctx Context to work in. 1629 * @param[in] private_destructor Optional destructor function for private objects assigned 1630 * to the nodes via lys_set_private(). If NULL, the private objects are not freed by libyang. 1631 */ 1632void ly_ctx_clean(struct ly_ctx *ctx, void (*private_destructor)(const struct lys_node *node, void *priv)); 1633 1634/** 1635 * @brief Free all internal structures of the specified context. 1636 * 1637 * The function should be used before terminating the application to destroy 1638 * and free all structures internally used by libyang. If the caller uses 1639 * multiple contexts, the function should be called for each used context. 1640 * 1641 * All instance data are supposed to be freed before destroying the context. 1642 * Data models are destroyed automatically as part of ly_ctx_destroy() call. 1643 * 1644 * @param[in] ctx libyang context to destroy 1645 * @param[in] private_destructor Optional destructor function for private objects assigned 1646 * to the nodes via lys_set_private(). If NULL, the private objects are not freed by libyang. 1647 * Remember the differences between the structures derived from ::lys_node and always check 1648 * ::lys_node#nodetype. 1649 */ 1650void ly_ctx_destroy(struct ly_ctx *ctx, void (*private_destructor)(const struct lys_node *node, void *priv)); 1651 1652/** 1653 * @brief Transform a data path in XML format (node prefixes are XML namespace prefixes of module namespaces) 1654 * to JSON format (node prefixes are module names directly). 1655 * 1656 * @param[in] ctx Context to work in. 1657 * @param[in] xml_path Path in XML format to transform. 1658 * @param[in] xml XML tree to be used for XML namespace prefix resolution. 1659 * @return Transformed JSON data path, needs to be freed. NULL on error. 1660 */ 1661char *ly_path_xml2json(struct ly_ctx *ctx, const char *xml_path, struct lyxml_elem *xml); 1662 1663/** 1664 * @brief Transform a data path into schema path (see @ref howtoxpath). 1665 * 1666 * Some XPath tokens such as "*" or "//" should not be used because they cannot be properly 1667 * transformed into schema path. If used, any following nodes will not be transformed and simply copied, 1668 * so use at your own risk! It causes no problems if the path ends with the aforementioned tokens. 1669 * 1670 * @param[in] ctx Context to work in. 1671 * @param[in] data_path Data path to be transformed. 1672 * @return Created schema path, NULL on error. 1673 */ 1674char *ly_path_data2schema(struct ly_ctx *ctx, const char *data_path); 1675 1676/** @} context */ 1677 1678/** 1679 * @defgroup nodeset Tree nodes set 1680 * @ingroup datatree 1681 * @ingroup schematree 1682 * @{ 1683 * 1684 * Structure and functions to hold and manipulate with sets of nodes from schema or data trees. 1685 */ 1686 1687/** 1688 * @brief set array of ::ly_set 1689 * It is kept in union to keep ::ly_set generic for data as well as schema trees 1690 */ 1691union ly_set_set { 1692 struct lys_node **s; /**< array of pointers to a ::lys_node objects */ 1693 struct lyd_node **d; /**< array of pointers to a ::lyd_node objects */ 1694 void **g; /**< dummy array for generic work */ 1695}; 1696 1697/** 1698 * @brief Structure to hold a set of (not necessary somehow connected) ::lyd_node or ::lys_node objects. 1699 * Caller is supposed to not mix the type of objects added to the set and according to its knowledge about 1700 * the set content, it is supposed to access the set via the sset, dset or set members of the structure. 1701 * 1702 * Until ly_set_rm() or ly_set_rm_index() is used, the set keeps the order of the inserted items as they 1703 * were added into the set, so the first added item is on array index 0. 1704 * 1705 * To free the structure, use ly_set_free() function, to manipulate with the structure, use other 1706 * ly_set_* functions. 1707 */ 1708struct ly_set { 1709 unsigned int size; /**< allocated size of the set array */ 1710 unsigned int number; /**< number of elements in (used size of) the set array */ 1711 union ly_set_set set; /**< set array - union to keep ::ly_set generic for data as well as schema trees */ 1712}; 1713 1714/** 1715 * @brief Option for ly_set_add() to allow duplicities in the ly_set structure so the 1716 * set is not used as a set, but as a list of (container for) items. 1717 */ 1718#define LY_SET_OPT_USEASLIST 0x01 1719 1720/** 1721 * @brief Create and initiate new ::ly_set structure. 1722 * 1723 * @return Created ::ly_set structure or NULL in case of error. 1724 */ 1725struct ly_set *ly_set_new(void); 1726 1727/** 1728 * @brief Duplicate the existing set. 1729 * 1730 * @param[in] set Original set to duplicate 1731 * @return Duplication of the original set. 1732 */ 1733struct ly_set *ly_set_dup(const struct ly_set *set); 1734 1735/** 1736 * @brief Add a ::lyd_node or ::lys_node object into the set 1737 * 1738 * Since it is a set, the function checks for duplicity and if the 1739 * node is already in the set, the index of the previously added 1740 * node is returned. 1741 * 1742 * @param[in] set Set where the \p node will be added. 1743 * @param[in] node The ::lyd_node or ::lys_node object to be added into the \p set; 1744 * @param[in] options Options to change behavior of the function. Accepted options are: 1745 * - #LY_SET_OPT_USEASLIST - do not check for duplicities 1746 * @return -1 on failure, index of the \p node in the set on success 1747 */ 1748int ly_set_add(struct ly_set *set, void *node, int options); 1749 1750/** 1751 * @brief Add all objects from \p src to \p trg. 1752 * 1753 * Since it is a set, the function checks for duplicities. 1754 * After success, \p src is completely freed. 1755 * 1756 * @param[in] trg Target (result) set. 1757 * @param[in] src Source set. 1758 * @param[in] options Options to change behavior of the function. Accepted options are: 1759 * - #LY_SET_OPT_USEASLIST - do not check for duplicities 1760 * @return -1 on failure, number of objects added into \p trg on success. 1761 */ 1762int ly_set_merge(struct ly_set *trg, struct ly_set *src, int options); 1763 1764/** 1765 * @brief Get know if the set contains the specified object. 1766 * @param[in] set Set to explore. 1767 * @param[in] node Object to be found in the set. 1768 * @return Index of the object in the set or -1 if the object is not present in the set. 1769 */ 1770int ly_set_contains(const struct ly_set *set, void *node); 1771 1772/** 1773 * @brief Remove all objects from the set, but keep the set container for further use. 1774 * 1775 * @param[in] set Set to clean. 1776 * @return 0 on success 1777 */ 1778int ly_set_clean(struct ly_set *set); 1779 1780/** 1781 * @brief Remove a ::lyd_node or ::lys_node object from the set. 1782 * 1783 * Note that after removing a node from a set, indexes of other nodes in the set can change 1784 * (the last object is placed instead of the removed object). 1785 * 1786 * @param[in] set Set from which the \p node will be removed. 1787 * @param[in] node The ::lyd_node or ::lys_node object to be removed from the \p set; 1788 * @return 0 on success 1789 */ 1790int ly_set_rm(struct ly_set *set, void *node); 1791 1792/** 1793 * @brief Remove a ::lyd_node or ::lys_node object from the set index. 1794 * 1795 * Note that after removing a node from a set, indexes of other nodes in the set can change 1796 * (the last object is placed instead of the removed object). 1797 * 1798 * @param[in] set Set from which a node will be removed. 1799 * @param[in] index Index of the ::lyd_node or ::lys_node object in the \p set to be removed from the \p set; 1800 * @return 0 on success 1801 */ 1802int ly_set_rm_index(struct ly_set *set, unsigned int index); 1803 1804/** 1805 * @brief Free the ::ly_set data. Frees only the set structure content, not the referred data. 1806 * 1807 * @param[in] set The set to be freed. 1808 */ 1809void ly_set_free(struct ly_set *set); 1810 1811/**@} nodeset */ 1812 1813/** 1814 * @defgroup printerflags Printer flags 1815 * @ingroup datatree 1816 * 1817 * Validity flags for data nodes. 1818 * 1819 * @{ 1820 */ 1821#define LYP_WITHSIBLINGS 0x01 /**< Flag for printing also the (following) sibling nodes of the data node. */ 1822#define LYP_FORMAT 0x02 /**< Flag for formatted output. */ 1823#define LYP_KEEPEMPTYCONT 0x04 /**< Preserve empty non-presence containers */ 1824#define LYP_WD_MASK 0xF0 /**< Mask for with-defaults modes */ 1825#define LYP_WD_EXPLICIT 0x00 /**< Explicit mode - print only data explicitly being present in the data tree. 1826 Note that this is the default value when no WD option is specified. */ 1827#define LYP_WD_TRIM 0x10 /**< Do not print the nodes with the value equal to their default value */ 1828#define LYP_WD_ALL 0x20 /**< Include implicit default nodes */ 1829#define LYP_WD_ALL_TAG 0x40 /**< Same as #LYP_WD_ALL but also adds attribute 'default' with value 'true' to 1830 all nodes that has its default value. The 'default' attribute has namespace: 1831 urn:ietf:params:xml:ns:netconf:default:1.0 and thus the attributes are 1832 printed only when the ietf-netconf-with-defaults module is present in libyang 1833 context (but in that case this namespace is always printed). */ 1834#define LYP_WD_IMPL_TAG 0x80 /**< Same as LYP_WD_ALL_TAG but the attributes are added only to the nodes that 1835 are not explicitly present in the original data tree despite their 1836 value is equal to their default value. There is the same limitation regarding 1837 the presence of ietf-netconf-with-defaults module in libyang context. */ 1838#define LYP_NETCONF 0x100 /**< Print the data tree for use in NETCONF meaning: 1839 - for RPC output - skip the top-level RPC node, 1840 - for action output - skip all the parents of and the action node itself, 1841 - for action input - enclose the data in an action element in the base YANG namespace, 1842 - for all other data - print the whole data tree normally. */ 1843 1844/** 1845 * @} 1846 */ 1847 1848/** 1849 * @defgroup logger Logger 1850 * @{ 1851 * 1852 * Publicly visible functions and values of the libyang logger. For more 1853 * information, see \ref howtologger. 1854 */ 1855 1856/** 1857 * @typedef LY_LOG_LEVEL 1858 * @brief Verbosity levels of the libyang logger. 1859 */ 1860typedef enum { 1861 LY_LLERR = 0, /**< Print only error messages, default value. */ 1862 LY_LLWRN = 1, /**< Print error and warning messages. */ 1863 LY_LLVRB = 2, /**< Besides errors and warnings, print some other verbose messages. */ 1864 LY_LLDBG = 3 /**< Print all messages including some development debug messages (be careful, 1865 without subsequently calling ly_verb_dbg() no debug messages will be printed!). */ 1866} LY_LOG_LEVEL; 1867 1868/** 1869 * @brief Set logger verbosity level. 1870 * @param[in] level Verbosity level. 1871 * @return Previous verbosity level. 1872 */ 1873LY_LOG_LEVEL ly_verb(LY_LOG_LEVEL level); 1874 1875/** 1876 * @defgroup logopts Logging options 1877 * @ingroup logger 1878 * 1879 * Logging option bits of libyang. 1880 * 1881 * @{ 1882 */ 1883#define LY_LOLOG 0x01 /**< Log messages normally, using callback if set. If not set, messages will 1884 not be printed by libyang. */ 1885#define LY_LOSTORE 0x02 /**< Store any generated errors or warnings, never verbose or debug messages. 1886 Note that if #LY_LOLOG is not set then verbose and debug messages are always lost. */ 1887#define LY_LOSTORE_LAST 0x06 /**< Store any generated errors or warnings but only the last message, always overwrite 1888 the previous one. */ 1889 1890/** 1891 * @} 1892 */ 1893 1894/** 1895 * @brief Set additional logger options. Default is #LY_LOLOG | #LY_LOSTORE_LAST. 1896 * 1897 * @param[in] opts Bitfield of @ref logopts. 1898 * @return Previous logger options. 1899 */ 1900int ly_log_options(int opts); 1901 1902#ifndef NDEBUG 1903 1904/** 1905 * @defgroup dbggroup Debug message groups 1906 * @ingroup logger 1907 * 1908 * Selected displayed debug message groups. 1909 * 1910 * @{ 1911 */ 1912 1913#define LY_LDGDICT 0x01 /**< Dictionary additions and deletions. */ 1914#define LY_LDGYANG 0x02 /**< YANG parser messages. */ 1915#define LY_LDGYIN 0x04 /**< YIN parser messages. */ 1916#define LY_LDGXPATH 0x08 /**< XPath parsing end evaluation. */ 1917#define LY_LDGDIFF 0x10 /**< Diff processing and creation. */ 1918#define LY_LDGAPI 0x20 /**< API tracing. */ 1919#define LY_LDGHASH 0x40 /**< Hash table modifications. */ 1920 1921/** 1922 * @} 1923 */ 1924 1925/** 1926 * @brief Enable specific debugging messages (independent of log level). 1927 * @param[in] dbg_groups Bitfield of enabled debug message groups (see @ref dbggroup). 1928 */ 1929void ly_verb_dbg(int dbg_groups); 1930 1931#endif 1932 1933/** 1934 * @brief Set logger callback. 1935 * 1936 * !IMPORTANT! If an error has a specific error-app-tag defined in the model, it will NOT be set 1937 * at the time of calling this callback. It will be set right after, so to retrieve it 1938 * it must be checked afterwards with ly_errapptag(). 1939 * 1940 * @param[in] clb Logging callback. 1941 * @param[in] path flag to resolve and provide path as the third parameter of the callback function. In case of 1942 * validation and some other errors, it can be useful to get the path to the problematic element. Note, 1943 * that according to the tree type and the specific situation, the path can slightly differs (keys 1944 * presence) or it can be NULL, so consider it as an optional parameter. If the flag is 0, libyang will 1945 * not bother with resolving the path. 1946 */ 1947void ly_set_log_clb(void (*clb)(LY_LOG_LEVEL level, const char *msg, const char *path), int path); 1948 1949/** 1950 * @brief Get logger callback. 1951 * @return Logger callback (can be NULL). 1952 */ 1953void (*ly_get_log_clb(void))(LY_LOG_LEVEL, const char *, const char *); 1954 1955/** 1956 * @typedef LY_ERR 1957 * @brief libyang's error codes available via ly_errno extern variable. 1958 * @ingroup logger 1959 */ 1960typedef enum { 1961 LY_SUCCESS = 0, /**< no error, not set by functions, included just to complete #LY_ERR enumeration */ 1962 LY_EMEM, /**< Memory allocation failure */ 1963 LY_ESYS, /**< System call failure */ 1964 LY_EINVAL, /**< Invalid value */ 1965 LY_EINT, /**< Internal error */ 1966 LY_EVALID, /**< Validation failure */ 1967 LY_EPLUGIN /**< Error reported by a plugin */ 1968} LY_ERR; 1969 1970/** 1971 * @typedef LY_VECODE 1972 * @brief libyang's codes of validation error. Whenever ly_errno is set to LY_EVALID, the ly_vecode is also set 1973 * to the appropriate LY_VECODE value. 1974 * @ingroup logger 1975 */ 1976typedef enum { 1977 LYVE_SUCCESS = 0, /**< no error */ 1978 1979 LYVE_XML_MISS, /**< missing XML object */ 1980 LYVE_XML_INVAL, /**< invalid XML object */ 1981 LYVE_XML_INCHAR, /**< invalid XML character */ 1982 1983 LYVE_EOF, /**< unexpected end of input data */ 1984 LYVE_INSTMT, /**< invalid statement (schema) */ 1985 /* */ 1986 LYVE_INPAR, /**< invalid (in)direct parent (schema) */ 1987 LYVE_INID, /**< invalid identifier (schema) */ 1988 LYVE_INDATE, /**< invalid date format */ 1989 LYVE_INARG, /**< invalid value of a statement argument (schema) */ 1990 LYVE_MISSSTMT, /**< missing required statement (schema) */ 1991 /* */ 1992 LYVE_MISSARG, /**< missing required statement argument (schema) */ 1993 LYVE_TOOMANY, /**< too many instances of some object */ 1994 LYVE_DUPID, /**< duplicated identifier (schema) */ 1995 LYVE_DUPLEAFLIST, /**< multiple instances of leaf-list */ 1996 LYVE_DUPLIST, /**< multiple instances of list */ 1997 LYVE_NOUNIQ, /**< unique leaves match on 2 list instances (data) */ 1998 LYVE_ENUM_INVAL, /**< invalid enum value (schema) */ 1999 LYVE_ENUM_INNAME, /**< invalid enum name (schema) */ 2000 /* */ 2001 /* */ 2002 LYVE_ENUM_WS, /**< enum name with leading/trailing whitespaces (schema) */ 2003 LYVE_BITS_INVAL, /**< invalid bits value (schema) */ 2004 LYVE_BITS_INNAME, /**< invalid bits name (schema) */ 2005 /* */ 2006 /* */ 2007 LYVE_INMOD, /**< invalid module name */ 2008 /* */ 2009 LYVE_KEY_NLEAF, /**< list key is not a leaf (schema) */ 2010 LYVE_KEY_TYPE, /**< invalid list key type (schema) */ 2011 LYVE_KEY_CONFIG, /**< key config value differs from the list config value */ 2012 LYVE_KEY_MISS, /**< list key not found (schema) */ 2013 LYVE_KEY_DUP, /**< duplicated key identifier (schema) */ 2014 LYVE_INREGEX, /**< invalid regular expression (schema) */ 2015 LYVE_INRESOLV, /**< no resolvents found (schema) */ 2016 LYVE_INSTATUS, /**< invalid derivation because of status (schema) */ 2017 LYVE_CIRC_LEAFREFS,/**< circular chain of leafrefs detected (schema) */ 2018 LYVE_CIRC_FEATURES,/**< circular chain of features detected (schema) */ 2019 LYVE_CIRC_IMPORTS, /**< circular chain of imports detected (schema) */ 2020 LYVE_CIRC_INCLUDES,/**< circular chain of includes detected (schema) */ 2021 LYVE_INVER, /**< non-matching YANG versions of module and its submodules (schema) */ 2022 LYVE_SUBMODULE, /**< submodule given instead of a module */ 2023 2024 LYVE_OBSDATA, /**< obsolete data instantiation (data) */ 2025 /* */ 2026 LYVE_NORESOLV, /**< no resolvents found for an expression (data) */ 2027 LYVE_INELEM, /**< invalid element (data) */ 2028 /* */ 2029 LYVE_MISSELEM, /**< missing required element (data) */ 2030 LYVE_INVAL, /**< invalid value of an element (data) */ 2031 LYVE_INMETA, /**< invalid metadata (attribute) value (data) */ 2032 LYVE_INATTR, /**< invalid attribute in an element (data) */ 2033 LYVE_MISSATTR, /**< missing attribute in an element (data) */ 2034 LYVE_NOCONSTR, /**< value out of range/length/pattern (data) */ 2035 LYVE_INCHAR, /**< unexpected characters (data) */ 2036 LYVE_INPRED, /**< predicate resolution fail (data) */ 2037 LYVE_MCASEDATA, /**< data for more cases of a choice (data) */ 2038 LYVE_NOMUST, /**< unsatisfied must condition (data) */ 2039 LYVE_NOWHEN, /**< unsatisfied when condition (data) */ 2040 LYVE_INORDER, /**< invalid order of elements (data) */ 2041 LYVE_INWHEN, /**< irresolvable when condition (data) */ 2042 LYVE_NOMIN, /**< min-elements constraint not honored (data) */ 2043 LYVE_NOMAX, /**< max-elements constraint not honored (data) */ 2044 LYVE_NOREQINS, /**< required instance does not exits (data) */ 2045 LYVE_NOLEAFREF, /**< leaf pointed to by leafref does not exist (data) */ 2046 LYVE_NOMANDCHOICE, /**< no mandatory choice case branch exists (data) */ 2047 2048 LYVE_XPATH_INTOK, /**< unexpected XPath token */ 2049 LYVE_XPATH_EOF, /**< unexpected end of an XPath expression */ 2050 LYVE_XPATH_INOP, /**< invalid XPath operation operands */ 2051 /* */ 2052 LYVE_XPATH_INCTX, /**< invalid XPath context type */ 2053 LYVE_XPATH_INMOD, /**< invalid module name */ 2054 LYVE_XPATH_INFUNC, /**< invalid XPath function name */ 2055 LYVE_XPATH_INARGCOUNT, /**< invalid number of arguments for an XPath function */ 2056 LYVE_XPATH_INARGTYPE, /**< invalid type of arguments for an XPath function */ 2057 LYVE_XPATH_DUMMY, /**< invalid use of the XPath dummy node */ 2058 LYVE_XPATH_NOEND, /**< unterminated string */ 2059 2060 LYVE_PATH_INCHAR, /**< invalid characters (path) */ 2061 LYVE_PATH_INMOD, /**< invalid module name (path) */ 2062 LYVE_PATH_MISSMOD, /**< missing module name (path) */ 2063 LYVE_PATH_INNODE, /**< invalid node name (path) */ 2064 LYVE_PATH_INKEY, /**< invalid key name (path) */ 2065 LYVE_PATH_MISSKEY, /**< missing some list keys (path) */ 2066 LYVE_PATH_INIDENTREF, /**< missing module name prefix in identityref predicate value (path) */ 2067 LYVE_PATH_EXISTS, /**< target node already exists (path) */ 2068 LYVE_PATH_MISSPAR, /**< some parent of the target node is missing (path) */ 2069 LYVE_PATH_PREDTOOMANY, /**< too many predicates specified (path) */ 2070} LY_VECODE; 2071 2072/** 2073 * @cond INTERNAL 2074 * Get address of (thread-specific) `ly_errno' variable. 2075 */ 2076LY_ERR *ly_errno_glob_address(void); 2077 2078/** 2079 * @endcond INTERNAL 2080 * @brief libyang specific (thread-safe) errno (see #LY_ERR for the list of possible values and their meaning). 2081 */ 2082#define ly_errno (*ly_errno_glob_address()) 2083 2084/** 2085 * @brief Get the last (thread, context-specific) validation error code. 2086 * 2087 * This value is set only if ly_errno is #LY_EVALID. 2088 * 2089 * @param[in] ctx Relative context. 2090 * @return Validation error code. 2091 */ 2092LY_VECODE ly_vecode(const struct ly_ctx *ctx); 2093 2094/** 2095 * @brief Get the last (thread, context-specific) error message. If the corresponding module defined 2096 * a specific error message, it will be used instead the default one. 2097 * 2098 * Sometimes, the error message is extended with path of the element where the problem is. 2099 * The path is available via ly_errpath(). 2100 * 2101 * @param[in] ctx Relative context. 2102 * @return Text of the last error message, empty string if there is no error. 2103 */ 2104const char *ly_errmsg(const struct ly_ctx *ctx); 2105 2106/** 2107 * @brief Get the last (thread, context-specific) path of the element where was an error. 2108 * 2109 * The path always corresponds to the error message available via ly_errmsg(), so 2110 * whenever a subsequent error message is printed, the path is erased or rewritten. 2111 * The path reflects the type of the processed tree - data path for data tree functions 2112 * and schema path in case of schema tree functions. In case of processing YIN schema 2113 * or XML data, the path can be just XML path. In such a case, the corresponding 2114 * ly_vecode (value 1-3) is set. 2115 * 2116 * @param[in] ctx Relative context. 2117 * @return Path of the error element, empty string if error path does not apply to the last error. 2118 */ 2119const char *ly_errpath(const struct ly_ctx *ctx); 2120 2121/** 2122 * @brief Get the last (thread, context-specific) error-app-tag if there was a specific one defined 2123 * in the module for the last error. 2124 * 2125 * The app-tag always corresponds to the error message available via ly_errmsg(), so 2126 * whenever a subsequent error message is printed, the app-tag is erased or rewritten. 2127 * 2128 * @param[in] ctx Relative context. 2129 * @return Error-app-tag of the last error, empty string if the error-app-tag does not apply to the last error. 2130 */ 2131const char *ly_errapptag(const struct ly_ctx *ctx); 2132 2133/** 2134 * @brief Libyang full error structure. 2135 */ 2136struct ly_err_item { 2137 LY_LOG_LEVEL level; 2138 LY_ERR no; 2139 LY_VECODE vecode; 2140 char *msg; 2141 char *path; 2142 char *apptag; 2143 struct ly_err_item *next; 2144 struct ly_err_item *prev; /* first item's prev points to the last item */ 2145}; 2146 2147/** 2148 * @brief Get the first (thread, context-specific) generated error structure. 2149 * 2150 * @param[in] ctx Relative context. 2151 * @return First error structure (can be NULL), do not modify! 2152 */ 2153struct ly_err_item *ly_err_first(const struct ly_ctx *ctx); 2154 2155/** 2156 * @brief Print the error structure as if just generated. 2157 * 2158 * @param[in] eitem Error item structure to print. 2159 */ 2160void ly_err_print(struct ly_err_item *eitem); 2161 2162/** 2163 * @brief Free error structures from a context. 2164 * 2165 * If \p eitem is not set, free all the error structures. 2166 * 2167 * @param[in] ctx Relative context. 2168 * @param[in] eitem Oldest error structure to remove, optional. 2169 */ 2170void ly_err_clean(struct ly_ctx *ctx, struct ly_err_item *eitem); 2171 2172/** 2173 * @} logger 2174 */ 2175 2176#ifdef __cplusplus 2177} 2178#endif 2179 2180#endif /* LY_LIBYANG_H_ */ 2181