Radek Krejci | 5aeea3a | 2018-09-05 13:29:36 +0200 | [diff] [blame] | 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 | |
Radek Krejci | 0af5f5d | 2018-09-07 15:00:30 +0200 | [diff] [blame] | 18 | #include <stdint.h> |
| 19 | |
Radek Krejci | 5aeea3a | 2018-09-05 13:29:36 +0200 | [diff] [blame] | 20 | #ifdef __cplusplus |
| 21 | extern "C" { |
| 22 | #endif |
| 23 | |
| 24 | /** |
Radek Krejci | e53a8dc | 2018-10-17 12:52:40 +0200 | [diff] [blame] | 25 | * @mainpage About |
| 26 | * |
| 27 | * libyang is a library implementing processing of the YANG schemas and data modeled by the YANG language. The |
| 28 | * library is implemented in C for GNU/Linux and provides C API. |
| 29 | * |
| 30 | * @section about-features Main Features |
| 31 | * |
| 32 | * - [Parsing (and validating) schemas](@ref howtoschemasparsers) in YANG format. |
| 33 | * - [Parsing (and validating) schemas](@ref howtoschemasparsers) in YIN format. |
| 34 | * - [Parsing, validating and printing instance data](@ref howtodata) in XML format. |
| 35 | * - [Parsing, validating and printing instance data](@ref howtodata) in JSON format |
| 36 | * ([RFC 7951](https://tools.ietf.org/html/rfc7951)). |
| 37 | * - [Manipulation with the instance data](@ref howtodatamanipulators). |
| 38 | * - Support for [default values in the instance data](@ref howtodatawd) ([RFC 6243](https://tools.ietf.org/html/rfc6243)). |
| 39 | * - Support for [YANG extensions and user types](@ref howtoschemaplugins). |
| 40 | * - Support for [YANG Metadata](@ref howtoschemametadata) ([RFC 7952](https://tools.ietf.org/html/rfc6243)). |
| 41 | * |
| 42 | * The current implementation covers YANG 1.0 ([RFC 6020](https://tools.ietf.org/html/rfc6020)) as well as |
| 43 | * YANG 1.1 ([RFC 7950](https://tools.ietf.org/html/rfc7950)). |
| 44 | * |
| 45 | * @section about-license License |
| 46 | * |
| 47 | * Copyright (c) 2015-2017 CESNET, z.s.p.o. |
| 48 | * |
| 49 | * (The BSD 3-Clause License) |
| 50 | * |
| 51 | * Redistribution and use in source and binary forms, with or without |
| 52 | * modification, are permitted provided that the following conditions |
| 53 | * are met: |
| 54 | * 1. Redistributions of source code must retain the above copyright |
| 55 | * notice, this list of conditions and the following disclaimer. |
| 56 | * 2. Redistributions in binary form must reproduce the above copyright |
| 57 | * notice, this list of conditions and the following disclaimer in |
| 58 | * the documentation and/or other materials provided with the |
| 59 | * distribution. |
| 60 | * 3. Neither the name of the Company nor the names of its contributors |
| 61 | * may be used to endorse or promote products derived from this |
| 62 | * software without specific prior written permission. |
| 63 | */ |
| 64 | |
| 65 | /** |
| 66 | * @page howto How To ... |
| 67 | * |
| 68 | * - @subpage howtocontext |
| 69 | * - @subpage howtoschemas |
| 70 | * - @subpage howtodata |
| 71 | * - @subpage howtoxpath |
| 72 | * - @subpage howtoxml |
| 73 | * - @subpage howtothreads |
| 74 | * - @subpage howtologger |
| 75 | * - @subpage howtostructures |
| 76 | */ |
| 77 | |
| 78 | /** |
| 79 | * @page howtostructures Data Structures |
| 80 | * |
| 81 | * @section sizedarrays Sized Arrays |
| 82 | * |
| 83 | * The structure starts with 32bit number storing size of the array - the number of the items inside. The size is part of the |
Radek Krejci | 2c4e717 | 2018-10-19 15:56:26 +0200 | [diff] [blame] | 84 | * array to have it allocated together with the array itself only when it is needed. However, the pointers to the array always |
| 85 | * points after the 32b number, so items can be accessed directly as for standard C arrays. Because of a known size (available |
| 86 | * via ::LY_ARRAY_SIZE macro), it is not terminated by any special byte (sequence), so there is also no limitation for specific |
| 87 | * content of the stored records (e.g. that first byte must not be NULL). |
Radek Krejci | e53a8dc | 2018-10-17 12:52:40 +0200 | [diff] [blame] | 88 | * |
Radek Krejci | 2c4e717 | 2018-10-19 15:56:26 +0200 | [diff] [blame] | 89 | * The sized arrays must be carefully freed (which should be done anyway only internally), since pointers to the sized arrays used |
| 90 | * in libyang structures, does not point to the beginning of the allocated space. |
Radek Krejci | e53a8dc | 2018-10-17 12:52:40 +0200 | [diff] [blame] | 91 | * |
| 92 | * - ::LY_ARRAY_SIZE |
Radek Krejci | e53a8dc | 2018-10-17 12:52:40 +0200 | [diff] [blame] | 93 | * - ::LY_ARRAY_FOR |
| 94 | * |
| 95 | * @section struct_lists Lists |
| 96 | * |
| 97 | * The lists are structures connected via a `next` pointer. Iterating over the siblings can be simply done by ::LY_LIST_FOR macro. |
| 98 | */ |
| 99 | |
| 100 | /** |
Radek Krejci | 0af5f5d | 2018-09-07 15:00:30 +0200 | [diff] [blame] | 101 | * @defgroup context Context |
| 102 | * @{ |
| 103 | * |
| 104 | * Structures and functions to manipulate with the libyang "containers". The \em context concept allows callers |
| 105 | * to work in environments with different sets of YANG schemas. More detailed information can be found at |
| 106 | * @ref howtocontext page. |
| 107 | */ |
| 108 | |
| 109 | /** |
Radek Krejci | 5aeea3a | 2018-09-05 13:29:36 +0200 | [diff] [blame] | 110 | * @struct ly_ctx |
| 111 | * @brief libyang context handler. |
| 112 | */ |
| 113 | struct ly_ctx; |
| 114 | |
Radek Krejci | 0af5f5d | 2018-09-07 15:00:30 +0200 | [diff] [blame] | 115 | /**@} context */ |
Radek Krejci | 5aeea3a | 2018-09-05 13:29:36 +0200 | [diff] [blame] | 116 | |
| 117 | #include "log.h" |
| 118 | #include "set.h" |
| 119 | #include "dict.h" |
Radek Krejci | 0af5f5d | 2018-09-07 15:00:30 +0200 | [diff] [blame] | 120 | #include "tree_schema.h" |
| 121 | |
| 122 | /** |
| 123 | * @ingroup context |
| 124 | * @{ |
| 125 | */ |
| 126 | |
| 127 | /** |
| 128 | * @defgroup contextoptions Context options |
| 129 | * @ingroup context |
| 130 | * |
| 131 | * Options to change context behavior. |
| 132 | * @{ |
| 133 | */ |
| 134 | |
| 135 | #define LY_CTX_ALLIMPLEMENTED 0x01 /**< All the imports of the schema being parsed are treated implemented. */ |
| 136 | #define LY_CTX_TRUSTED 0x02 /**< Handle the schema being parsed as trusted and skip its validation |
| 137 | tests. Note that while this option improves performance, it can |
| 138 | lead to an undefined behavior if the schema is not correct. */ |
| 139 | #define LY_CTX_NOYANGLIBRARY 0x04 /**< Do not internally implement ietf-yang-library module. The option |
| 140 | causes that function ly_ctx_info() does not work (returns NULL) until |
| 141 | the ietf-yang-library module is loaded manually. While any revision |
| 142 | of this schema can be loaded with this option, note that the only |
| 143 | revisions implemented by ly_ctx_info() are 2016-04-09 and 2018-01-17. |
Radek Krejci | ca828d9 | 2018-09-20 14:19:43 +0200 | [diff] [blame] | 144 | This option cannot be changed on existing context. */ |
Radek Krejci | 0af5f5d | 2018-09-07 15:00:30 +0200 | [diff] [blame] | 145 | #define LY_CTX_DISABLE_SEARCHDIRS 0x08 /**< Do not search for schemas in context's searchdirs neither in current |
| 146 | working directory. It is entirely skipped and the only way to get |
| 147 | schema data for imports or for ly_ctx_load_module() is to use the |
| 148 | callbacks provided by caller via ly_ctx_set_module_imp_clb() */ |
| 149 | #define LY_CTX_DISABLE_SEARCHDIR_CWD 0x10 /**< Do not automatically search for schemas in current working |
| 150 | directory, which is by default searched automatically (despite not |
| 151 | recursively). */ |
| 152 | #define LY_CTX_PREFER_SEARCHDIRS 0x20 /**< When searching for schema, prefer searchdirs instead of user callback. */ |
| 153 | /**@} contextoptions */ |
| 154 | |
| 155 | /** |
| 156 | * @brief Create libyang context. |
| 157 | * |
| 158 | * Context is used to hold all information about schemas. Usually, the application is supposed |
| 159 | * to work with a single context in which libyang is holding all schemas (and other internal |
| 160 | * information) according to which the data trees will be processed and validated. So, the schema |
| 161 | * trees are tightly connected with the specific context and they are held by the context internally |
| 162 | * - caller does not need to keep pointers to the schemas returned by lys_parse(), context knows |
| 163 | * about them. The data trees created with lyd_parse() are still connected with the specific context, |
| 164 | * but they are not internally held by the context. The data tree just points and lean on some data |
| 165 | * held by the context (schema tree, string dictionary, etc.). Therefore, in case of data trees, caller |
| 166 | * is supposed to keep pointers returned by the lyd_parse() and manage the data tree on its own. This |
| 167 | * also affects the number of instances of both tree types. While you can have only one instance of |
| 168 | * specific schema connected with a single context, number of data tree instances is not connected. |
| 169 | * |
| 170 | * @param[in] search_dir Directory where libyang will search for the imported or included modules |
| 171 | * and submodules. If no such directory is available, NULL is accepted. |
| 172 | * @param[in] options Context options, see @ref contextoptions. |
| 173 | * @param[out] new_ctx Pointer to the created libyang context if LY_SUCCESS returned. |
| 174 | * @return LY_ERR return value. |
| 175 | */ |
| 176 | LY_ERR ly_ctx_new(const char *search_dir, int options, struct ly_ctx **new_ctx); |
| 177 | |
| 178 | /** |
| 179 | * @brief Add the search path into libyang context |
| 180 | * |
| 181 | * To reset search paths set in the context, use ly_ctx_unset_searchdirs() and then |
| 182 | * set search paths again. |
| 183 | * |
| 184 | * @param[in] ctx Context to be modified. |
| 185 | * @param[in] search_dir New search path to add to the current paths previously set in ctx. |
Radek Krejci | ad57350 | 2018-09-07 15:26:55 +0200 | [diff] [blame] | 186 | * @return LY_ERR return value. |
Radek Krejci | 0af5f5d | 2018-09-07 15:00:30 +0200 | [diff] [blame] | 187 | */ |
Radek Krejci | ad57350 | 2018-09-07 15:26:55 +0200 | [diff] [blame] | 188 | LY_ERR ly_ctx_set_searchdir(struct ly_ctx *ctx, const char *search_dir); |
Radek Krejci | 0af5f5d | 2018-09-07 15:00:30 +0200 | [diff] [blame] | 189 | |
| 190 | /** |
| 191 | * @brief Clean the search path(s) from the libyang context |
| 192 | * |
| 193 | * @param[in] ctx Context to be modified. |
Radek Krejci | 0759b79 | 2018-09-20 13:53:15 +0200 | [diff] [blame] | 194 | * @param[in] value Searchdir to be removed, use NULL to remove them all. |
Radek Krejci | 0af5f5d | 2018-09-07 15:00:30 +0200 | [diff] [blame] | 195 | * @return LY_ERR return value |
| 196 | */ |
Radek Krejci | 0759b79 | 2018-09-20 13:53:15 +0200 | [diff] [blame] | 197 | LY_ERR ly_ctx_unset_searchdirs(struct ly_ctx *ctx, const char *value); |
Radek Krejci | 0af5f5d | 2018-09-07 15:00:30 +0200 | [diff] [blame] | 198 | |
| 199 | /** |
| 200 | * @brief Get the NULL-terminated list of the search paths in libyang context. Do not modify the result! |
| 201 | * |
| 202 | * @param[in] ctx Context to query. |
| 203 | * @return NULL-terminated list (array) of the search paths, NULL if no searchpath was set. |
| 204 | * Do not modify the provided data in any way! |
| 205 | */ |
| 206 | const char * const *ly_ctx_get_searchdirs(const struct ly_ctx *ctx); |
| 207 | |
| 208 | /** |
| 209 | * @brief Get the currently set context's options. |
| 210 | * |
| 211 | * @param[in] ctx Context to query. |
| 212 | * @return Combination of all the currently set context's options, see @ref contextoptions. |
| 213 | */ |
Radek Krejci | 3fbe89a | 2018-09-20 13:54:46 +0200 | [diff] [blame] | 214 | int ly_ctx_get_options(const struct ly_ctx *ctx); |
Radek Krejci | 0af5f5d | 2018-09-07 15:00:30 +0200 | [diff] [blame] | 215 | |
| 216 | /** |
Radek Krejci | ca828d9 | 2018-09-20 14:19:43 +0200 | [diff] [blame] | 217 | * @brief Set some of the context's options, see @ref contextoptions. |
Radek Krejci | 0af5f5d | 2018-09-07 15:00:30 +0200 | [diff] [blame] | 218 | * @param[in] ctx Context to be modified. |
Radek Krejci | ca828d9 | 2018-09-20 14:19:43 +0200 | [diff] [blame] | 219 | * @param[in] option Combination of the context's options to be set, see @ref contextoptions. |
| 220 | * @return LY_ERR value. |
Radek Krejci | 0af5f5d | 2018-09-07 15:00:30 +0200 | [diff] [blame] | 221 | */ |
Radek Krejci | ca828d9 | 2018-09-20 14:19:43 +0200 | [diff] [blame] | 222 | LY_ERR ly_ctx_set_option(struct ly_ctx *ctx, int option); |
Radek Krejci | 0af5f5d | 2018-09-07 15:00:30 +0200 | [diff] [blame] | 223 | |
| 224 | /** |
Radek Krejci | ca828d9 | 2018-09-20 14:19:43 +0200 | [diff] [blame] | 225 | * @brief Unset some of the context's options, see @ref contextoptions. |
Radek Krejci | 0af5f5d | 2018-09-07 15:00:30 +0200 | [diff] [blame] | 226 | * @param[in] ctx Context to be modified. |
Radek Krejci | ca828d9 | 2018-09-20 14:19:43 +0200 | [diff] [blame] | 227 | * @param[in] option Combination of the context's options to be unset, see @ref contextoptions. |
| 228 | * @return LY_ERR value. |
Radek Krejci | 0af5f5d | 2018-09-07 15:00:30 +0200 | [diff] [blame] | 229 | */ |
Radek Krejci | ca828d9 | 2018-09-20 14:19:43 +0200 | [diff] [blame] | 230 | LY_ERR ly_ctx_unset_option(struct ly_ctx *ctx, int option); |
Radek Krejci | 0af5f5d | 2018-09-07 15:00:30 +0200 | [diff] [blame] | 231 | |
| 232 | /** |
| 233 | * @brief Get current ID of the modules set. The value is available also |
| 234 | * as module-set-id in ly_ctx_info() result. |
| 235 | * |
| 236 | * @param[in] ctx Context to be examined. |
| 237 | * @return Numeric identifier of the current context's modules set. |
| 238 | */ |
| 239 | uint16_t ly_ctx_get_module_set_id(const struct ly_ctx *ctx); |
| 240 | |
| 241 | /** |
| 242 | * @brief Free all internal structures of the specified context. |
| 243 | * |
| 244 | * The function should be used before terminating the application to destroy |
| 245 | * and free all structures internally used by libyang. If the caller uses |
| 246 | * multiple contexts, the function should be called for each used context. |
| 247 | * |
| 248 | * All instance data are supposed to be freed before destroying the context. |
| 249 | * Data models are destroyed automatically as part of ly_ctx_destroy() call. |
| 250 | * |
| 251 | * @param[in] ctx libyang context to destroy |
| 252 | * @param[in] private_destructor Optional destructor function for private objects assigned |
| 253 | * to the nodes via lys_set_private(). If NULL, the private objects are not freed by libyang. |
Radek Krejci | e53a8dc | 2018-10-17 12:52:40 +0200 | [diff] [blame] | 254 | * Remember the differences between the structures derived from ::lysc_node and always check |
| 255 | * ::lysc_node#nodetype. |
Radek Krejci | 0af5f5d | 2018-09-07 15:00:30 +0200 | [diff] [blame] | 256 | */ |
| 257 | void ly_ctx_destroy(struct ly_ctx *ctx, void (*private_destructor)(const struct lysc_node *node, void *priv)); |
| 258 | |
| 259 | /** @} context */ |
| 260 | |
| 261 | #ifdef __cplusplus |
| 262 | } |
| 263 | #endif |
Radek Krejci | 5aeea3a | 2018-09-05 13:29:36 +0200 | [diff] [blame] | 264 | |
| 265 | #endif /* LY_LIBYANG_H_ */ |