yumapro  20.10-10
YumaPro SDK
Remote Procedure Call (RPC)

NETCONF Remote Procedure Call Support. More...

Collaboration diagram for Remote Procedure Call (RPC):

Data Structures

struct  agt_rpc_cbset_t
 the agt_rpc module stores a set of callbacks for each RPC More...
 
struct  agt_rpc_subsys_t
 header for 1 subsystem that has a SIL-SA callback function registered for the RPC method in the agt_rpc_cbset_t struct containing the subsysQ More...
 

Macros

#define AGT_RPC_NUM_CALLBACK_PHASES   3
 this constant is for the number of callback slots allocated in a 'cbset', and only includes the RPC phases that allow callback functions Change from all phases to save memory for 2 pointers that were never used
 

Typedefs

typedef status_t(* agt_rpc_method_t) (ses_cb_t *scb, rpc_msg_t *msg, xml_node_t *methnode)
 Template for RPC server callbacks. More...
 
typedef status_t(* agt_rpc_data_cb_t) (ses_cb_t *scb, rpc_msg_t *msg, uint32 indent)
 Callback template for RPCs that use an inline callback function instead of generating a malloced val_value_t tree. More...
 

Enumerations

Functions

status_t agt_rpc_init (void)
 Initialize the agt_rpc module. More...
 
void agt_rpc_cleanup (void)
 Cleanup the agt_rpc module. More...
 
status_t agt_rpc_register_method (const xmlChar *module, const xmlChar *method_name, agt_rpc_phase_t phase, agt_rpc_method_t method)
 add callback for 1 phase of RPC processing More...
 
void agt_rpc_support_method (const xmlChar *module, const xmlChar *method_name)
 mark an RPC method or action as supported within the server More...
 
void agt_rpc_unsupport_method (const xmlChar *module, const xmlChar *method_name)
 mark an RPC method or action as unsupported within the server More...
 
void agt_rpc_unregister_method (const xmlChar *module, const xmlChar *method_name)
 remove the callback functions for all phases of RPC or Action processing for the specified RPC method or action More...
 
boolean agt_rpc_dispatch (ses_cb_t *scb, xml_node_t *top)
 Dispatch an incoming <rpc> request. More...
 
status_t agt_rpc_load_config_file (const xmlChar *filespec, cfg_template_t *cfg, boolean isload, ses_id_t use_sid, dlq_hdr_t *errQ)
 Dispatch an internal <load-config> request. More...
 
val_value_tagt_rpc_get_config_file (const xmlChar *filespec, cfg_template_t *targetcfg, ses_id_t use_sid, dlq_hdr_t *errorQ, status_t *res)
 Dispatch an internal <load-config> request except skip the INVOKE phase and just remove the 'config' node from the input and return it. More...
 
status_t agt_rpc_replay_config (void)
 Dispatch an internal <replay-config> request used for OP_EDITOP_LOAD to load the running from startup and OP_EDITOP_REPLACE to restore running from backup. More...
 
status_t agt_rpc_fill_rpc_error (const rpc_err_rec_t *err, val_value_t *rpcerror)
 Fill one <rpc-error> like element using the specified namespace and name, which may be different than NETCONF. More...
 
void agt_rpc_send_error_reply (ses_cb_t *scb, status_t retres)
 Operation failed or was never attempted. More...
 
status_t agt_rpc_send_rpc_error (ses_cb_t *scb, xml_msg_hdr_t *msg, const rpc_err_rec_t *err, int32 indent, boolean isfirst, boolean islast)
 Send one <rpc-error> element on the specified session. More...
 
ncx_backptr_tagt_rpc_get_first_backptr (void)
 Get the first backptr to the registered and supported RPC methods on the server. More...
 
ncx_backptr_tagt_rpc_get_next_backptr (ncx_backptr_t *curptr)
 Get the next backptr to the registered and supported RPC methods on the server. More...
 
status_t agt_rpc_check_rpc_invoke (ses_cb_t *scb, rpc_msg_t *msg, obj_template_t *rpcobj)
 Some RPC node parsed, check if it can be invoked or not. More...
 
status_t agt_rpc_parse_rpc_input (ses_cb_t *scb, rpc_msg_t *msg, obj_template_t *rpcobj, xml_node_t *method)
 RPC received, parse parameters against rpcio for 'input'. More...
 
