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_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_start_patch2 (const xmlChar patch_id_str, boolean system_edit, boolean skip_sil, const xmlChar comment, yang_patch_cb_t **retcb)
	Start a YANG Patch request that can have multiple edits with complete parameters (YPW-1826) 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...

status_t	db_api_send_ypha_request (val_value_t *msgval)
	Create a <yp-ha-mode> 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_add_edit()

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

pcb	patch control block in progress
edit_id_str	index value for the edit
edit_target	edit target path string
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))
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"

Returns: status

Here is the call graph for this function:

◆ 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

Here is the call graph for this function:

◆ db_api_check_edit_ex()

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

[out]

errstr

address of return error string (may be NULL)

*errstr pointer 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:

◆ db_api_free_patch()

void db_api_free_patch ( yang_patch_cb_t * pcb )

Free a patch control block.

Parameters

pcb	patch control block in progress

Here is the call graph for this function:

◆ 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()

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:

◆ 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:

Here is the caller 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_full2()

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.

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>"

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
skip_sil	TRUE 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:

◆ 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

Here is the call graph for this function:

◆ db_api_send_getfilter()

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

filespec	file specification to contain the XML instance document retrieved from the server
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

Here is the call graph for this function:

Here is the caller graph for this function:

◆ 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

Here is the call graph for this function:

◆ db_api_send_patch()

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

pcb	patch control block in progress

Returns: status

Here is the call graph for this function:

◆ 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

Here is the call graph for this function:

◆ 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_send_ypha_request()

status_t db_api_send_ypha_request ( val_value_t * msgval )

Create a <yp-ha-mode> request and send it to the main server.

Parameters

msgval Complete message to send to the server (NOT just payload!). Used as const but system APIs require non-const pointers

Returns: status

Here is the call graph for this function:

◆ db_api_service_ready()

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:

◆ 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

Here is the call graph for this function:

◆ db_api_start_patch2()

status_t db_api_start_patch2	(	const xmlChar *	patch_id_str,
		boolean	system_edit,
		boolean	skip_sil,
		const xmlChar *	comment,
		yang_patch_cb_t **	retcb
	)

Start a YANG Patch request that can have multiple edits with complete parameters (YPW-1826)

* Steps to use:
*  1) db_api_start_patch2
*  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
	skip_sil	TRUE to skip SIL callbacks (default) FALSE to invoke SIL callbacks for this patch
	comment	string to override default 'DB-API patch' NULL to use the default comment
[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

Here is the call graph for this function:

Here is the caller graph for this function:

Macros

Functions

Detailed Description

Function Documentation

◆ db_api_add_edit()

◆ db_api_check_edit()

◆ db_api_check_edit_ex()

◆ db_api_free_patch()

◆ db_api_get_last_msg_id()

◆ db_api_register_service()

◆ 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_full2()

◆ db_api_send_enter_maintmode()

◆ db_api_send_enter_maintmode_ex()

◆ db_api_send_exit_maintmode()

◆ db_api_send_getconfig()

◆ db_api_send_getfilter()

◆ db_api_send_getfilter_cb()

◆ db_api_send_patch()

◆ db_api_send_protocol_control()

◆ db_api_send_set_loglevel()

◆ db_api_send_subrpc_request()

◆ db_api_send_ypha_request()

◆ db_api_service_ready()

◆ db_api_start_patch()

◆ db_api_start_patch2()