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