status_t agt_rpc_post_psd_state (ses_cb_t *scb, rpc_msg_t *msg, status_t psdres)
 Fixup parmset after parse phase. More...
 
status_t agt_rpc_invoke_rpc (ses_cb_t *scb, rpc_msg_t *msg, xml_node_t *method_node)
 Invoke an RPC – need to call following functions first: More...
 
status_t agt_rpc_invoke_action (ses_cb_t *scb, rpc_msg_t *msg, xml_node_t *method_node, val_value_t *action_val)
 Invoke an Action – need to call following functions first: More...
 
rpc_msg_tagt_rpc_new_dummy_msg (void)
 Create a dummy rpc_msg_t. More...
 
boolean agt_rpc_callback_set (obj_template_t *obj)
 Check if an RPC callback is registered for this object for SIL-SA usage. More...
 
void agt_rpc_callback_regdone (obj_template_t *obj)
 Set the RPC as register done. More...
 
boolean agt_rpc_callback_is_regdone (obj_template_t *obj)
 Set the RPC as register done. More...
 
status_t agt_rpc_register_subsys_callback (const xmlChar *subsys_id, const xmlChar *modname, const xmlChar *rpcname)
 Register an object specific RPC callback function. More...
 
void agt_rpc_unregister_subsys_callback (const xmlChar *subsys_id, const xmlChar *modname, const xmlChar *rpcname)
 Unregister an object specific RPC callback function. More...
 
void agt_rpc_add_return_val (val_value_t *return_val, rpc_msg_t *msg)
 Add a return value to the msg. More...
 
void agt_rpc_add_return_vals (dlq_hdr_t *return_valQ, rpc_msg_t *msg)
 Add a Q of return values to the msg. More...
 
void agt_rpc_clear_return_data (rpc_msg_t *msg)
 Clear the return data Q. More...
 
status_t agt_rpc_handle_subsys_request (void *sil_sa_cb, ses_cb_t *scb, const xmlChar *modname, const xmlChar *rpcname, val_value_t *rpc_input_val, dlq_hdr_t *return_dataQ)
 Handles incoming <rpc-request> server request messages from a subsystem. More...
 
status_t agt_rpc_handle_subsys_action (void *sil_sa_cb, ses_cb_t *scb, const xmlChar *path, val_value_t *action_input_val, dlq_hdr_t *return_dataQ)
 Handles incoming <action-request> server request messages. More...
 
void agt_rpc_finish_reply (uint32 sid, void *msg)
 Finish the rpc-reply for a remote operation. More...
 
void agt_rpc_reorder_dataQ (rpc_msg_t *msg)
 Reorder the dataQ. More...
 
void agt_rpc_free_subsys (agt_rpc_subsys_t *cb)
 Clean and free a subsys record. More...
 
agt_rpc_subsys_tagt_rpc_new_subsys (const xmlChar *subsys_id)
 Malloc and Initialize a subsys record. More...
 
agt_rpc_subsys_tagt_rpc_find_subsys (dlq_hdr_t *subsysQ, const xmlChar *subsys_id)
 Find a subsystem control block. More...
 
status_t agt_rpc_subrpc_dispatch (ses_cb_t *scb, rpc_msg_t *msg, const xmlChar *rpc_module, const xmlChar *rpc_name, val_value_t *rpc_method, const xmlChar *out_filespec)
 Dispatch an incoming <subrpc-request> request. More...
 
void agt_rpc_unload_module (ncx_module_t *mod)
 Check all the rpc objects from this module and clean any callbacks because the module is being unloaded. More...
 

Detailed Description

NETCONF Remote Procedure Call Support.

Uses the rpc_msg_t struct and other support from the ncxlib.

Typedef Documentation

typedef status_t(* agt_rpc_data_cb_t) (ses_cb_t *scb, rpc_msg_t *msg, uint32 indent)

Callback template for RPCs that use an inline callback function instead of generating a malloced val_value_t tree.

Parameters
scbsession control block
msgRPC request in progress
indentstart indent amount; ignored if the server is configured not to use PDU indentation
Returns
status of the output operation
typedef status_t(* agt_rpc_method_t) (ses_cb_t *scb, rpc_msg_t *msg, xml_node_t *methnode)

