yumapro  20.10-9
YumaPro SDK
DB-API Functions

DB-API functions are used in the db-api-app and combo-app. More...

Collaboration diagram for DB-API Functions:

Macros

#define DB_API   (const xmlChar *)"db-api"
 YControl service name.
 
#define DB_API_MOD   (const xmlChar *)"yumaworks-db-api"
 DB-API YANG module.
 
#define DB_API_OBJ   (const xmlChar *)"db-api"
 db-api container name
 
#define DB_API_REQ_OK(ST)   (ST >= DB_API_ST_READY)
 Check if DB-API state is ready.
 

Functions

status_t db_api_register_service (void)
 Register the DB-API service with the YControl layer. More...
 
status_t db_api_register_service_ex (boolean with_db_lock)
 Register the DB-API service with the YControl layer. More...
 
boolean db_api_service_ready (void)
 Check if the DB-API service is done initializing, and is now ready to send requests to the server. More...
 
status_t db_api_send_edit (const xmlChar *edit_target, const xmlChar *edit_operation, const xmlChar *edit_xml_value)
 Create a YANG Patch edit request and send it to the DB-API service on the main server. More...
 
status_t db_api_send_edit_ex (const xmlChar *edit_target, const xmlChar *edit_operation, const xmlChar *edit_xml_value, const xmlChar *patch_id_str, boolean system_edit)
 Create a YANG Patch edit request and send it to the DB-API service on the main server. More...
 
status_t db_api_send_edit_full (const xmlChar *edit_target, const xmlChar *edit_operation, const xmlChar *edit_xml_value, const xmlChar *patch_id_str, boolean system_edit, const xmlChar *insert_point, const xmlChar *insert_where)
 Create a YANG Patch edit request and send it to the DB-API service on the main server. More...
 
status_t db_api_send_edit_full2 (const xmlChar *edit_target, const xmlChar *edit_operation, const xmlChar *edit_xml_value, const xmlChar *patch_id_str, boolean system_edit, const xmlChar *insert_point, const xmlChar *insert_where, boolean skip_sil)
 Create a YANG Patch edit request and send it to the DB-API service on the main server. More...
 
status_t db_api_check_edit (void)
 Check on the status of an edit in progress. More...
 
status_t db_api_check_edit_ex (const xmlChar **errstr)
 Check on the status of an edit in progress. More...
 
status_t db_api_send_getconfig (const xmlChar *filespec, boolean withdef)
 Create a <getconfig> request and send it to the main server. More...
 
status_t db_api_send_getfilter (const xmlChar *filespec, boolean withdef, boolean get_config, const xmlChar *xpath_filter)
 Retrieve data from the server with complete parameters. More...
 
status_t db_api_start_patch (const xmlChar *patch_id_str, boolean system_edit, yang_patch_cb_t **retcb)
 Start a YANG Patch request that can have multiple edits. More...
 
status_t db_api_add_edit (yang_patch_cb_t *pcb, const xmlChar *edit_id_str, const xmlChar *edit_target, const xmlChar *edit_operation, const xmlChar *edit_xml_value, const xmlChar *insert_point, const xmlChar *insert_where)
 Create an edit request and add to YANG Patch in progress. More...
 
status_t db_api_send_patch (yang_patch_cb_t *pcb)
 Send a previously created patch request. More...
 
void db_api_free_patch (yang_patch_cb_t *pcb)
 Free a patch control block. More...
 
status_t db_api_send_enter_maintmode (void)
 Create a <enter-maintmode> request and send it to the main server. More...
 
status_t db_api_send_enter_maintmode_ex (boolean read_ok, boolean operation_ok)
 Create a <enter-maintmode> request and send it to the main server. More...
 
status_t db_api_send_exit_maintmode (void)
 Create a <exit-maintmode> request and send it to the main server. More...
 
status_t db_api_send_set_loglevel (const char *dlevel)
 Create a <set-log-level> request and send it to the main server. More...
 
status_t db_api_request_local_db_lock (void)
 API to request that the local system has the Db-Edit-Lock. More...
 
status_t db_api_release_local_db_lock (void)
 API to release the local system Db-Edit-Lock. More...
 
status_t db_api_send_subrpc_request (const xmlChar *user_id, const xmlChar *rpc_modname, const xmlChar *rpc_name, const xmlChar *in_filespec, const xmlChar *out_filespec)
 Create a <subrpc-request> request and send it to the main server. More...
 

Detailed Description

DB-API functions are used in the db-api-app and combo-app.

