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_send_edit_oper (const xmlChar edit_target, const xmlChar edit_operation, const xmlChar edit_value, const xmlChar patch_id_str, const xmlChar comment_str, const xmlChar insert_point, const xmlChar *insert_where, ncx_msg_encoding_t edit_encoding, ncx_instfmt_t edit_id_format)
	Create a YANG Patch edit request and send it to the DB-API service on the main server. More...

status_t	db_api_register_service_ex (boolean with_db_lock)
	Register the DB-API service with the YControl layer. 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_check_edit (void)
	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_cb (db_api_dataresp_cbfn_t cbfn, void cookie, boolean withdef, boolean get_config, const xmlChar xpath_filter)
	Retrieve data from the server with user callback. 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_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...

status_t	db_api_send_protocol_control (const xmlChar action, const xmlChar protocol)
	Create a <protocol-control> request and send it to the main server. More...

uint32	db_api_get_last_msg_id (void)
	API to get the last message ID sent by the db-api system. 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

◆ db_api_check_edit()

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

◆ db_api_get_last_msg_id()

uint32 db_api_get_last_msg_id ( void )

API to get the last message ID sent by the db-api system.

Returns: message ID (0 is not initialized)

◆ db_api_register_service_ex()

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_lock TRUE to initialize db-lock service

Returns: status

Here is the call graph for this function:

◆ db_api_release_local_db_lock()

status_t db_api_release_local_db_lock ( void )

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

Returns: status

◆ db_api_request_local_db_lock()

status_t db_api_request_local_db_lock ( void )

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

Returns: status

◆ db_api_send_edit()

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.

THIS API MUST ONLY BE USED WITHIN A YCONTROL SUBSYSTEM.

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_target	target resource (YANG-API path expression)
edit_operation	edit operation (create merge replace delete remove)
edit_xml_value	XML 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:

◆ db_api_send_edit_ex()

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.

THIS API MUST ONLY BE USED WITHIN A YCONTROL SUBSYSTEM.

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_target	target resource (YANG-API path expression)
edit_operation	edit operation (create merge replace delete remove)
edit_xml_value	XML payload in string form, whitespace allowed MAY BE NULL if no value required (delete remove))
patch_id_str	string to use as the patch ID NULL to use the default patch-id field
system_edit	TRUE 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:

◆ db_api_send_edit_full()

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.

THIS API MUST ONLY BE USED WITHIN A YCONTROL SUBSYSTEM.

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_target	target resource (YANG-API path expression)
edit_operation	edit operation (create merge replace delete remove)
edit_xml_value	XML payload in string form, whitespace allowed MAY BE NULL if no value required (delete remove))
patch_id_str	string to use as the patch ID NULL to use the default patch-id field
system_edit	TRUE 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_point	is 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:

◆ db_api_send_edit_oper()

status_t db_api_send_edit_oper	(	const xmlChar *	edit_target,
		const xmlChar *	edit_operation,
		const xmlChar *	edit_value,
		const xmlChar *	patch_id_str,
		const xmlChar *	comment_str,
		const xmlChar *	insert_point,
		const xmlChar *	insert_where,
		ncx_msg_encoding_t	edit_encoding,
		ncx_instfmt_t	edit_id_format
	)

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

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

The content should represent the intended target resource as specified in YANG-API (NOT RESTCONF, unless RESTCONF format is specified)

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_target	target resource (YANG-API path expression)
edit_operation	edit operation (create merge replace delete remove)
edit_value	XML/JSON/CBOR payload in string form, whitespace allowed MAY BE NULL if no value required (delete remove))
patch_id_str	string to use as the patch ID
comment_str	comment string or NULL to use default
insert_point	is 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"
edit_encoding	encoding that represents corresponding encoding type. Default XML.
edit_id_format	identifies the instance identifier string format types Default XML YANG-API format.

Returns: status

Here is the call graph for this function:

◆ db_api_send_enter_maintmode()

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

◆ db_api_send_enter_maintmode_ex()

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_ok	T:allowed 'read' bit should be set
operation_ok	T:allowed 'operation' bit should be set

Returns: status

◆ db_api_send_exit_maintmode()

status_t db_api_send_exit_maintmode ( void )

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

Returns: status

◆ db_api_send_getconfig()

status_t db_api_send_getconfig	(	const xmlChar *	filespec,
		boolean	withdef
	)

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

Parameters

filespec	file specification to contain the XML instance document retrieved from the server
withdef	TRUE to get with defaults; FALSE to leave out defaults

Returns: status

See also: db_api_send_getfilter

◆ db_api_send_getfilter_cb()

status_t db_api_send_getfilter_cb	(	db_api_dataresp_cbfn_t	cbfn,
		void *	cookie,
		boolean	withdef,
		boolean	get_config,
		const xmlChar *	xpath_filter
	)

Retrieve data from the server with user callback.

Info on processing val_value_t trees, refer to [Data Trees] (https://docs.yumaworks.com/en/latest/ypserver/yang-data-nodes.html)

Create a <getconfig> request and send it to the main server.
An XPath filter can be sent as a parameter.
The callback function is used to process the internal val_value_t
Use this API instead of db_api_getfilter to avoid disk usage

Parameters

cbfn	Data Response Callback Function to use
cookie	parameter to pass to callback function after reply received
withdef	TRUE to get with defaults; FALSE to leave out defaults
get_config	TRUE for config only; FALSE for get (config + state)
xpath_filter	XPath expression (may be nULL)

Returns: status; if any error then callback will not be invoked

◆ db_api_send_protocol_control()

status_t db_api_send_protocol_control	(	const xmlChar *	action,
		const xmlChar *	protocol
	)

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

Refer to the <protocol-control> operation in yumaworks-system.yang

Parameters

action	protocol action
protocol	protocol name

Returns: status

◆ db_api_send_set_loglevel()

status_t db_api_send_set_loglevel ( const char * dlevel )

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

Parameters

dlevel debug level string

Returns: status

◆ db_api_send_subrpc_request()

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_id	user name to run RPC on server; NULL system user
	rpc_modname	module name containing the RPC or NULL to scan all modules for the first match of rpc_name
	rpc_name	name of the RPC (must be present)
	in_filespec	file specification to contain the XML instance document for the rpc-method element (if needed)
[out]	out_filespec	file specification to contain the XML instance document retrieved from the server (must be present) out_filespec file named by out_filespec created if operation succeeded.

Returns: status

Here is the call graph for this function:

◆ db_api_start_patch()

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_str	string to use as the patch ID NULL to use the default patch-id field
	system_edit	TRUE if this edit is from the system and should
[out]	retcb	address of return control block *retcb the 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

Macros

Functions

Detailed Description

Function Documentation

◆ db_api_check_edit()

◆ db_api_get_last_msg_id()

◆ db_api_register_service_ex()

◆ db_api_release_local_db_lock()

◆ db_api_request_local_db_lock()

◆ db_api_send_edit()

◆ db_api_send_edit_ex()

◆ db_api_send_edit_full()

◆ db_api_send_edit_oper()

◆ db_api_send_enter_maintmode()

◆ db_api_send_enter_maintmode_ex()

◆ db_api_send_exit_maintmode()

◆ db_api_send_getconfig()

◆ db_api_send_getfilter_cb()

◆ db_api_send_protocol_control()

◆ db_api_send_set_loglevel()

◆ db_api_send_subrpc_request()

◆ db_api_start_patch()