output_internal.h

Go to the documentation of this file.

/*
 * Copyright 2019-2024 the Pacemaker project contributors
 *
 * The version control history for this file may have further details.
 *
 * This source code is licensed under the GNU Lesser General Public License
 * version 2.1 or later (LGPLv2.1+) WITHOUT ANY WARRANTY.
 */
 
#ifndef PCMK__OUTPUT_INTERNAL__H
#define PCMK__OUTPUT_INTERNAL__H
 
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <libxml/tree.h>
#include <libxml/HTMLtree.h>
 
#include <glib.h>
#include <crm/common/results.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#if defined(PCMK__WITH_ATTRIBUTE_OUTPUT_ARGS)
#define PCMK__OUTPUT_ARGS(ARGS...) __attribute__((output_args(ARGS)))
#else
#define PCMK__OUTPUT_ARGS(ARGS...)
#endif
 
typedef struct pcmk__output_s pcmk__output_t;
 
typedef pcmk__output_t * (*pcmk__output_factory_t)(char **argv);
 
typedef int (*pcmk__message_fn_t)(pcmk__output_t *out, va_list args);
 
typedef struct pcmk__message_entry_s {
    const char *message_id;
 
    const char *fmt_name;
 
    pcmk__message_fn_t fn;
} pcmk__message_entry_t;
 
typedef struct pcmk__supported_format_s {
    const char *name;
 
    pcmk__output_factory_t create;
 
    GOptionEntry *options;
} pcmk__supported_format_t;
 
/* The following three blocks need to be updated each time a new base formatter
 * is added.
 */
 
extern GOptionEntry pcmk__html_output_entries[];
extern GOptionEntry pcmk__text_output_entries[];
 
pcmk__output_t *pcmk__mk_html_output(char **argv);
pcmk__output_t *pcmk__mk_log_output(char **argv);
pcmk__output_t *pcmk__mk_none_output(char **argv);
pcmk__output_t *pcmk__mk_text_output(char **argv);
pcmk__output_t *pcmk__mk_xml_output(char **argv);
 
#define PCMK__SUPPORTED_FORMAT_HTML { "html", pcmk__mk_html_output, pcmk__html_output_entries }
#define PCMK__SUPPORTED_FORMAT_LOG  { "log", pcmk__mk_log_output, NULL }
#define PCMK__SUPPORTED_FORMAT_NONE { PCMK_VALUE_NONE, pcmk__mk_none_output, NULL }
#define PCMK__SUPPORTED_FORMAT_TEXT { "text", pcmk__mk_text_output, pcmk__text_output_entries }
#define PCMK__SUPPORTED_FORMAT_XML  { "xml", pcmk__mk_xml_output, NULL }
 
struct pcmk__output_s {
    const char *fmt_name;
 
    bool quiet;
 
    gchar *request;
 
    FILE *dest;
 
    GHashTable *messages;
 
    void *priv;
 
    bool (*init) (pcmk__output_t *out);
 
    void (*free_priv) (pcmk__output_t *out);
 
    void (*finish) (pcmk__output_t *out, crm_exit_t exit_status, bool print,
                    void **copy_dest);
 
    void (*reset) (pcmk__output_t *out);
 
    void (*register_message) (pcmk__output_t *out, const char *message_id,
                              pcmk__message_fn_t fn);
 
    int (*message) (pcmk__output_t *out, const char *message_id, ...);
 
    void (*subprocess_output) (pcmk__output_t *out, int exit_status,
                               const char *proc_stdout, const char *proc_stderr);
 
    void (*version) (pcmk__output_t *out, bool extended);
 
    int (*info) (pcmk__output_t *out, const char *format, ...) G_GNUC_PRINTF(2, 3);
 
    int (*transient) (pcmk__output_t *out, const char *format, ...)
        G_GNUC_PRINTF(2, 3);
 
    void (*err) (pcmk__output_t *out, const char *format, ...) G_GNUC_PRINTF(2, 3);
 
    void (*output_xml) (pcmk__output_t *out, const char *name, const char *buf);
 
    void (*begin_list) (pcmk__output_t *out, const char *singular_noun,
                        const char *plural_noun, const char *format, ...)
                        G_GNUC_PRINTF(4, 5);
 
    void (*list_item) (pcmk__output_t *out, const char *name, const char *format, ...)
                      G_GNUC_PRINTF(3, 4);
 
    void (*increment_list) (pcmk__output_t *out);
 
    void (*end_list) (pcmk__output_t *out);
 
    bool (*is_quiet) (pcmk__output_t *out);
 
    void (*spacer) (pcmk__output_t *out);
 
    void (*progress) (pcmk__output_t *out, bool end);
 
    void (*prompt) (const char *prompt, bool echo, char **dest);
};
 
int
pcmk__call_message(pcmk__output_t *out, const char *message_id, ...);
 
void pcmk__output_free(pcmk__output_t *out);
 
int pcmk__output_new(pcmk__output_t **out, const char *fmt_name,
                     const char *filename, char **argv);
 
