lib/northbound.h

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