YumaWorks

Check the Online Manual for Up to Date Information

Set Hook

A Set Hook is a function that is invoked within the transaction when an object is modified. When the netconfd-pro server has been configured to provide a candidate configuration, Set Hook code will be invoked when changes are done to the <candidate> configuration. If --target=running then the Set Hook will be invoked at the start of the transaction on the running datastore. This callback will be invoked before EDIT1 or EDIT2 callbacks for the same object.

NOTE: Set Hook callbacks will not be invoke during explicit validate command and in case of the following netconfd-pro parameters are set to TRUE:  --sil-validate-candidate or --sil-skip-load.

Set Hook can be invoked during the Load; However, it is not allowed to add new edits. So, callbacks are treated as Transaction Hook style callbacks and can perform only validation tasks and cannot edit datastore. Any add_edit() during Load will be ignored, it is not an error just skip the call and go back with NO_ERR status.

The following function template definition is used for Set Hook callback functions:

/* Typedef of the agt_hook_cb callback as follows */
typedef status_t 
    (*agt_hook_cb_t) (ses_cb_t *scb,
                      rpc_msg_t *msg,
                      agt_cfg_transaction_t *txcb,
                      op_editop_t editop,
                      val_value_t  *newval,
                      val_value_t  *curval);

Set Hook callback function is hooked into the server with the agt_cb_hook_register function, described below. The agt_cb_hook_register function is used to declare the callback as a specific style callback. The registration is done during the Initialization Phase 1 before the startup configuration is loaded into the running configuration database and before running configurations are loaded.

extern status_t
    agt_cb_hook_register (const xmlChar *defpath,
                          agt_hook_fmt_t format,
                          agt_hook_type_t type,
                          agt_cb_hook_t cbfn);

The format parameter is important when you want to specify how Set Hook callbacks will be invoked. There are two options available for this parameter:

• AGT_HOOKFMT_NODE: Set the type of the callback to this value if You want to make sure that the callback will be invoked only when you modify the node that registered the callback but not any of its children.

• AGT_HOOKFMT_SUBTREE: If the format is set to this value, the callback will be invoked if you edit children as well.

The type parameter is important when you want to set the type of callback. There are two options available for this parameter, either Set Hook or Transaction Hook callback:

• AGT_HOOK_TYPE_SETHOOK: Set the type of the callback to this value if You want to register Set Hook callback.

• AGT_HOOK_TYPE_TRANSACTION: Set the type of the callback to this value if You want to register Transaction Hook callback.

The following example code illustrates how hook-based callbacks can be cleaned up.The callbacks cleanup is getting done during Clean-up Phase.

extern void
    agt_cb_hook_unregister (const xmlChar *defpath);

NOTE: It is possible to register different callbacks for the same object, for instance, there can be Set Hook and Transaction Hook callbacks registered for the same object, as well as there can be EDIT or GET2 callbacks for the same object. However, in order to cleanup callbacks, unregister them, you need to run different cleanup functions. The EDIT and GET2 callbacks have their own unregister functions and hook-based callbacks have their own unregister function. 

For examples, refer to the following articles:

How do I use a Set Hook to add a new node?

How do I use a Set Hook to delete a node? 

How do I use a Set Hook to update a new node during CREATE?

How do I use a Set Hook to modify an edit in progress?

Hooks callback interaction with EDIT2 callbacks (target=candidate)

In case there are multiple Set-Hook callbacks registered and the callbacks add several extra edits to the  transaction with help of add_edit() API the server will have the following interaction with added edits and normal edits that are coming  from PDU. Assume we register Set-Hook callback, Set-Order-Hook,  Transaction-Hook and EDIT2 callback for the same list object, for example "ietf-interface" module and "/if:interfaces/if:interface" list object. So any time the "interface" list is getting edited the server invokes Set-Hook callback and adds up an extra "interface" in addition to the regular edit. The following callback invocation order is expected in this case:

Edit on candidate datastore:

1. Transaction Start
2. Set Order Hook for "/if:interface[name=vlan1]"
3. Set Hook for "/if:interface[name=vlan1]" to add "/if:interface[name=vlan2]"
4. Set Order Hook for "/if:interface[name=vlan2]"
5. SIL Callback (Validate Phase) for "/if:interface[name=vlan1]"
6. SIL Callback (Validate Phase) for "/if:interface[name=vlan2]"
7. Transaction Complete

Edit on running datastore (after <commit>):

1. Transaction Start
2. SIL Callback (Validate Phase) for "/if:interface[name=vlan1]"
3. SIL Callback (Validate Phase) for "/if:interface[name=vlan2]"
4. Validate Complete
5. SIL Callback (Apply Phase) for "/if:interface[name=vlan1]"
6. SIL Callback (Apply Phase) for "/if:interface[name=vlan2]"
7. Apply Complete
8. SIL Callback (Commit Phase) for "/if:interface[name=vlan1]"
9. SIL Callback (Commit Phase) for "/if:interface[name=vlan2]"
10. Transaction Hook for "/if:interface[name=vlan1]"
11. Transaction Hook for "/if:interface[name=vlan2]"
12. Commit/Rollback Complete
13. Transaction Complete

Hooks callback interaction with EDIT2 callbacks (target=running)

Assume  the same scenario but the default target in this case is set to  running. The callbacks invocation order is expected to be:

1. Transaction Start
2. Set Order Hook for "/if:interface[name=vlan1]"
3. Set Hook for "/if:interface[name=vlan1]" to add "/if:interface[name=vlan2]"
4. Set Order Hook for "/if:interface[name=vlan2]"
5. SIL Callback (Validate Phase) for "/if:interface[name=vlan1]"
6. SIL Callback (Validate Phase) for "/if:interface[name=vlan2]"
7. SIL Callback (Apply Phase) for "/if:interface[name=vlan1]"
8. SIL Callback (Apply Phase) for "/if:interface[name=vlan2]"
9. SIL Callback (Commit Phase) for "/if:interface[name=vlan1]"
10. SIL Callback (Commit Phase) for "/if:interface[name=vlan2]"
11. Transaction Hook for "/if:interface[name=vlan1]"
12. Transaction Hook for "/if:interface[name=vlan2]"
13. Transaction Complete