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__CRM_COMMON_OUTPUT_INTERNAL__H
#define PCMK__CRM_COMMON_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[];

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, NULL }
#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_name);

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 // PCMK__CRM_COMMON_OUTPUT_INTERNAL__H