How do I use Set Hook with SIL-SA? : YumaWorks

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