![[bottom]](../icons/bottom.png){kind=icon}
![[previous]](../icons/n_left.png){kind=icon}
![[next]](../icons/n_right.png){kind=icon}
![[first]](../icons/n_first.png){kind=icon}
![[last]](../icons/n_last.png){kind=icon}
![[top]](../icons/n_top.png){kind=icon}
![[index]](../icons/index.png){kind=icon}
![[help]](../icons/help.png){kind=icon}
*/
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_CIB_TYPES__H
11 # define PCMK__CRM_CIB_CIB_TYPES__H
12
13 # include <glib.h> // gboolean, GList
14 # include <libxml/tree.h> // xmlNode
15 # include <crm/common/ipc.h>
16 # include <crm/common/xml.h>
17
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21
22 /**
23 * \file
24 * \brief Data types for Cluster Information Base access
25 * \ingroup cib
26 */
27
28 enum cib_variant {
29 cib_undefined = 0,
30 cib_native = 1,
31 cib_file = 2,
32 cib_remote = 3,
33
34 #if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
35 //! \deprecated This value will be removed in a future release
36 cib_database = 4,
37 #endif // !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
38 };
39
40 enum cib_state {
41 // NOTE: sbd (as of at least 1.5.2) uses this value
42 cib_connected_command,
43
44 // NOTE: sbd (as of at least 1.5.2) uses this value
45 cib_connected_query,
46
47 cib_disconnected
48 };
49
50 enum cib_conn_type {
51 cib_command,
52
53 // NOTE: sbd (as of at least 1.5.2) uses this value
54 cib_query,
55
56 cib_no_connection,
57 cib_command_nonblocking,
58 };
59
60 enum cib_call_options {
61 cib_none = 0,
62 cib_verbose = (1 << 0), //!< Prefer stderr to logs
63 cib_xpath = (1 << 1),
64 cib_multiple = (1 << 2),
65 cib_can_create = (1 << 3),
66 cib_discard_reply = (1 << 4),
67 cib_no_children = (1 << 5),
68 cib_xpath_address = (1 << 6),
69
70 //! \deprecated This value will be removed in a future release
71 cib_mixed_update = (1 << 7),
72
73 /* @COMPAT: cib_scope_local is processed only in the legacy function
74 * parse_local_options_v1().
75 *
76 * If (host == NULL):
77 * * In legacy mode, the CIB manager forwards a request to the primary
78 * instance unless cib_scope_local is set or the local node is primary.
79 * * Outside of legacy mode:
80 * * If a request modifies the CIB, the CIB manager forwards it to all
81 * nodes.
82 * * Otherwise, the CIB manager processes the request locally.
83 *
84 * There is no current use case for this implementing this flag in
85 * non-legacy mode.
86 */
87
88 // NOTE: sbd (as of at least 1.5.2) uses this value
89 //! \deprecated This value will be removed in a future release
90 cib_scope_local = (1 << 8),
91
92 cib_dryrun = (1 << 9),
93
94 /*!
95 * \brief Process request when the client commits the active transaction
96 *
97 * Add the request to the client's active transaction instead of processing
98 * it immediately. If the client has no active transaction, or if the
99 * request is not supported in transactions, the call will fail.
100 *
101 * The request is added to the transaction synchronously, and the return
102 * value indicates whether it was added successfully.
103 *
104 * Refer to \p cib_api_operations_t:init_transaction() and
105 * \p cib_api_operations_t:end_transaction() for more details on CIB
106 * transactions.
107 */
108 cib_transaction = (1 << 10),
109
110 /*!
111 * \brief Treat new attribute values as atomic score updates where possible
112 *
113 * This option takes effect when updating XML attributes. For an attribute
114 * named \c "name", if the new value is \c "name++" or \c "name+=X" for some
115 * score \c X, the new value is set as follows:
116 * * If attribute \c "name" is not already set to some value in the element
117 * being updated, the new value is set as a literal string.
118 * * If the new value is \c "name++", then the attribute is set to its
119 * existing value (parsed as a score) plus 1.
120 * * If the new value is \c "name+=X" for some score \c X, then the
121 * attribute is set to its existing value plus \c X, where the existing
122 * value and \c X are parsed and added as scores.
123 *
124 * Scores are integer values capped at \c INFINITY and \c -INFINITY. Refer
125 * to Pacemaker Explained and to the \c char2score() function for more
126 * details on scores, including how they're parsed and added.
127 *
128 * Note: This is implemented only for modify operations.
129 */
130 cib_score_update = (1 << 11),
131
132 // NOTE: sbd (as of at least 1.5.2) uses this value
133 cib_sync_call = (1 << 12),
134
135 cib_no_mtime = (1 << 13),
136
137 #if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
138 //! \deprecated This value will be removed in a future release
139 cib_zero_copy = (1 << 14),
140 #endif // !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
141
142 cib_inhibit_notify = (1 << 16),
143
144 #if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
145 //! \deprecated This value will be removed in a future release
146 cib_quorum_override = (1 << 20),
147 #endif // !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
148
149 //! \deprecated This value will be removed in a future release
150 cib_inhibit_bcast = (1 << 24),
151
152 cib_force_diff = (1 << 28),
153 };
154
155 typedef struct cib_s cib_t;
156
157 typedef struct cib_api_operations_s {
158 // NOTE: sbd (as of at least 1.5.2) uses this
159 int (*signon) (cib_t *cib, const char *name, enum cib_conn_type type);
160
161 //! \deprecated This method will be removed and should not be used
162 int (*signon_raw) (cib_t *cib, const char *name, enum cib_conn_type type,
163 int *event_fd);
164
165 // NOTE: sbd (as of at least 1.5.2) uses this
166 int (*signoff) (cib_t *cib);
167
168 int (*free) (cib_t *cib);
169
170 //! \deprecated This method will be removed and should not be used
171 int (*set_op_callback) (cib_t *cib, void (*callback) (const xmlNode *msg,
172 int callid, int rc,
173 xmlNode *output));
174
175 // NOTE: sbd (as of at least 1.5.2) uses this
176 int (*add_notify_callback) (cib_t *cib, const char *event,
177 void (*callback) (const char *event,
178 xmlNode *msg));
179
180 // NOTE: sbd (as of at least 1.5.2) uses this
181 int (*del_notify_callback) (cib_t *cib, const char *event,
182 void (*callback) (const char *event,
183 xmlNode *msg));
184 // NOTE: sbd (as of at least 1.5.2) uses this
185 int (*set_connection_dnotify) (cib_t *cib,
186 void (*dnotify) (gpointer user_data));
187
188 //! \deprecated This method will be removed and should not be used
189 int (*inputfd) (cib_t *cib);
190
191 // NOTE: sbd (as of at least 1.5.2) uses this
192 //! \deprecated This method will be removed and should not be used
193 int (*noop) (cib_t *cib, int call_options);
194
195 int (*ping) (cib_t *cib, xmlNode **output_data, int call_options);
196
197 // NOTE: sbd (as of at least 1.5.2) uses this
198 int (*query) (cib_t *cib, const char *section, xmlNode **output_data,
199 int call_options);
200
201 int (*query_from) (cib_t *cib, const char *host, const char *section,
202 xmlNode **output_data, int call_options);
203
204 //! \deprecated This method will be removed and should not be used
205 int (*is_master) (cib_t *cib);
206
207 //! \deprecated Use the set_primary() method instead
208 int (*set_master) (cib_t *cib, int call_options);
209
210 //! \deprecated Use the set_secondary() method instead
211 int (*set_slave) (cib_t *cib, int call_options);
212
213 //! \deprecated This method will be removed and should not be used
214 int (*set_slave_all) (cib_t *cib, int call_options);
215
216 int (*sync) (cib_t *cib, const char *section, int call_options);
217 int (*sync_from) (cib_t *cib, const char *host, const char *section,
218 int call_options);
219 int (*upgrade) (cib_t *cib, int call_options);
220 int (*bump_epoch) (cib_t *cib, int call_options);
221
222 /*!
223 * The \c <failed> element in the reply to a failed creation call is
224 * deprecated since 2.1.8.
225 */
226 int (*create) (cib_t *cib, const char *section, xmlNode *data,
227 int call_options);
228 int (*modify) (cib_t *cib, const char *section, xmlNode *data,
229 int call_options);
230
231 //! \deprecated Use the \p modify() method instead
232 int (*update) (cib_t *cib, const char *section, xmlNode *data,
233 int call_options);
234
235 int (*replace) (cib_t *cib, const char *section, xmlNode *data,
236 int call_options);
237 int (*remove) (cib_t *cib, const char *section, xmlNode *data,
238 int call_options);
239 int (*erase) (cib_t *cib, xmlNode **output_data, int call_options);
240
241 //! \deprecated This method does nothing and should not be called
242 int (*delete_absolute) (cib_t *cib, const char *section, xmlNode *data,
243 int call_options);
244
245 //! \deprecated This method is not implemented and should not be used
246 int (*quit) (cib_t *cib, int call_options);
247
248 int (*register_notification) (cib_t *cib, const char *callback,
249 int enabled);
250 gboolean (*register_callback) (cib_t *cib, int call_id, int timeout,
251 gboolean only_success, void *user_data,
252 const char *callback_name,
253 void (*callback) (xmlNode*, int, int,
254 xmlNode*, void *));
255 gboolean (*register_callback_full)(cib_t *cib, int call_id, int timeout,
256 gboolean only_success, void *user_data,
257 const char *callback_name,
258 void (*callback)(xmlNode *, int, int,
259 xmlNode *, void *),
260 void (*free_func)(void *));
261
262 /*!
263 * \brief Set the local CIB manager as the cluster's primary instance
264 *
265 * \param[in,out] cib CIB connection
266 * \param[in] call_options Group of enum cib_call_options flags
267 *
268 * \return Legacy Pacemaker return code (in particular, pcmk_ok on success)
269 */
270 int (*set_primary)(cib_t *cib, int call_options);
271
272 /*!
273 * \brief Set the local CIB manager as a secondary instance
274 *
275 * \param[in,out] cib CIB connection
276 * \param[in] call_options Group of enum cib_call_options flags
277 *
278 * \return Legacy Pacemaker return code (in particular, pcmk_ok on success)
279 */
280 int (*set_secondary)(cib_t *cib, int call_options);
281
282 /*!
283 * \brief Get the given CIB connection's unique client identifier(s)
284 *
285 * These can be used to check whether this client requested the action that
286 * triggered a CIB notification.
287 *
288 * \param[in] cib CIB connection
289 * \param[out] async_id If not \p NULL, where to store asynchronous client
290 * ID
291 * \param[out] sync_id If not \p NULL, where to store synchronous client
292 * ID
293 *
294 * \return Legacy Pacemaker return code
295 *
296 * \note Some variants may have only one client for both asynchronous and
297 * synchronous requests.
298 */
299 int (*client_id)(const cib_t *cib, const char **async_id,
300 const char **sync_id);
301
302 /*!
303 * \brief Initiate an atomic CIB transaction for this client
304 *
305 * If the client has initiated a transaction and a new request's call
306 * options contain \p cib_transaction, the new request is appended to the
307 * transaction for later processing.
308 *
309 * Supported requests are those that meet the following conditions:
310 * * can be processed synchronously (with any changes applied to a working
311 * CIB copy)
312 * * are not queries
313 * * do not involve other nodes
314 * * do not affect the state of pacemaker-based itself
315 *
316 * Currently supported CIB API functions include:
317 * * \p bump_epoch()
318 * * \p create()
319 * * \p erase()
320 * * \p modify()
321 * * \p remove()
322 * * \p replace()
323 * * \p upgrade()
324 *
325 * Because the transaction is atomic, individual requests do not trigger
326 * callbacks or notifications when they are processed, and they do not
327 * receive output XML. The commit request itself can trigger callbacks and
328 * notifications if any are registered.
329 *
330 * An \c init_transaction() call is always synchronous.
331 *
332 * \param[in,out] cib CIB connection
333 *
334 * \return Legacy Pacemaker return code
335 */
336 int (*init_transaction)(cib_t *cib);
337
338 /*!
339 * \brief End and optionally commit this client's CIB transaction
340 *
341 * When a client commits a transaction, all requests in the transaction are
342 * processed in a FIFO manner until either a request fails or all requests
343 * have been processed. Changes are applied to a working copy of the CIB.
344 * If a request fails, the transaction and working CIB copy are discarded,
345 * and an error is returned. If all requests succeed, the working CIB copy
346 * replaces the initial CIB copy.
347 *
348 * Callbacks and notifications can be triggered by the commit request itself
349 * but not by the individual requests in a transaction.
350 *
351 * An \c end_transaction() call with \p commit set to \c false is always
352 * synchronous.
353 *
354 * \param[in,out] cib CIB connection
355 * \param[in] commit If \p true, commit transaction; otherwise,
356 * discard it
357 * \param[in] call_options Group of <tt>enum cib_call_options</tt>
358 * flags
359 *
360 * \return Legacy Pacemaker return code
361 */
362 int (*end_transaction)(cib_t *cib, bool commit, int call_options);
363
364 /*!
365 * \brief Set the user as whom all CIB requests via methods will be executed
366 *
367 * By default, the value of the \c CIB_user environment variable is used if
368 * set. Otherwise, the current effective user is used.
369 *
370 * \param[in,out] cib CIB connection
371 * \param[in] user Name of user whose permissions to use when
372 * processing requests
373 */
374 void (*set_user)(cib_t *cib, const char *user);
375
376 int (*fetch_schemas)(cib_t *cib, xmlNode **output_data, const char *after_ver,
377 int call_options);
378 } cib_api_operations_t;
379
380 struct cib_s {
381 // NOTE: sbd (as of at least 1.5.2) uses this
382 enum cib_state state;
383
384 enum cib_conn_type type;
385 enum cib_variant variant;
386
387 int call_id;
388 int call_timeout;
389 void *variant_opaque;
390 void *delegate_fn;
391
392 GList *notify_list;
393
394 //! \deprecated This method will be removed in a future release
395 void (*op_callback) (const xmlNode *msg, int call_id, int rc,
396 xmlNode *output);
397
398 // NOTE: sbd (as of at least 1.5.2) uses this
399 cib_api_operations_t *cmds;
400
401 xmlNode *transaction;
402
403 char *user;
404 };
405
406 #ifdef __cplusplus
407 }
408 #endif
409
410 #endif // PCMK__CRM_CIB_CIB_TYPES__H
![[top]](../icons/top.png){kind=icon}
![[bottom]](../icons/n_bottom.png){kind=icon}
*/