![[first]](../icons/first.png){kind=icon}
![[previous]](../icons/n_left.png){kind=icon}
![[next]](../icons/n_right.png){kind=icon}
![[last]](../icons/n_last.png){kind=icon}
![[top]](../icons/n_top.png){kind=icon}
![[bottom]](../icons/bottom.png){kind=icon}
![[index]](../icons/index.png){kind=icon}
![[help]](../icons/help.png){kind=icon}
*/
1 /*
2 * Copyright 2019-2023 the Pacemaker project contributors
3 *
4 * The version control history for this file may have further details.
5 *
6 * This source code is licensed under the GNU Lesser General Public License
7 * version 2.1 or later (LGPLv2.1+) WITHOUT ANY WARRANTY.
8 */
9
10 #ifndef PCMK__OUTPUT_INTERNAL__H
11 # define PCMK__OUTPUT_INTERNAL__H
12
13 # include <stdbool.h>
14 # include <stdint.h>
15 # include <stdio.h>
16 # include <libxml/tree.h>
17 # include <libxml/HTMLtree.h>
18
19 # include <glib.h>
20 # include <crm/common/results.h>
21
22 #ifdef __cplusplus
23 extern "C" {
24 #endif
25
26 /**
27 * \file
28 * \brief Formatted output for pacemaker tools
29 */
30
31 #if defined(PCMK__WITH_ATTRIBUTE_OUTPUT_ARGS)
32 # define PCMK__OUTPUT_ARGS(ARGS...) __attribute__((output_args(ARGS)))
33 #else
34 # define PCMK__OUTPUT_ARGS(ARGS...)
35 #endif
36
37 typedef struct pcmk__output_s pcmk__output_t;
38
39 /*!
40 * \internal
41 * \brief The type of a function that creates a ::pcmk__output_t.
42 *
43 * Instances of this type are passed to pcmk__register_format(), stored in an
44 * internal data structure, and later accessed by pcmk__output_new(). For
45 * examples, see pcmk__mk_xml_output() and pcmk__mk_text_output().
46 *
47 * \param[in] argv The list of command line arguments.
48 */
49 typedef pcmk__output_t * (*pcmk__output_factory_t)(char **argv);
50
51 /*!
52 * \internal
53 * \brief The type of a custom message formatting function.
54 *
55 * These functions are defined by various libraries to support formatting of
56 * types aside from the basic types provided by a ::pcmk__output_t.
57 *
58 * The meaning of the return value will be different for each message.
59 * In general, however, 0 should be returned on success and a positive value
60 * on error.
61 *
62 * \param[in,out] out Output object to use to display message
63 * \param[in,out] args Message-specific arguments needed
64 *
65 * \note These functions must not call va_start or va_end - that is done
66 * automatically before the custom formatting function is called.
67 */
68 typedef int (*pcmk__message_fn_t)(pcmk__output_t *out, va_list args);
69
70 /*!
71 * \internal
72 * \brief Internal type for tracking custom messages.
73 *
74 * Each library can register functions that format custom message types. These
75 * are commonly used to handle some library-specific type. Registration is
76 * done by first defining a table of ::pcmk__message_entry_t structures and
77 * then passing that table to pcmk__register_messages(). Separate handlers
78 * can be defined for the same message, but for different formats (xml vs.
79 * text). Unknown formats will be ignored.
80 *
81 * Additionally, a "default" value for fmt_table can be used. In this case,
82 * fn will be registered for all supported formats. It is also possible to
83 * register a default and then override that registration with a format-specific
84 * function if necessary.
85 *
86 * \note The ::pcmk__message_entry_t table is processed in one pass, in order,
87 * from top to bottom. This means later entries with the same message_id will
88 * override previous ones. Thus, any default entry must come before any
89 * format-specific entries for the same message_id.
90 */
91 typedef struct pcmk__message_entry_s {
92 /*!
93 * \brief The message to be handled.
94 *
95 * This must be the same ID that is passed to the message function of
96 * a ::pcmk__output_t. Unknown message IDs will be ignored.
97 */
98 const char *message_id;
99
100 /*!
101 * \brief The format type this handler is for.
102 *
103 * This name must match the fmt_name of the currently active formatter in
104 * order for the registered function to be called. It is valid to have
105 * multiple entries for the same message_id but with different fmt_name
106 * values.
107 */
108 const char *fmt_name;
109
110 /*!
111 * \brief The function to be called for message_id given a match on
112 * fmt_name. See comments on ::pcmk__message_fn_t.
113 */
114 pcmk__message_fn_t fn;
115 } pcmk__message_entry_t;
116
117 /*!
118 * \internal
119 * \brief This structure contains everything needed to add support for a
120 * single output formatter to a command line program.
121 */
122 typedef struct pcmk__supported_format_s {
123 /*!
124 * \brief The name of this output formatter, which should match the
125 * fmt_name parameter in some ::pcmk__output_t structure.
126 */
127 const char *name;
128
129 /*!
130 * \brief A function that creates a ::pcmk__output_t.
131 */
132 pcmk__output_factory_t create;
133
134 /*!
135 * \brief Format-specific command line options. This can be NULL if
136 * no command line options should be supported.
137 */
138 GOptionEntry *options;
139 } pcmk__supported_format_t;
140
141 /* The following three blocks need to be updated each time a new base formatter
142 * is added.
143 */
144
145 extern GOptionEntry pcmk__html_output_entries[];
146 extern GOptionEntry pcmk__log_output_entries[];
147 extern GOptionEntry pcmk__none_output_entries[];
148 extern GOptionEntry pcmk__text_output_entries[];
149 extern GOptionEntry pcmk__xml_output_entries[];
150
151 pcmk__output_t *pcmk__mk_html_output(char **argv);
152 pcmk__output_t *pcmk__mk_log_output(char **argv);
153 pcmk__output_t *pcmk__mk_none_output(char **argv);
154 pcmk__output_t *pcmk__mk_text_output(char **argv);
155 pcmk__output_t *pcmk__mk_xml_output(char **argv);
156
157 #define PCMK__SUPPORTED_FORMAT_HTML { "html", pcmk__mk_html_output, pcmk__html_output_entries }
158 #define PCMK__SUPPORTED_FORMAT_LOG { "log", pcmk__mk_log_output, pcmk__log_output_entries }
159 #define PCMK__SUPPORTED_FORMAT_NONE { PCMK__VALUE_NONE, pcmk__mk_none_output, \
160 pcmk__none_output_entries }
161 #define PCMK__SUPPORTED_FORMAT_TEXT { "text", pcmk__mk_text_output, pcmk__text_output_entries }
162 #define PCMK__SUPPORTED_FORMAT_XML { "xml", pcmk__mk_xml_output, pcmk__xml_output_entries }
163
164 /*!
165 * \brief This structure contains everything that makes up a single output
166 * formatter.
167 *
168 * Instances of this structure may be created by calling pcmk__output_new()
169 * with the name of the desired formatter. They should later be freed with
170 * pcmk__output_free().
171 */
172 struct pcmk__output_s {
173 /*!
174 * \brief The name of this output formatter.
175 */
176 const char *fmt_name;
177
178 /*!
179 * \brief Should this formatter supress most output?
180 *
181 * \note This setting is not respected by all formatters. In general,
182 * machine-readable output formats will not support this while
183 * user-oriented formats will. Callers should use is_quiet()
184 * to test whether to print or not.
185 */
186 bool quiet;
187
188 /*!
189 * \brief A copy of the request that generated this output.
190 *
191 * In the case of command line usage, this would be the command line
192 * arguments. For other use cases, it could be different.
193 */
194 gchar *request;
195
196 /*!
197 * \brief Where output should be written.
198 *
199 * This could be a file handle, or stdout or stderr. This is really only
200 * useful internally.
201 */
202 FILE *dest;
203
204 /*!
205 * \brief Custom messages that are currently registered on this formatter.
206 *
207 * Keys are the string message IDs, values are ::pcmk__message_fn_t function
208 * pointers.
209 */
210 GHashTable *messages;
211
212 /*!
213 * \brief Implementation-specific private data.
214 *
215 * Each individual formatter may have some private data useful in its
216 * implementation. This points to that data. Callers should not rely on
217 * its contents or structure.
218 */
219 void *priv;
220
221 /*!
222 * \internal
223 * \brief Take whatever actions are necessary to prepare out for use. This is
224 * called by pcmk__output_new(). End users should not need to call this.
225 *
226 * \note For formatted output implementers - This function should be written in
227 * such a way that it can be called repeatedly on an already initialized
228 * object without causing problems, or on a previously finished object
229 * without crashing.
230 *
231 * \param[in,out] out The output functions structure.
232 *
233 * \return true on success, false on error.
234 */
235 bool (*init) (pcmk__output_t *out);
236
237 /*!
238 * \internal
239 * \brief Free the private formatter-specific data.
240 *
241 * This is called from pcmk__output_free() and does not typically need to be
242 * called directly.
243 *
244 * \param[in,out] out The output functions structure.
245 */
246 void (*free_priv) (pcmk__output_t *out);
247
248 /*!
249 * \internal
250 * \brief Take whatever actions are necessary to end formatted output.
251 *
252 * This could include flushing output to a file, but does not include freeing
253 * anything. The finish method can potentially be fairly complicated, adding
254 * additional information to the internal data structures or doing whatever
255 * else. It is therefore suggested that finish only be called once.
256 *
257 * \note The print parameter will only affect those formatters that do all
258 * their output at the end. Console-oriented formatters typically print
259 * a line at a time as they go, so this parameter will not affect them.
260 * Structured formatters will honor it, however.
261 *
262 * \note The copy_dest parameter does not apply to all formatters. Console-
263 * oriented formatters do not build up a structure as they go, and thus
264 * do not have anything to return. Structured formatters will honor it,
265 * however. Note that each type of formatter will return a different
266 * type of value in this parameter. To use this parameter, call this
267 * function like so:
268 *
269 * \code
270 * xmlNode *dest = NULL;
271 * out->finish(out, exit_code, false, (void **) &dest);
272 * \endcode
273 *
274 * \param[in,out] out The output functions structure.
275 * \param[in] exit_status The exit value of the whole program.
276 * \param[in] print Whether this function should write any output.
277 * \param[out] copy_dest A destination to store a copy of the internal
278 * data structure for this output, or NULL if no
279 * copy is required. The caller should free this
280 * memory when done with it.
281 */
282 void (*finish) (pcmk__output_t *out, crm_exit_t exit_status, bool print,
283 void **copy_dest);
284
285 /*!
286 * \internal
287 * \brief Finalize output and then immediately set back up to start a new set
288 * of output.
289 *
290 * This is conceptually the same as calling finish and then init, though in
291 * practice more be happening behind the scenes.
292 *
293 * \note This function differs from finish in that no exit_status is added.
294 * The idea is that the program is not shutting down, so there is not
295 * yet a final exit code. Call finish on the last time through if this
296 * is needed.
297 *
298 * \param[in,out] out The output functions structure.
299 */
300 void (*reset) (pcmk__output_t *out);
301
302 /*!
303 * \internal
304 * \brief Register a custom message.
305 *
306 * \param[in,out] out The output functions structure.
307 * \param[in] message_id The name of the message to register. This name
308 * will be used as the message_id parameter to the
309 * message function in order to call the custom
310 * format function.
311 * \param[in] fn The custom format function to call for message_id.
312 */
313 void (*register_message) (pcmk__output_t *out, const char *message_id,
314 pcmk__message_fn_t fn);
315
316 /*!
317 * \internal
318 * \brief Call a previously registered custom message.
319 *
320 * \param[in,out] out The output functions structure.
321 * \param[in] message_id The name of the message to call. This name must
322 * be the same as the message_id parameter of some
323 * previous call to register_message.
324 * \param[in] ... Arguments to be passed to the registered function.
325 *
326 * \return A standard Pacemaker return code. Generally: 0 if a function was
327 * registered for the message, that function was called, and returned
328 * successfully; EINVAL if no function was registered; or pcmk_rc_no_output
329 * if a function was called but produced no output.
330 */
331 int (*message) (pcmk__output_t *out, const char *message_id, ...);
332
333 /*!
334 * \internal
335 * \brief Format the output of a completed subprocess.
336 *
337 * \param[in,out] out The output functions structure.
338 * \param[in] exit_status The exit value of the subprocess.
339 * \param[in] proc_stdout stdout from the completed subprocess.
340 * \param[in] proc_stderr stderr from the completed subprocess.
341 */
342 void (*subprocess_output) (pcmk__output_t *out, int exit_status,
343 const char *proc_stdout, const char *proc_stderr);
344
345 /*!
346 * \internal
347 * \brief Format version information. This is useful for the --version
348 * argument of command line tools.
349 *
350 * \param[in,out] out The output functions structure.
351 * \param[in] extended Add additional version information.
352 */
353 void (*version) (pcmk__output_t *out, bool extended);
354
355 /*!
356 * \internal
357 * \brief Format an informational message that should be shown to
358 * to an interactive user. Not all formatters will do this.
359 *
360 * \note A newline will automatically be added to the end of the format
361 * string, so callers should not include a newline.
362 *
363 * \note It is possible for a formatter that supports this method to
364 * still not print anything out if is_quiet returns true.
365 *
366 * \param[in,out] out The output functions structure.
367 * \param[in] buf The message to be printed.
368 * \param[in] ... Arguments to be formatted.
369 *
370 * \return A standard Pacemaker return code. Generally: pcmk_rc_ok
371 * if output was produced and pcmk_rc_no_output if it was not.
372 * As not all formatters implement this function, those that
373 * do not will always just return pcmk_rc_no_output.
374 */
375 int (*info) (pcmk__output_t *out, const char *format, ...) G_GNUC_PRINTF(2, 3);
376
377 /*!
378 * \internal
379 * \brief Like \p info() but for messages that should appear only
380 * transiently. Not all formatters will do this.
381 *
382 * The originally envisioned use case is for console output, where a
383 * transient status-related message may be quickly overwritten by a refresh.
384 *
385 * \param[in,out] out The output functions structure.
386 * \param[in] format The format string of the message to be printed.
387 * \param[in] ... Arguments to be formatted.
388 *
389 * \return A standard Pacemaker return code. Generally: \p pcmk_rc_ok if
390 * output was produced and \p pcmk_rc_no_output if it was not. As
391 * not all formatters implement this function, those that do not
392 * will always just return \p pcmk_rc_no_output.
393 */
394 int (*transient) (pcmk__output_t *out, const char *format, ...)
395 G_GNUC_PRINTF(2, 3);
396
397 /*!
398 * \internal
399 * \brief Format an error message that should be shown to an interactive
400 * user. Not all formatters will do this.
401 *
402 * \note A newline will automatically be added to the end of the format
403 * string, so callers should not include a newline.
404 *
405 * \note Formatters that support this method should always generate output,
406 * even if is_quiet returns true.
407 *
408 * \param[in,out] out The output functions structure.
409 * \param[in] buf The message to be printed.
410 * \param[in] ... Arguments to be formatted.
411 */
412 void (*err) (pcmk__output_t *out, const char *format, ...) G_GNUC_PRINTF(2, 3);
413
414 /*!
415 * \internal
416 * \brief Format already formatted XML.
417 *
418 * \param[in,out] out The output functions structure.
419 * \param[in] name A name to associate with the XML.
420 * \param[in] buf The XML in a string.
421 */
422 void (*output_xml) (pcmk__output_t *out, const char *name, const char *buf);
423
424 /*!
425 * \internal
426 * \brief Start a new list of items.
427 *
428 * \note For text output, this corresponds to another level of indentation. For
429 * XML output, this corresponds to wrapping any following output in another
430 * layer of tags.
431 *
432 * \note If singular_noun and plural_noun are non-NULL, calling end_list will
433 * result in a summary being added.
434 *
435 * \param[in,out] out The output functions structure.
436 * \param[in] singular_noun When outputting the summary for a list with
437 * one item, the noun to use.
438 * \param[in] plural_noun When outputting the summary for a list with
439 * more than one item, the noun to use.
440 * \param[in] format The format string.
441 * \param[in] ... Arguments to be formatted.
442 */
443 void (*begin_list) (pcmk__output_t *out, const char *singular_noun,
444 const char *plural_noun, const char *format, ...)
445 G_GNUC_PRINTF(4, 5);
446
447 /*!
448 * \internal
449 * \brief Format a single item in a list.
450 *
451 * \param[in,out] out The output functions structure.
452 * \param[in] name A name to associate with this item.
453 * \param[in] format The format string.
454 * \param[in] ... Arguments to be formatted.
455 */
456 void (*list_item) (pcmk__output_t *out, const char *name, const char *format, ...)
457 G_GNUC_PRINTF(3, 4);
458
459 /*!
460 * \internal
461 * \brief Increment the internal counter of the current list's length.
462 *
463 * Typically, this counter is maintained behind the scenes as a side effect
464 * of calling list_item(). However, custom functions that maintain lists
465 * some other way will need to manage this counter manually. This is
466 * useful for implementing custom message functions and should not be
467 * needed otherwise.
468 *
469 * \param[in,out] out The output functions structure.
470 */
471 void (*increment_list) (pcmk__output_t *out);
472
473 /*!
474 * \internal
475 * \brief Conclude a list.
476 *
477 * \note If begin_list was called with non-NULL for both the singular_noun
478 * and plural_noun arguments, this function will output a summary.
479 * Otherwise, no summary will be added.
480 *
481 * \param[in,out] out The output functions structure.
482 */
483 void (*end_list) (pcmk__output_t *out);
484
485 /*!
486 * \internal
487 * \brief Should anything be printed to the user?
488 *
489 * \note This takes into account both the \p quiet value as well as the
490 * current formatter.
491 *
492 * \param[in,out] out The output functions structure.
493 *
494 * \return true if output should be supressed, false otherwise.
495 */
496 bool (*is_quiet) (pcmk__output_t *out);
497
498 /*!
499 * \internal
500 * \brief Output a spacer. Not all formatters will do this.
501 *
502 * \param[in,out] out The output functions structure.
503 */
504 void (*spacer) (pcmk__output_t *out);
505
506 /*!
507 * \internal
508 * \brief Output a progress indicator. This is likely only useful for
509 * plain text, console based formatters.
510 *
511 * \param[in,out] out The output functions structure
512 * \param[in] end If true, output a newline afterwards (this should
513 * only be used the last time this function is called)
514 *
515 */
516 void (*progress) (pcmk__output_t *out, bool end);
517
518 /*!
519 * \internal
520 * \brief Prompt the user for input. Not all formatters will do this.
521 *
522 * \note This function is part of pcmk__output_t, but unlike all other
523 * function it does not take that as an argument. In general, a
524 * prompt will go directly to the screen and therefore bypass any
525 * need to use the formatted output code to decide where and how
526 * to display.
527 *
528 * \param[in] prompt The prompt to display. This is required.
529 * \param[in] echo If true, echo the user's input to the screen. Set
530 * to false for password entry.
531 * \param[out] dest Where to store the user's response. This is
532 * required.
533 */
534 void (*prompt) (const char *prompt, bool echo, char **dest);
535 };
536
537 /*!
538 * \internal
539 * \brief Call a formatting function for a previously registered message.
540 *
541 * \note This function is for implementing custom formatters. It should not
542 * be called directly. Instead, call out->message.
543 *
544 * \param[in,out] out The output functions structure.
545 * \param[in] message_id The message to be handled. Unknown messages
546 * will be ignored.
547 * \param[in] ... Arguments to be passed to the registered function.
548 */
549 int
550 pcmk__call_message(pcmk__output_t *out, const char *message_id, ...);
551
552 /*!
553 * \internal
554 * \brief Free a ::pcmk__output_t structure that was previously created by
555 * pcmk__output_new().
556 *
557 * \note While the create and finish functions are designed in such a way that
558 * they can be called repeatedly, this function will completely free the
559 * memory of the object. Once this function has been called, producing
560 * more output requires starting over from pcmk__output_new().
561 *
562 * \param[in,out] out The output structure.
563 */
564 void pcmk__output_free(pcmk__output_t *out);
565
566 /*!
567 * \internal
568 * \brief Create a new ::pcmk__output_t structure.
569 *
570 * This also registers message functions from libcrmcommon.
571 *
572 * \param[in,out] out The destination of the new ::pcmk__output_t.
573 * \param[in] fmt_name How should output be formatted?
574 * \param[in] filename Where should formatted output be written to? This
575 * can be a filename (which will be overwritten if it
576 * already exists), or NULL or "-" for stdout. For no
577 * output, pass a filename of "/dev/null".
578 * \param[in] argv The list of command line arguments.
579 *
580 * \return Standard Pacemaker return code
581 */
582 int pcmk__output_new(pcmk__output_t **out, const char *fmt_name,
583 const char *filename, char **argv);
584
585 /*!
586 * \internal
587 * \brief Register a new output formatter, making it available for use
588 * the same as a base formatter.
589 *
590 * \param[in,out] group A ::GOptionGroup that formatted output related command
591 * line arguments should be added to. This can be NULL
592 * for use outside of command line programs.
593 * \param[in] name The name of the format. This will be used to select a
594 * format from command line options and for displaying help.
595 * \param[in] create A function that creates a ::pcmk__output_t.
596 * \param[in] options Format-specific command line options. These will be
597 * added to the context. This argument can also be NULL.
598 *
599 * \return Standard Pacemaker return code
600 */
601 int
602 pcmk__register_format(GOptionGroup *group, const char *name,
603 pcmk__output_factory_t create,
604 const GOptionEntry *options);
605
606 /*!
607 * \internal
608 * \brief Register an entire table of output formatters at once.
609 *
610 * \param[in,out] group A ::GOptionGroup that formatted output related command
611 * line arguments should be added to. This can be NULL
612 * for use outside of command line programs.
613 * \param[in] table An array of ::pcmk__supported_format_t which should
614 * all be registered. This array must be NULL-terminated.
615 *
616 */
617 void
618 pcmk__register_formats(GOptionGroup *group,
619 const pcmk__supported_format_t *table);
620
621 /*!
622 * \internal
623 * \brief Unregister a previously registered table of custom formatting
624 * functions and destroy the internal data structures associated with them.
625 */
626 void
627 pcmk__unregister_formats(void);
628
629 /*!
630 * \internal
631 * \brief Register a function to handle a custom message.
632 *
633 * \note This function is for implementing custom formatters. It should not
634 * be called directly. Instead, call out->register_message.
635 *
636 * \param[in,out] out The output functions structure.
637 * \param[in] message_id The message to be handled.
638 * \param[in] fn The custom format function to call for message_id.
639 */
640 void
641 pcmk__register_message(pcmk__output_t *out, const char *message_id,
642 pcmk__message_fn_t fn);
643
644 /*!
645 * \internal
646 * \brief Register an entire table of custom formatting functions at once.
647 *
648 * This table can contain multiple formatting functions for the same message ID
649 * if they are for different format types.
650 *
651 * \param[in,out] out The output functions structure.
652 * \param[in] table An array of ::pcmk__message_entry_t values which should
653 * all be registered. This array must be NULL-terminated.
654 */
655 void
656 pcmk__register_messages(pcmk__output_t *out,
657 const pcmk__message_entry_t *table);
658
659 /* Functions that are useful for implementing custom message formatters */
660
661 /*!
662 * \internal
663 * \brief A printf-like function.
664 *
665 * This function writes to out->dest and indents the text to the current level
666 * of the text formatter's nesting. This function should be used when implementing
667 * custom message functions for the text output format. It should not be used
668 * for any other purpose.
669 *
670 * Typically, this function should be used instead of printf.
671 *
672 * \param[in,out] out The output functions structure.
673 * \param[in] format The format string.
674 * \param[in] ... Arguments to be passed to the format string.
675 */
676 void
677 pcmk__indented_printf(pcmk__output_t *out, const char *format, ...) G_GNUC_PRINTF(2, 3);
/* ![[first]](../icons/n_first.png)
![[top]](../icons/top.png)
*/
678
679 /*!
680 * \internal
681 * \brief A vprintf-like function.
682 *
683 * This function is like pcmk__indented_printf(), except it takes a va_list instead
684 * of a list of arguments. This function should be used when implementing custom
685 * functions for the text output format. It should not be used for any other purpose.
686 *
687 * Typically, this function should be used instead of vprintf.
688 *
689 * \param[in,out] out The output functions structure.
690 * \param[in] format The format string.
691 * \param[in] args A list of arguments to apply to the format string.
692 */
693 void
694 pcmk__indented_vprintf(pcmk__output_t *out, const char *format, va_list args) G_GNUC_PRINTF(2, 0);
695
696
697 /*!
698 * \internal
699 * \brief A printf-like function.
700 *
701 * This function writes to out->dest without indenting the text. This function
702 * should be used when implementing custom message functions for the text output
703 * format. It should not be used for any other purpose.
704 *
705 * \param[in,out] out The output functions structure.
706 * \param[in] format The format string.
707 * \param[in] ... Arguments to be passed to the format string.
708 */
709 void
710 pcmk__formatted_printf(pcmk__output_t *out, const char *format, ...) G_GNUC_PRINTF(2, 3);
711
712 /*!
713 * \internal
714 * \brief A vprintf-like function.
715 *
716 * This function is like pcmk__formatted_printf(), except it takes a va_list instead
717 * of a list of arguments. This function should be used when implementing custom
718 * message functions for the text output format. It should not be used for any
719 * other purpose.
720 *
721 * \param[in,out] out The output functions structure.
722 * \param[in] format The format string.
723 * \param[in] args A list of arguments to apply to the format string.
724 */
725 void
726 pcmk__formatted_vprintf(pcmk__output_t *out, const char *format, va_list args) G_GNUC_PRINTF(2, 0);
727
728 /*!
729 * \internal
730 * \brief Prompt the user for input.
731 *
732 * \param[in] prompt The prompt to display
733 * \param[in] echo If true, echo the user's input to the screen. Set
734 * to false for password entry.
735 * \param[out] dest Where to store the user's response.
736 */
737 void
738 pcmk__text_prompt(const char *prompt, bool echo, char **dest);
739
740 /*!
741 * \internal
742 * \brief Get the log level used by the formatted output logger
743 *
744 * \param[in] out Output object
745 *
746 * \return Log level used by \p out
747 */
748 uint8_t
749 pcmk__output_get_log_level(const pcmk__output_t *out);
750
751 /*!
752 * \internal
753 * \brief Set the log level used by the formatted output logger.
754 *
755 * \param[in,out] out The output functions structure.
756 * \param[in] log_level The log level constant (LOG_INFO, LOG_ERR, etc.)
757 * to use.
758 *
759 * \note By default, LOG_INFO is used.
760 * \note Almost all formatted output messages will respect this setting.
761 * However, out->err will always log at LOG_ERR.
762 */
763 void
764 pcmk__output_set_log_level(pcmk__output_t *out, uint8_t log_level);
765
766 /*!
767 * \internal
768 * \brief Create and return a new XML node with the given name, as a child of the
769 * current list parent. The new node is then added as the new list parent,
770 * meaning all subsequent nodes will be its children. This is used when
771 * implementing custom functions.
772 *
773 * \param[in,out] out The output functions structure.
774 * \param[in] name The name of the node to be created.
775 * \param[in] ... Name/value pairs to set as XML properties.
776 */
777 xmlNodePtr
778 pcmk__output_xml_create_parent(pcmk__output_t *out, const char *name, ...)
779 G_GNUC_NULL_TERMINATED;
780
781 /*!
782 * \internal
783 * \brief Add a copy of the given node as a child of the current list parent.
784 * This is used when implementing custom message functions.
785 *
786 * \param[in,out] out The output functions structure.
787 * \param[in] node An XML node to copy as a child.
788 */
789 void
790 pcmk__output_xml_add_node_copy(pcmk__output_t *out, xmlNodePtr node);
791
792 /*!
793 * \internal
794 * \brief Create and return a new XML node with the given name, as a child of the
795 * current list parent. This is used when implementing custom functions.
796 *
797 * \param[in,out] out The output functions structure.
798 * \param[in] name The name of the node to be created.
799 * \param[in] ... Name/value pairs to set as XML properties.
800 */
801 xmlNodePtr
802 pcmk__output_create_xml_node(pcmk__output_t *out, const char *name, ...)
803 G_GNUC_NULL_TERMINATED;
804
805 /*!
806 * \internal
807 * \brief Like pcmk__output_create_xml_node(), but add the given text content to the
808 * new node.
809 *
810 * \param[in,out] out The output functions structure.
811 * \param[in] name The name of the node to be created.
812 * \param[in] content The text content of the node.
813 */
814 xmlNodePtr
815 pcmk__output_create_xml_text_node(pcmk__output_t *out, const char *name, const char *content);
816
817 /*!
818 * \internal
819 * \brief Push a parent XML node onto the stack. This is used when implementing
820 * custom message functions.
821 *
822 * The XML output formatter maintains an internal stack to keep track of which nodes
823 * are parents in order to build up the tree structure. This function can be used
824 * to temporarily push a new node onto the stack. After calling this function, any
825 * other formatting functions will have their nodes added as children of this new
826 * parent.
827 *
828 * \param[in,out] out The output functions structure
829 * \param[in] parent XML node to add
830 */
831 void
832 pcmk__output_xml_push_parent(pcmk__output_t *out, xmlNodePtr parent);
833
834 /*!
835 * \internal
836 * \brief Pop a parent XML node onto the stack. This is used when implementing
837 * custom message functions.
838 *
839 * This function removes a parent node from the stack. See pcmk__xml_push_parent()
840 * for more details.
841 *
842 * \note Little checking is done with this function. Be sure you only pop parents
843 * that were previously pushed. In general, it is best to keep the code between
844 * push and pop simple.
845 *
846 * \param[in,out] out The output functions structure.
847 */
848 void
849 pcmk__output_xml_pop_parent(pcmk__output_t *out);
850
851 /*!
852 * \internal
853 * \brief Peek a parent XML node onto the stack. This is used when implementing
854 * custom message functions.
855 *
856 * This function peeks a parent node on stack. See pcmk__xml_push_parent()
857 * for more details. It has no side-effect and can be called for an empty stack.
858 *
859 * \note Little checking is done with this function.
860 *
861 * \param[in,out] out The output functions structure.
862 *
863 * \return NULL if stack is empty, otherwise the parent of the stack.
864 */
865 xmlNodePtr
866 pcmk__output_xml_peek_parent(pcmk__output_t *out);
867
868 /*!
869 * \internal
870 * \brief Create a new XML node consisting of the provided text inside an HTML
871 * element node of the given name.
872 *
873 * \param[in,out] out The output functions structure.
874 * \param[in] element_name The name of the new HTML element.
875 * \param[in] id The CSS ID selector to apply to this element.
876 * If NULL, no ID is added.
877 * \param[in] class_name The CSS class selector to apply to this element.
878 * If NULL, no class is added.
879 * \param[in] text The text content of the node.
880 */
881 xmlNodePtr
882 pcmk__output_create_html_node(pcmk__output_t *out, const char *element_name, const char *id,
883 const char *class_name, const char *text);
884
885 /*!
886 * \internal
887 * \brief Add an HTML tag to the <head> section.
888 *
889 * The arguments after name are a NULL-terminated list of keys and values,
890 * all of which will be added as attributes to the given tag. For instance,
891 * the following code would generate the tag "<meta http-equiv='refresh' content='19'>":
892 *
893 * \code
894 * pcmk__html_add_header("meta", "http-equiv", "refresh", "content", "19", NULL);
895 * \endcode
896 *
897 * \param[in] name The HTML tag for the new node.
898 * \param[in] ... A NULL-terminated key/value list of attributes.
899 */
900 void
901 pcmk__html_add_header(const char *name, ...)
902 G_GNUC_NULL_TERMINATED;
903
904 /*!
905 * \internal
906 * \brief Handle end-of-program error reporting
907 *
908 * \param[in,out] error A GError object potentially containing some error.
909 * If NULL, do nothing.
910 * \param[in,out] out The output functions structure. If NULL, any errors
911 * will simply be printed to stderr.
912 */
913 void pcmk__output_and_clear_error(GError **error, pcmk__output_t *out);
914
915 int pcmk__xml_output_new(pcmk__output_t **out, xmlNodePtr *xml);
916 void pcmk__xml_output_finish(pcmk__output_t *out, xmlNodePtr *xml);
917 int pcmk__log_output_new(pcmk__output_t **out);
918 int pcmk__text_output_new(pcmk__output_t **out, const char *filename);
919
920 /*!
921 * \internal
922 * \brief Select an updated return code for an operation on a \p pcmk__output_t
923 *
924 * This function helps to keep an up-to-date record of the most relevant return
925 * code from a series of operations on a \p pcmk__output_t object. For example,
926 * suppose the object has already produced some output, and we've saved a
927 * \p pcmk_rc_ok return code. A new operation did not produce any output and
928 * returned \p pcmk_rc_no_output. We can ignore the new \p pcmk_rc_no_output
929 * return code and keep the previous \p pcmk_rc_ok return code.
930 *
931 * It prioritizes return codes as follows (from highest to lowest priority):
932 * 1. Other return codes (unexpected errors)
933 * 2. \p pcmk_rc_ok
934 * 3. \p pcmk_rc_no_output
935 *
936 * \param[in] old_rc Saved return code from \p pcmk__output_t operations
937 * \param[in] new_rc New return code from a \p pcmk__output_t operation
938 *
939 * \retval \p old_rc \p new_rc is \p pcmk_rc_no_output, or \p new_rc is
940 * \p pcmk_rc_ok and \p old_rc is not \p pcmk_rc_no_output
941 * \retval \p new_rc Otherwise
942 */
943 static inline int
944 pcmk__output_select_rc(int old_rc, int new_rc)
945 {
946 switch (new_rc) {
947 case pcmk_rc_no_output:
948 return old_rc;
949 case pcmk_rc_ok:
950 switch (old_rc) {
951 case pcmk_rc_no_output:
952 return new_rc;
953 default:
954 return old_rc;
955 }
956 default:
957 return new_rc;
958 }
959 }
960
961 #if defined(PCMK__UNIT_TESTING)
962 /* If we are building libcrmcommon_test.a, add this accessor function so we can
963 * inspect the internal formatters hash table.
964 */
965 GHashTable *pcmk__output_formatters(void);
966 #endif
967
968 #define PCMK__OUTPUT_SPACER_IF(out_obj, cond) \
969 if (cond) { \
970 out->spacer(out); \
971 }
972
973 #define PCMK__OUTPUT_LIST_HEADER(out_obj, cond, retcode, title...) \
974 if (retcode == pcmk_rc_no_output) { \
975 PCMK__OUTPUT_SPACER_IF(out_obj, cond); \
976 retcode = pcmk_rc_ok; \
977 out_obj->begin_list(out_obj, NULL, NULL, title); \
978 }
979
980 #define PCMK__OUTPUT_LIST_FOOTER(out_obj, retcode) \
981 if (retcode == pcmk_rc_ok) { \
982 out_obj->end_list(out_obj); \
983 }
984
985 #ifdef __cplusplus
986 }
987 #endif
988
989 #endif
![[last]](../icons/last.png){kind=icon}
![[bottom]](../icons/n_bottom.png){kind=icon}
*/