root/include/crm/common/output_internal.h

/* [previous][next][first][last][top][bottom][index][help] */

INCLUDED FROM


   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

/* [previous][next][first][last][top][bottom][index][help] */