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