The Session Hook callback function is a user callback that is invoked when a session starts and ends.
This callback is invoked before any data structures and components have been cleaned up and their data destroyed. It can be used to perform session end or start tasks that are not related to a specific YANG module.
The following function template definition is used for Session Hook callback functions:
/* Typedef of the agt_cb_session_hook_t callback
*
* The Session Hook callback is invoked when a session starts
* and ends.
* Use ses.h macros like SES_MY_USERNAME(scb) to get
* data like client username.
* Max Callbacks: No limit (except available heap memory)
*
* INPUTS:
* ses_event == session event type
* scb == session control block for the session event
*
* OUTPUTS:
* none
*
* RETURNS:
* none
*/
typedef void
(*agt_cb_session_hook_t) (ncx_ses_event_t ses_event,
const ses_cb_t *scb);Where session event pointer can have the following values:
- NCX_SES_EVENT_START: means the session is getting started
- NCX_SES_EVENT_END: means the session is getting ended
The Session Hook callback function is hooked into the server with the agt_cb_session_hook_register function, described below. The registration can be done during the Initialization Phase, before or after the running configuration has been loaded from the startup file.
/********************************************************************
* FUNCTION agt_cb_session_hook_register
*
* Register a Session Hook callback.
*
* Max Callbacks: No limit (except available heap memory)
*
* INPUT:
* cbfn == address of callback function to use
*
* RETURN:
* the status of the operation.
*
********************************************************************/
extern status_t
agt_cb_session_hook_register (agt_cb_session_hook_t cbfn);The following example code illustrates how the callbacks can be cleaned up. The callbacks clean up is getting done during module Cleanup Phase.
/********************************************************************
* FUNCTION agt_cb_session_hook_unregister
*
* Unregister a Session Hook callback.
* This function unregisters a Session Hook callback.
*
* INPUT:
* cbfn == address of callback function to use
*
* RETURN:
* none
*
******************************************************************/
extern void
agt_cb_session_hook_unregister (agt_cb_session_hook_t cbfn);Session Hook Callback Example
Let us go through simple examples that will illustrate how to utilize the Session Hook callbacks for the specific purposes. First we need a YANG module. Consider the following simplified, but functional, example. You can download the YANG module used in this example from attachments and run make_sil_dir_pro to auto-generate stub SIL code for this module.
Note: The Session Hook callback is not part of the auto-generated code and you will have to add a registration, clean up and callback function.
SIL code Generation command that was used in this example. Please refer to the attached SIL code.
> make_sil_dir_pro session-hook --sil-get2 --sil-edit2
Refer to the following YANG module. It can be found in the attachments in this article:
module session-hook {
namespace "http://netconfcentral.org/ns/ses-hook";
prefix "seshk";
revision "2020-07-09" {
description "Initial revision.";
}
typedef state {
type enumeration {
enum disabled;
enum enabled;
enum non-def-enum;
}
}
typedef admin-state {
type state;
}
container interface-cont {
leaf admin-status-dyn {
type admin-state;
}
}
}In the following example we are going to register Session Hook callbacks. In the callback function we are going to check if a session that is getting started is a RESTCONF session and the input encoding is XML and then will generate specific logging information for the current session. Refer to the attached YANG module and its SIL code for a complete example.
As an example callback function refer to the following snippet.
/********************************************************************
* FUNCTION session_hook_callback
*
* The Session Hook callback is invoked when a session starts
* and ends.
*
* INPUTS:
* ses_event == session event type
* scb == session control block for the session event
*
* RETURNS:
* status
********************************************************************/
static void
session_hook_callback (ncx_ses_event_t ses_event,
const ses_cb_t *scb)
{
if (LOGDEBUG) {
log_debug("\n\nEnter Session Hook callback for %s@%s",
SES_MY_USERNAME(scb) ? SES_MY_USERNAME(scb) : NCX_EL_NOBODY,
SES_PEERADDR(scb) ? SES_PEERADDR(scb) : NCX_EL_LOCALHOST);
}
/* Perform specific tasks when the session is ended or started
* and only if the current session protocol is RESTCONF
* and the session has an input that is encoded in XML
*/
ncx_display_mode_t input_mode = SES_IN_ENCODING(scb);
if (input_mode == NCX_DISPLAY_MODE_XML) {
if (SES_PROTOCOL(scb) == NCX_PROTO_RESTCONF) {
if (ses_event == NCX_SES_EVENT_START) {
if (LOGDEBUG) {
log_debug("\n ++++ RESTCONF Session Start ++++");
}
} else if (ses_event == NCX_SES_EVENT_END) {
if (LOGDEBUG) {
log_debug("\n ---- RESTCONF Session END ----");
}
}
}
}
return;
} /* session_hook_callback */The following table summarized the ses_cb_t macros that are defined in ncx/ses.h:
| Macro | Description |
|---|---|
| SES_MY_SID(S) | Access session ID |
| SES_MY_USERNAME(S) | Access session username |
| SES_IN_ENCODING(S) | Access expected encoding of incoming messages |
| SES_OUT_ENCODING(S) | Access expected encoding of outcoming messages |
| SES_TRANSPORT(S) | Access transport type of the session |
| SES_PEERADDR(S) | Access Internet Protocol address string |
| SES_PROTOCOL(S) | Access protocol version of the session |
| SES_IS_CALLHOME(S) | TRUE if callhome session |