root/include/crm/common/output_internal.h

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

INCLUDED FROM


   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

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