int
pcmk__register_format(GOptionGroup *group, const char *name,
                      pcmk__output_factory_t create,
                      const GOptionEntry *options);
 
void
pcmk__register_formats(GOptionGroup *group,
                       const pcmk__supported_format_t *table);
 
void
pcmk__unregister_formats(void);
 
void
pcmk__register_message(pcmk__output_t *out, const char *message_id,
                       pcmk__message_fn_t fn);
 
void
pcmk__register_messages(pcmk__output_t *out,
                        const pcmk__message_entry_t *table);
 
/* Functions that are useful for implementing custom message formatters */
 
void pcmk__output_text_set_fancy(pcmk__output_t *out, bool enabled);
 
void
pcmk__indented_printf(pcmk__output_t *out, const char *format, ...) G_GNUC_PRINTF(2, 3);
 
void
pcmk__indented_vprintf(pcmk__output_t *out, const char *format, va_list args) G_GNUC_PRINTF(2, 0);
 
 
void
pcmk__formatted_printf(pcmk__output_t *out, const char *format, ...) G_GNUC_PRINTF(2, 3);
 
void
pcmk__formatted_vprintf(pcmk__output_t *out, const char *format, va_list args) G_GNUC_PRINTF(2, 0);
 
void
pcmk__text_prompt(const char *prompt, bool echo, char **dest);
 
uint8_t
pcmk__output_get_log_level(const pcmk__output_t *out);
 
void
pcmk__output_set_log_level(pcmk__output_t *out, uint8_t log_level);
 
void pcmk__output_set_log_filter(pcmk__output_t *out, const char *file,
                                 const char *function, uint32_t line,
                                 uint32_t tags);
 
 
xmlNodePtr
pcmk__output_xml_create_parent(pcmk__output_t *out, const char *name, ...)
G_GNUC_NULL_TERMINATED;
 
void
pcmk__output_xml_add_node_copy(pcmk__output_t *out, xmlNodePtr node);
 
xmlNodePtr
pcmk__output_create_xml_node(pcmk__output_t *out, const char *name, ...)
G_GNUC_NULL_TERMINATED;
 
xmlNodePtr
pcmk__output_create_xml_text_node(pcmk__output_t *out, const char *name, const char *content);
 
void
pcmk__output_xml_push_parent(pcmk__output_t *out, xmlNodePtr parent);
 
void
pcmk__output_xml_pop_parent(pcmk__output_t *out);
 
xmlNodePtr
pcmk__output_xml_peek_parent(pcmk__output_t *out);
 
xmlNodePtr
pcmk__output_create_html_node(pcmk__output_t *out, const char *element_name, const char *id,
                              const char *class_name, const char *text);
 
xmlNode *pcmk__html_create(xmlNode *parent, const char *name, const char *id,
                           const char *class);
 
void
pcmk__html_add_header(const char *name, ...)
G_GNUC_NULL_TERMINATED;
 
void pcmk__output_and_clear_error(GError **error, pcmk__output_t *out);
 
int pcmk__xml_output_new(pcmk__output_t **out, xmlNodePtr *xml);
void pcmk__xml_output_finish(pcmk__output_t *out, crm_exit_t exit_status, xmlNodePtr *xml);
int pcmk__log_output_new(pcmk__output_t **out);
int pcmk__text_output_new(pcmk__output_t **out, const char *filename);
 
// @COMPAT This can be removed when `crm_mon -X` and daemon metadata are removed
bool pcmk__output_get_legacy_xml(pcmk__output_t *out);
 
// @COMPAT This can be removed when `crm_mon -X` and daemon metadata are removed
void pcmk__output_set_legacy_xml(pcmk__output_t *out);
 
void pcmk__output_enable_list_element(pcmk__output_t *out);
 
static inline int
pcmk__output_select_rc(int old_rc, int new_rc)
{
    switch (new_rc) {
        case pcmk_rc_no_output:
            return old_rc;
        case pcmk_rc_ok:
            switch (old_rc) {
                case pcmk_rc_no_output:
                    return new_rc;
                default:
                    return old_rc;
            }
        default:
            return new_rc;
    }
}
 
#if defined(PCMK__UNIT_TESTING)
/* If we are building libcrmcommon_test.a, add this accessor function so we can
 * inspect the internal formatters hash table.
 */
GHashTable *pcmk__output_formatters(void);
#endif
 
#define PCMK__OUTPUT_SPACER_IF(out_obj, cond)   \
    if (cond) {                                 \
        out->spacer(out);                       \
    }
 
#define PCMK__OUTPUT_LIST_HEADER(out_obj, cond, retcode, title...)  \
    if (retcode == pcmk_rc_no_output) {                             \
        PCMK__OUTPUT_SPACER_IF(out_obj, cond);                      \
        retcode = pcmk_rc_ok;                                       \
        out_obj->begin_list(out_obj, NULL, NULL, title);            \
    }
 
#define PCMK__OUTPUT_LIST_FOOTER(out_obj, retcode)  \
    if (retcode == pcmk_rc_ok) {                    \
        out_obj->end_list(out_obj);                 \
    }
 
#ifdef __cplusplus
}
#endif
 
#endif