Subtree Filtering used by NETCONF and RESTCONF Operations. More...

Collaboration diagram for Subtree Filtering:

Functions
ncx_filptr_t *	agt_tree_prune_filter (ses_cb_t scb, rpc_msg_t msg, const cfg_template_t cfg, boolean getop, boolean do_all)
	get and get-config step 1. More...

ncx_filptr_t *	agt_tree_prune_filter2 (ses_cb_t scb, rpc_msg_t msg, val_value_t root, obj_template_t root_obj, val_value_t filter, boolean getop, boolean do_all)
	get and get-config step 1. More...

void	agt_tree_output_filter (ses_cb_t scb, rpc_msg_t msg, ncx_filptr_t *top, int32 indent, boolean getop)
	get and get-config step 2. More...

boolean	agt_tree_test_filter (xml_msg_hdr_t msghdr, ses_cb_t scb, val_value_t filter, val_value_t topval)
	notification filter evaluation More...

void	agt_tree_output_node_from_obj_xml (ses_cb_t scb, xml_msg_hdr_t msg, ncx_filptr_t filptr, obj_template_t obj, int32 indent, boolean getop)
	Output the get2 callback node from the value node to the specified session. More...

void	agt_tree_output_node_from_obj_json (ses_cb_t scb, xml_msg_hdr_t msg, ncx_filptr_t filptr, obj_template_t obj, int32 indent, boolean getop, boolean isfirst, boolean islast, boolean isfirstchild, boolean isfirstsibling, boolean force_lastsibling, boolean force_lastsib_value, boolean force_array_obj)
	Output the get2 callback node from the value node to the specified session; JSON format. More...

void	agt_tree_output_node_from_obj_cbor (ses_cb_t scb, xml_msg_hdr_t msg, ncx_filptr_t filptr, obj_template_t obj, boolean getop, cbor_wr_parms_t *parms)
	Output the get2 callback node from the value node to the specified session. More...

boolean	agt_tree_attr_test (val_value_t filval, val_value_t targval)
	Check any attribute match expressions. More...

boolean	agt_tree_content_match_test (ses_cb_t scb, const xmlChar testval, val_value_t *curval)
	Check a content match node against the corresponding node in the target. More...

obj_template_t *	agt_tree_find_child_object (xmlns_id_t obj_id, const xmlChar obj_name, obj_template_t parent_obj, boolean *more_matches)
	find the child object template from a namespace ID (may be zero) More...

boolean	agt_tree_filter_ok_for_nolock (val_value_t *filterval)
	Check a filter to see if it selects only top-level config=false. More...

status_t	agt_tree_cvt_subtree_xpath (ses_cb_t scb, rpc_msg_t msg, const cfg_template_t cfg, boolean getop, val_value_t filter, boolean skiptop, xmlChar *xpathstr)
	Convert a subtree filter to an XPath filter. More...

status_t	agt_tree_get2_retrieve_value (xml_msg_hdr_t msg, ses_cb_t scb, ncx_filptr_t parent_filptr, ncx_filptr_t filptr, val_value_t filchild, obj_template_t filobj, val_value_t curval, boolean getop, boolean force_remove, getcb_api_mode_t api_mode, int32 startindent)
	Get the value for the specified object via the get2 callback or check the parent result for the node. More...

status_t	agt_tree_get2_check_value (xml_msg_hdr_t msg, ses_cb_t scb, obj_template_t filobj, val_value_t curval)
	Get the value for the specified object via the get2 callback and just simple check if it is exist or not. More...

status_t	agt_tree_get2_retrieve_aio_values (xml_msg_hdr_t msg, ses_cb_t scb, ncx_filptr_t parent_filptr, ncx_filptr_t filptr, val_value_t filchild, obj_template_t filobj, val_value_t *curval, boolean getop, getcb_api_mode_t api_mode, int32 startindent)
	Get the value for the specified object via the get2 callback or check the parent result for the node. More...

Detailed Description

Subtree Filtering used by NETCONF and RESTCONF Operations.

Supports <get-config>, <get>, and <get-data> operations. Calls local and/or remote GET2 callbacks if needed to get the requested data

Function Documentation

◆ agt_tree_attr_test()

boolean agt_tree_attr_test	(	val_value_t *	filval,
		val_value_t *	targval
	)

Check any attribute match expressions.

Parameters

filval	filter node value
targval	corresponding node from the target

Returns: TRUE if no tests failed
FALSE if any tests fail (exits at first failure)

Here is the call graph for this function:

◆ agt_tree_content_match_test()

boolean agt_tree_content_match_test	(	ses_cb_t *	scb,
		const xmlChar *	testval,
		val_value_t *	curval
	)

Check a content match node against the corresponding node in the target.

Parameters

scb	session control block
testval	string to compare with
curval	target node to compare against