All functions in this module are user APIs for subsystem use only!

Function Documentation

status_t db_api_add_edit ( yang_patch_cb_t pcb,
const xmlChar *  edit_id_str,
const xmlChar *  edit_target,
const xmlChar *  edit_operation,
const xmlChar *  edit_xml_value,
const xmlChar *  insert_point,
const xmlChar *  insert_where 
)

Create an edit request and add to YANG Patch in progress.

If return NO_ERR then a new edit is added to pcb

Parameters
pcbpatch control block in progress
edit_id_strindex value for the edit
edit_targetedit target path string
edit_operationedit operation (create merge replace delete remove)
edit_xml_valueXML payload in string form, whitespace allowed
MAY BE NULL if no value required (delete remove))
insert_pointis a string like the target except a different instance of the same list of leaf-list; only for before, after
insert_where<insert enum="" string>="">
  • "before"
  • "after"
  • "first"
  • "last"
Returns
status

Here is the call graph for this function:

status_t db_api_check_edit ( void  )

Check on the status of an edit in progress.

Returns
status
  • ERR_NCX_NOT_FOUND if final status and no message response is pending
  • ERR_NCX_SKIPPED if final status is not known yet
  • NO_ERR if there is a last-completed operation that completed with an OK response
  • <errcode> if there is a last-completed operation that completed with an ERROR response

Here is the call graph for this function:

status_t db_api_check_edit_ex ( const xmlChar **  errstr)

Check on the status of an edit in progress.

Get the error string if any

Parameters
errstraddress of return error string (may be NULL)
Return values
*errstrpointer to error string if return value is not NO_ERR and there is a response from the server that had an error string
Returns
status
  • ERR_NCX_NOT_FOUND if final status and no message response is pending
  • ERR_NCX_SKIPPED if final status is not known yet
  • NO_ERR if there is a last-completed operation that completed with an OK response
  • <errcode> if there is a last-completed operation that completed with an ERROR response

Here is the caller graph for this function:

void db_api_free_patch ( yang_patch_cb_t pcb)

Free a patch control block.

Parameters
pcbpatch control block in progress

Here is the call graph for this function:

status_t db_api_register_service ( void  )

Register the DB-API service with the YControl layer.

Must be called before any other DB-API function can be used.

Returns
status

Here is the call graph for this function:

status_t db_api_register_service_ex ( boolean  with_db_lock)

Register the DB-API service with the YControl layer.

Extended to support db-lock.

Must be called before any other DB-API function can be used.

Parameters
with_db_lockTRUE to initialize db-lock service
Returns
status

Here is the call graph for this function:

Here is the caller graph for this function:

status_t db_api_release_local_db_lock ( void  )

API to release the local system Db-Edit-Lock.

Returns
status

Here is the call graph for this function:

status_t db_api_request_local_db_lock ( void  )

API to request that the local system has the Db-Edit-Lock.

Returns
status

Here is the call graph for this function:

status_t db_api_send_edit ( const xmlChar *  edit_target,
const xmlChar *  edit_operation,
const xmlChar *  edit_xml_value 
)

Create a YANG Patch edit request and send it to the DB-API service on the main server.

The content should represent the intended target resource as specified in YANG-API (NOT RESTCONF) Only the data resource identifier is provided, not the API wrapper identifiers (so this can change when RESTCONF is supported) Example leaf:

    edit_target /interfaces/interface/eth0/mtu
    edit_value "<mtu>9000</mtu>
    edit_operation "merge"
  Example list:
    edit_operation "create"
    edit_target /interfaces/interface/eth0/ipv4
    edit_value "<ipv4>
                     <enabled>true</enabled><
                     <forwarding>true</forwarding>
                     <address>204.102.10.4</address>
                     <prefix-length>24</prefix-length>
                   </ipv4>"

Uses db_api_send_edit_full2 with the following defaults:

  • patch_id_str is NULL
  • system_edit is FALSE
  • insert_point is NULL
  • insert_where is NULL
  • skip_sil is TRUE
Parameters
edit_targettarget resource (YANG-API path expression)
edit_operationedit operation (create merge replace delete remove)
edit_xml_valueXML payload in string form, whitespace allowed
MAY BE NULL if no value required (delete remove))
Returns
status

Here is the call graph for this function:

status_t db_api_send_edit_ex ( const xmlChar *  edit_target,
const xmlChar *  edit_operation,
const xmlChar *  edit_xml_value,
const xmlChar *  patch_id_str,
boolean  system_edit 
)

