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.13" 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