root/include/crm/cib/internal.h

/* */

INCLUDED FROM

DEFINITIONS

1. cib__client_triggers_refresh

   1 /*
   2  * Copyright 2004-2024 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__CRM_CIB_INTERNAL__H
  11 #define PCMK__CRM_CIB_INTERNAL__H
  12 
  13 #include <crm/cib.h>
  14 #include <crm/common/ipc_internal.h>
  15 #include <crm/common/output_internal.h>
  16 #include <crm/common/servers_internal.h>
  17 #include <crm/common/strings_internal.h>
  18 
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22 
  23 // Request types for CIB manager IPC/CPG
  24 #define PCMK__CIB_REQUEST_SECONDARY     "cib_slave"
  25 #define PCMK__CIB_REQUEST_PRIMARY       "cib_master"
  26 #define PCMK__CIB_REQUEST_SYNC_TO_ALL   "cib_sync"
  27 #define PCMK__CIB_REQUEST_SYNC_TO_ONE   "cib_sync_one"
  28 #define PCMK__CIB_REQUEST_IS_PRIMARY    "cib_ismaster"
  29 #define PCMK__CIB_REQUEST_BUMP          "cib_bump"
  30 #define PCMK__CIB_REQUEST_QUERY         "cib_query"
  31 #define PCMK__CIB_REQUEST_CREATE        "cib_create"
  32 #define PCMK__CIB_REQUEST_MODIFY        "cib_modify"
  33 #define PCMK__CIB_REQUEST_DELETE        "cib_delete"
  34 #define PCMK__CIB_REQUEST_ERASE         "cib_erase"
  35 #define PCMK__CIB_REQUEST_REPLACE       "cib_replace"
  36 #define PCMK__CIB_REQUEST_APPLY_PATCH   "cib_apply_diff"
  37 #define PCMK__CIB_REQUEST_UPGRADE       "cib_upgrade"
  38 #define PCMK__CIB_REQUEST_ABS_DELETE    "cib_delete_alt"
  39 #define PCMK__CIB_REQUEST_NOOP          "noop"
  40 #define PCMK__CIB_REQUEST_SHUTDOWN      "cib_shutdown_req"
  41 #define PCMK__CIB_REQUEST_COMMIT_TRANSACT   "cib_commit_transact"
  42 #define PCMK__CIB_REQUEST_SCHEMAS       "cib_schemas"
  43 
  44 /*!
  45  * \internal
  46  * \enum cib__op_attr
  47  * \brief Flags for CIB operation attributes
  48  */
  49 enum cib__op_attr {
  50     cib__op_attr_none           = 0,        //!< No special attributes
  51     cib__op_attr_modifies       = (1 << 1), //!< Modifies CIB
  52     cib__op_attr_privileged     = (1 << 2), //!< Requires privileges
  53     cib__op_attr_local          = (1 << 3), //!< Must only be processed locally
  54     cib__op_attr_replaces       = (1 << 4), //!< Replaces CIB
  55     cib__op_attr_writes_through = (1 << 5), //!< Writes to disk on success
  56     cib__op_attr_transaction    = (1 << 6), //!< Supported in a transaction
  57 };
  58 
  59 /*!
  60  * \internal
  61  * \enum cib__op_type
  62  * \brief Types of CIB operations
  63  */
  64 enum cib__op_type {
  65     cib__op_abs_delete,
  66     cib__op_apply_patch,
  67     cib__op_bump,
  68     cib__op_commit_transact,
  69     cib__op_create,
  70     cib__op_delete,
  71     cib__op_erase,
  72     cib__op_is_primary,
  73     cib__op_modify,
  74     cib__op_noop,
  75     cib__op_ping,
  76     cib__op_primary,
  77     cib__op_query,
  78     cib__op_replace,
  79     cib__op_secondary,
  80     cib__op_shutdown,
  81     cib__op_sync_all,
  82     cib__op_sync_one,
  83     cib__op_upgrade,
  84     cib__op_schemas,
  85 };
  86 
  87 gboolean cib_diff_version_details(xmlNode * diff, int *admin_epoch, int *epoch, int *updates,
  88                                   int *_admin_epoch, int *_epoch, int *_updates);
  89 
  90 gboolean cib_read_config(GHashTable * options, xmlNode * current_cib);
  91 
  92 typedef int (*cib__op_fn_t)(const char *, int, const char *, xmlNode *,
  93                             xmlNode *, xmlNode *, xmlNode **, xmlNode **);
  94 
  95 typedef struct cib__operation_s {
  96     const char *name;
  97     enum cib__op_type type;
  98     uint32_t flags; //!< Group of <tt>enum cib__op_attr</tt> flags
  99 } cib__operation_t;
 100 
 101 typedef struct cib_notify_client_s {
 102     const char *event;
 103     const char *obj_id;         /* implement one day */
 104     const char *obj_type;       /* implement one day */
 105     void (*callback) (const char *event, xmlNode * msg);
 106 
 107 } cib_notify_client_t;
 108 
 109 typedef struct cib_callback_client_s {
 110     void (*callback) (xmlNode *, int, int, xmlNode *, void *);
 111     const char *id;
 112     void *user_data;
 113     gboolean only_success;
 114     struct timer_rec_s *timer;
 115     void (*free_func)(void *);
 116 } cib_callback_client_t;
 117 
 118 struct timer_rec_s {
 119     int call_id;
 120     int timeout;
 121     guint ref;
 122     cib_t *cib;
 123 };
 124 
 125 #define cib__set_call_options(cib_call_opts, call_for, flags_to_set) do {   \
 126         cib_call_opts = pcmk__set_flags_as(__func__, __LINE__,              \
 127             LOG_TRACE, "CIB call", (call_for), (cib_call_opts),             \
 128             (flags_to_set), #flags_to_set); \
 129     } while (0)
 130 
 131 #define cib__clear_call_options(cib_call_opts, call_for, flags_to_clear) do {  \
 132         cib_call_opts = pcmk__clear_flags_as(__func__, __LINE__,               \
 133             LOG_TRACE, "CIB call", (call_for), (cib_call_opts),                \
 134             (flags_to_clear), #flags_to_clear);                                \
 135     } while (0)
 136 
 137 cib_t *cib_new_variant(void);
 138 
 139 /*!
 140  * \internal
 141  * \brief Check whether a given CIB client's update should trigger a refresh
 142  *
 143  * Here, "refresh" means that Pacemaker daemons write out their current state.
 144  *
 145  * If a Pacemaker daemon or one of certain Pacemaker CLI tools modifies the CIB,
 146  * we can assume that the CIB hasn't diverged from the true cluster state. A
 147  * "safe" CLI tool requests that all relevant daemons update their state before
 148  * the tool requests any CIB modifications directly.
 149  *
 150  * In contrast, other "unsafe" tools (for example, \c cibadmin and external
 151  * tools) may request arbitrary CIB changes.
 152  *
 153  * A Pacemaker daemon can write out its current state to the CIB when it's
 154  * notified of an update from an unsafe client, to ensure the CIB still contains
 155  * the daemon's correct state.
 156  *
 157  * \param[in] name  CIB client name
 158  *
 159  * \return \c true if the CIB client should trigger a refresh, or \c false
 160  *         otherwise
 161  */
 162 static inline bool
 163 cib__client_triggers_refresh(const char *name)
     /*  */
 164 {
 165     return (pcmk__parse_server(name) == pcmk_ipc_unknown)
 166            && !pcmk__str_any_of(name,
 167                                 "attrd_updater",
 168                                 "crm_attribute",
 169                                 "crm_node",
 170                                 "crm_resource",
 171                                 "crm_ticket",
 172                                 NULL);
 173 }
 174 
 175 int cib__get_notify_patchset(const xmlNode *msg, const xmlNode **patchset);
 176 
 177 int cib_perform_op(cib_t *cib, const char *op, uint32_t call_options,
 178                    cib__op_fn_t fn, bool is_query, const char *section,
 179                    xmlNode *req, xmlNode *input, bool manage_counters,
 180                    bool *config_changed, xmlNode **current_cib,
 181                    xmlNode **result_cib, xmlNode **diff, xmlNode **output);
 182 
 183 int cib__create_op(cib_t *cib, const char *op, const char *host,
 184                    const char *section, xmlNode *data, int call_options,
 185                    const char *user_name, const char *client_name,
 186                    xmlNode **op_msg);
 187 
 188 int cib__extend_transaction(cib_t *cib, xmlNode *request);
 189 
 190 void cib_native_callback(cib_t * cib, xmlNode * msg, int call_id, int rc);
 191 void cib_native_notify(gpointer data, gpointer user_data);
 192 
 193 int cib__get_operation(const char *op, const cib__operation_t **operation);
 194 
 195 int cib_process_query(const char *op, int options, const char *section, xmlNode * req,
 196                       xmlNode * input, xmlNode * existing_cib, xmlNode ** result_cib,
 197                       xmlNode ** answer);
 198 
 199 int cib_process_erase(const char *op, int options, const char *section, xmlNode * req,
 200                       xmlNode * input, xmlNode * existing_cib, xmlNode ** result_cib,
 201                       xmlNode ** answer);
 202 
 203 int cib_process_bump(const char *op, int options, const char *section, xmlNode * req,
 204                      xmlNode * input, xmlNode * existing_cib, xmlNode ** result_cib,
 205                      xmlNode ** answer);
 206 
 207 int cib_process_replace(const char *op, int options, const char *section, xmlNode * req,
 208                         xmlNode * input, xmlNode * existing_cib, xmlNode ** result_cib,
 209                         xmlNode ** answer);
 210 
 211 int cib_process_create(const char *op, int options, const char *section, xmlNode * req,
 212                        xmlNode * input, xmlNode * existing_cib, xmlNode ** result_cib,
 213                        xmlNode ** answer);
 214 
 215 int cib_process_modify(const char *op, int options, const char *section, xmlNode * req,
 216                        xmlNode * input, xmlNode * existing_cib, xmlNode ** result_cib,
 217                        xmlNode ** answer);
 218 
 219 int cib_process_delete(const char *op, int options, const char *section, xmlNode * req,
 220                        xmlNode * input, xmlNode * existing_cib, xmlNode ** result_cib,
 221                        xmlNode ** answer);
 222 
 223 int cib_process_diff(const char *op, int options, const char *section, xmlNode * req,
 224                      xmlNode * input, xmlNode * existing_cib, xmlNode ** result_cib,
 225                      xmlNode ** answer);
 226 
 227 int cib_process_upgrade(const char *op, int options, const char *section, xmlNode * req,
 228                         xmlNode * input, xmlNode * existing_cib, xmlNode ** result_cib,
 229                         xmlNode ** answer);
 230 
 231 /*!
 232  * \internal
 233  * \brief Query or modify a CIB
 234  *
 235  * \param[in]     op            PCMK__CIB_REQUEST_* operation to be performed
 236  * \param[in]     options       Flag set of \c cib_call_options
 237  * \param[in]     section       XPath to query or modify
 238  * \param[in]     req           unused
 239  * \param[in]     input         Portion of CIB to modify (used with
 240  *                              PCMK__CIB_REQUEST_CREATE,
 241  *                              PCMK__CIB_REQUEST_MODIFY, and
 242  *                              PCMK__CIB_REQUEST_REPLACE)
 243  * \param[in,out] existing_cib  Input CIB (used with PCMK__CIB_REQUEST_QUERY)
 244  * \param[in,out] result_cib    CIB copy to make changes in (used with
 245  *                              PCMK__CIB_REQUEST_CREATE,
 246  *                              PCMK__CIB_REQUEST_MODIFY,
 247  *                              PCMK__CIB_REQUEST_DELETE, and
 248  *                              PCMK__CIB_REQUEST_REPLACE)
 249  * \param[out]    answer        Query result (used with PCMK__CIB_REQUEST_QUERY)
 250  *
 251  * \return Legacy Pacemaker return code
 252  */
 253 int cib_process_xpath(const char *op, int options, const char *section,
 254                       const xmlNode *req, xmlNode *input, xmlNode *existing_cib,
 255                       xmlNode **result_cib, xmlNode ** answer);
 256 
 257 int cib_internal_op(cib_t * cib, const char *op, const char *host,
 258                     const char *section, xmlNode * data,
 259                     xmlNode ** output_data, int call_options, const char *user_name);
 260 
 261 
 262 int cib_file_read_and_verify(const char *filename, const char *sigfile,
 263                              xmlNode **root);
 264 int cib_file_write_with_digest(xmlNode *cib_root, const char *cib_dirname,
 265                                const char *cib_filename);
 266 
 267 void cib__set_output(cib_t *cib, pcmk__output_t *out);
 268 
 269 cib_callback_client_t* cib__lookup_id (int call_id);
 270 
 271 /*!
 272  * \internal
 273  * \brief Connect to, query, and optionally disconnect from the CIB
 274  *
 275  * Open a read-write connection to the CIB manager if an already connected
 276  * client is not passed in. Then query the CIB and store the resulting XML.
 277  * Finally, disconnect if the CIB connection isn't being returned to the caller.
 278  *
 279  * \param[in,out] out         Output object (may be \p NULL)
 280  * \param[in,out] cib         If not \p NULL, where to store CIB connection
 281  * \param[out]    cib_object  Where to store query result
 282  *
 283  * \return Standard Pacemaker return code
 284  *
 285  * \note If \p cib is not \p NULL, the caller is responsible for freeing \p *cib
 286  *       using \p cib_delete().
 287  * \note If \p *cib points to an existing \p cib_t object, this function will
 288  *       reuse it instead of creating a new one. If the existing client is
 289  *       already connected, the connection will be reused, even if it's
 290  *       read-only.
 291  */
 292 int cib__signon_query(pcmk__output_t *out, cib_t **cib, xmlNode **cib_object);
 293 
 294 int cib__signon_attempts(cib_t *cib, enum cib_conn_type type, int attempts);
 295 
 296 int cib__clean_up_connection(cib_t **cib);
 297 
 298 int cib__update_node_attr(pcmk__output_t *out, cib_t *cib, int call_options,
 299                           const char *section, const char *node_uuid, const char *set_type,
 300                           const char *set_name, const char *attr_id, const char *attr_name,
 301                           const char *attr_value, const char *user_name,
 302                           const char *node_type);
 303 
 304 int cib__get_node_attrs(pcmk__output_t *out, cib_t *cib, const char *section,
 305                         const char *node_uuid, const char *set_type, const char *set_name,
 306                         const char *attr_id, const char *attr_name, const char *user_name,
 307                         xmlNode **result);
 308 
 309 int cib__delete_node_attr(pcmk__output_t *out, cib_t *cib, int options,
 310                           const char *section, const char *node_uuid, const char *set_type,
 311                           const char *set_name, const char *attr_id, const char *attr_name,
 312                           const char *attr_value, const char *user_name);
 313 
 314 #ifdef __cplusplus
 315 }
 316 #endif
 317 
 318 #endif // PCMK__CRM_CIB_INTERNAL__H

/* */