YumaWorks

The Startup Hook function is the user/system callback that is invoked before any changes done to the <startup> datastore. It is invoked only if the <startup> capability is enabled.

The Startup Hook callback is invoked before any modifications to the <startup> datastore during <edit-config>, <copy-config> and <delete-config> operation. This callback is not limited hence any number of callbacks can be registered.

If an application needs to perform additional validations, check or any other actions before the <startup> datastore is modified or accessed, this new Startup Hook can be used.

The callback will be called for the following operations:

• Any <edit-config> if the --target=running and <startup> is enabled
• After <commit> operation if --target=candidate and <startup> is enabled
• After <copy-config> if the target of the copying is the <startup> datastore
• <delete-config> if the target of deletion is <startup> datastore and the <startup> datastore is enabled.
  

Below CLI parameters can effect the callback invocation:

• --with-startup=true: <copy-config> and <delete-config> will invoke the callbacks
• --with-startup=false: <copy-config> and <delete-config> will NOT invoke the callbacks.

If the  callback fails then no further actions will be executed and the server would reply with the error. The following function template definition is used for Startup Hook callback functions:

/* Typedef of the startup_hook callback */
typedef status_t
  (*agt_cb_startup_hook_t)(ses_cb_t *scb,
             rpc_msg_t *msg,
             cfg_template_t source_config,
             cfg_template_t target_config);

Callback Template

• Type: User Callback
• Max Callbacks: No limit (except available heap memory)
• File: agt_cb.h
• Template:   agt_cb_startup_hook
  • Inputs:
    • scb == session control block making the request
    • msg == incoming rpc_msg_t in progress
    • source == datastore which is being copied
    • target == datastore which is being edited 
  • Outputs: none
  • Returns: status_t
    • Status of the callback function execution 
• Register: agt_cb_startup_hook_register
• Unregister:  agt_cb_startup_hook_unregister 

Register Callback

The Startup Hook callback is object independent and module independent callback which means there is no need to link it to the specific object as it is done for EDIT or GET callbacks.

The Startup Hook callback function is hooked into the server with the agt_cb_startup_hook_register function, as described below.

The registration is done during the Initialization Phase 1. Initialization function with the registration of the Startup Hook callback type may look as follows:

/******************************************************************** 
* FUNCTION interfaces_init
* 
* initialize the server instrumentation library.
* Initialization Phase 1
* 
*********************************************************************/ 
static status_t 
     interfaces_init (void) 
{ 
   ...

    /* register startup hook callback */ 
    res = 
        agt_cb_startup_hook_register(startup_hook_callback); 
    if (res != NO_ERR) { 
        return res; 
    }

   ...
}

Now whenever the <startup> is being modified the startup_hook_callback function is called and provide access to source datastore and the startup datastore. If there are multiple callbacks registered, all the callbacks are called one after the other. The below code illustrates how the callbacks are unregistered or cleaned up:

/******************************************************************** 
* FUNCTION  interfaces_cleanup
*    cleanup the server instrumentation library 
* 
********************************************************************/ 
void interfaces_cleanup (void)
{
  ...

    /* Unregister startup hook callback */ 
    agt_cb_startup_hook_unregister(startup_hook_callback); 

  ...
}

Callback Example

The following sections illustrates how to utilize the Startup Hook callback in examples. The Startup Hook callback is called just before the <startup> is being modified.  The purpose of this function is to give more flexible and easier development for users. In case there is a need to access the <startup> datastore right before the server copies into it, there is Startup Hook callback. 

The following example code illustrates how the Startup Hook callback may look like:

/********************************************************************
* FUNCTION startup_hook_callback
*
* Startup Hook callback
* The Startup Hook Complete function is the
* user/system callback that is invoked before
* any changes to the <startup> during edit-config, copy-config and
* delete-config operation.
*
* Max Callbacks: No limit (except available heap memory)
*
* INPUT:
* scb == session control block making the request
* msg == incoming rpc_msg_t in progress
* source_config == datastore which is being copied
* target_config == datastore that is being edited
*
* RETURNS:
* status
********************************************************************/
static status_t startup_hook_callback (ses_cb_t *scb,
                                       rpc_msg_t *msg,
                                       cfg_template_t *source_config,
                                       cfg_template_t *target_config)
{

  (void)scb;
  (void)msg;
  (void)source_config;
  (void)target_config;

  log_debug("\n\nEnter startup_hook_callback callback");

  /* notify application that the <startup> is being modified */ 
  log_debug("\n <startup> is being modified");  

  return NO_ERR;

} /* startup_hook_callback */