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