root/include/crm/common/output_internal.h

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

INCLUDED FROM


DEFINITIONS

This source file includes following definitions.
  1. pcmk__indented_printf

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

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