2  yp-show External Interface

The yangcli-pro client application supports an external vendor library that is loaded at boot-time by the yangcli_pro application.  This library code is run in the context of the main yangcli-pro process.  It is used to hook vendor-specific functions into the yangcli application,.

The following tasks are supported by the yp-yangcli-show library interface:

The default external show library is located in called libyp_show.so, it  is located in the library path, such as /usr/lib/yumapro/libyp_show.so.

There is an example yp-yangcli-show library in the libshow directory of the YumaPro source tree.  This file in the 'src' directory called example-show.c contains some stub code showing how this library is used.

 

2.1  Mandatory YANG Module Definitions

If vendors add foo-bar to the show commands, then there has to be a YANG module.
They have to make this YANG module and then they have to load the module in their init function. The function ncxmod_load_module() is called to load the new YANG module.

Example template like this:

 

static ncx_module_t *mymod = NULL;

status_t foo_init (void)

{

    status_t res = ncxmod_load_module(mod_name,

                              mod_revision, NULL, &mymod);

   ...   
  

}

 

 

 

For the show command defined in yangcli-pro.yang, vendors can have their own implementation. They have to register their own functions to overwrite the existing show functions in yangcli-pro.  

Use ycli_show_extern_register_callbacks() to register the cli show functions at init time.

 

Example:

 

/********************************************************************

* FUNCTION ycli_show_extern_register_callbacks

* Register the external callbacks for show implementation

* INPUTS:

*    module   == YANG module used for this function

*    showfn_keyword == key word used for this function.

*    showfn ==  show function callback

* RETURNS:

*   status of the function registration.

*

*********************************************************************/

 

ycli_show_extern_register_callbacks (

                        (const xmlChar *) "yangcli-pro",

                        (const xmlChar *) "cache",

                        your_show_cache_function);

 

2.2  Mandatory yp-show API Functions

The following API functions should be defined in all yp-library code:

 

The following example shows example-show.h contents from the libshow/src directory:

 

#ifndef _H_example_show

#define _H_example_show

/*

 * Copyright (c) 2012, YumaWorks, Inc., All Rights Reserved.

 *

 * Unless required by applicable law or agreed to in writing,

 * software distributed under the License is distributed on an

 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY

 * KIND, either express or implied.  See the License for the

 * specific language governing permissions and limitations

 * under the License.    

 */

 

 

#ifndef _H_status

#include "status.h"

#endif

 

 

/* yangcli show init callback

 * This callback is invoked to add yangcli_show_cmd_register().
* It is called at yangcli initialization.

 * INPUTS:none

 * RETURNS:

 *  status; error will abort startup

 */

extern status_t yp_show_init (void);

 

 

/* yangcli show cleanup callback

 * this callback is invoked once during yangcli_cleanup

 */

extern void yp_show_cleanup (void);

 

 

 

 

2.3  Terminal Customization APIs

The yp-show library can contain callbacks for altering the display output that is rendered to the standard output in interactive mode.  This callback can alter the output before it is displayed to the user.

Command output is processed in the following order:

  1. Raw command output using the specified display mode

  2. yp-show terminal hook to alter output text

  3. pipe command filtering

  4. --More-- pagination

 

2.3.1  Register Callbacks

There are 2 callbacks that are registered, using one function from yangcli_term.h:

 

 

/********************************************************************

* FUNCTION ycli_register_term_callback

*

* Register a custom callback to process to server response

* or command output before it is processed by Pipe and More

*

* INPUTS:

*   test_callback == test command callback

*   exec_callback == exec command callback

*********************************************************************/

extern void

    ycli_register_term_callback (term_test_cbfn_t test_callback,

                                 term_cbfn_t exec_callback);

 

 

 

 

2.3.2  Test Function

 

The term_test_cbfn_t callback is invoked to determine if the command output should be processed by the “exec” callback.

 

/* external term handler test callback

* FUNCTION term_api_test_fn

*

* This API tests whether the term_api_fn is needed for this

* command or not;

*

* INPUTS:

*   session_cb == session control block

*   command_name == name of command being invoked or replied

*   reply_output == TRUE if being called from reply handler

*                   FALSE if being called from local command output

* RETURNS:

*    TRUE if command output API hook needed

*    FALSE if ommand output API hook not needed

*********************************************************************/

typedef boolean

    (*term_test_cbfn_t) (void *session_cb,

                         const char *command_name,

                         boolean reply_output);

 

 

2.3.3 Exec Function

The term_cbfn_t callback is invoked to alter the terminal output

 

 

/* external term handler callback

* FUNCTION term_api_fn

*

* This API alters the command or server output so

* yangcli_term can process the More and Pipe commands

*

* INPUTS:

*   session_cb == session control block

*   in_filespec == input filespec for API to process

*   out_filespec == output file for API to write output

* RETURNS:

*    status

*********************************************************************/

 

typedef status_t

    (*term_cbfn_t) (void *session_cb,

                    const char *in_filespec,

                    const char *out_filespec);

 

 

2.3.4 Example

The following code can be found in the libshow/src/example-show.cpp source file.

 

Registration:

 

extern "C" status_t yp_show_init (void)

{

    status_t res = NO_ERR;

 

    log_debug("\nyp_show init\n");

 

    ycli_register_term_callback(term_api_test_fn, term_api_fn);

    return NO_ERR;

}

 

Example test callback:

 

 

/* example terminal output test API

 */

static boolean

    term_api_test_fn (void *session_cb,

                      const char *command_name,

                      boolean reply_output)

{

    /* current session control block if needed */

    session_cb_t *cb = (session_cb_t *)session_cb;

    (void)cb;

 

    if (reply_output == FALSE) {

        return FALSE;

    }

 

    if (!strcmp(command_name, "get") ||

        !strcmp(command_name, "get-config")) {

 

        return TRUE;

    }

 

    return FALSE;

 

}  /* term_api_test_fn */

 

 

Example exec callback:

 

 

/* example terminal output API

 * This API alters the command or server output so

 * yangcli_term can process the More and Pipe commands

 */

static status_t

    term_api_fn (void *session_cb,

                 const char *in_filespec,

                 const char *out_filespec)

{

    /* current session control block if needed */

    session_cb_t *cb = (session_cb_t *)session_cb;

    (void)cb;

 

    /* get file into a buffer

     * this is just one way to process the input;

     * a line-by-line approach could be used to save memory

     */

    xmlChar *in_buff = NULL;

    status_t res = ncx_file_to_buffer(in_filespec, &in_buff);

    if (in_buff == NULL || res != NO_ERR) {

        m__free(in_buff);

        return res;

    }

 

    /* change all the '{' and '}' chars to spaces just

     * as an example of altering the output

     */

    xmlChar *p = in_buff;

    while (*p) {

        if (*p == '{' || *p == '}') {

            *p = ' ';

        }

        p++;

    }

 

    /* write altered buffer out to a file */

    res = ncx_buffer_to_file(out_filespec, in_buff);

 

    m__free(in_buff);

 

    return res;

 

}  /* term_api_fn */