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