]>
Commit | Line | Data |
---|---|---|
1c2facd1 RW |
1 | /* |
2 | * Copyright (C) 2018 NetDEF, Inc. | |
3 | * Renato Westphal | |
4 | * | |
5 | * This program is free software; you can redistribute it and/or modify it | |
6 | * under the terms of the GNU General Public License as published by the Free | |
7 | * Software Foundation; either version 2 of the License, or (at your option) | |
8 | * any later version. | |
9 | * | |
10 | * This program is distributed in the hope that it will be useful, but WITHOUT | |
11 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
12 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for | |
13 | * more details. | |
14 | * | |
15 | * You should have received a copy of the GNU General Public License along | |
16 | * with this program; see the file COPYING; if not, write to the Free Software | |
17 | * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA | |
18 | */ | |
19 | ||
20 | #ifndef _FRR_NORTHBOUND_H_ | |
21 | #define _FRR_NORTHBOUND_H_ | |
22 | ||
fbdc1c0a | 23 | #include "thread.h" |
1c2facd1 | 24 | #include "hook.h" |
1c2facd1 RW |
25 | #include "linklist.h" |
26 | #include "openbsd-tree.h" | |
1a4bc045 RW |
27 | #include "yang.h" |
28 | #include "yang_translator.h" | |
1c2facd1 RW |
29 | |
30 | /* Forward declaration(s). */ | |
31 | struct vty; | |
32 | ||
33 | /* Northbound events. */ | |
34 | enum nb_event { | |
35 | /* | |
36 | * The configuration callback is supposed to verify that the changes are | |
37 | * valid and can be applied. | |
38 | */ | |
39 | NB_EV_VALIDATE, | |
40 | ||
41 | /* | |
42 | * The configuration callback is supposed to prepare all resources | |
43 | * required to apply the changes. | |
44 | */ | |
45 | NB_EV_PREPARE, | |
46 | ||
47 | /* | |
48 | * Transaction has failed, the configuration callback needs to release | |
49 | * all resources previously allocated. | |
50 | */ | |
51 | NB_EV_ABORT, | |
52 | ||
53 | /* | |
54 | * The configuration changes need to be applied. The changes can't be | |
55 | * rejected at this point (errors are logged and ignored). | |
56 | */ | |
57 | NB_EV_APPLY, | |
58 | }; | |
59 | ||
60 | /* | |
61 | * Northbound operations. | |
62 | * | |
63 | * Refer to the documentation comments of nb_callbacks for more details. | |
64 | */ | |
65 | enum nb_operation { | |
66 | NB_OP_CREATE, | |
67 | NB_OP_MODIFY, | |
68 | NB_OP_DELETE, | |
69 | NB_OP_MOVE, | |
70 | NB_OP_APPLY_FINISH, | |
71 | NB_OP_GET_ELEM, | |
72 | NB_OP_GET_NEXT, | |
73 | NB_OP_GET_KEYS, | |
74 | NB_OP_LOOKUP_ENTRY, | |
75 | NB_OP_RPC, | |
76 | }; | |
77 | ||
78 | union nb_resource { | |
79 | int fd; | |
80 | void *ptr; | |
81 | }; | |
82 | ||
83 | struct nb_callbacks { | |
84 | /* | |
85 | * Configuration callback. | |
86 | * | |
87 | * A presence container, list entry, leaf-list entry or leaf of type | |
88 | * empty has been created. | |
89 | * | |
90 | * For presence-containers and list entries, the callback is supposed to | |
91 | * initialize the default values of its children (if any) from the YANG | |
92 | * models. | |
93 | * | |
94 | * event | |
95 | * The transaction phase. Refer to the documentation comments of | |
96 | * nb_event for more details. | |
97 | * | |
98 | * dnode | |
99 | * libyang data node that is being created. | |
100 | * | |
101 | * resource | |
102 | * Pointer to store resource(s) allocated during the NB_EV_PREPARE | |
103 | * phase. The same pointer can be used during the NB_EV_ABORT and | |
104 | * NB_EV_APPLY phases to either release or make use of the allocated | |
105 | * resource(s). It's set to NULL when the event is NB_EV_VALIDATE. | |
106 | * | |
107 | * Returns: | |
108 | * - NB_OK on success. | |
109 | * - NB_ERR_VALIDATION when a validation error occurred. | |
110 | * - NB_ERR_RESOURCE when the callback failed to allocate a resource. | |
111 | * - NB_ERR_INCONSISTENCY when an inconsistency was detected. | |
112 | * - NB_ERR for other errors. | |
113 | */ | |
114 | int (*create)(enum nb_event event, const struct lyd_node *dnode, | |
115 | union nb_resource *resource); | |
116 | ||
117 | /* | |
118 | * Configuration callback. | |
119 | * | |
120 | * The value of a leaf has been modified. | |
121 | * | |
122 | * List keys don't need to implement this callback. When a list key is | |
123 | * modified, the northbound treats this as if the list was deleted and a | |
124 | * new one created with the updated key value. | |
125 | * | |
126 | * event | |
127 | * The transaction phase. Refer to the documentation comments of | |
128 | * nb_event for more details. | |
129 | * | |
130 | * dnode | |
131 | * libyang data node that is being modified | |
132 | * | |
133 | * resource | |
134 | * Pointer to store resource(s) allocated during the NB_EV_PREPARE | |
135 | * phase. The same pointer can be used during the NB_EV_ABORT and | |
136 | * NB_EV_APPLY phases to either release or make use of the allocated | |
137 | * resource(s). It's set to NULL when the event is NB_EV_VALIDATE. | |
138 | * | |
139 | * Returns: | |
140 | * - NB_OK on success. | |
141 | * - NB_ERR_VALIDATION when a validation error occurred. | |
142 | * - NB_ERR_RESOURCE when the callback failed to allocate a resource. | |
143 | * - NB_ERR_INCONSISTENCY when an inconsistency was detected. | |
144 | * - NB_ERR for other errors. | |
145 | */ | |
146 | int (*modify)(enum nb_event event, const struct lyd_node *dnode, | |
147 | union nb_resource *resource); | |
148 | ||
149 | /* | |
150 | * Configuration callback. | |
151 | * | |
152 | * A presence container, list entry, leaf-list entry or optional leaf | |
153 | * has been deleted. | |
154 | * | |
155 | * The callback is supposed to delete the entire configuration object, | |
156 | * including its children when they exist. | |
157 | * | |
158 | * event | |
159 | * The transaction phase. Refer to the documentation comments of | |
160 | * nb_event for more details. | |
161 | * | |
162 | * dnode | |
163 | * libyang data node that is being deleted. | |
164 | * | |
165 | * Returns: | |
166 | * - NB_OK on success. | |
167 | * - NB_ERR_VALIDATION when a validation error occurred. | |
168 | * - NB_ERR_INCONSISTENCY when an inconsistency was detected. | |
169 | * - NB_ERR for other errors. | |
170 | */ | |
171 | int (*delete)(enum nb_event event, const struct lyd_node *dnode); | |
172 | ||
173 | /* | |
174 | * Configuration callback. | |
175 | * | |
176 | * A list entry or leaf-list entry has been moved. Only applicable when | |
177 | * the "ordered-by user" statement is present. | |
178 | * | |
179 | * event | |
180 | * The transaction phase. Refer to the documentation comments of | |
181 | * nb_event for more details. | |
182 | * | |
183 | * dnode | |
184 | * libyang data node that is being moved. | |
185 | * | |
186 | * Returns: | |
187 | * - NB_OK on success. | |
188 | * - NB_ERR_VALIDATION when a validation error occurred. | |
189 | * - NB_ERR_INCONSISTENCY when an inconsistency was detected. | |
190 | * - NB_ERR for other errors. | |
191 | */ | |
192 | int (*move)(enum nb_event event, const struct lyd_node *dnode); | |
193 | ||
194 | /* | |
195 | * Optional configuration callback. | |
196 | * | |
197 | * The 'apply_finish' callbacks are called after all other callbacks | |
198 | * during the apply phase (NB_EV_APPLY). These callbacks are called only | |
199 | * under one of the following two cases: | |
200 | * - The data node has been created or modified (but not deleted); | |
201 | * - Any change was made within the descendants of the data node (e.g. a | |
202 | * child leaf was modified, created or deleted). | |
203 | * | |
204 | * In the second case above, the 'apply_finish' callback is called only | |
205 | * once even if multiple changes occurred within the descendants of the | |
206 | * data node. | |
207 | * | |
208 | * dnode | |
209 | * libyang data node associated with the 'apply_finish' callback. | |
210 | */ | |
211 | void (*apply_finish)(const struct lyd_node *dnode); | |
212 | ||
213 | /* | |
214 | * Operational data callback. | |
215 | * | |
1a4bc045 RW |
216 | * The callback function should return the value of a specific leaf, |
217 | * leaf-list entry or inform if a typeless value (presence containers or | |
218 | * leafs of type empty) exists or not. | |
1c2facd1 RW |
219 | * |
220 | * xpath | |
221 | * YANG data path of the data we want to get. | |
222 | * | |
223 | * list_entry | |
1a4bc045 | 224 | * Pointer to list entry (might be NULL). |
1c2facd1 RW |
225 | * |
226 | * Returns: | |
227 | * Pointer to newly created yang_data structure, or NULL to indicate | |
228 | * the absence of data. | |
229 | */ | |
230 | struct yang_data *(*get_elem)(const char *xpath, | |
231 | const void *list_entry); | |
232 | ||
233 | /* | |
1a4bc045 | 234 | * Operational data callback for YANG lists and leaf-lists. |
1c2facd1 | 235 | * |
1a4bc045 RW |
236 | * The callback function should return the next entry in the list or |
237 | * leaf-list. The 'list_entry' parameter will be NULL on the first | |
238 | * invocation. | |
1c2facd1 | 239 | * |
1a4bc045 RW |
240 | * parent_list_entry |
241 | * Pointer to parent list entry. | |
1c2facd1 RW |
242 | * |
243 | * list_entry | |
1a4bc045 | 244 | * Pointer to (leaf-)list entry. |
1c2facd1 RW |
245 | * |
246 | * Returns: | |
1a4bc045 RW |
247 | * Pointer to the next entry in the (leaf-)list, or NULL to signal |
248 | * that the end of the (leaf-)list was reached. | |
1c2facd1 | 249 | */ |
1a4bc045 RW |
250 | const void *(*get_next)(const void *parent_list_entry, |
251 | const void *list_entry); | |
1c2facd1 RW |
252 | |
253 | /* | |
254 | * Operational data callback for YANG lists. | |
255 | * | |
256 | * The callback function should fill the 'keys' parameter based on the | |
99fb518f RW |
257 | * given list_entry. Keyless lists don't need to implement this |
258 | * callback. | |
1c2facd1 RW |
259 | * |
260 | * list_entry | |
261 | * Pointer to list entry. | |
262 | * | |
263 | * keys | |
264 | * Structure to be filled based on the attributes of the provided | |
265 | * list entry. | |
266 | * | |
267 | * Returns: | |
268 | * NB_OK on success, NB_ERR otherwise. | |
269 | */ | |
270 | int (*get_keys)(const void *list_entry, struct yang_list_keys *keys); | |
271 | ||
272 | /* | |
273 | * Operational data callback for YANG lists. | |
274 | * | |
275 | * The callback function should return a list entry based on the list | |
99fb518f RW |
276 | * keys given as a parameter. Keyless lists don't need to implement this |
277 | * callback. | |
1c2facd1 | 278 | * |
1a4bc045 RW |
279 | * parent_list_entry |
280 | * Pointer to parent list entry. | |
281 | * | |
1c2facd1 RW |
282 | * keys |
283 | * Structure containing the keys of the list entry. | |
284 | * | |
285 | * Returns: | |
286 | * Pointer to the list entry if found, or NULL if not found. | |
287 | */ | |
1a4bc045 RW |
288 | const void *(*lookup_entry)(const void *parent_list_entry, |
289 | const struct yang_list_keys *keys); | |
1c2facd1 RW |
290 | |
291 | /* | |
292 | * RPC and action callback. | |
293 | * | |
294 | * Both 'input' and 'output' are lists of 'yang_data' structures. The | |
295 | * callback should fetch all the input parameters from the 'input' list, | |
296 | * and add output parameters to the 'output' list if necessary. | |
297 | * | |
298 | * xpath | |
299 | * XPath of the YANG RPC or action. | |
300 | * | |
301 | * input | |
302 | * Read-only list of input parameters. | |
303 | * | |
304 | * output | |
305 | * List of output parameters to be populated by the callback. | |
306 | * | |
307 | * Returns: | |
308 | * NB_OK on success, NB_ERR otherwise. | |
309 | */ | |
310 | int (*rpc)(const char *xpath, const struct list *input, | |
311 | struct list *output); | |
312 | ||
313 | /* | |
314 | * Optional callback to show the CLI command associated to the given | |
315 | * YANG data node. | |
316 | * | |
317 | * vty | |
318 | * The vty terminal to dump the configuration to. | |
319 | * | |
320 | * dnode | |
321 | * libyang data node that should be shown in the form of a CLI | |
322 | * command. | |
323 | * | |
324 | * show_defaults | |
325 | * Specify whether to display default configuration values or not. | |
326 | * This parameter can be ignored most of the time since the | |
327 | * northbound doesn't call this callback for default leaves or | |
328 | * non-presence containers that contain only default child nodes. | |
329 | * The exception are commands associated to multiple configuration | |
330 | * nodes, in which case it might be desirable to hide one or more | |
331 | * parts of the command when this parameter is set to false. | |
332 | */ | |
333 | void (*cli_show)(struct vty *vty, struct lyd_node *dnode, | |
334 | bool show_defaults); | |
335 | }; | |
336 | ||
337 | /* | |
338 | * Northbound-specific data that is allocated for each schema node of the native | |
339 | * YANG modules. | |
340 | */ | |
341 | struct nb_node { | |
342 | /* Back pointer to the libyang schema node. */ | |
343 | const struct lys_node *snode; | |
344 | ||
345 | /* Data path of this YANG node. */ | |
346 | char xpath[XPATH_MAXLEN]; | |
347 | ||
348 | /* Priority - lower priorities are processed first. */ | |
349 | uint32_t priority; | |
350 | ||
351 | /* Callbacks implemented for this node. */ | |
352 | struct nb_callbacks cbs; | |
353 | ||
354 | /* | |
355 | * Pointer to the parent node (disconsidering non-presence containers). | |
356 | */ | |
357 | struct nb_node *parent; | |
358 | ||
359 | /* Pointer to the nearest parent list, if any. */ | |
360 | struct nb_node *parent_list; | |
361 | ||
544ca69a RW |
362 | /* Flags. */ |
363 | uint8_t flags; | |
364 | ||
1c2facd1 RW |
365 | #ifdef HAVE_CONFD |
366 | /* ConfD hash value corresponding to this YANG path. */ | |
367 | int confd_hash; | |
368 | #endif | |
369 | }; | |
544ca69a RW |
370 | /* The YANG container or list contains only config data. */ |
371 | #define F_NB_NODE_CONFIG_ONLY 0x01 | |
99fb518f RW |
372 | /* The YANG list doesn't contain key leafs. */ |
373 | #define F_NB_NODE_KEYLESS_LIST 0x02 | |
1c2facd1 RW |
374 | |
375 | struct frr_yang_module_info { | |
376 | /* YANG module name. */ | |
377 | const char *name; | |
378 | ||
379 | /* Northbound callbacks. */ | |
380 | const struct { | |
381 | /* Data path of this YANG node. */ | |
382 | const char *xpath; | |
383 | ||
384 | /* Callbacks implemented for this node. */ | |
385 | struct nb_callbacks cbs; | |
386 | ||
387 | /* Priority - lower priorities are processed first. */ | |
388 | uint32_t priority; | |
389 | } nodes[]; | |
390 | }; | |
391 | ||
392 | /* Northbound error codes. */ | |
393 | enum nb_error { | |
394 | NB_OK = 0, | |
395 | NB_ERR, | |
396 | NB_ERR_NO_CHANGES, | |
397 | NB_ERR_NOT_FOUND, | |
398 | NB_ERR_LOCKED, | |
399 | NB_ERR_VALIDATION, | |
400 | NB_ERR_RESOURCE, | |
401 | NB_ERR_INCONSISTENCY, | |
402 | }; | |
403 | ||
404 | /* Default priority. */ | |
405 | #define NB_DFLT_PRIORITY (UINT32_MAX / 2) | |
406 | ||
407 | /* Default maximum of configuration rollbacks to store. */ | |
408 | #define NB_DLFT_MAX_CONFIG_ROLLBACKS 20 | |
409 | ||
410 | /* Northbound clients. */ | |
411 | enum nb_client { | |
412 | NB_CLIENT_CLI = 0, | |
5bce33b3 | 413 | NB_CLIENT_CONFD, |
a7ca2199 | 414 | NB_CLIENT_SYSREPO, |
1c2facd1 RW |
415 | }; |
416 | ||
417 | /* Northbound configuration. */ | |
418 | struct nb_config { | |
419 | struct lyd_node *dnode; | |
420 | uint32_t version; | |
421 | }; | |
422 | ||
423 | /* Northbound configuration callback. */ | |
424 | struct nb_config_cb { | |
425 | RB_ENTRY(nb_config_cb) entry; | |
426 | enum nb_operation operation; | |
427 | char xpath[XPATH_MAXLEN]; | |
428 | const struct nb_node *nb_node; | |
429 | const struct lyd_node *dnode; | |
430 | }; | |
431 | RB_HEAD(nb_config_cbs, nb_config_cb); | |
432 | RB_PROTOTYPE(nb_config_cbs, nb_config_cb, entry, nb_config_cb_compare); | |
433 | ||
434 | /* Northbound configuration change. */ | |
435 | struct nb_config_change { | |
436 | struct nb_config_cb cb; | |
437 | union nb_resource resource; | |
438 | bool prepare_ok; | |
439 | }; | |
440 | ||
441 | /* Northbound configuration transaction. */ | |
442 | struct nb_transaction { | |
443 | enum nb_client client; | |
444 | char comment[80]; | |
445 | struct nb_config *config; | |
446 | struct nb_config_cbs changes; | |
447 | }; | |
448 | ||
1a4bc045 RW |
449 | /* Callback function used by nb_oper_data_iterate(). */ |
450 | typedef int (*nb_oper_data_cb)(const struct lys_node *snode, | |
451 | struct yang_translator *translator, | |
452 | struct yang_data *data, void *arg); | |
453 | ||
454 | /* Iterate over direct child nodes only. */ | |
455 | #define NB_OPER_DATA_ITER_NORECURSE 0x0001 | |
456 | ||
1c2facd1 RW |
457 | DECLARE_HOOK(nb_notification_send, (const char *xpath, struct list *arguments), |
458 | (xpath, arguments)) | |
459 | ||
460 | extern int debug_northbound; | |
461 | extern struct nb_config *running_config; | |
462 | ||
544ca69a RW |
463 | /* |
464 | * Create a northbound node for all YANG schema nodes. | |
465 | */ | |
466 | void nb_nodes_create(void); | |
467 | ||
468 | /* | |
469 | * Delete all northbound nodes from all YANG schema nodes. | |
470 | */ | |
471 | void nb_nodes_delete(void); | |
472 | ||
1c2facd1 RW |
473 | /* |
474 | * Find the northbound node corresponding to a YANG data path. | |
475 | * | |
476 | * xpath | |
477 | * XPath to search for (with or without predicates). | |
478 | * | |
479 | * Returns: | |
480 | * Pointer to northbound node if found, NULL otherwise. | |
481 | */ | |
482 | extern struct nb_node *nb_node_find(const char *xpath); | |
483 | ||
484 | /* | |
485 | * Create a new northbound configuration. | |
486 | * | |
487 | * dnode | |
488 | * Pointer to a libyang data node containing the configuration data. If NULL | |
489 | * is given, an empty configuration will be created. | |
490 | * | |
491 | * Returns: | |
492 | * Pointer to newly created northbound configuration. | |
493 | */ | |
494 | extern struct nb_config *nb_config_new(struct lyd_node *dnode); | |
495 | ||
496 | /* | |
497 | * Delete a northbound configuration. | |
498 | * | |
499 | * config | |
500 | * Pointer to the config that is going to be deleted. | |
501 | */ | |
502 | extern void nb_config_free(struct nb_config *config); | |
503 | ||
504 | /* | |
505 | * Duplicate a northbound configuration. | |
506 | * | |
507 | * config | |
508 | * Northbound configuration to duplicate. | |
509 | * | |
510 | * Returns: | |
511 | * Pointer to duplicated configuration. | |
512 | */ | |
513 | extern struct nb_config *nb_config_dup(const struct nb_config *config); | |
514 | ||
515 | /* | |
516 | * Merge one configuration into another. | |
517 | * | |
518 | * config_dst | |
519 | * Configuration to merge to. | |
520 | * | |
521 | * config_src | |
522 | * Configuration to merge config_dst with. | |
523 | * | |
524 | * preserve_source | |
525 | * Specify whether config_src should be deleted or not after the merge | |
526 | * operation. | |
527 | * | |
528 | * Returns: | |
529 | * NB_OK on success, NB_ERR otherwise. | |
530 | */ | |
531 | extern int nb_config_merge(struct nb_config *config_dst, | |
532 | struct nb_config *config_src, bool preserve_source); | |
533 | ||
534 | /* | |
535 | * Replace one configuration by another. | |
536 | * | |
537 | * config_dst | |
538 | * Configuration to be replaced. | |
539 | * | |
540 | * config_src | |
541 | * Configuration to replace config_dst. | |
542 | * | |
543 | * preserve_source | |
544 | * Specify whether config_src should be deleted or not after the replace | |
545 | * operation. | |
546 | */ | |
547 | extern void nb_config_replace(struct nb_config *config_dst, | |
548 | struct nb_config *config_src, | |
549 | bool preserve_source); | |
550 | ||
551 | /* | |
552 | * Edit a candidate configuration. | |
553 | * | |
554 | * candidate | |
555 | * Candidate configuration to edit. | |
556 | * | |
557 | * nb_node | |
558 | * Northbound node associated to the configuration being edited. | |
559 | * | |
560 | * operation | |
561 | * Operation to apply. | |
562 | * | |
563 | * xpath | |
564 | * XPath of the configuration node being edited. | |
565 | * | |
566 | * previous | |
567 | * Previous value of the configuration node. Should be used only when the | |
568 | * operation is NB_OP_MOVE, otherwise this parameter is ignored. | |
569 | * | |
570 | * data | |
571 | * New value of the configuration node. | |
572 | * | |
573 | * Returns: | |
574 | * - NB_OK on success. | |
575 | * - NB_ERR_NOT_FOUND when the element to be deleted was not found. | |
576 | * - NB_ERR for other errors. | |
577 | */ | |
578 | extern int nb_candidate_edit(struct nb_config *candidate, | |
579 | const struct nb_node *nb_node, | |
580 | enum nb_operation operation, const char *xpath, | |
581 | const struct yang_data *previous, | |
582 | const struct yang_data *data); | |
583 | ||
584 | /* | |
585 | * Check if a candidate configuration is outdated and needs to be updated. | |
586 | * | |
587 | * candidate | |
588 | * Candidate configuration to check. | |
589 | * | |
590 | * Returns: | |
591 | * true if the candidate is outdated, false otherwise. | |
592 | */ | |
593 | extern bool nb_candidate_needs_update(const struct nb_config *candidate); | |
594 | ||
595 | /* | |
596 | * Update a candidate configuration by rebasing the changes on top of the latest | |
597 | * running configuration. Resolve conflicts automatically by giving preference | |
598 | * to the changes done in the candidate configuration. | |
599 | * | |
600 | * candidate | |
601 | * Candidate configuration to update. | |
602 | * | |
603 | * Returns: | |
604 | * NB_OK on success, NB_ERR otherwise. | |
605 | */ | |
606 | extern int nb_candidate_update(struct nb_config *candidate); | |
607 | ||
608 | /* | |
609 | * Validate a candidate configuration. Perform both YANG syntactic/semantic | |
610 | * validation and code-level validation using the northbound callbacks. | |
611 | * | |
612 | * WARNING: the candidate can be modified as part of the validation process | |
613 | * (e.g. add default nodes). | |
614 | * | |
615 | * candidate | |
616 | * Candidate configuration to validate. | |
617 | * | |
618 | * Returns: | |
619 | * NB_OK on success, NB_ERR_VALIDATION otherwise. | |
620 | */ | |
621 | extern int nb_candidate_validate(struct nb_config *candidate); | |
622 | ||
623 | /* | |
624 | * Create a new configuration transaction but do not commit it yet. Only | |
625 | * validate the candidate and prepare all resources required to apply the | |
626 | * configuration changes. | |
627 | * | |
628 | * candidate | |
629 | * Candidate configuration to commit. | |
630 | * | |
631 | * client | |
632 | * Northbound client performing the commit. | |
633 | * | |
634 | * comment | |
635 | * Optional comment describing the commit. | |
636 | * | |
637 | * transaction | |
638 | * Output parameter providing the created transaction when one is created | |
639 | * successfully. In this case, it must be either aborted using | |
640 | * nb_candidate_commit_abort() or committed using | |
641 | * nb_candidate_commit_apply(). | |
642 | * | |
643 | * Returns: | |
644 | * - NB_OK on success. | |
645 | * - NB_ERR_NO_CHANGES when the candidate is identical to the running | |
646 | * configuration. | |
647 | * - NB_ERR_LOCKED when there's already another transaction in progress. | |
648 | * - NB_ERR_VALIDATION when the candidate fails the validation checks. | |
649 | * - NB_ERR_RESOURCE when the system fails to allocate resources to apply | |
650 | * the candidate configuration. | |
651 | * - NB_ERR for other errors. | |
652 | */ | |
653 | extern int nb_candidate_commit_prepare(struct nb_config *candidate, | |
654 | enum nb_client client, | |
655 | const char *comment, | |
656 | struct nb_transaction **transaction); | |
657 | ||
658 | /* | |
659 | * Abort a previously created configuration transaction, releasing all resources | |
660 | * allocated during the preparation phase. | |
661 | * | |
662 | * transaction | |
663 | * Candidate configuration to abort. It's consumed by this function. | |
664 | */ | |
665 | extern void nb_candidate_commit_abort(struct nb_transaction *transaction); | |
666 | ||
667 | /* | |
668 | * Commit a previously created configuration transaction. | |
669 | * | |
670 | * transaction | |
671 | * Configuration transaction to commit. It's consumed by this function. | |
672 | * | |
673 | * save_transaction | |
674 | * Specify whether the transaction should be recorded in the transactions log | |
675 | * or not. | |
676 | * | |
677 | * transaction_id | |
678 | * Optional output parameter providing the ID of the committed transaction. | |
679 | */ | |
680 | extern void nb_candidate_commit_apply(struct nb_transaction *transaction, | |
681 | bool save_transaction, | |
682 | uint32_t *transaction_id); | |
683 | ||
684 | /* | |
685 | * Create a new transaction to commit a candidate configuration. This is a | |
686 | * convenience function that performs the two-phase commit protocol | |
687 | * transparently to the user. The cost is reduced flexibility, since | |
688 | * network-wide and multi-daemon transactions require the network manager to | |
689 | * take into account the results of the preparation phase of multiple managed | |
690 | * entities. | |
691 | * | |
692 | * candidate | |
693 | * Candidate configuration to commit. It's preserved regardless if the commit | |
694 | * operation fails or not. | |
695 | * | |
696 | * client | |
697 | * Northbound client performing the commit. | |
698 | * | |
699 | * save_transaction | |
700 | * Specify whether the transaction should be recorded in the transactions log | |
701 | * or not. | |
702 | * | |
703 | * comment | |
704 | * Optional comment describing the commit. | |
705 | * | |
706 | * transaction_id | |
707 | * Optional output parameter providing the ID of the committed transaction. | |
708 | * | |
709 | * Returns: | |
710 | * - NB_OK on success. | |
711 | * - NB_ERR_NO_CHANGES when the candidate is identical to the running | |
712 | * configuration. | |
713 | * - NB_ERR_LOCKED when there's already another transaction in progress. | |
714 | * - NB_ERR_VALIDATION when the candidate fails the validation checks. | |
715 | * - NB_ERR_RESOURCE when the system fails to allocate resources to apply | |
716 | * the candidate configuration. | |
717 | * - NB_ERR for other errors. | |
718 | */ | |
719 | extern int nb_candidate_commit(struct nb_config *candidate, | |
720 | enum nb_client client, bool save_transaction, | |
721 | const char *comment, uint32_t *transaction_id); | |
722 | ||
1a4bc045 RW |
723 | /* |
724 | * Iterate over operetional data. | |
725 | * | |
726 | * xpath | |
727 | * Data path of the YANG data we want to iterate over. | |
728 | * | |
729 | * translator | |
730 | * YANG module translator (might be NULL). | |
731 | * | |
732 | * flags | |
733 | * NB_OPER_DATA_ITER_ flags to control how the iteration is performed. | |
734 | * | |
735 | * cb | |
736 | * Function to call with each data node. | |
737 | * | |
738 | * arg | |
739 | * Arbitrary argument passed as the fourth parameter in each call to 'cb'. | |
740 | * | |
741 | * Returns: | |
742 | * NB_OK on success, NB_ERR otherwise. | |
743 | */ | |
744 | extern int nb_oper_data_iterate(const char *xpath, | |
745 | struct yang_translator *translator, | |
746 | uint32_t flags, nb_oper_data_cb cb, void *arg); | |
747 | ||
1c2facd1 RW |
748 | /* |
749 | * Validate if the northbound operation is valid for the given node. | |
750 | * | |
751 | * operation | |
752 | * Operation we want to check. | |
753 | * | |
754 | * snode | |
755 | * libyang schema node we want to check. | |
756 | * | |
757 | * Returns: | |
758 | * true if the operation is valid, false otherwise. | |
759 | */ | |
760 | extern bool nb_operation_is_valid(enum nb_operation operation, | |
761 | const struct lys_node *snode); | |
762 | ||
763 | /* | |
764 | * Send a YANG notification. This is a no-op unless the 'nb_notification_send' | |
765 | * hook was registered by a northbound plugin. | |
766 | * | |
767 | * xpath | |
768 | * XPath of the YANG notification. | |
769 | * | |
770 | * arguments | |
771 | * Linked list containing the arguments that should be sent. This list is | |
772 | * deleted after being used. | |
773 | * | |
774 | * Returns: | |
775 | * NB_OK on success, NB_ERR otherwise. | |
776 | */ | |
777 | extern int nb_notification_send(const char *xpath, struct list *arguments); | |
778 | ||
779 | /* | |
780 | * Return a human-readable string representing a northbound event. | |
781 | * | |
782 | * event | |
783 | * Northbound event. | |
784 | * | |
785 | * Returns: | |
786 | * String representation of the given northbound event. | |
787 | */ | |
788 | extern const char *nb_event_name(enum nb_event event); | |
789 | ||
790 | /* | |
791 | * Return a human-readable string representing a northbound operation. | |
792 | * | |
793 | * operation | |
794 | * Northbound operation. | |
795 | * | |
796 | * Returns: | |
797 | * String representation of the given northbound operation. | |
798 | */ | |
799 | extern const char *nb_operation_name(enum nb_operation operation); | |
800 | ||
801 | /* | |
802 | * Return a human-readable string representing a northbound error. | |
803 | * | |
804 | * error | |
805 | * Northbound error. | |
806 | * | |
807 | * Returns: | |
808 | * String representation of the given northbound error. | |
809 | */ | |
810 | extern const char *nb_err_name(enum nb_error error); | |
811 | ||
812 | /* | |
813 | * Return a human-readable string representing a northbound client. | |
814 | * | |
815 | * client | |
816 | * Northbound client. | |
817 | * | |
818 | * Returns: | |
819 | * String representation of the given northbound client. | |
820 | */ | |
821 | extern const char *nb_client_name(enum nb_client client); | |
822 | ||
823 | /* | |
824 | * Initialize the northbound layer. Should be called only once during the | |
825 | * daemon initialization process. | |
826 | * | |
827 | * modules | |
828 | * Array of YANG modules to parse and initialize. | |
829 | * | |
830 | * nmodules | |
831 | * Size of the modules array. | |
832 | */ | |
fbdc1c0a | 833 | extern void nb_init(struct thread_master *tm, const struct frr_yang_module_info *modules[], |
1c2facd1 RW |
834 | size_t nmodules); |
835 | ||
836 | /* | |
837 | * Finish the northbound layer gracefully. Should be called only when the daemon | |
838 | * is exiting. | |
839 | */ | |
840 | extern void nb_terminate(void); | |
841 | ||
842 | #endif /* _FRR_NORTHBOUND_H_ */ |