blob: 89a51a8d224bace38646f94d7aa8bcb1f0d169ab [file] [log] [blame]
Radek Krejci5aeea3a2018-09-05 13:29:36 +02001/**
2 * @file log.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
4 * @brief Logger manipulation routines and error definitions.
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_LOG_H_
16#define LY_LOG_H_
17
Radek Krejci5aeea3a2018-09-05 13:29:36 +020018#ifdef __cplusplus
19extern "C" {
20#endif
21
Radek Krejciad573502018-09-07 15:26:55 +020022/* dummy context structure */
23struct ly_ctx;
24
Radek Krejci5aeea3a2018-09-05 13:29:36 +020025/**
26 * @defgroup log Logger
27 * @{
28 *
29 * Publicly visible functions and values of the libyang logger. For more
30 * information, see \ref howtologger.
31 */
32
33/**
34 * @typedef LY_LOG_LEVEL
35 * @brief Verbosity levels of the libyang logger.
36 */
37typedef enum
38{
39 LY_LLERR = 0, /**< Print only error messages, default value. */
40 LY_LLWRN = 1, /**< Print error and warning messages. */
41 LY_LLVRB = 2, /**< Besides errors and warnings, print some other verbose messages. */
42 LY_LLDBG = 3 /**< Print all messages including some development debug messages (be careful,
43 without subsequently calling ly_verb_dbg() no debug messages will be printed!). */
44} LY_LOG_LEVEL;
45
46/**
47 * @brief Set logger verbosity level.
48 * @param[in] level Verbosity level.
49 * @return Previous verbosity level.
50 */
51LY_LOG_LEVEL ly_verb (LY_LOG_LEVEL level);
52
53/**
54 * @defgroup logopts Logging options
55 * @ingroup logger
56 *
57 * Logging option bits of libyang.
58 *
59 * @{
60 */
61#define LY_LOLOG 0x01 /**< Log messages normally, using callback if set. If not set, messages will
62 not be printed by libyang. */
63#define LY_LOSTORE 0x02 /**< Store any generated errors or warnings, never verbose or debug messages.
64 Note that if #LY_LOLOG is not set then verbose and debug messages are always lost. */
65#define LY_LOSTORE_LAST 0x06 /**< Store any generated errors or warnings but only the last message, always overwrite
66 the previous one. */
67
68/**
69 * @}
70 */
71
72/**
73 * @brief Set additional logger options. Default is #LY_LOLOG | #LY_LOSTORE_LAST.
74 *
75 * @param[in] opts Bitfield of @ref logopts.
76 * @return Previous logger options.
77 */
78int ly_log_options (int opts);
79
80#ifndef NDEBUG
81
82/**
83 * @defgroup dbggroup Debug message groups
84 * @ingroup log
85 *
86 * Selected displayed debug message groups.
87 *
88 * @{
89 */
90
91#define LY_LDGDICT 0x01 /**< Dictionary additions and deletions. */
92#define LY_LDGYANG 0x02 /**< YANG parser messages. */
93#define LY_LDGYIN 0x04 /**< YIN parser messages. */
94#define LY_LDGXPATH 0x08 /**< XPath parsing end evaluation. */
95#define LY_LDGDIFF 0x10 /**< Diff processing and creation. */
96
97/**
98 * @}
99 */
100
101/**
102 * @brief Enable specific debugging messages (independent of log level).
103 * @param[in] dbg_groups Bitfield of enabled debug message groups (see @ref dbggroup).
104 */
105void ly_verb_dbg (int dbg_groups);
106
107#endif
108
109/**
110 * @brief Set logger callback.
111 *
112 * !IMPORTANT! If an error has a specific error-app-tag defined in the model, it will NOT be set
113 * at the time of calling this callback. It will be set right after, so to retrieve it
114 * it must be checked afterwards with ly_errapptag().
115 *
116 * @param[in] clb Logging callback.
117 * @param[in] path flag to resolve and provide path as the third parameter of the callback function. In case of
118 * validation and some other errors, it can be useful to get the path to the problematic element. Note,
119 * that according to the tree type and the specific situation, the path can slightly differs (keys
120 * presence) or it can be NULL, so consider it as an optional parameter. If the flag is 0, libyang will
121 * not bother with resolving the path.
122 */
123void ly_set_log_clb (void(*clb) (LY_LOG_LEVEL level, const char *msg, const char *path), int path);
124
125/**
126 * @brief Get logger callback.
127 * @return Logger callback (can be NULL).
128 */
129void (*ly_get_log_clb (void)) (LY_LOG_LEVEL, const char *, const char *);
130
131/** @} log */
132
133/**
134 * @defgroup errors Error information
135 * @{
136 */
137
138/**
139 * @typedef LY_ERR
140 * @brief libyang's error codes returned by the libyang functions.
141 */
142typedef enum
143{
144 LY_SUCCESS = 0, /**< no error, not set by functions, included just to complete #LY_ERR enumeration */
145 LY_EMEM, /**< Memory allocation failure */
Radek Krejcidc1c7e72018-09-07 14:58:20 +0200146 LY_ESYS, /**< System call failure */
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200147 LY_EINVAL, /**< Invalid value */
148 LY_EEXIST, /**< Item already exists */
Radek Krejcid33273d2018-10-25 14:55:52 +0200149 LY_ENOTFOUND, /**< Item does not exists */
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200150 LY_EINT, /**< Internal error */
151 LY_EVALID, /**< Validation failure */
Radek Krejci151a5b72018-10-19 14:21:44 +0200152 LY_EPLUGIN, /**< Error reported by a plugin */
153 LY_EDENIED /**< Operation is not allowed */
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200154} LY_ERR;
155
156/**
157 * @typedef LY_VECODE
158 * @brief libyang's codes of validation error. Whenever ly_errno is set to LY_EVALID, the ly_vecode is also set
159 * to the appropriate LY_VECODE value.
160 * @ingroup logger
161 */
162typedef enum {
163 LYVE_SUCCESS = 0, /**< no error */
Radek Krejci94aa9942018-09-07 17:12:17 +0200164 LYVE_SYNTAX, /**< generic syntax error */
165 LYVE_SYNTAX_YANG, /**< YANG-related syntax error */
David Sedlák0a875b42019-03-07 22:24:05 +0100166 LYVE_SYNTAX_YIN, /**< YIN-related syntax error */
Radek Krejci70853c52018-10-15 14:46:16 +0200167 LYVE_REFERENCE, /**< invalid referencing or using an item */
Radek Krejcib1646a92018-11-02 16:08:26 +0100168 LYVE_XPATH, /**< invalid XPath expression */
Radek Krejci70853c52018-10-15 14:46:16 +0200169 LYVE_SEMANTICS /**< generic semantic error */
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200170} LY_VECODE;
171
172/**
173 * @brief Libyang full error structure.
174 */
175struct ly_err_item {
176 LY_LOG_LEVEL level;
177 LY_ERR no;
178 LY_VECODE vecode;
179 char *msg;
180 char *path;
181 char *apptag;
182 struct ly_err_item *next;
183 struct ly_err_item *prev; /* first item's prev points to the last item */
184};
185
186/**
187 * @brief Get the last (thread, context-specific) validation error code.
188 *
189 * This value is set only if ly_errno is #LY_EVALID.
190 *
191 * @param[in] ctx Relative context.
192 * @return Validation error code.
193 */
194LY_VECODE ly_vecode(const struct ly_ctx *ctx);
195
196/**
Radek Krejcid33273d2018-10-25 14:55:52 +0200197 * @brief Get the last (thread, context-specific) error code.
198 *
199 * @param[in] ctx Relative context.
200 * @return LY_ERR value of the last error code.
201 */
202LY_ERR ly_errcode(const struct ly_ctx *ctx);
203
204/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200205 * @brief Get the last (thread, context-specific) error message. If the coresponding module defined
206 * a specific error message, it will be used instead the default one.
207 *
208 * Sometimes, the error message is extended with path of the element where the problem is.
209 * The path is available via ly_errpath().
210 *
211 * @param[in] ctx Relative context.
212 * @return Text of the last error message, empty string if there is no error.
213 */
214const char *ly_errmsg(const struct ly_ctx *ctx);
215
216/**
217 * @brief Get the last (thread, context-specific) path of the element where was an error.
218 *
219 * The path always corresponds to the error message available via ly_errmsg(), so
220 * whenever a subsequent error message is printed, the path is erased or rewritten.
221 * The path reflects the type of the processed tree - data path for data tree functions
222 * and schema path in case of schema tree functions. In case of processing YIN schema
223 * or XML data, the path can be just XML path. In such a case, the corresponding
224 * ly_vecode (value 1-3) is set.
225 *
226 * @param[in] ctx Relative context.
227 * @return Path of the error element, empty string if error path does not apply to the last error.
228 */
229const char *ly_errpath(const struct ly_ctx *ctx);
230
231/**
232 * @brief Get the last (thread, context-specific) error-app-tag if there was a specific one defined
233 * in the module for the last error.
234 *
235 * The app-tag always corresponds to the error message available via ly_errmsg(), so
236 * whenever a subsequent error message is printed, the app-tag is erased or rewritten.
237 *
238 * @param[in] ctx Relative context.
239 * @return Error-app-tag of the last error, empty string if the error-app-tag does not apply to the last error.
240 */
241const char *ly_errapptag(const struct ly_ctx *ctx);
242
243/**
244 * @brief Get the first (thread, context-specific) generated error structure.
245 *
246 * @param[in] ctx Relative context.
247 * @return First error structure (can be NULL), do not modify!
248 */
249struct ly_err_item *ly_err_first(const struct ly_ctx *ctx);
250
251/**
252 * @brief Print the error structure as if just generated.
253 *
254 * @param[in] eitem Error item structure to print.
255 */
256void ly_err_print(struct ly_err_item *eitem);
257
258/**
259 * @brief Free error structures from a context.
260 *
261 * If \p eitem is not set, free all the error structures.
262 *
263 * @param[in] ctx Relative context.
264 * @param[in] eitem Oldest error structure to remove, optional.
265 */
266void ly_err_clean(struct ly_ctx *ctx, struct ly_err_item *eitem);
267
268/** @} errors */
269
270#ifdef __cplusplus
271}
272#endif
273
274#endif /* LY_LOG_H_ */