blob: 38c757b341abf6b6afe739163c39affab73e9008 [file] [log] [blame]
Radek Krejcie7b95092019-05-15 11:03:07 +02001/**
Michal Vasko52927e22020-03-16 17:26:14 +01002 * @file printer_data.h
Radek Krejcie7b95092019-05-15 11:03:07 +02003 * @author Radek Krejci <rkrejci@cesnet.cz>
Michal Vasko52927e22020-03-16 17:26:14 +01004 * @brief Data printers for libyang
Radek Krejcie7b95092019-05-15 11:03:07 +02005 *
6 * Copyright (c) 2015-2019 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_PRINTER_DATA_H_
16#define LY_PRINTER_DATA_H_
17
18#include <stdio.h>
19#include <unistd.h>
20
21#include "tree_data.h"
22
23/**
24 * @defgroup dataprinterflags Data printer flags
25 * @ingroup datatree
26 *
27 * Validity flags for data nodes.
28 *
29 * @{
30 */
31#define LYDP_WITHSIBLINGS 0x01 /**< Flag for printing also the (following) sibling nodes of the data node. */
32#define LYDP_FORMAT 0x02 /**< Flag for formatted output. */
33#define LYDP_KEEPEMPTYCONT 0x04 /**< Preserve empty non-presence containers */
34#define LYDP_WD_MASK 0xF0 /**< Mask for with-defaults modes */
35#define LYDP_WD_EXPLICIT 0x00 /**< Explicit mode - print only data explicitly being present in the data tree.
36 Note that this is the default value when no WD option is specified. */
37#define LYDP_WD_TRIM 0x10 /**< Do not print the nodes with the value equal to their default value */
38#define LYDP_WD_ALL 0x20 /**< Include implicit default nodes */
39#define LYDP_WD_ALL_TAG 0x40 /**< Same as #LYP_WD_ALL but also adds attribute 'default' with value 'true' to
40 all nodes that has its default value. The 'default' attribute has namespace:
41 urn:ietf:params:xml:ns:netconf:default:1.0 and thus the attributes are
42 printed only when the ietf-netconf-with-defaults module is present in libyang
43 context (but in that case this namespace is always printed). */
44#define LYDP_WD_IMPL_TAG 0x80 /**< Same as LYP_WD_ALL_TAG but the attributes are added only to the nodes that
45 are not explicitly present in the original data tree despite their
46 value is equal to their default value. There is the same limitation regarding
47 the presence of ietf-netconf-with-defaults module in libyang context. */
Radek Krejcie7b95092019-05-15 11:03:07 +020048/**
49 * @}
50 */
51
52/**
53 * @brief Print data tree in the specified format into a memory block.
54 * It is up to caller to free the returned string by free().
55 *
56 * @param[out] strp Pointer to store the resulting dump.
57 * @param[in] root Root node of the data tree to print. It can be actually any (not only real root)
58 * node of the data tree to print the specific subtree.
59 * @param[in] format Data output format.
60 * @param[in] options [Data printer flags](@ref dataprinterflags). With \p format LYD_LYB, only #LYP_WITHSIBLINGS option is accepted.
Radek Krejci26a5dfb2019-07-26 14:51:06 +020061 * @return Number of printed characters (excluding the null byte used to end the string) in case of success.
Radek Krejcie7b95092019-05-15 11:03:07 +020062 * @return Negative value failure (absolute value corresponds to LY_ERR values).
63 */
64ssize_t lyd_print_mem(char **strp, const struct lyd_node *root, LYD_FORMAT format, int options);
65
66/**
67 * @brief Print data tree in the specified format into a file descriptor.
68 *
69 * @param[in] fd File descriptor where to print the data.
70 * @param[in] root Root node of the data tree to print. It can be actually any (not only real root)
71 * node of the data tree to print the specific subtree.
72 * @param[in] format Data output format.
73 * @param[in] options [Data printer flags](@ref dataprinterflags). With \p format LYD_LYB, only #LYP_WITHSIBLINGS option is accepted.
Radek Krejci26a5dfb2019-07-26 14:51:06 +020074 * @return Number of printed characters (excluding the null byte used to end the string) in case of success.
Radek Krejcie7b95092019-05-15 11:03:07 +020075 * @return Negative value failure (absolute value corresponds to LY_ERR values).
76 */
77ssize_t lyd_print_fd(int fd, const struct lyd_node *root, LYD_FORMAT format, int options);
78
79/**
80 * @brief Print data tree in the specified format into a file stream.
81 *
82 * @param[in] f File stream where to print the schema.
83 * @param[in] root Root node of the data tree to print. It can be actually any (not only real root)
84 * node of the data tree to print the specific subtree.
85 * @param[in] format Data output format.
86 * @param[in] options [Data printer flags](@ref dataprinterflags). With \p format LYD_LYB, only #LYP_WITHSIBLINGS option is accepted.
Radek Krejci26a5dfb2019-07-26 14:51:06 +020087 * @return Number of printed characters (excluding the null byte used to end the string) in case of success.
Radek Krejcie7b95092019-05-15 11:03:07 +020088 * @return Negative value failure (absolute value corresponds to LY_ERR values).
89 */
90ssize_t lyd_print_file(FILE *f, const struct lyd_node *root, LYD_FORMAT format, int options);
91
92/**
93 * @brief Print data tree in the specified format into a file.
94 *
95 * @param[in] path File where to print the schema.
96 * @param[in] root Root node of the data tree to print. It can be actually any (not only real root)
97 * node of the data tree to print the specific subtree.
98 * @param[in] format Data output format.
99 * @param[in] options [Data printer flags](@ref dataprinterflags). With \p format LYD_LYB, only #LYP_WITHSIBLINGS option is accepted.
Radek Krejci26a5dfb2019-07-26 14:51:06 +0200100 * @return Number of printed characters (excluding the null byte used to end the string) in case of success.
Radek Krejcie7b95092019-05-15 11:03:07 +0200101 * @return Negative value failure (absolute value corresponds to LY_ERR values).
102 */
103ssize_t lyd_print_path(const char *path, const struct lyd_node *root, LYD_FORMAT format, int options);
104
105/**
106 * @brief Print data tree in the specified format using the provided callback.
107 *
108 * @param[in] writeclb Callback function to write the data (see write(2)).
109 * @param[in] arg Optional caller-specific argument to be passed to the \p writeclb callback.
110 * @param[in] root Root node of the data tree to print. It can be actually any (not only real root)
111 * node of the data tree to print the specific subtree.
112 * @param[in] format Data output format.
113 * @param[in] options [Data printer flags](@ref dataprinterflags). With \p format LYD_LYB, only #LYP_WITHSIBLINGS option is accepted.
Radek Krejci26a5dfb2019-07-26 14:51:06 +0200114 * @return Number of printed characters (excluding the null byte used to end the string) in case of success.
Radek Krejcie7b95092019-05-15 11:03:07 +0200115 * @return Negative value failure (absolute value corresponds to LY_ERR values).
116 */
117ssize_t lyd_print_clb(ssize_t (*writeclb)(void *arg, const void *buf, size_t count), void *arg, const struct lyd_node *root,
118 LYD_FORMAT format, int options);
119
120#endif /* LY_PRINTER_DATA_H_ */