![[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-2020 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 CRM_OUTPUT__H
11 # define CRM_OUTPUT__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.3"
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 void (*info) (pcmk__output_t *out, const char *format, ...) G_GNUC_PRINTF(2, 3);
365
366 /*!
367 * \internal
368 * \brief Format an error message that should be shown to an interactive
369 * user. Not all formatters will do this.
370 *
371 * \note A newline will automatically be added to the end of the format
372 * string, so callers should not include a newline.
373 *
374 * \param[in,out] out The output functions structure.
375 * \param[in] buf The message to be printed.
376 * \param[in] ... Arguments to be formatted.
377 */
378 void (*err) (pcmk__output_t *out, const char *format, ...) G_GNUC_PRINTF(2, 3);
379
380 /*!
381 * \internal
382 * \brief Format already formatted XML.
383 *
384 * \param[in,out] out The output functions structure.
385 * \param[in] name A name to associate with the XML.
386 * \param[in] buf The XML in a string.
387 */
388 void (*output_xml) (pcmk__output_t *out, const char *name, const char *buf);
389
390 /*!
391 * \internal
392 * \brief Start a new list of items.
393 *
394 * \note For text output, this corresponds to another level of indentation. For
395 * XML output, this corresponds to wrapping any following output in another
396 * layer of tags.
397 *
398 * \note If singular_noun and plural_noun are non-NULL, calling end_list will
399 * result in a summary being added.
400 *
401 * \param[in,out] out The output functions structure.
402 * \param[in] singular_noun When outputting the summary for a list with
403 * one item, the noun to use.
404 * \param[in] plural_noun When outputting the summary for a list with
405 * more than one item, the noun to use.
406 * \param[in] format The format string.
407 * \param[in] ... Arguments to be formatted.
408 */
409 void (*begin_list) (pcmk__output_t *out, const char *singular_noun,
410 const char *plural_noun, const char *format, ...)
411 G_GNUC_PRINTF(4, 5);
412
413 /*!
414 * \internal
415 * \brief Format a single item in a list.
416 *
417 * \param[in,out] out The output functions structure.
418 * \param[in] name A name to associate with this item.
419 * \param[in] format The format string.
420 * \param[in] ... Arguments to be formatted.
421 */
422 void (*list_item) (pcmk__output_t *out, const char *name, const char *format, ...)
423 G_GNUC_PRINTF(3, 4);
424
425 /*!
426 * \internal
427 * \brief Increment the internal counter of the current list's length.
428 *
429 * Typically, this counter is maintained behind the scenes as a side effect
430 * of calling list_item(). However, custom functions that maintain lists
431 * some other way will need to manage this counter manually. This is
432 * useful for implementing custom message functions and should not be
433 * needed otherwise.
434 *
435 * \param[in,out] out The output functions structure.
436 */
437 void (*increment_list) (pcmk__output_t *out);
438
439 /*!
440 * \internal
441 * \brief Conclude a list.
442 *
443 * \note If begin_list was called with non-NULL for both the singular_noun
444 * and plural_noun arguments, this function will output a summary.
445 * Otherwise, no summary will be added.
446 *
447 * \param[in,out] out The output functions structure.
448 */
449 void (*end_list) (pcmk__output_t *out);
450
451 /*!
452 * \internal
453 * \brief Should anything be printed to the user?
454 *
455 * \note This takes into account both the \p quiet value as well as the
456 * current formatter.
457 *
458 * \param[in] out The output functions structure.
459 *
460 * \return true if output should be supressed, false otherwise.
461 */
462 bool (*is_quiet) (pcmk__output_t *out);
463 };
464
465 /*!
466 * \internal
467 * \brief Call a formatting function for a previously registered message.
468 *
469 * \note This function is for implementing custom formatters. It should not
470 * be called directly. Instead, call out->message.
471 *
472 * \param[in,out] out The output functions structure.
473 * \param[in] message_id The message to be handled. Unknown messages
474 * will be ignored.
475 * \param[in] ... Arguments to be passed to the registered function.
476 */
477 int
478 pcmk__call_message(pcmk__output_t *out, const char *message_id, ...);
479
480 /*!
481 * \internal
482 * \brief Free a ::pcmk__output_t structure that was previously created by
483 * pcmk__output_new().
484 *
485 * \note While the create and finish functions are designed in such a way that
486 * they can be called repeatedly, this function will completely free the
487 * memory of the object. Once this function has been called, producing
488 * more output requires starting over from pcmk__output_new().
489 *
490 * \param[in,out] out The output structure.
491 */
492 void pcmk__output_free(pcmk__output_t *out);
493
494 /*!
495 * \internal
496 * \brief Create a new ::pcmk__output_t structure.
497 *
498 * \param[in,out] out The destination of the new ::pcmk__output_t.
499 * \param[in] fmt_name How should output be formatted?
500 * \param[in] filename Where should formatted output be written to? This
501 * can be a filename (which will be overwritten if it
502 * already exists), or NULL or "-" for stdout. For no
503 * output, pass a filename of "/dev/null".
504 * \param[in] argv The list of command line arguments.
505 *
506 * \return Standard Pacemaker return code
507 */
508 int pcmk__output_new(pcmk__output_t **out, const char *fmt_name,
509 const char *filename, char **argv);
510
511 /*!
512 * \internal
513 * \brief Register a new output formatter, making it available for use
514 * the same as a base formatter.
515 *
516 * \param[in,out] group A ::GOptionGroup that formatted output related command
517 * line arguments should be added to. This can be NULL
518 * for use outside of command line programs.
519 * \param[in] name The name of the format. This will be used to select a
520 * format from command line options and for displaying help.
521 * \param[in] create A function that creates a ::pcmk__output_t.
522 * \param[in] options Format-specific command line options. These will be
523 * added to the context. This argument can also be NULL.
524 *
525 * \return 0 on success or an error code on error.
526 */
527 int
528 pcmk__register_format(GOptionGroup *group, const char *name,
529 pcmk__output_factory_t create, GOptionEntry *options);
530
531 /*!
532 * \internal
533 * \brief Register an entire table of output formatters at once.
534 *
535 * \param[in,out] group A ::GOptionGroup that formatted output related command
536 * line arguments should be added to. This can be NULL
537 * for use outside of command line programs.
538 * \param[in] table An array of ::pcmk__supported_format_t which should
539 * all be registered. This array must be NULL-terminated.
540 *
541 */
542 void
543 pcmk__register_formats(GOptionGroup *group, pcmk__supported_format_t *table);
544
545 /*!
546 * \internal
547 * \brief Unregister a previously registered table of custom formatting
548 * functions and destroy the internal data structures associated with them.
549 */
550 void
551 pcmk__unregister_formats(void);
552
553 /*!
554 * \internal
555 * \brief Register a function to handle a custom message.
556 *
557 * \note This function is for implementing custom formatters. It should not
558 * be called directly. Instead, call out->register_message.
559 *
560 * \param[in,out] out The output functions structure.
561 * \param[in] message_id The message to be handled.
562 * \param[in] fn The custom format function to call for message_id.
563 */
564 void
565 pcmk__register_message(pcmk__output_t *out, const char *message_id,
566 pcmk__message_fn_t fn);
567
568 /*!
569 * \internal
570 * \brief Register an entire table of custom formatting functions at once.
571 *
572 * This table can contain multiple formatting functions for the same message ID
573 * if they are for different format types.
574 *
575 * \param[in,out] out The output functions structure.
576 * \param[in] table An array of ::pcmk__message_entry_t values which should
577 * all be registered. This array must be NULL-terminated.
578 */
579 void
580 pcmk__register_messages(pcmk__output_t *out, pcmk__message_entry_t *table);
581
582 /* Functions that are useful for implementing custom message formatters */
583
584 /*!
585 * \internal
586 * \brief A printf-like function.
587 *
588 * This function writes to out->dest and indents the text to the current level
589 * of the text formatter's nesting. This should be used when implementing
590 * custom message functions instead of printf.
591 *
592 * \param[in,out] out The output functions structure.
593 */
594 void
595 pcmk__indented_printf(pcmk__output_t *out, const char *format, ...) G_GNUC_PRINTF(2, 3);
596
597 /*!
598 * \internal
599 * \brief A vprintf-like function.
600 *
601 * This function is like pcmk__indented_printf(), except it takes a va_list instead
602 * of a list of arguments. This should be used when implementing custom message
603 * functions instead of vprintf.
604 *
605 * \param[in,out] out The output functions structure.
606 * \param[in] format The format string.
607 * \param[in] args A list of arguments to apply to the format string.
608 */
609 void
610 pcmk__indented_vprintf(pcmk__output_t *out, const char *format, va_list args) G_GNUC_PRINTF(2, 0);
611
612 /*!
613 * \internal
614 * \brief Create and return a new XML node with the given name, as a child of the
615 * current list parent. The new node is then added as the new list parent,
616 * meaning all subsequent nodes will be its children. This is used when
617 * implementing custom functions.
618 *
619 * \param[in,out] out The output functions structure.
620 * \param[in] name The name of the node to be created.
621 */
622 xmlNodePtr
623 pcmk__output_xml_create_parent(pcmk__output_t *out, const char *name);
624
625 /*!
626 * \internal
627 * \brief Add the given node as a child of the current list parent. This is
628 * used when implementing custom message functions.
629 *
630 * \param[in,out] out The output functions structure.
631 * \param[in] node An XML node to be added as a child.
632 */
633 void
634 pcmk__output_xml_add_node(pcmk__output_t *out, xmlNodePtr node);
635
636 /*!
637 * \internal
638 * \brief Create and return a new XML node with the given name, as a child of the
639 * current list parent. This is used when implementing custom functions.
640 *
641 * \param[in,out] out The output functions structure.
642 * \param[in] name The name of the node to be created.
643 */
644 xmlNodePtr
645 pcmk__output_create_xml_node(pcmk__output_t *out, const char *name);
646
647 /*!
648 * \internal
649 * \brief Like pcmk__output_create_xml_node(), but add the given text content to the
650 * new node.
651 *
652 * \param[in,out] out The output functions structure.
653 * \param[in] name The name of the node to be created.
654 * \param[in] content The text content of the node.
655 */
656 xmlNodePtr
657 pcmk__output_create_xml_text_node(pcmk__output_t *out, const char *name, const char *content);
658
659 /*!
660 * \internal
661 * \brief Push a parent XML node onto the stack. This is used when implementing
662 * custom message functions.
663 *
664 * The XML output formatter maintains an internal stack to keep track of which nodes
665 * are parents in order to build up the tree structure. This function can be used
666 * to temporarily push a new node onto the stack. After calling this function, any
667 * other formatting functions will have their nodes added as children of this new
668 * parent.
669 *
670 * \param[in,out] out The output functions structure.
671 * \param[in] node The node to be added/
672 */
673 void
674 pcmk__output_xml_push_parent(pcmk__output_t *out, xmlNodePtr node);
675
676 /*!
677 * \internal
678 * \brief Pop a parent XML node onto the stack. This is used when implementing
679 * custom message functions.
680 *
681 * This function removes a parent node from the stack. See pcmk__xml_push_parent()
682 * for more details.
683 *
684 * \note Little checking is done with this function. Be sure you only pop parents
685 * that were previously pushed. In general, it is best to keep the code between
686 * push and pop simple.
687 *
688 * \param[in,out] out The output functions structure.
689 */
690 void
691 pcmk__output_xml_pop_parent(pcmk__output_t *out);
692
693 /*!
694 * \internal
695 * \brief Peek a parent XML node onto the stack. This is used when implementing
696 * custom message functions.
697 *
698 * This function peeks a parent node on stack. See pcmk__xml_push_parent()
699 * for more details. It has no side-effect and can be called for an empty stack.
700 *
701 * \note Little checking is done with this function.
702 *
703 * \param[in,out] out The output functions structure.
704 *
705 * \return NULL if stack is empty, otherwise the parent of the stack.
706 */
707 xmlNodePtr
708 pcmk__output_xml_peek_parent(pcmk__output_t *out);
709
710 /*!
711 * \internal
712 * \brief Create a new XML node consisting of the provided text inside an HTML
713 * element node of the given name.
714 *
715 * \param[in,out] out The output functions structure.
716 * \param[in] element_name The name of the new HTML element.
717 * \param[in] id The CSS ID selector to apply to this element.
718 * If NULL, no ID is added.
719 * \param[in] class_name The CSS class selector to apply to this element.
720 * If NULL, no class is added.
721 * \param[in] text The text content of the node.
722 */
723 xmlNodePtr
724 pcmk__output_create_html_node(pcmk__output_t *out, const char *element_name, const char *id,
725 const char *class_name, const char *text);
726
727 /*!
728 * \internal
729 * \brief Add an HTML tag to the <head> section.
730 *
731 * The arguments after name are a NULL-terminated list of keys and values,
732 * all of which will be added as attributes to the given tag. For instance,
733 * the following code would generate the tag "<meta http-equiv='refresh' content='19'>":
734 *
735 * \code
736 * pcmk__html_add_header("meta", "http-equiv", "refresh", "content", "19", NULL);
737 * \endcode
738 *
739 * \param[in] name The HTML tag for the new node.
740 * \param[in] ... A NULL-terminated key/value list of attributes.
741 */
742 void
743 pcmk__html_add_header(const char *name, ...)
744 G_GNUC_NULL_TERMINATED;
745
746 #define PCMK__OUTPUT_SPACER_IF(out_obj, cond) \
747 if (cond) { \
748 out_obj->info(out_obj, "%s", ""); \
749 }
750
751 #define PCMK__OUTPUT_LIST_HEADER(out_obj, cond, retcode, title...) \
752 if (retcode == pcmk_rc_no_output) { \
753 PCMK__OUTPUT_SPACER_IF(out_obj, cond); \
754 retcode = pcmk_rc_ok; \
755 out_obj->begin_list(out_obj, NULL, NULL, title); \
756 }
757
758 #define PCMK__OUTPUT_LIST_FOOTER(out_obj, retcode) \
759 if (retcode == pcmk_rc_ok) { \
760 out_obj->end_list(out_obj); \
761 }
762
763 #ifdef __cplusplus
764 }
765 #endif
766
767 #endif
![[top]](../icons/top.png){kind=icon}
![[bottom]](../icons/n_bottom.png){kind=icon}
*/