XPath Callback

Note

This callback is available starting in version 22.10T-8.

The XPath Boolean EVAL Callback is used in netconfd-pro to allow SIL code to handle XPath processing instead of using the internal XPath engine to process the XPath evaluation.

A SIL callback function for XPath Boolean Evaluation can be registered and used, similar to an EDIT2 Callback. It is responsible for providing the boolean result for a 'must' or 'when' expression evaluation.

The callback can choose to handle the expression evaluation, or skip it, in which case the server will process the evaluation with the XPath engine.

Often it is much faster for SIL code to maintain internal state or to validate the requirements of a 'must' expression during the SIL callback edit phases. In either case, edit transaction performance can be greatly improved with proper use of this callback function.

Callback Overview

• Register an XPath callback for a specific YANG configuration data node.

• The target object for the callback will be the object for the context node in the 'must' or 'when' XPath evaluation.

• Only 'must' and 'when' evaluation done during datastore validation is affected.

• When any 'must' or 'when' expression needs evaluation for a specific data node instance, the XPath callback will be checked.

• The callback may need to check the XPath expression string if more than one 'must' or 'when' statement is defined for the object.

• The callback returns ERR_NCX_SKIPPED if the expression is not supported by the callback.

• The callback uses the config data tree and possibly internal system state to determine the key leafs for the evaluation.

• The callback uses the config data tree and possibly internal system state to determine the boolean result for the evaluation.

Restrictions

The XPath callback is extremely restricted in the APIs that it can use:

• No XPath evaluation

• No "get_data" APIs

• No alteration of any server data

• No alteration of the transaction in progress

XPath Boolean EVAL Callback

The following function template definition is used for XPath 'must' and 'when' statement evaluation

typedef status_t (*xpath_bool_eval_fn_t)(struct xpath_pcb_t_ *pcb, val_value_t *context, val_value_t *docroot, boolean *result)

XPath Boolean EVAL Replacement Callback.

Callback to implement the XPath semantics for a must or when statement for a datastore object.

Use XPATH_EXPRSTR(pcb) to examine the XPath expression The callback must return ERR_NCX_SKIPPED if the expression evaluation is skipped.

Only supported for used during datastore processing to access configuration nodes (val_value_t tree) Support for GET2 callbacks not supported at this time

Used in the server to optimize datastore validation and delete_dead_nodes when-stmt processing.

Param pcb:

XPath parser control block in use

Param context:

context value node to use. The object of this node contains a pointer to this callback function

Param docroot:

document root value node to use.

Param result:

[out] address of return result if NO_ERR

• *result is TRUE if the must/when result is true

• *result is FALSE if the must/when result is false

Retval NO_ERR:

if test is done and *result is valid

Retval ERR_NCX_SKIPPED:

if test is not done and *result is not valid. Actual XPath eval will be done instead.

Retval other:

error to force the XPath test to fail with an error and datastore operation will fail

Return:

status

Force TRUE XPath Result

There is a utility XPath callback function in agt/agt_util.h that can be used to return 'true' for the XPath evaluation callback.

Note

The 'agt_xpath_force_true' function has the same effect as removing the 'must' or 'when' statement from the YANG module. Use with extreme caution.

This API should only be used if the internal instrumentation code will handle all 'must' and 'when' evaluation for the object, and all such evaluations should always return 'true'.

status_t agt_xpath_force_true(struct xpath_pcb_t_ *pcb, val_value_t *context, val_value_t *docroot, boolean *result)

XPath Boolean EVAL Replacement Callback.

Callback to implement the XPath semantics for a must or when statement for a datastore object.

Use XPATH_EXPRSTR(pcb) to examine the XPath expression The callback must return ERR_NCX_SKIPPED if the expression evaluation is skipped.

Only supported for used during datastore processing to access configuration nodes (val_value_t tree) Support for GET2 callbacks not supported at this time

Used in the server to optimize datastore validation and delete_dead_nodes when-stmt processing.

Parameters:

• pcb -- XPath parser control block in use

• context -- context value node to use. The object of this node contains a pointer to this callback function

• docroot -- document root value node to use.

• result -- [out] address of return result if NO_ERR

  • *result is TRUE if the must/when result is true

  • *result is FALSE if the must/when result is false

Return values:

• NO_ERR -- if test is done and *result is valid

• ERR_NCX_SKIPPED -- if test is not done and *result is not valid. Actual XPath eval will be done instead.

• other -- error to force the XPath test to fail with an error and datastore operation will fail

Returns:

status

XPath Callback Initialization and Cleanup

• An XPath Boolean EVAL callback function is registered with the 'agt_cb_register_xpath_callback' function, described below.

• The registration is done during the Initialization Phase 1 before the startup configuration is loaded into the running configuration database.

• There is no special cleanup callback needed. The 'agt_cb_unregister_callbacks' function will unregister the XPath callback.

• This callback can only be used in SIL code. SIL-SA code is not supported.