Create a YANG Patch edit request and send it to the DB-API service on the main server.

Add patch_id and system_edit flag.

The content should represent the intended target resource as specified in YANG-API (NOT RESTCONF) Only the data resource identifier is provided, not the API wrapper identifiers (so this can change when RESTCONF is supported)

Uses db_api_send_edit_full2 with the following defaults:

  • insert_point is NULL
  • insert_where is NULL
  • skip_sil is TRUE
Parameters
edit_targettarget resource (YANG-API path expression)
edit_operationedit operation (create merge replace delete remove)
edit_xml_valueXML payload in string form, whitespace allowed
MAY BE NULL if no value required (delete remove))
patch_id_strstring to use as the patch ID
NULL to use the default patch-id field
system_editTRUE if this edit is from the system and should bypass access control enforcement
FALSE if this edit is from a user and should not bypass access control enforcement
Returns
status
See also
db_api_send_edit

Here is the call graph for this function:

status_t db_api_send_edit_full ( const xmlChar *  edit_target,
const xmlChar *  edit_operation,
const xmlChar *  edit_xml_value,
const xmlChar *  patch_id_str,
boolean  system_edit,
const xmlChar *  insert_point,
const xmlChar *  insert_where 
)

Create a YANG Patch edit request and send it to the DB-API service on the main server.

Adds insert operation support.

The content should represent the intended target resource as specified in YANG-API (NOT RESTCONF) Only the data resource identifier is provided, not the API wrapper identifiers (so this can change when RESTCONF is supported)

  Example leaf:
    edit_target /interfaces/interface/eth0/mtu
    edit_value "<mtu>9000</mtu>
    edit_operation "merge"
    patch_id_str "my-patch-x01'
    system_edit true

Example list:

edit_operation <operation string>="">

  • "create"
  • "delete"
  • "insert"
  • "merge"
  • "move"
  • "replace"
  • "remove"
    edit_target /interfaces/interface/eth0/ipv4
    edit_value "<ipv4>
                     <enabled>true</enabled><
                     <forwarding>true</forwarding>
                     <address>204.102.10.4</address>
                     <prefix-length>24</prefix-length>
                   </ipv4>"

Uses db_api_send_edit_full2 with the following defaults:

  • skip_sil is TRUE
Parameters
edit_targettarget resource (YANG-API path expression)
edit_operationedit operation (create merge replace delete remove)
edit_xml_valueXML payload in string form, whitespace allowed
MAY BE NULL if no value required (delete remove))
patch_id_strstring to use as the patch ID
NULL to use the default patch-id field
system_editTRUE if this edit is from the system and should bypass access control enforcement
FALSE if this edit is from a user and should not bypass access control enforcement
insert_pointis a string like the target except a different instance of the same list of leaf-list; only for before, after.
NULL to ignore this parameter
insert_where<insert enum="" string>="">
  • "before"
  • "after"
  • "first"
  • "last"
    NULL to ignore this parameter
Returns
status
See also
db_api_send_edit

Here is the call graph for this function:

status_t db_api_send_edit_full2 ( const xmlChar *  edit_target,
const xmlChar *  edit_operation,
const xmlChar *  edit_xml_value,
const xmlChar *  patch_id_str,
boolean  system_edit,
const xmlChar *  insert_point,
const xmlChar *  insert_where,
boolean  skip_sil 
)

Create a YANG Patch edit request and send it to the DB-API service on the main server.

This patch can have exactly one edit. Provides full access to all 1-shot send_edit parameters.

The content should represent the intended target resource as specified in YANG-API (NOT RESTCONF) Only the data resource identifier is provided, not the API wrapper identifiers (so this can change when RESTCONF is supported)

  Example leaf:
    edit_target /interfaces/interface/eth0/mtu
    edit_value "<mtu>9000</mtu>
    edit_operation "merge"
    patch_id_str "my-patch-x01'
    system_edit true

Example list:

edit_operation <operation string>="">

  • "create"
  • "delete"
  • "insert"
  • "merge"
  • "move"
  • "replace"
  • "remove"
    edit_target /interfaces/interface/eth0/ipv4
    edit_value "<ipv4>
                     <enabled>true</enabled><
                     <forwarding>true</forwarding>
                     <address>204.102.10.4</address>
                     <prefix-length>24</prefix-length>
                   </ipv4>"