Returns: TRUE if content match test OK
FALSE if content different or target is a complex data type and not a simple type

◆ agt_tree_cvt_subtree_xpath()

status_t agt_tree_cvt_subtree_xpath	(	ses_cb_t *	scb,
		rpc_msg_t *	msg,
		const cfg_template_t *	cfg,
		boolean	getop,
		val_value_t *	filter,
		boolean *	skiptop,
		xmlChar **	xpathstr
	)

Convert a subtree filter to an XPath filter.

The GET2 callbacks are more correct for XPath so this should be done if possible.

Set –convert-subtree-filter=true in CLI or .conf file.

Parameters

	scb	session control block NULL if access control should not be applied
	msg	rpc_msg_t in progress
	cfg	config target to check against
	getop	TRUE if this is a <get> and not a <get-config>. The target is expected to be the <running> config, and all state data will be available for the filter output. FALSE if this is a <get-config> and only the specified target in available for filter output
	filter	filter value to check
[out]	skiptop	address of return skiptop flag *skiptop TRUE if pre-process filter pruned everything so output empty instead of any data
[out]	xpathstr	address of return strnig *xpathstr set to return buffer; this is malloced; call m__free!

Returns: status

Here is the call graph for this function:

◆ agt_tree_filter_ok_for_nolock()

boolean agt_tree_filter_ok_for_nolock ( val_value_t * filterval )

Check a filter to see if it selects only top-level config=false.

Only present if PTHREADS=1

Parameters

filterval value node to check; expected to have a subtree filter as child nodes

Returns: TRUE if OK for nolock get; FALSE otherwise

Here is the call graph for this function:

Here is the caller graph for this function:

◆ agt_tree_find_child_object()

obj_template_t * agt_tree_find_child_object	(	xmlns_id_t	obj_id,
		const xmlChar *	obj_name,
		obj_template_t *	parent_obj,
		boolean *	more_matches
	)

find the child object template from a namespace ID (may be zero)

Parameters

	obj_id	namespace ID of child object zero for first match, *more_matches will be set
	obj_name	local-name of child object
	parent_obj	parent object
[out]	more_matches	address of return more matches flag *more_matches TRUE is obj_id was zero and there more matches found besides the one being returned now

Returns: pointer to object template if found
NULL if not found

Here is the call graph for this function:

◆ agt_tree_get2_check_value()

status_t agt_tree_get2_check_value	(	xml_msg_hdr_t *	msg,
		ses_cb_t *	scb,
		obj_template_t *	filobj,
		val_value_t *	curval
	)

Get the value for the specified object via the get2 callback and just simple check if it is exist or not.

If it does not exist it may cause deletion of a parent filter

Parameters

msg	incoming or outgoing message header in progress
scb	session control block NULL if no read access control is desired
filobj	object template for the real object that matches 'filchild' (which is anyxml)
curval	current database node of the parent or ancestor of the object being retrieved

Returns: status: NO_ERR, ERR_NCX_NO_INSTANCE, some error

Here is the call graph for this function:

◆ agt_tree_get2_retrieve_aio_values()

status_t agt_tree_get2_retrieve_aio_values	(	xml_msg_hdr_t *	msg,
		ses_cb_t *	scb,
		ncx_filptr_t *	parent_filptr,
		ncx_filptr_t *	filptr,
		val_value_t *	filchild,
		obj_template_t *	filobj,
		val_value_t *	curval,
		boolean	getop,
		getcb_api_mode_t	api_mode,
		int32	startindent
	)

Get the value for the specified object via the get2 callback or check the parent result for the node.

Parameters

	msg	incoming or outgoing message header in progress
	scb	session control block NULL if no read access control is desired
	parent_filptr	parent node of the filptr
[in,out]	filptr	pointer to malloced filter pointer record to fill in filptr->get2cb is set
	filchild	the anyxml version of the node to match in filobj
	filobj	object template for the real object that matches 'filchild' (which is anyxml)
	curval	current database node of the parent or ancestor of the object being retrieved
	getop	TRUE if this is a <get> and not a <get-config> The target is expected to be the <running> config, and all state data will be available for the filter output. FALSE if this is a <get-config> and only the specified target in available for filter output
	api_mode	GETCB_API_MODE_NORMAL or GETGB_API_MODE_1SHOT
	startindent	start message indent amount

Returns: status: NO_ERR, ERR_NCX_NO_INSTANCE, some error

Here is the call graph for this function:

◆ agt_tree_get2_retrieve_value()

status_t agt_tree_get2_retrieve_value	(	xml_msg_hdr_t *	msg,
		ses_cb_t *	scb,
		ncx_filptr_t *	parent_filptr,
		ncx_filptr_t *	filptr,
		val_value_t *	filchild,
		obj_template_t *	filobj,
		val_value_t *	curval,
		boolean	getop,
		boolean *	force_remove,
		getcb_api_mode_t	api_mode,
		int32	startindent
	)