status_t agt_cb_register_xpath_callback(const xmlChar *modname, const xmlChar *defpath, const xmlChar *version, xpath_bool_eval_fn_t cbfn)

Register an object specific XPath callback function.

Use the same fn for all must/when stmts for the object Function must return ERR_NCX_SKIPPED if invoked for an unsupported expression.

Parameters:

• modname -- module that defines the target object for these callback functions

• defpath -- Xpath with default (or no) prefixes defining the object that will get the callbacks

• version --

  exact module revision date expected if condition not met then an error will be logged (TBD: force unload of module!)

  NULL means use any version of the module

• cbfn -- address of callback function to use

Returns:

status

The following example shows how the 'agt_xpath_force_true' function can be used for an object:

res = agt_cb_register_xpath_callback(
    y_bbf_l2_fwd_M_bbf_l2_fwd,
    (const xmlChar *)"/bbf-l2-fwd:forwarding/forwarders/forwarder/ports/port/sub-interface",
    y_bbf_l2_fwd_R_bbf_l2_fwd,
    agt_xpath_force_true);
if (res != NO_ERR) {
    return res;
}

XPath Callback Example

In this example the XPath expression is checked to determine if it should be skipped or not. This function can be found in agt/agt_util.h.

/**
 * @brief XPath Boolean EVAL Replacement Callback
 *
 * Callback to implement the XPath semantics for a
 * must or when statement for a datastore object.
 *
 * Use XPATH_EXPRSTR(pcb) to examine the XPath expression
 * The callback must return ERR_NCX_SKIPPED if the expression
 * evaluation is skipped.
 *
 * Only supported for used during datastore processing
 * to access configuration nodes (val_value_t tree)
 * Support for GET2 callbacks not supported at this time
 *
 * Used in the server to optimize datastore validation
 * and delete_dead_nodes when-stmt processing.
 *
 * @param pcb XPath parser control block in use
 * @param context context value node to use.
 *    The object of this node contains a pointer
 *    to this callback function
 * @param docroot document root value node to use.
 * @param[out] result address of return result if NO_ERR
 *  -   *result is TRUE if the must/when result is true
 *  -   *result is FALSE if the must/when result is false
 * @return status
 * @retval NO_ERR if test is done and *result is valid
 * @retval ERR_NCX_SKIPPED if test is not done and
 *      *result is not valid. Actual XPath eval will be
 *      done instead.
 * @retval other error to force the XPath test to fail
 *     with an error and datastore operation will fail
 */
status_t
    agt_xpath_example (struct xpath_pcb_t_ *pcb,
                       val_value_t *context,
                       val_value_t *docroot,
                       boolean *result)
{
    /* get the XPath expression
     * There are many fields in the 'pcb' setup that
     * could also be checked. See documentation
     */
    const xmlChar *expr = XPATH_EXPRSTR(pcb);

    /* the XPath expression that this callback handles */
    const xmlChar *myexpr = (const xmlChar *)"/some/node = 5";

    /* exit now if expression not the one expected */
    if (xml_strcmp(expr, myexpr)) {
        return ERR_NCX_SKIPPED;
    }

    /* If needed the context node and docroot can be
     * traversed using val_child and val.h APIs
     * This is a configuration validation check so
     * only config=true nodes within the 'docroot' tree
     * can be accessed.
     */
    (void)context;
    (void)docroot;

    /* after processing the XPath data tree and/or internal
     * data, the *result must be set and NO_ERR returned
     */
    *result = TRUE;
    return NO_ERR;

} /* agt_xpath_example */

Automatic Code Generation For XPath Callbacks

The ywx:sil-xpath-function extension can be used to have the SIL code generation (e.g., make_sil_dir_pro) handle the XPath callback code generation.

Using An Auto-Generated Callback

If the value default is used then the SIL code will generate:

• a code stub for the XPath callback

• the code to register the XPath callback

• the code to unregister all callbacks for the data node, if no other callbacks registered for the node.

• If the 'split' format for code generation is used then:

  • the 'user' C file will contain the XPath callback function definition

  • the 'user' H file will contain the XPath callback function declaration

  • the 'system' C file will contain the XPath callback registration code in the 'init' function

  • the 'system' C file will contain the XPath callback un-registration code in the 'cleanup' function

• If the 'no-split' format for code generation is used then all functions will be in the C file.

Using An Existing Callback

If the value is not default then it must be a valid C function name. The SIL code will generate:

• the code to register the XPath callback

• the code to unregister all callbacks for the data node, if no other callbacks registered for the node.

• If the function is 'agt_xpath_force_true` then no additional CLI parameters are needed for the code generation.

• If the function is a custom callback, then the --sil-include CLI parameter should be used to allow the generated code to find this function declaration.

• If the 'split' format for code generation is used then:

  • the 'system' C file will contain the XPath callback registration code in the 'init' function

  • the 'system' C file will contain the XPath callback un-registration code in the 'cleanup' function

• If the 'no-split' format for code generation is used then all functions will be in the C file.