Show Raw Command
The 'show raw' command allows custom show command syntax to be used without a YANG definition. Unlike the external show command (e.g. 'show fan'), there is no YANG 'augment' of the show command input parameters.
There is a 'show raw' callback that is registered.
This is a global callback, not 1 callback per command like 'show fan'
The purpose of the callback is to process the input parameters and display the appropriate output to the session using the 'log' API functions.
Example:
The show command parameters do not match built-in parameters or any top-level YANG data nodes, so the 'show raw' callback is invoked.
> show mgmt-interface
The callback retrieves some interface data and displays it.
Got a USERGET reply
rpc-reply
data
interfaces-state
interface eno1
type ianaift:ethernetCsmacd
oper-status up
phys-address 3c:7c:3f:1d:83:aa
speed 1000000000
statistics
in-octets 1175608815
in-unicast-pkts 994299
in-multicast-pkts 279430
in-discards 0
in-errors 0
out-octets 1992002672
out-unicast-pkts 1471183
out-discards 0
out-errors 0
Show Raw Callback Function
The 'show raw' callback can examine the command line and take 1 of 3 actions:
skip: return
ERR_NCX_SKIPPED
to indicate that no attempt to process the command was doneprocess ok: return
NO_ERR
to indicate that the command line was processed without error.process error: return some other status (e.g.
ERR_NCX_OPERATION_FAILED
to indicate that the command line was processed but there was an error.
The callback function can utilize the USERGET API Functions to retrieve data from the connected NETCONF server before displaying output for the show command.
The first time the callback is invokded for a command line, the 'reply_valset' parameter will be 'NULL'. If the callback starts a 'USERGET' retrieval operation then it will be invoked again when the response is retrieved. In this case the 'reply_valset' parameter will not be NULL.
The callback function is named 'ycli_show_raw_extern_fn_t'.
It is defined in the 'ycli/yangcli_libshow.h' file.
/********************************************************************
* FUNCTION ycli_show_raw_extern_fn
*
* Special show command that does not requiring registering
* the show command keyword and a YANG module.
*
* Only one 'show raw' callback can be registered.
* If found, it will be checked when the show command is detected.
* The raw unparsed line will be passed
* No valset is provided since no YANG is known for this command
*
* INPUTS:
* server_cb == server control block in case needed tfor USERGET
* session_cb == session control block in case needed for USERGET
* line == CLI input in progress; the start of the line will
* be the first string after the 'show' keyword.
* reply_valset == REPLY from USERGET IF THIS IS 2nd - Nth CALL
* cookie == context pointer passed in register time, (may be null)
*
* RETURNS: NO_ERR or error.
* ERR_NCX_SKIPPED if the line is not handled
*********************************************************************/
typedef status_t
(*ycli_show_raw_extern_fn_t) (server_cb_t *server_cb,
session_cb_t *session_cb,
const xmlChar *line,
val_value_t *reply_valset,
void *cookie);
Show Raw API Functions
There are a limited number of internal API functions that are supported for use by a 'show raw' callback.
Show Raw Registration
The callback must be registered.
There is no 'unregiser' function required.
The command stays registered until the program exits.
The function is named 'ycli_show_raw_extern_register_callback'
It is defined in 'ycli/yangcli_libshow.h'
/********************************************************************
* FUNCTION ycli_show_raw_extern_register_callback
*
* Register the show raw external callback for raw show implementation
*
* INPUTS:
* showfn == show function callback
* cookie == context pointer (may be null)
* RETURNS:
* status of the function registration.
*
*********************************************************************/
extern status_t
ycli_show_raw_extern_register_callback (ycli_show_raw_extern_fn_t showfn,
void *cookie);
Example:
See the 'yp_show_init' function in 'example-show.cpp'
#ifdef SHOW_RAW
/* Create a cookie context if any or NULL */
void *cookie_show_raw = NULL;
ycli_show_raw_extern_register_callback(show_raw,
cookie_show_raw);
#endif // SHOW_RAW
USERGET API Functions
There is an API function available to send a sget operation to the current session.
This is optional to use
Multiple retrieval cycles can be done
The output is not displayed to the user. Instead the 'show raw' callback is invoked with the reply data and is expected to display the data.
The function is named 'ycli_show_raw_start_userget'
It is defined in 'ycli/yangcli_libshow.h'
/********************************************************************
* FUNCTION ycli_show_raw_start_userget
*
* Special USERGET retrieval command to get data from the server
*
* Only one USERGET can be invoked at a time.
* A repeat USERGET is allowed after this request succeeds
*
* INPUTS:
* server_cb == server control block to use
* session_cb == session control block in to use
* filter_path == filter path string for sget or sget-config command
* config_only == TRUE for sget-config; FALSE for sget
*
* RETURNS:
* NO_ERR or error.
*********************************************************************/
status_t
ycli_show_raw_start_userget (server_cb_t *server_cb,
session_cb_t *session_cb,
const xmlChar *filter_path,
boolean config_only);
Example:
status_t res =
ycli_show_raw_start_userget(server_cb,
session_cb,
xpath_expr,
config_only);
Show Raw Callback Example
The example function does the following tasks:
checks for the 'show mgmt-interface' command
returns
ERR_NCX_SKIPPED
if anything else
starts a USERGET retrieval operation for the XPath expression
/interfaces-state/interface[name='eno1']
returns
NO_ERR
but 'USERGET' mode was started so not done
displays the result when invoked a second time
returns
NO_ERR
and this time command is done
/********************************************************************
* FUNCTION ycli_show_raw_extern_fn
*
* Special show command that does not requiring registering
* the show command keyword and a YANG module.
*
* Only one 'show raw' callback can be registered.
* If found, it will be checked when the show command is detected.
* The raw unparsed line will be passed
* No valset is provided since no YANG is known for this command
*
* INPUTS:
* server_cb == server control block in case needed tfor USERGET
* session_cb == session control block in case needed for USERGET
* line == CLI input in progress
* reply_valset == REPLY from USERGET IF THIS IS 2nd - Nth CALL
* cookie == context pointer passed in register time, (may be null)
*
* RETURNS: NO_ERR or error.
* ERR_NCX_SKIPPED if the line is not handled
*********************************************************************/
static status_t
show_raw (server_cb_t *server_cb,
session_cb_t *session_cb,
const xmlChar *line,
val_value_t *reply_valset,
void *cookie)
{
if (LOGDEBUG) {
log_debug("\nEnter show_raw");
log_debug_append("\n line: '%s'\n", line);
}
if (reply_valset) {
/* this is a 2nd - Nth callback with the response for
* a USERGET retrieval. Must finish the display
* or start another USERGET retrieval
*/
log_info("\nGot a USERGET reply");
val_dump_value_ex(reply_valset, // val
0, // startindent
NCX_DISPLAY_MODE_CLI, // display_mode
DINFO); // lvl
log_info_append("\n");
return NO_ERR;
}
/* check if the command line needs to be processed
* this is completely up to the implementation
* The line has already been rejected for a built-in show
* command with YANG schema in the rpc show
*/
if (xml_strcmp(line, (const xmlChar *)"mgmt-interface")) {
return ERR_NCX_SKIPPED;
}
/* check the session_cb: if NULL there is no session
* in this example, only handle server retrieval
*/
if (session_cb == nullptr) {
log_error("\nError: Cannot retrieve session data: Not connected");
return ERR_NCX_SKIPPED;
}
/* once this callback decides to handle a show command
* it is expected to generate all the output or start
* a session retrieval operation to get data from the server
*/
/* Callback is expected to create the XPath expression somehow */
(void)cookie;
const xmlChar *xpath_expr =
(const xmlChar *)"/interfaces-state/interface[name='eno1']";
boolean config_only = false;
status_t res =
ycli_show_raw_start_userget(server_cb,
session_cb,
xpath_expr,
config_only);
return res;
} /* show_raw */