Get the value for the specified object via the get2 callback or check the parent result for the node.

Parameters

	msg	incoming or outgoing message header in progress
	scb	session control block NULL if no read access control is desired
	parent_filptr	filptr tree result of the parent object
[in,out]	filptr	pointer to malloced filter pointer record to fill in filptr->get2cb is set
	filchild	filter node for the child being retrieved
	filobj	object template for the real object that matches 'filchild' (which is anyxml)
	curval	current database node of the parent or ancestor of the object being retrieved
	getop	TRUE if this is a <get> and not a <get-config> The target is expected to be the <running> config, and all state data will be available for the filter output. FALSE if this is a <get-config> and only the specified target in available for filter output
[out]	force_remove	address of return force_remove flag *force_remove TRUE if the object template for a content match node was missing or if the callback returned any error for the content-match node FALSE if all content match nodes were OK
	api_mode	GETCB_API_MODE_NORMAL or GETGB_API_MODE_1SHOT
	startindent	start message indent amount

Returns: status: NO_ERR, ERR_NCX_NO_INSTANCE, some error

Here is the call graph for this function:

Here is the caller graph for this function:

◆ agt_tree_output_filter()

void agt_tree_output_filter	(	ses_cb_t *	scb,
		rpc_msg_t *	msg,
		ncx_filptr_t *	top,
		int32	indent,
		boolean	getop
	)

get and get-config step 2.

Output the pruned subtree filter to the specified session.

Parameters

scb	session control block NULL if access control should not be applied
msg	rpc_msg_t in progress
top	ncx_filptr tree to output
indent	start indent amount
getop	TRUE if <get>, FALSE if <get-config>

Here is the call graph for this function:

Here is the caller graph for this function:

◆ agt_tree_output_node_from_obj_cbor()

void agt_tree_output_node_from_obj_cbor	(	ses_cb_t *	scb,
		xml_msg_hdr_t *	msg,
		ncx_filptr_t *	filptr,
		obj_template_t *	obj,
		boolean	getop,
		cbor_wr_parms_t *	parms
	)

Output the get2 callback node from the value node to the specified session.

CBOR encoding.

Parameters

scb	session control block
msg	xml_msg_hdr in progress
filptr	filter node to use
obj	object template for the value node to output
getop	TRUE if get operation; FALSE if get-config
parms	CBOR write parms to use

◆ agt_tree_output_node_from_obj_json()

void agt_tree_output_node_from_obj_json	(	ses_cb_t *	scb,
		xml_msg_hdr_t *	msg,
		ncx_filptr_t *	filptr,
		obj_template_t *	obj,
		int32	indent,
		boolean	getop,
		boolean	isfirst,
		boolean	islast,
		boolean	isfirstchild,
		boolean	isfirstsibling,
		boolean	force_lastsibling,
		boolean	force_lastsib_value,
		boolean	force_array_obj
	)

Output the get2 callback node from the value node to the specified session; JSON format.

Parameters

scb	session control block
msg	xml_msg_hdr in progress
filptr	filter node to use
obj	object template for values node to output
indent	start indent amount
getop	TRUE if <get>, FALSE if <get-config>
isfirst	TRUE if this is the first (top) val printed
islast	TRUE if this is the last (top) val printed
isfirstchild	TRUE if this is the first child of a parent node FALSE if this is the 2nd - Nth value of an array
isfirstsibling	TRUE if this is the first value of an array FALSE if this is the 2nd - Nth value of an array
force_lastsibling	TRUE to force this as the last sibling TRUE or FALSE to check the sibling of 'val'
force_lastsib_value	TRUE to force this as the last sibling FALSE to force this as not the last sibling ignore if force_lastsibling is FALSE
force_array_obj	TRUE to treat select leafs and containers as leaf-lists and lists which normally have only 1 instance in their actual context, but select removes the context

Here is the call graph for this function:

◆ agt_tree_output_node_from_obj_xml()

void agt_tree_output_node_from_obj_xml	(	ses_cb_t *	scb,
		xml_msg_hdr_t *	msg,
		ncx_filptr_t *	filptr,
		obj_template_t *	obj,
		int32	indent,
		boolean	getop
	)

Output the get2 callback node from the value node to the specified session.

XML encoding.

Parameters

scb	session control block
msg	xml_msg_hdr in progress
filptr	filter node to use
obj	object template for the value node to output
indent	start indent amount
getop	TRUE if <get>, FALSE if <get-config>

Here is the call graph for this function:

◆ agt_tree_prune_filter()

