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