Template for RPC server callbacks.

The same template is used for all RPC callback phases The callback is expected to validate if needed and then invoke if needed.

Parameters
scbsession invoking the RPC
msgmessage in progress for this <rpc> request
the msg->rpc_input value node contains the input (if any). It is a container matching the rpc/input node for the YANG rpc
methnodeXML node for the operation, which can be used in error reporting (or ignored)
Returns
return status for the phase
  • An error in validate phase will cancel invoke phase
  • An rpc-error will be added if an error is returned and the msg error Q is empty

Enumeration Type Documentation

There are 3 different callbacks possible in the server processing chain.

Only AGT_RPC_PH_INVOKE is needed to do any work Validate is needed if parameter checking beyond the YANG constraints, such as checking if a needed lock is available

The engine will check for optional callbacks during RPC processing.

Enumerator
AGT_RPC_PH_VALIDATE 

(2) cb after the input is parsed

AGT_RPC_PH_INVOKE 

(3) cb to invoke the requested method

AGT_RPC_PH_POST_REPLY 

(5) cb after the reply is generated

AGT_RPC_PH_PARSE 

(1) NO CB FOR THIS STATE

AGT_RPC_PH_REPLY 

(4) NO CB FOR THIS STATE

Function Documentation

void agt_rpc_add_return_val ( val_value_t return_val,
rpc_msg_t msg 
)

Add a return value to the msg.

Parameters
return_valvalue to add
msgmessage to add value into

Here is the call graph for this function:

void agt_rpc_add_return_vals ( dlq_hdr_t *  return_valQ,
rpc_msg_t msg 
)

Add a Q of return values to the msg.

Parameters
return_valQQ of values to add
msgmessage to add value into

Here is the call graph for this function:

boolean agt_rpc_callback_is_regdone ( obj_template_t obj)

Set the RPC as register done.

Parameters
objobject to set
Returns
TRUE if register done; FALSE otherwise

Here is the call graph for this function:

Here is the caller graph for this function:

void agt_rpc_callback_regdone ( obj_template_t obj)

Set the RPC as register done.

Parameters
objobject to set

Here is the call graph for this function:

Here is the caller graph for this function:

boolean agt_rpc_callback_set ( obj_template_t obj)

Check if an RPC callback is registered for this object for SIL-SA usage.

Parameters
objobject to check
Returns
TRUE if RPC callback registered; FALSE if not

Here is the call graph for this function:

Here is the caller graph for this function:

status_t agt_rpc_check_rpc_invoke ( ses_cb_t scb,
rpc_msg_t msg,
obj_template_t rpcobj 
)

Some RPC node parsed, check if it can be invoked or not.

Parameters
scbsession control block
msgrpc_msg_t in progress
rpcobjRPC object template to use (may be NULL)
Returns
status

Here is the call graph for this function:

Here is the caller graph for this function:

void agt_rpc_cleanup ( void  )

Cleanup the agt_rpc module.

Unregister the top-level NETCONF <rpc> element should call once to cleanup RPC server module

Here is the call graph for this function:

void agt_rpc_clear_return_data ( rpc_msg_t msg)

Clear the return data Q.

Parameters
msgmessage to add value into

Here is the call graph for this function:

boolean agt_rpc_dispatch ( ses_cb_t scb,
xml_node_t top 
)

Dispatch an incoming <rpc> request.

called by top.c: This function is registered with top_register_node for the module 'yuma-netconf', top-node 'rpc'

Parameters
scbsession control block
toptop element descriptor
Returns
TRUE if scb is still valid
FALSE if scb has been deleted during this call

Here is the call graph for this function:

Here is the caller graph for this function:

status_t agt_rpc_fill_rpc_error ( const rpc_err_rec_t err,
val_value_t rpcerror 
)

Fill one <rpc-error> like element using the specified namespace and name, which may be different than NETCONF.

Parameters
errerror record to use to fill 'rpcerror'
rpcerrorNCX_BT_CONTAINER value struct already initialized. The val_add_child function will use this parm as the parent. This namespace will be used for all child nodes
Returns
status

Here is the call graph for this function:

