AVAILABLE SINCE 20.10-0 RELEASE
For more information on what is Set Hook callback and more detailed definition refer to How do I use Set Hook callback?
This article describes how to use Set Hook within SIL-SA code and what are the differences between regular Set Hook usage within SIL code and SIL-SA code.
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.
In the SIL-SA there is no any Transaction control block TXCB; however, the callbacks still need to have sufficient substitution for all the crucial flags from Transaction control block. As a result the SIL-SA callback template is different.
The following function template definition is used for Set Hook callback for SIL-SA functions:
/* Typedef of the agt_cb_sa_hook_t callback */
typedef status_t
(*agt_cb_sa_hook_t) (ses_cb_t *scb,
rpc_msg_t *msg,
op_editop_t editop,
val_value_t *newval,
val_value_t *curval,
const xmlChar *transaction_id,
boolean isvalidate,
boolean isload,
boolean isrunning);| scb | session control block making the request |
| msg | incoming rpc_msg_t in progress |
| editop | edit operation enumeration for the node being edited |
| newval | value holding the proposed changes to apply to the current config, depending on the editop value. |
| curval | current values from the <running> or <candidate> configuration, if any. Could be NULL for create and other operations. |
| transaction_id | transaction ID of the transaction control block in progress |
| isvalidate | TRUE if this Transaction is for <validate> operation |
| isload | TRUE if this Transaction is for a Load operation |
| isrunning | TRUE if this Transaction is for the the running datastore |
Set Hook SIL-SA callback function is hooked into the server with the agt_cb_sa_hook_register function, described below. The agt_cb_sa_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_sa_hook_register (const xmlChar *defpath,
agt_hook_fmt_t format,
agt_hook_type_t type,
agt_cb_sa_hook_t cbfn)| defpath | absolute path expression string indicating which node the callback function is for. |
| format | different hook formats dictates specific hook functionality |
| type | different hook types dictates hook invocation point |
| cbfn | address of SIL-SA callback function to use |
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_sa_hook_unregister (const xmlChar *defpath)The following diagram illustrates the message sequence between the server and the subsystem when the Set Hook callback is invoked.
Important differences SIL vs SIL-SA
The following table illustrates most important difference between SIL and SIL-SA version of the Set Hook callback:
Difference | SIL | SIL-SA |
| Type Definition | agt_cb_hook_t | agt_cb_sa_hook_t |
| Registration Function | agt_cb_hook_register() | agt_cb_sa_hook_register() |
| Clean Up Function | agt_cb_hook_unregister() | agt_cb_sa_hook_unregister() |
| Add Edit API | agt_val_add_edit() | sil_sa_add_edit() |
| Get Data API | agt_val_get_data() | sil_sa_get_data() |
| Transaction Control Block | Available | NOT available |
For examples, refer to the following articles:
How do I use SIL-SA version of Set Hook to add a new node?
Also, refer to the following SIL examples, just make sure to change the APIs described in the above
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?