ncx_filptr_t * agt_tree_prune_filter	(	ses_cb_t *	scb,
		rpc_msg_t *	msg,
		const cfg_template_t *	cfg,
		boolean	getop,
		boolean *	do_all
	)

get and get-config step 1.

Need to evaluate the entire subtree filter and remove nodes which are not in the result set.

The filter subtree usually starts out as type NCX_BT_CONTAINER but a single select node could be present instead.

The <filter> subtree starts out as type NCX_BT_CONTAINER (root) and is converted by val_parse as follows:


    Subtree Filter:
      NCX_BT_ANY -- start type
    changed to real types during parsing
      NCX_BT_CONTAINER   -->  container node
      NCX_BT_EMPTY    -->  select node
      NCX_BT_STRING  -->  content select node

Parameters

	scb	session control block NULL if access control should not be applied
[in,out]	msg	rpc_msg_t in progress msg->rpc_filter.op_filter is pruned as needed by setting the VAL_FL_FILTERED bit.in the val->flags field for the start of subtrees which failed the filter test. Only nodes which result in non-NULL output should remain unchanged at the end of this procedure.
	cfg	config target to check against
	getop	TRUE if this is a <get> and not a <get-config>. The target is expected to be the <running> config, and all state data will be available for the filter output. FALSE if this is a <get-config> and only the specified target in available for filter output
[out]	do_all	address of return do_all flag *do_all TRUE if the return value is NULL but there was a top-level content match node that passed so all top-level contents should be done FALSE if return non-NULL or skip all

Returns: pointer to generated tree of matching nodes
NULL if no match

Here is the call graph for this function:

Here is the caller graph for this function:

◆ agt_tree_prune_filter2()

ncx_filptr_t * agt_tree_prune_filter2	(	ses_cb_t *	scb,
		rpc_msg_t *	msg,
		val_value_t *	root,
		obj_template_t *	root_obj,
		val_value_t *	filter,
		boolean	getop,
		boolean *	do_all
	)

get and get-config step 1.

(extended) Need to evaluate the entire subtree filter and remove nodes which are not in the result set.

The filter subtree usually starts out as type NCX_BT_CONTAINER but a single select node could be present instead.

The <filter> subtree starts out as type NCX_BT_CONTAINER (root) and is converted by val_parse as follows:


    Subtree Filter:
      NCX_BT_ANY -- start type
    changed to real types during parsing
      NCX_BT_CONTAINER   -->  container node
      NCX_BT_EMPTY    -->  select node
      NCX_BT_STRING  -->  content select node

Parameters

	scb	session control block NULL if access control should not be applied
[in,out]	msg	rpc_msg_t in progress msg->rpc_filter.op_filter is pruned as needed by setting the VAL_FL_FILTERED bit.in the val->flags field for the start of subtrees which failed the filter test. Only nodes which result in non-NULL output should remain unchanged at the end of this procedure.
	root	subtree root to search
	root_obj	object template for `root`
	filter	filter value received in request
	getop	TRUE if this is a <get> and not a <get-config>. The target is expected to be the <running> config, and all state data will be available for the filter output. FALSE if this is a <get-config> and only the specified target in available for filter output
[out]	do_all	address of return do_all flag *do_all TRUE if the return value is NULL but there was a top-level content match node that passed so all top-level contents should be done FALSE if return non-NULL or skip all

Returns: pointer to generated tree of matching nodes
NULL if no match

Here is the call graph for this function:

Here is the caller graph for this function:

◆ agt_tree_test_filter()

boolean agt_tree_test_filter	(	xml_msg_hdr_t *	msghdr,
		ses_cb_t *	scb,
		val_value_t *	filter,
		val_value_t *	topval
	)

notification filter evaluation

Need to evaluate the entire subtree filter and return 'FALSE' if any nodes in the filter are not in the result set (this is probably a notification payload)

Parameters

msghdr	message in progress; needed for access control
scb	session control block; needed for access control
filter	subtree filter to use
topval	value tree to check against

Returns: TRUE if the filter matched; notification can be sent
FALSE if the filter did not match; notification not sent

Here is the call graph for this function:

Functions

Detailed Description

Function Documentation

◆ agt_tree_attr_test()

◆ agt_tree_content_match_test()

◆ agt_tree_cvt_subtree_xpath()

◆ agt_tree_filter_ok_for_nolock()

◆ agt_tree_find_child_object()

◆ agt_tree_get2_check_value()

◆ agt_tree_get2_retrieve_aio_values()

◆ agt_tree_get2_retrieve_value()

◆ agt_tree_output_filter()

◆ agt_tree_output_node_from_obj_cbor()

◆ agt_tree_output_node_from_obj_json()

◆ agt_tree_output_node_from_obj_xml()

◆ agt_tree_prune_filter()

◆ agt_tree_prune_filter2()

◆ agt_tree_test_filter()