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