Parameters
edit_targettarget resource (YANG-API path expression)
edit_operationedit operation (create merge replace delete remove)
edit_xml_valueXML payload in string form, whitespace allowed
MAY BE NULL if no value required (delete remove))
patch_id_strstring to use as the patch ID
NULL to use the default patch-id field
system_editTRUE if this edit is from the system and should bypass access control enforcement
FALSE if this edit is from a user and should not bypass access control enforcement
insert_pointis a string like the target except a different instance of the same list of leaf-list; only for before, after.
NULL to ignore this parameter
insert_where<insert enum="" string>="">
  • "before"
  • "after"
  • "first"
  • "last"
    NULL to ignore this parameter
skip_silTRUE to skip the SIL and SIL-SA callbacks on the main server
FALSE to invoke the SIL and SIL-SA callbacks for this transaction
Returns
status
See also
db_api_send_edit

Here is the call graph for this function:

Here is the caller graph for this function:

status_t db_api_send_enter_maintmode ( void  )

Create a <enter-maintmode> request and send it to the main server.

Sends a request with default parameters.

Returns
status
status_t db_api_send_enter_maintmode_ex ( boolean  read_ok,
boolean  operation_ok 
)

Create a <enter-maintmode> request and send it to the main server.

Supports 'allowed' parameter

Parameters
read_okT:allowed 'read' bit should be set
operation_okT:allowed 'operation' bit should be set
Returns
status
status_t db_api_send_exit_maintmode ( void  )

Create a <exit-maintmode> request and send it to the main server.

Returns
status
status_t db_api_send_getconfig ( const xmlChar *  filespec,
boolean  withdef 
)

Create a <getconfig> request and send it to the main server.

Parameters
filespecfile specification to contain the XML instance document retrieved from the server
withdefTRUE to get with defaults; FALSE to leave out defaults
Returns
status
See also
db_api_send_getfilter

Here is the call graph for this function:

status_t db_api_send_getfilter ( const xmlChar *  filespec,
boolean  withdef,
boolean  get_config,
const xmlChar *  xpath_filter 
)

Retrieve data from the server with complete parameters.

Create a <getconfig> request and send it to the main server. An XPath filter can be sent as a parameter

Parameters
filespecfile specification to contain the XML instance document retrieved from the server
withdefTRUE to get with defaults; FALSE to leave out defaults
get_configTRUE for config only; FALSE for get (config + state)
xpath_filterXPath expression (may be nULL)
Returns
status

Here is the call graph for this function:

Here is the caller graph for this function:

status_t db_api_send_patch ( yang_patch_cb_t pcb)

Send a previously created patch request.

This does not free the pcb! Must call db_api_free_patch after this call

Parameters
pcbpatch control block in progress
Returns
status

Here is the call graph for this function:

status_t db_api_send_set_loglevel ( const char *  dlevel)

Create a <set-log-level> request and send it to the main server.

Parameters
dleveldebug level string
Returns
status
status_t db_api_send_subrpc_request ( const xmlChar *  user_id,
const xmlChar *  rpc_modname,
const xmlChar *  rpc_name,
const xmlChar *  in_filespec,
const xmlChar *  out_filespec 
)

Create a <subrpc-request> request and send it to the main server.

Parameters
user_iduser name to run RPC on server; NULL system user
rpc_modnamemodule name containing the RPC or NULL to scan all modules for the first match of rpc_name
rpc_namename of the RPC (must be present)
in_filespecfile specification to contain the XML instance document for the rpc-method element (if needed)
out_filespecfile specification to contain the XML instance document retrieved from the server (must be present)
Return values
out_filespecfile named by out_filespec created if operation succeeded.
Returns
status

Here is the call graph for this function:

boolean db_api_service_ready ( void  )

Check if the DB-API service is done initializing, and is now ready to send requests to the server.

Returns
TRUE if ready state; FALSE otherwise

Here is the caller graph for this function:

status_t db_api_start_patch ( const xmlChar *  patch_id_str,
boolean  system_edit,
yang_patch_cb_t **  retcb 
)

Start a YANG Patch request that can have multiple edits.

  Steps to use:
   1) db_api_start_patch
   2 .. N-2) db_api_add_edit
   N-1) db_api_send_patch
   N) db_api_free_patch
Parameters
patch_id_strstring to use as the patch ID
NULL to use the default patch-id field
system_editTRUE if this edit is from the system and should
retcbaddress of return control block
Return values
*retcbthe patch control block in progress
Must free with ab_api_free_patch!!
Returns
status
See also
db_api_add_edit
db_api_send_patch
db_api_free_patch

Here is the call graph for this function: