blob: 89296788b13d2b2f46f2e592f9a34a77cbcfbf03 [file] [log] [blame]
Radek Krejcia5bba312020-01-09 15:41:20 +01001/**
2 * @file printer.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
4 * @brief Generic libyang printer structures and functions
5 *
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_H_
16#define LY_PRINTER_H_
17
Radek Krejci535ea9f2020-05-29 16:01:05 +020018#include <stdio.h>
Radek Krejcia5bba312020-01-09 15:41:20 +010019#include <unistd.h>
20
Radek Krejci535ea9f2020-05-29 16:01:05 +020021#include "log.h"
22
Radek Krejcica376bd2020-06-11 16:04:06 +020023#ifdef __cplusplus
24extern "C" {
25#endif
26
Radek Krejcia5bba312020-01-09 15:41:20 +010027/**
28 * @brief Printer output structure specifying where the data are printed.
29 */
Radek Krejci241f6b52020-05-21 18:13:49 +020030struct ly_out;
Radek Krejcia5bba312020-01-09 15:41:20 +010031
32/**
33 * @brief Types of the printer's output
34 */
Radek Krejci241f6b52020-05-21 18:13:49 +020035typedef enum LY_OUT_TYPE {
36 LY_OUT_ERROR = -1, /**< error value to indicate failure of the functions returning LY_OUT_TYPE */
37 LY_OUT_FD, /**< file descriptor printer */
38 LY_OUT_FDSTREAM, /**< internal replacement for LY_OUT_FD in case vdprintf() is not available */
39 LY_OUT_FILE, /**< FILE stream printer */
40 LY_OUT_FILEPATH, /**< filepath printer */
41 LY_OUT_MEMORY, /**< memory printer */
42 LY_OUT_CALLBACK /**< callback printer */
43} LY_OUT_TYPE;
Radek Krejcia5bba312020-01-09 15:41:20 +010044
45/**
46 * @brief Get output type of the printer handler.
47 *
48 * @param[in] out Printer handler.
49 * @return Type of the printer's output.
50 */
Radek Krejci241f6b52020-05-21 18:13:49 +020051LY_OUT_TYPE ly_out_type(const struct ly_out *out);
Radek Krejcia5bba312020-01-09 15:41:20 +010052
53/**
54 * @brief Reset the output medium to write from its beginning, so the following printer function will rewrite the current data
55 * instead of appending.
56 *
57 * Note that in case the underlying output is not seekable (stream referring a pipe/FIFO/socket or the callback output type),
58 * nothing actually happens despite the function succeeds. Also note that the medium is not returned to the state it was when
Radek Krejcic5a12e12020-05-27 17:09:59 +020059 * the handler was created. For example, file is seeked into the offset zero and truncated, the content from the time it was opened with
60 * ly_out_new_file() is not restored.
Radek Krejcia5bba312020-01-09 15:41:20 +010061 *
62 * @param[in] out Printer handler.
63 * @return LY_SUCCESS in case of success
64 * @return LY_ESYS in case of failure
65 */
Radek Krejci241f6b52020-05-21 18:13:49 +020066LY_ERR ly_out_reset(struct ly_out *out);
Radek Krejcia5bba312020-01-09 15:41:20 +010067
68/**
69 * @brief Create printer handler using callback printer function.
70 *
71 * @param[in] writeclb Pointer to the printer callback function writing the data (see write(2)).
72 * @param[in] arg Optional caller-specific argument to be passed to the @p writeclb callback.
Radek Krejci84ce7b12020-06-11 17:28:25 +020073 * @param[out] out Created printer handler supposed to be passed to different ly*_print() functions.
74 * @return LY_SUCCESS in case of success
75 * @return LY_EMEM in case allocating the @p out handler fails.
Radek Krejcia5bba312020-01-09 15:41:20 +010076 */
Radek Krejci84ce7b12020-06-11 17:28:25 +020077LY_ERR ly_out_new_clb(ssize_t (*writeclb)(void *arg, const void *buf, size_t count), void *arg, struct ly_out **out);
Radek Krejcia5bba312020-01-09 15:41:20 +010078
79/**
80 * @brief Get or reset callback function associated with a callback printer handler.
81 *
82 * @param[in] out Printer handler.
83 * @param[in] fd Optional value of a new file descriptor for the handler. If -1, only the current file descriptor value is returned.
84 * @return Previous value of the file descriptor.
85 */
Radek Krejci241f6b52020-05-21 18:13:49 +020086ssize_t (*ly_out_clb(struct ly_out *out, ssize_t (*writeclb)(void *arg, const void *buf, size_t count)))(void *arg, const void *buf, size_t count);
Radek Krejcia5bba312020-01-09 15:41:20 +010087
88/**
89 * @brief Get or reset callback function's argument aasociated with a callback printer handler.
90 *
91 * @param[in] out Printer handler.
92 * @param[in] arg caller-specific argument to be passed to the callback function associated with the printer handler.
93 * If NULL, only the current file descriptor value is returned.
94 * @return The previous callback argument.
95 */
Radek Krejci241f6b52020-05-21 18:13:49 +020096void *ly_out_clb_arg(struct ly_out *out, void *arg);
Radek Krejcia5bba312020-01-09 15:41:20 +010097
98/**
99 * @brief Create printer handler using file descriptor.
100 *
101 * @param[in] fd File descriptor to use.
Radek Krejci84ce7b12020-06-11 17:28:25 +0200102 * @param[out] out Created printer handler supposed to be passed to different ly*_print() functions.
103 * @return LY_SUCCESS in case of success
104 * @return LY_ERR value in case of failure.
Radek Krejcia5bba312020-01-09 15:41:20 +0100105 */
Radek Krejci84ce7b12020-06-11 17:28:25 +0200106LY_ERR ly_out_new_fd(int fd, struct ly_out **out);
Radek Krejcia5bba312020-01-09 15:41:20 +0100107
108/**
109 * @brief Get or reset file descriptor printer handler.
110 *
111 * @param[in] out Printer handler.
112 * @param[in] fd Optional value of a new file descriptor for the handler. If -1, only the current file descriptor value is returned.
113 * @return Previous value of the file descriptor. Note that caller is responsible for closing the returned file descriptor in case of setting new descriptor @p fd.
114 * @return -1 in case of error when setting up the new file descriptor.
115 */
Radek Krejci241f6b52020-05-21 18:13:49 +0200116int ly_out_fd(struct ly_out *out, int fd);
Radek Krejcia5bba312020-01-09 15:41:20 +0100117
118/**
119 * @brief Create printer handler using file stream.
120 *
121 * @param[in] f File stream to use.
Radek Krejci84ce7b12020-06-11 17:28:25 +0200122 * @param[out] out Created printer handler supposed to be passed to different ly*_print() functions.
123 * @return LY_SUCCESS in case of success
124 * @return LY_ERR value in case of failure.
Radek Krejcia5bba312020-01-09 15:41:20 +0100125 */
Radek Krejci84ce7b12020-06-11 17:28:25 +0200126LY_ERR ly_out_new_file(FILE *f, struct ly_out **out);
Radek Krejcia5bba312020-01-09 15:41:20 +0100127
128/**
129 * @brief Get or reset file stream printer handler.
130 *
131 * @param[in] out Printer handler.
132 * @param[in] f Optional new file stream for the handler. If NULL, only the current file stream is returned.
133 * @return Previous file stream of the handler. Note that caller is responsible for closing the returned stream in case of setting new stream @p f.
134 */
Radek Krejci241f6b52020-05-21 18:13:49 +0200135FILE *ly_out_file(struct ly_out *out, FILE *f);
Radek Krejcia5bba312020-01-09 15:41:20 +0100136
137/**
138 * @brief Create printer handler using memory to dump data.
139 *
140 * @param[in] strp Pointer to store the resulting data. If it points to a pointer to an allocated buffer and
141 * @p size of the buffer is set, the buffer is used (and extended if needed) to store the printed data.
142 * @param[in] size Size of the buffer provided via @p strp. In case it is 0, the buffer for the printed data
143 * is newly allocated even if @p strp points to a pointer to an existing buffer.
Radek Krejci84ce7b12020-06-11 17:28:25 +0200144 * @param[out] out Created printer handler supposed to be passed to different ly*_print() functions.
145 * @return LY_SUCCESS in case of success
146 * @return LY_ERR value in case of failure.
Radek Krejcia5bba312020-01-09 15:41:20 +0100147 */
Radek Krejci84ce7b12020-06-11 17:28:25 +0200148LY_ERR ly_out_new_memory(char **strp, size_t size, struct ly_out **out);
Radek Krejcia5bba312020-01-09 15:41:20 +0100149
150/**
151 * @brief Get or change memory where the data are dumped.
152 *
153 * @param[in] out Printer handler.
Radek Krejcibaeb8382020-05-27 16:44:53 +0200154 * @param[in] strp Optional new string pointer to store the resulting data, same rules as in ly_out_new_memory() are applied.
Radek Krejcia5bba312020-01-09 15:41:20 +0100155 * @param[in] size Size of the buffer provided via @p strp. In case it is 0, the buffer for the printed data
Radek Krejcibaeb8382020-05-27 16:44:53 +0200156 * is newly allocated even if @p strp points to a pointer to an existing buffer. In case the @p strp is NULL, this
157 * parameter is ignored.
Radek Krejcia5bba312020-01-09 15:41:20 +0100158 * @return Previous dumped data. Note that the caller is responsible to free the data in case of changing string pointer @p strp.
159 */
Radek Krejci241f6b52020-05-21 18:13:49 +0200160char *ly_out_memory(struct ly_out *out, char **strp, size_t size);
Radek Krejcia5bba312020-01-09 15:41:20 +0100161
162/**
163 * @brief Create printer handler file of the given filename.
164 *
165 * @param[in] filepath Path of the file where to write data.
166 * @return NULL in case of error.
167 * @return Created printer handler supposed to be passed to different ly*_print_*() functions.
168 */
Radek Krejci84ce7b12020-06-11 17:28:25 +0200169LY_ERR ly_out_new_filepath(const char *filepath, struct ly_out **out);
Radek Krejcia5bba312020-01-09 15:41:20 +0100170
171/**
172 * @brief Get or change the filepath of the file where the printer prints the data.
173 *
174 * Note that in case of changing the filepath, the current file is closed and a new one is
175 * created/opened instead of renaming the previous file. Also note that the previous filepath
176 * string is returned only in case of not changing it's value.
177 *
178 * @param[in] out Printer handler.
179 * @param[in] filepath Optional new filepath for the handler. If and only if NULL, the current filepath string is returned.
180 * @return Previous filepath string in case the @p filepath argument is NULL.
181 * @return NULL if changing filepath succeedes and ((void *)-1) otherwise.
182 */
Radek Krejci241f6b52020-05-21 18:13:49 +0200183const char *ly_out_filepath(struct ly_out *out, const char *filepath);
Radek Krejcia5bba312020-01-09 15:41:20 +0100184
185/**
186 * @brief Generic printer of the given format string into the specified output.
187 *
Radek Krejci241f6b52020-05-21 18:13:49 +0200188 * Alternatively, ly_write() can be used.
Radek Krejcia5bba312020-01-09 15:41:20 +0100189 *
190 * @param[in] out Output specification.
191 * @param[in] format format string to be printed.
192 * @return LY_ERR value, number of the printed bytes is updated in lyout::printed.
Radek Krejcibaeb8382020-05-27 16:44:53 +0200193 * @return The number of printed bytes.
194 * @return Negative value in case of error, absolute value of the return code maps to LY_ERR value.
Radek Krejcia5bba312020-01-09 15:41:20 +0100195 */
Radek Krejcibaeb8382020-05-27 16:44:53 +0200196ssize_t ly_print(struct ly_out *out, const char *format, ...);
Radek Krejcia5bba312020-01-09 15:41:20 +0100197
198/**
Radek Krejci099fd212020-05-27 18:17:35 +0200199 * @brief Flush the output from any internal buffers and clean any auxiliary data.
200 * @param[in] out Output specification.
201 */
202void ly_print_flush(struct ly_out *out);
203
204/**
Radek Krejcia5bba312020-01-09 15:41:20 +0100205 * @brief Generic printer of the given string buffer into the specified output.
206 *
Radek Krejci241f6b52020-05-21 18:13:49 +0200207 * Alternatively, ly_print() can be used.
Radek Krejcia5bba312020-01-09 15:41:20 +0100208 *
209 * As an extension for printing holes (skipping some data until they are known),
210 * ly_write_skip() and ly_write_skipped() can be used.
211 *
212 * @param[in] out Output specification.
213 * @param[in] buf Memory buffer with the data to print.
214 * @param[in] len Length of the data to print in the @p buf.
Radek Krejcibaeb8382020-05-27 16:44:53 +0200215 * @return The number of printed bytes.
216 * @return Negative value in case of error, absolute value of the return code maps to LY_ERR value.
Radek Krejcia5bba312020-01-09 15:41:20 +0100217 */
Radek Krejcibaeb8382020-05-27 16:44:53 +0200218ssize_t ly_write(struct ly_out *out, const char *buf, size_t len);
Radek Krejcia5bba312020-01-09 15:41:20 +0100219
220/**
221 * @brief Free the printer handler.
222 * @param[in] out Printer handler to free.
Radek Krejci241f6b52020-05-21 18:13:49 +0200223 * @param[in] clb_arg_destructor Freeing function for printer callback (LY_OUT_CALLBACK) argument.
224 * @param[in] destroy Flag to free allocated buffer (for LY_OUT_MEMORY) or to
225 * close stream/file descriptor (for LY_OUT_FD, LY_OUT_FDSTREAM and LY_OUT_FILE)
Radek Krejcia5bba312020-01-09 15:41:20 +0100226 */
Radek Krejci241f6b52020-05-21 18:13:49 +0200227void ly_out_free(struct ly_out *out, void (*clb_arg_destructor)(void *arg), int destroy);
Radek Krejcia5bba312020-01-09 15:41:20 +0100228
Radek Krejcica376bd2020-06-11 16:04:06 +0200229#ifdef __cplusplus
230}
231#endif
232
Radek Krejcia5bba312020-01-09 15:41:20 +0100233#endif /* LY_PRINTER_H_ */