agt_rpc_subsys_t* agt_rpc_find_subsys ( dlq_hdr_t *  subsysQ,
const xmlChar *  subsys_id 
)

Find a subsystem control block.

Parameters
subsysQQ of subsys records to search
subsys_idsubsystem name
Returns
found struct or NULL if not

Here is the call graph for this function:

Here is the caller graph for this function:

void agt_rpc_finish_reply ( uint32  sid,
void *  msg 
)

Finish the rpc-reply for a remote operation.

Used by yp-controller for remote operations

Parameters
sidsession ID to send on
msgrequest message to use for reply

Here is the call graph for this function:

void agt_rpc_free_subsys ( agt_rpc_subsys_t cb)

Clean and free a subsys record.

Parameters
cbsubsystem record

Here is the caller graph for this function:

val_value_t* agt_rpc_get_config_file ( const xmlChar *  filespec,
cfg_template_t targetcfg,
ses_id_t  use_sid,
dlq_hdr_t *  errorQ,
status_t res 
)

Dispatch an internal <load-config> request except skip the INVOKE phase and just remove the 'config' node from the input and return it.

  • Create a dummy session and RPC message
  • Call a special agt_ps_parse function to parse the config file
  • Call the special agt_ncx function to invoke the proper parmset and application 'validate' callback functions, and record all the error/warning messages
  • return the <config> element if no errors
  • otherwise return all the error messages in a Q
Parameters
filespecXML config filespec to get
targetcfgtarget database to validate against
use_sidsession ID to use for the access control
errorQaddress of return queue of rpc_err_rec_t structs
resaddress of return status
Return values
errorQif any errors, the error structs are transferred to the errorQ (if it is non-NULL). In this case, the caller must free these data structures with ncx/rpc_err_clean_errQ
*resreturn status
Returns
malloced and filled in struct representing a <config> element NULL if some error, check errorQ and *res
ncx_backptr_t* agt_rpc_get_first_backptr ( void  )

Get the first backptr to the registered and supported RPC methods on the server.

Returns
pointer to first backptr (node is obj_template_t *)

Here is the call graph for this function:

Here is the caller graph for this function:

ncx_backptr_t* agt_rpc_get_next_backptr ( ncx_backptr_t curptr)

Get the next backptr to the registered and supported RPC methods on the server.

Parameters
curptrcurrent backptr to use
Returns
pointer to next backptr (node is obj_template_t *)

Here is the call graph for this function:

Here is the caller graph for this function:

status_t agt_rpc_handle_subsys_action ( void *  sil_sa_cb,
ses_cb_t scb,
const xmlChar *  path,
val_value_t action_input_val,
dlq_hdr_t *  return_dataQ 
)

Handles incoming <action-request> server request messages.

SIL-SA only! Called from sil-sa/sil_sa.c

Parameters
sil_sa_cbSIl_SA control block cast as void *
scbsession control block of the subsystem
pathinstance-identifier of the action
action_input_val<action> input parameters
return_dataQQ to hold val_value_t return values
Return values
return_dataQreturn values may be added
Returns
status

Here is the call graph for this function:

status_t agt_rpc_handle_subsys_request ( void *  sil_sa_cb,
ses_cb_t scb,
const xmlChar *  modname,
const xmlChar *  rpcname,
val_value_t rpc_input_val,
dlq_hdr_t *  return_dataQ 
)

Handles incoming <rpc-request> server request messages from a subsystem.

SIL-SA only! Called from sil-sa/sil_sa.c

Parameters
sil_sa_cbSIl_SA control block cast as void *
scbsession control block of the subsystem
modnamemodule name of operation
rpcnameoperation name
rpc_input_val<rpc> input parameters
return_dataQQ to hold val_value_t return values
Return values
return_dataQreturn values may be added
Returns
status

Here is the call graph for this function:

status_t agt_rpc_init ( void  )

Initialize the agt_rpc module.

Adds the agt_rpc_dispatch function as the handler for the NETCONF <rpc> top-level element. should call once to init RPC server module

Returns
NO_ERR if all okay, the minimum spare requests will be malloced

Here is the call graph for this function:

Here is the caller graph for this function:

