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