status_t agt_rpc_invoke_action ( ses_cb_t scb,
rpc_msg_t msg,
xml_node_t method_node,
val_value_t action_val 
)

Invoke an Action – need to call following functions first:

  • agt_rpc_check_rpc_invoke
  • agt_rpc_parse_rpc_input (if any input)
  • agt_rpc_post_psd_state (if any input expected)
Parameters
scbsession control block
msgrpc_msg_t in progress
method_nodeXML node of the <rpc> start tag (NULL if none)
action_valvalue tree setup for processing; ancestors to this value contain the keys needed for the action callback
Returns
status

Here is the caller graph for this function:

status_t agt_rpc_invoke_rpc ( ses_cb_t scb,
rpc_msg_t msg,
xml_node_t method_node 
)

Invoke an RPC – need to call following functions first:

  • agt_rpc_check_rpc_invoke
  • agt_rpc_parse_rpc_input (if any input)
  • agt_rpc_post_psd_state (if any input expected)
Parameters
scbsession control block
msgrpc_msg_t in progress
method_nodeXML node of the <rpc> start tag (NULL if none)
Returns
status

Here is the caller graph for this function:

status_t agt_rpc_load_config_file ( const xmlChar *  filespec,
cfg_template_t cfg,
boolean  isload,
ses_id_t  use_sid,
dlq_hdr_t *  errQ 
)

Dispatch an internal <load-config> request.

used for OP_EDITOP_LOAD to load the running from startup and OP_EDITOP_REPLACE to restore running from backup

  • Create a dummy session and RPC message
  • Call a special agt_ps_parse function to parse the config file
  • Call the special agt_ncx function to invoke the proper parmset and application 'validate' callback functions, and record all the error/warning messages
  • Call the special ncx_agt function to invoke all the 'apply' callbacks as needed
  • transfer any error messages to the cfg->load_errQ
Parameters
filespecXML config filespec to load
cfgcfg_template_t to fill in
isloadTRUE for normal load-config
FALSE for restore backup load-config
use_sidsession ID to use for the access control
errQoptional Q of rpc_err_rec_t for error reporting
Returns
status

Here is the call graph for this function:

Here is the caller graph for this function:

rpc_msg_t* agt_rpc_new_dummy_msg ( void  )

Create a dummy rpc_msg_t.

Returns
pointer to malloced msg; need to free with rpc_free_msg

Here is the call graph for this function:

agt_rpc_subsys_t* agt_rpc_new_subsys ( const xmlChar *  subsys_id)

Malloc and Initialize a subsys record.

Parameters
subsys_idsubsystem name
Returns
malloced struct or NULL if error

Here is the caller graph for this function:

status_t agt_rpc_parse_rpc_input ( ses_cb_t scb,
rpc_msg_t msg,
obj_template_t rpcobj,
xml_node_t method 
)

RPC received, parse parameters against rpcio for 'input'.

Parameters
scbsession control block
msgrpc_msg_t in progress
rpcobjRPC object template to use
methodmethod node
Returns
status

Here is the call graph for this function:

Here is the caller graph for this function:

status_t agt_rpc_post_psd_state ( ses_cb_t scb,
rpc_msg_t msg,
status_t  psdres 
)

Fixup parmset after parse phase.

Only call if the RPC has an input PS

Parameters
scbsession control block
msgrpc_msg_t in progress
psdresresult from PSD state
Returns
status
status_t agt_rpc_register_method ( const xmlChar *  module,
const xmlChar *  method_name,
agt_rpc_phase_t  phase,
agt_rpc_method_t  method 
)

add callback for 1 phase of RPC processing

Parameters
modulemodule name of the RPC method
method_nameRPC method name
phaseRPC server callback phase for this callback
methodpointer to callback function
Returns
status of the operation

Here is the call graph for this function:

Here is the caller graph for this function:

status_t agt_rpc_register_subsys_callback ( const xmlChar *  subsys_id,
const xmlChar *  modname,
const xmlChar *  rpcname 
)

Register an object specific RPC callback function.

Parameters
subsys_idsubsystem ID registering the remote callback fn
modnamemodule that defines the target object for the remote callback functions
rpcnamename of the RPC method
Returns
status

Here is the call graph for this function:

void agt_rpc_reorder_dataQ ( rpc_msg_t msg)

Reorder the dataQ.

YPW-1432: data from SIL-SA responses will be in alphabetical order because the parent is an anydata and the SIL-SA code can use generic functions like val_make_string. SIL functions can insert data in the queue in the wrong order Need to sort the rpc_dataQ in YANG order Keep all instances of the same object in the same Q order as before

Parameters
msgmessage to adjust
Return values
msg->rpc_dataQcould be reordered

Here is the call graph for this function:

Here is the caller graph for this function:

status_t agt_rpc_replay_config ( void  )

Dispatch an internal <replay-config> request used for OP_EDITOP_LOAD to load the running from startup and OP_EDITOP_REPLACE to restore running from backup.

  • Create a dummy session and RPC message
  • Create a config transaction control block
  • Call the special agt_ncx function to invoke the proper parmset and application 'validate' callback functions, and record all the error/warning messages
  • Call the special agt_ncx function to invoke all the 'apply' callbacks as needed
  • transfer any error messages to the cfg->load_errQ
  • Dispose the transaction CB
Returns
status

Here is the call graph for this function:

void agt_rpc_send_error_reply ( ses_cb_t scb,
status_t  retres 
)

Operation failed or was never attempted.

Return an <rpc-reply> with an <rpc-error>

Parameters
scbsession control block
retreserror number for termination reason

Here is the call graph for this function:

Here is the caller graph for this function:

status_t agt_rpc_send_rpc_error ( ses_cb_t scb,
xml_msg_hdr_t msg,
const rpc_err_rec_t err,
int32  indent,
boolean  isfirst,
boolean  islast 
)

Send one <rpc-error> element on the specified session.

Parameters
scbsession control block
msgxml_msg_hdr_t in progress
errerror record to send
indentstarting indent count
isfirstTRUE if first error (JSON only)
islastTRUE if last error (JSON only)
Returns
status

Here is the call graph for this function:

Here is the caller graph for this function:

status_t agt_rpc_subrpc_dispatch ( ses_cb_t scb,
rpc_msg_t msg,
const xmlChar *  rpc_module,
const xmlChar *  rpc_name,
val_value_t rpc_method,
const xmlChar *  out_filespec 
)

Dispatch an incoming <subrpc-request> request.

called by agt_db_api.c

Parameters
scbYControl session control block
msgmalloced RPC message to use
rpc_moduleRPC module name or NULL to search for first find
rpc_namename of RPC method to invoke
rpc_methodanyxml val_value_t tree representing the input from the DB-API client; if missing then no input
out_filespecname of output file to use for the the XML file containing the response
Returns
status; can be NO_ERR even if <rpc-error> returned in the output file

Here is the call graph for this function:

void agt_rpc_support_method ( const xmlChar *  module,
const xmlChar *  method_name 
)

mark an RPC method or action as supported within the server

this is needed for operations dependent on capabilities

Parameters
modulemodule name of RPC method (really module name)
method_nameRPC method name

Here is the call graph for this function:

void agt_rpc_unload_module ( ncx_module_t mod)

Check all the rpc objects from this module and clean any callbacks because the module is being unloaded.

Parameters
modmodule being removed. This must be a real module not a submodule

Here is the call graph for this function:

void agt_rpc_unregister_method ( const xmlChar *  module,
const xmlChar *  method_name 
)

remove the callback functions for all phases of RPC or Action processing for the specified RPC method or action

Parameters
modulemodule name of RPC method or action name
method_nameRPC method or action name

Here is the call graph for this function:

Here is the caller graph for this function:

void agt_rpc_unregister_subsys_callback ( const xmlChar *  subsys_id,
const xmlChar *  modname,
const xmlChar *  rpcname 
)

Unregister an object specific RPC callback function.

Parameters
subsys_idsubsystem ID registering the remote callback fn
modnamemodule that defines the target object for the remote callback functions
rpcnamename of the RPC method

Here is the call graph for this function:

void agt_rpc_unsupport_method ( const xmlChar *  module,
const xmlChar *  method_name 
)

mark an RPC method or action as unsupported within the server

this is needed for operations dependent on capabilities

Parameters
modulemodule name of RPC method (really module name)
method_nameRPC method name

Here is the call graph for this function: