YANG Objects

This section describes the basic design of the YANG object tree and the API functions to access this tree.

Object Trees

The object tree is a tree representation of all the YANG module rpc, data definition, and notification statements. It starts with a 'root' container. This is defined with a YANG container statement which has an ncx:root extension statement within it. The <config> parameter within the <edit-config> operation is an example of an object node which is treated as a root container. Each configuration database maintained by the server (E.g., <candidate> and <running>) has a root container value node as its top-level object.

A root container does not have any child nodes defined in it within the YANG file. However, the YumaPro tools will treat this special container as if any top-level YANG data node is allowed to be a child node of the 'root' container type.

Object Tree Ordering

Top-Level Data Nodes are derived from:

  • data-def-stmt

  • rpc-stmt

  • notification-stmt

The YANG object tree is maintained in “schema order” wherever that is defined.

  • Top-Level Data Nodes:

    • These nodes are sorted:

      • Primary Key: local-name

      • Secondary Key: module-name

    • The top-level YANG objects from all loaded modules are present in the object tree (except if removed by status=obsolete or deviation=not-supported)

  • Child Data Nodes, RPC and Notification Nodes

    • Child nodes defined in the current module are in schema order (order they appear in the YANG module

    • Augmenting child nodes are in no defined order. They will be after all the real child nodes and the order may change depending on how the augmenting modules are loaded.

      • DO NOT DEPEND ON THE ORDER OF AUGMENTING DATA NODES

Object Node Types

There are 14 different YANG object node types, and a discriminated union of sub-data structures contains fields common to each sub-type. Object templates are defined in ncx/obj.h.

YANG Object Types

enum obj_type_t

enumeration for different YANG data def statement types the enum order is significant!!! do not change!!!

Values:

enumerator OBJ_TYP_NONE

not set

enumerator OBJ_TYP_ANYXML

This object represents a YANG 1.1 anydata data node.

enumerator OBJ_TYP_CONTAINER

This object represents a YANG presence or non-presence container.

  • If the ncx:root stmt present then the object represents a NETCONF database root, and no direct child nodes are expected

enumerator OBJ_TYP_LEAF

This object represents a YANG leaf data node.

enumerator OBJ_TYP_LEAF_LIST

This object represents a YANG leaf-list data node.

enumerator OBJ_TYP_LIST

This object represents a YANG list data node.

enumerator OBJ_TYP_CHOICE

This object represents a YANG choice schema node.

  • The only children allowed are case objects.

  • This object does not have instances in the data tree.

enumerator OBJ_TYP_CASE

This object represents a YANG case schema node.

  • This object does not have instances in the data tree. case: last named database object

enumerator OBJ_TYP_USES

This object represents a YANG uses schema node.

  • The contents of the grouping it represents will be expanded into object tree.

  • It is saved in the object tree even during operation, in order for the expanded objects to share common data.

  • This object does not have instances in the data tree.

  • Object has no name: The obj_get_name function returns the string 'uses'

enumerator OBJ_TYP_REFINE

This object represents a YANG refine statement.

  • It is used to alter the grouping contents during the expansion of a uses statement.

  • Must be a direct child of 'uses' stmt

  • It does not have instances in the data tree.

enumerator OBJ_TYP_AUGMENT

This object represents a YANG augment statement.

  • It is used to add additional child objects to an existing data definition statement.

  • This object is only allowed to be a child of a uses

  • statement or a top-level stateement within the module

  • It does not have instances in the data tree, however any children of the augment node will generate object nodes that have instances in the data tree.

enumerator OBJ_TYP_RPC

This object represents a YANG rpc statement.

  • It is used to define new <rpc> operations.

  • This object will only appear as a top-level statement within the module.

  • It does not have instances in the data tree.

  • Only 'rpcio' nodes are allowed to be children of an RPC node.

enumerator OBJ_TYP_RPCIO

This object represents a YANG input or output statement.

  • It is used to define input or output for an <rpc> operation.

  • This object will only appear as a child of an RPC node.

  • It does not have instances in the data tree. rpc input or output

enumerator OBJ_TYP_NOTIF

This object represents a YANG notification statement.

  • It is used to define new <notification> event types.

  • This object will only appear as a top-level statement within the module.

  • It does not have instances in the data tree.

enumerator OBJ_TYP_ANYDATA

This object represents a YANG 1.1 anydata data node.

enumerator OBJ_TYP_ACTION

This object represents a YANG 1.1 action schema node.

  • It is used to define a data-node specific operation.

  • The parent node must be a container or list

  • NMDA specifies all actions are accessed in <operational> not really data, YANG 1.1 only

obj_template_t

The following typedef is used to represent an object tree node:

struct obj_template_t

One YANG data-def-stmt.

Public Members

dlq_hdr_t qhdr

queue header

obj_type_t objtype

object type (def)

uint32 yang_hash

experimental: not used

uint32 flags

see OBJ_FL_* definitions

uint32 xflags

see OBJ_FL_* definitions

uint32 xflags2

see OBJ_FL_* definitions

uint32 uflags

see OBJ_FL_* definitions

uint8 silflags

see OBJ_FL_* definitions

uint8 sil_priority

picks SIL callback order

obj_testflags_t testflags

see AGT_TEST_FL_* definitions

obj_testflags_t desc_testflags

see AGT_TEST_FL_* definitions

ncx_error_t tkerr

file and line info for compiler

grp_template_t *grp

non-NULL == in a grp.datadefQ

obj_index_t index

object index for val_child ordering

obj_oid_t *oid

SNMP OID for this object (set if needed)

boolean set_snmp_flags

need SNMP flags

boolean xpath_oper_ok

object OK for referencing oper-data in XPath

struct obj_template_t_ *parent

backptr to parent

struct obj_template_t_ *usesobj

backptr to uses-obj if grouping expand

struct obj_template_t_ *augobj

backptr to augment-obj if augment expand

struct xpath_pcb_t_ *when

optional when clause

dlq_hdr_t metadataQ

Q of obj_metadata_t.

dlq_hdr_t appinfoQ

Q of ncx_appinfo_t.

dlq_hdr_t iffeatureQ

Q of ncx_iffeature_t.

dlq_hdr_t inherited_iffeatureQ

Q of obj_iffeature_ptr_t.

dlq_hdr_t inherited_whenQ

Q of ncx_backptr_t with node == xpath_pcb_t.

dlq_hdr_t *dataruleQ

Q obj NACM data-rule backptrs.

void *cbset

cbset is different based on the object type:

void *get2cb

get2fn is getcb_fn2_t for local GET2

struct ncx_module_t_ *mod

object module and namespace ID assigned at runtime this can be changed over and over as a uses statement is expanded.

The final expansion into a real object will leave the correct value in place

xmlns_id_t nsid

namespace ID assigned to the object at run-time

struct xpath_pcb_t_ *xpath_backptr[OBJ_NUM_XPATH_BACKPTRS]

xpath backptr caching support

dlq_hdr_t xpath_backptrQ

Q of ncx_back_ptr_t with node == xpath_pcb_t.

void *commit_test_cb

backptr to the commit_test record for this object which will only exist if this object has 'must' or 'when' statements defined within it

dlq_hdr_t *errmsgQ

custom error message used if this is the server running

void *yangmap_cb

if set, backptr to the nodemap in a YANG model mapping OBJ_IS_YANGMAP_SOURCE() indicates this is the source node OBJ_IS_YANGMAP_TARGET() indicates this is the target node

ncx_transaction_id_t edit_txid

current edit transaction ID for commit test pruning

ncx_transaction_id_t must_txid

current edit transaction ID for MUST test default nodes pruning

ncx_transaction_id_t when_txid

current edit transaction ID for WHEN test default nodes pruning

ncx_transaction_id_t leafref_txid

current edit transaction ID for intermediate leafref processing

union obj_template_t::def_ def
void *def_hook_cb

def_hook_cb is ncx_def_hook_cbfn_t callback function for Dynamic Default Hook callback.

ncx_sm_rootcb_t *rootcb

Schema Mount Control Block.

ncx_sid_t yang_sid

Each object specific variant has a YANG SID assigned for CBOR encoding.

The augment and uses variants do not actually get SID assignments.

uint32 yang_sid_tree

SID tree assignment if yang_sid is used.

union def_

object specific variants

Public Members

obj_container_t *container
obj_leaf_t *leaf
obj_leaflist_t *leaflist
obj_list_t *list
obj_choice_t *choic
obj_case_t *cas
obj_uses_t *uses
obj_refine_t *refine
obj_augment_t *augment
obj_rpc_t *rpc
obj_rpcio_t *rpcio
obj_notif_t *notif

obj_template_t Access Functions

The file ncx/obj.h contains many API functions so that object properties do not have to be accessed directly. The following table highlights the most commonly used functions. Refer to the H file for a complete definition of each API function.

obj_template_t Access Functions

obj_find_template

Find a top-level object template within a module.

obj_find_child

Find the specified child node within a complex object template . Skips over any nodes without names (augment, uses, etc.). Uses the module name that defines the obj_template_t to find a child.

obj_find_child_fast

Find the specified child node within a complex object template . Skips over any nodes without names (augment, uses, etc.). Uses the module namespace ID that to find a child.

obj_first_child

Get the first child node within a complex object template. Skips over any nodes without names.

obj_next_child

Get the next child node after the current specified child. Skips over any nodes without names.

obj_first_terminal_child

Get the first TERMINAL child object within a complex object template. Skips over any nodes without names.

obj_next_terminal_child

Get the next TERMINAL child object within a complex object template. Skips over any nodes without names.

obj_first_terminal_child_nokey

Get the first TERMINAL child object within a complex object template. Skips over any nodes without names and KEY leafs.

obj_next_terminal_child_nokey

Get the next TERMINAL child object within a complex object template. Skips over any nodes without names and KEY leafs.

obj_first_child_augok

Get the first child object within a complex object template. Skips over “refine” and “uses” nodes.

obj_next_child_augok

Get the next child object if the specified object has any children; return augment, not just obj_has_name. Skips over “refine” and “uses” nodes.

obj_first_child_deep

Get the first child node within a complex object template . Skips over any nodes without names, and also any choice and case nodes.

obj_next_child_deep

Get the next child object after the current specified child. Skips over any nodes without names, and also any choice and case nodes.

obj_previous_child

Get the previous child object if the specified object has any children. Skips over any nodes without names.

obj_last_child

Get the LAST child object within a complex object template. Skips over any nodes without names.

obj_find_case

Find the specified case object child object within the specific complex object node.

obj_find_type

Check if a typ_template_t in the obj typedefQ hierarchy.

obj_find_grouping

Check if a grp_template_t in the obj typedefQ hierarchy.

obj_find_key

Find a specific key component by key leaf identifier name.

obj_first_key

Get the first obj_key_t structure for the specified list object type.

obj_next_key

Get the next obj_key_t structure for the specified list object type.

obj_gen_object_id

Allocate and generate the YANG object ID for an object node.

obj_gen_object_id_prefix

Allocate and generate the YANG object ID for an object node. Uses the prefix in every node.

obj_gen_object_id_oid

Allocate and generate the YANG object ID for an object node. Uses the JSON/YANG module-name for prefix convention . Only print module name when namespace changes.

obj_gen_object_id_xpath

Allocate and generate the YANG object ID for an object node. Remove all conceptual choice and case nodes so the resulting string will represent the structure of the value tree for XPath searching.

obj_get_name

Get the object name string.

obj_set_name

Set the name field for this object.

obj_has_name

Return TRUE if the object has a name field.

obj_has_text_content

Return TRUE if the object has text content.

obj_get_status

Get the YANG status for the object.

obj_get_description

Get the YANG description statement for an object. Note that the server will always return a NULL pointer.

obj_get_alt_description

Get the alternate YANG description field for this obj ect. Check if any 'info', then 'help' appinfo nodes present.

obj_get_reference

Get the YANG reference statement for an object. Note that the server will always return a NULL pointer.

obj_get_config_flag

Get the YANG config statement value for an object.

obj_get_max_access

Get the YANG NCX max-access enumeration for an object. Return the explicit value or the inherited value.

obj_get_typestr

Get the name string for the type of an object.

obj_get_default

Get the YANG default value for an object.

obj_get_next_default

Get the next YANG default value for the specified object. Only leaf-list object type is supported.

obj_get_default_case

Get the name of the default case for a choice object.

obj_npcon_has_defaults

Check if the specified NP container has defaults within it. Must be a config object.

obj_get_level

Get the nest level for the specified object . Top-level is '1' . Does not count groupings as a level.

obj_has_typedefs

Check if the object has any nested typedefs in it . This must only be called if the object is defined in a grouping.

obj_get_typdef

Get the internal type definition for the leaf or leaf-list object.

obj_get_basetype

Get the internal base type enumeration for an object.

obj_get_mod_prefix

Get the module prefix for an object.

obj_get_mod_xmlprefix

Get the module prefix (XML format) for this object.

obj_get_mod_name

Get the module name containing an object.

obj_get_mod_version

Get the module revision date for the module containing an object.

obj_in_submodule

Check if the object is defined in a submodule.

obj_get_nsid

Get the internal XML namespace ID for an object.

obj_get_min_elements

Get the YANG min-elements value for a list or leaf-list object.

obj_get_max_elements

Get the YANG max-elements value for a list or leaf-list object.

obj_get_units

Get the YANG units field for a leaf or leaf-list object.

obj_get_parent

Get the parent object node for an object.

obj_get_real_parent

Get the parent object node for an object. Skips over choice and case.

obj_get_presence_string

Get the YANG presence statement for a container object.

obj_get_child_count

Get the number of child nodes for a complex object.

obj_get_fraction_digits

Get the YANG fraction-digits statement for a decimal64 leaf or leaf-list object.

obj_is_anyxml

Return TRUE if the object is YANG anyxml type.

obj_is_anydata

Return TRUE if the object is YANG anydata type.

obj_is_leaf

Return TRUE if the object is YANG leaf type.

obj_is_crypt_hash

Check if the object is a leaf of type crypt-hash. Return TRUE if the object is YANG crypt-hash leaf type.

obj_is_list

Return TRUE if the object is YANG list type.

obj_is_key

Return TRUE if the object is YANG key type.

obj_is_leafy

Return TRUE if the object is YANG leaf or leaf-list type.

obj_get_leaf_list_defset

Get the defset flag for a leaf-list. Return TRUE if leaf-list with original defaults.

obj_find_defval

Find a default for leaf-list. Return TRUE if found.

obj_is_container

Return TRUE if the object is YANG container type.

obj_is_choice

Return TRUE if the object is YANG choice type.

obj_is_case

Return TRUE if the object is YANG case type.

obj_is_uses

Return TRUE if the object is YANG uses type.

obj_is_terminal

Return TRUE if the object is YANG leaf, leaf-list, anyxml, or anydata type.

obj_is_mandatory

Return TRUE if the object is YANG mandatory statement.

obj_is_mandatory_when

Return TRUE if the object is YANG mandatory, but first check if any when statements are FALSE first.

obj_has_when_stmts

Check if any when statements apply to this object . Does not check if they are true, just any when statements present. Return TRUE if object has any when statement associated with it.

obj_is_cloned

Return TRUE if the object is expanded from a grouping or augment statement.

obj_is_augclone

Return TRUE if the object is expanded from an augment statement.

obj_is_augment

Return TRUE if the object is YANG augment statement.

obj_is_external_augment

Check if an object is an external augment. Return TRUE if an augment to another module.

obj_is_external_data_augment

Check if an object is an external augment of a data node. Return TRUE if an augment to data node in another module.

obj_is_refine

Return TRUE if the object is YANG refine statement.

obj_is_data

Check if the object is defined within data or within a notification or RPC instead.

obj_is_data_db

Return TRUE if the object is defined within a YANG database definition.

obj_is_data_node

Return TRUE if the object is a real node type.

obj_is_rpc

Return TRUE if the object is a YANG RPC type.

obj_rpc_has_input

Check if the RPC object has any real input children. Return TRUE if there are any input children.

obj_rpc_has_output

Check if the RPC object has any real output children. Return TRUE if there are any output children.

obj_is_rpcio

Return TRUE if the object is a YANG RPCIO type.

obj_is_action

Return TRUE if the object is a YANG action type.

obj_is_notif

Return TRUE if the object is a YANG notification type.

obj_is_empty

Return TRUE if object is empty of subclauses.

obj_in_rpc

Return TRUE if the object is defined within an RPC statement.

obj_in_notif

Return TRUE if the object is defined within a notification statement.

obj_is_xsdlist

Return TRUE if the object is marked as an XSD list.

obj_is_hidden

Return TRUE if object contains the ncx:hidden extension.

obj_is_root

Return TRUE if object contains the ncx:root extension.

obj_is_password

Return TRUE if object contains the ncx:password extension.

obj_is_cli

Return TRUE if object contains the ncx:cli extension.

obj_is_abstract

Return TRUE if object contains the ncx:abstract extension.

obj_is_xpath_string

Return TRUE if the object is a leaf or leaf-list containing an XPath string.

obj_is_schema_instance_string

Return TRUE if the object is a leaf or leaf-list containing a schema instance identifier string.

obj_is_secure

Return TRUE if object contains the nacm:secure extension.

obj_is_very_secure

Return TRUE if object contains the nacm:very-secure extension.

obj_is_sil_delete_children_first

Check if object is marked as ncx:sil-delete-children-first. Return TRUE if object contains ncx:sil-delete-children-first extension.

obj_is_block_user_create

Check if object is marked as ncx:user-write with create access disabled. Return TRUE if object is marked to block user create access.

obj_is_block_user_update

Check if object is marked as ncx:user-write with update access disabled.

Return TRUE if object is marked to block user update access.

obj_is_block_user_delete

Check if object is marked as ncx:user-write with delete access disabled.

Return TRUE if object is marked to block user delete access.

obj_is_system_ordered

Return TRUE if the list or leaf-list object is system ordered; FALSE if it is user ordered.

obj_is_np_container

Return TRUE if the object is a YANG non presence container.

obj_is_p_container

Return TRUE if the object is a YANG presence container.

obj_is_enabled

Return TRUE if the object is enabled; FALSE if any if-feature, when-stmt, or deviation-stmt has removed the object from the system.

obj_has_iffeature

Return TRUE if object has any if-feature statements.

obj_is_single_instance

Return TRUE if object is a single instance object.

obj_sort_children

Rearrange any child nodes in YANG schema order

obj_is_top

Check if the object is top-level object within the YANG module that defines it. Return TRUE if obj is a top-level object.

obj_is_datapath

Check if object is marked as a ywx:datapath object. Return TRUE if object is marked as datapath.

obj_has_children

Check if there are any accessible nodes within the object. Return TRUE if there are any accessible children.

obj_has_ro_children

Check if there are any accessible read-only child nodes within the object. Return TRUE if there are any accessible read-only children.

obj_has_ro_descendants

Check if there are any accessible read-only descendant nodes within the object. Return TRUE if there are any accessible read-only descendant.

obj_has_rw_children

Check if there are any accessible read-write child nodes within the object. Do not count list keys in this check. Return TRUE if there are any accessible read-write children.

obj_enabled_child_count

Get the count of the number of enabled child nodes for the object template. Returns number of enabled child nodes.

obj_get_keystr

Get the key string for this list object. Returns pointer to key string or NULL if none or not a list.

obj_is_supported

Check an RPC node to check if it is supported or not . It could be disabled at run-time without removing it. Return TRUE if object is supported.

obj_is_dup_local

Check if this object is one that has a duplicate sibling with the same local-name and different module namespace. Return if flagged as duplicate local-name.

obj_is_exclusive_rpc

Return TRUE if exclusive-rpc set; cannot be called by multiple sessions at once.

obj_parent_same_module

Check if the object parent object is the same. Return TRUE if parent from the same module or not sure. Return FALSE if parent not the same module and parent is not root.

obj_set_sil_priority

Set the SIL priority field.

obj_get_sil_priority

Get the SIL priority field.

obj_has_config_defaults

Check if the object itself or child nodes can have a default. Return TRUE if can have a default.

Object Tree Handling Examples

There are various API functions that can be used to locate desired objects. They differ widely by available information that you have prior the search and by desired search precision.

Find Top-Level Object

Find With the Object Name

If the top-level object name is unique, it is safe to find it by just its name.

obj_template_t *ncx_find_any_object(const xmlChar *objname)

Find any top-level object in any YANG module.

Check if an obj_template_t in in any module that matches the object name string

Parameters

objname -- object name to match

Returns

pointer to struct if present, NULL otherwise

const xmlChar *objname = (const xmlChar *)"interfaces";
obj_template_t *topobj = ncx_find_any_object(objname);
if (!topobj) {
    res = ERR_NCX_DEF_NOT_FOUND;
}

Find With the Module Pointer

If you know the module where the target object is located, and have the "ncx_module_t" pointer for the module, the following retrieval functions can be used:

obj_template_t *obj_find_template_top(ncx_module_t *mod, const xmlChar *modname, const xmlChar *objname)

Check if an obj_template_t in the mod->datadefQ or any of the include files visible to this module.

Top-level access is not tracked, so the 'test' variable is hard-wired to FALSE

Parameters
  • mod -- ncx_module to check

  • modname -- module name for the object (needed for augments) (may be NULL to match any 'objname' instance)

  • objname -- object name to find

Returns

pointer to struct if present, NULL otherwise

In this API function, the "module_name" parameter can be set to NULL.

obj_template_t *topobj =
    obj_find_template_top(mod, module_name, object_name);
if (!topobj) {
    res = ERR_NCX_DEF_NOT_FOUND;
}
obj_template_t *ncx_find_object(ncx_module_t *mod, const xmlChar *objname)

Find a top level module object.

Parameters
  • mod -- ncx_module to check

  • objname -- object name to find

Returns

pointer to struct if present, NULL otherwise

obj_template_t *topobj = ncx_find_object(mod, object_name);
if (!topobj) {
    res = ERR_NCX_DEF_NOT_FOUND;
}

Find With the Module Namespace ID

If the module namespace is known, then use this API function.

obj_template_t *ncx_find_object_nsid(xmlns_id_t nsid, const xmlChar *objname)

Find a top level module object by module NSID.

Parameters
  • nsid -- namespace ID to check

  • objname -- object name

Returns

pointer to struct if present, NULL otherwise

/* get the top object node using NSID of the OBJ */
obj_template_t *topobj = ncx_find_object_nsid(nsid, object_name);
if (!topobj) {
    res = ERR_NCX_DEF_NOT_FOUND;
}

Access Module Pointer

A module is usually loaded as server boot-time, but it can be loaded at run-time with the <load> or <load-bundle> operations.

The following code illustrates how the module pointer can be obtained during the module load procedure:

status_t ncxmod_load_module(const xmlChar *modname, const xmlChar *revision, dlq_hdr_t *savedevQ, ncx_module_t **retmod)

Determine the location of the specified module and then load it into the system, if not already loaded Main API for this module.

This is the only load module variant that checks if there are any errors recorded in the module or any of its dependencies !!! ONLY RETURNS TRUE IF MODULE AND ALL IMPORTS ARE LOADED OK !!!

Parameters
  • modname -- module name with no path prefix or file extension

  • revision -- optional revision date of 'modname' to find

  • savedevQ -- Q of ncx_save_deviations_t to use, if any

  • retmod -- address of return module (may be NULL)

Return values

*retmod -- pointer to requested module version

Returns

status

static status_t
     init_function (const xmlChar *modname,
                    const xmlChar *revision)
{

    ncx_module_t *mod = NULL;
    res = ncxmod_load_module(modname,
                             revision,
                             agt_get_savedevQ(),
                             &mod);
    if (res != NO_ERR) {
        return res;
    }

    // the "mod" pointer should be set if res == NO_ERR
}

To locate a module that is already loaded, use the following API function:

ncx_module_t *ncx_find_module(const xmlChar *modname, const xmlChar *revision)

Find a ncx_module_t in the ncx_sesmodQ.

These are the modules that are already loaded Does not look for submodule names if no module name found

Parameters
  • modname -- module name for the new module

  • revision -- module revision date for the new module (may be NULL)

Returns

module pointer if found or NULL if not found

// find a specific revision of the module
ncx_module_t *mod = ncx_find_module(modname, revision);
if (mod == NULL) {
    // find any revision of the module
    ncx_module_t *mod = ncx_find_module(modname, NULL);
    if (mod == NULL) {
        res = ERR_NCX_MOD_NOT_FOUND;
    }
}

Match Any Object

The second option to locate a top level object is to search through all the modules and try to match the object name string. The following API functions illustrate how to locate the top level object based on module name:

obj_template_t *ncx_match_any_object(const xmlChar *objname, ncx_name_match_t name_match, boolean alt_names, status_t *retres)

Match any object in any YANG module with extra search options.

Check if an obj_template_t in any module that matches the object name string (objname).

Use name_match to specify the type of name match desired Use alt_names to check objname as the alt-name for the object. This is usually only used in the CLI.

Parameters
  • objname -- object name to match

  • name_match -- name match mode enumeration

  • alt_names -- TRUE if alternate names should be checked after regular names; FALSE if not

  • retres -- address of return status

Return values

*retres -- return status

Returns

pointer to struct if present, NULL otherwise

status_t res = NO_ERR;
obj_template_t *topobj =
    ncx_match_any_object(object_name, NCX_MATCH_FIRST, alt_names, &res);

In the above example, the NCX_MATCH_FIRST parameter dictates the API function to stop search on the first match. Alternatively, the parameter can be changed to the following options:

Match Mode

Description

NCX_MATCH_EXACT

Try a case-sensitive exact-length match

NCX_MATCH_EXACT_NOCASE

Try a case-insensitive exact-length match

NCX_MATCH_ONE

Try a case-sensitive partial-name match

NCX_MATCH_ONE_NOCASE

Try a case-insensitive partial-name match

NCX_MATCH_FIRST

Try a case-sensitive first match

NCX_MATCH_FIRST_NOCASE

Try a case-insensitive first match

The 'alt_names' parameter dictates if alternative names should be checked in addition to the YANG node names. If set to TRUE the check will be applied; if set to FALSE the check will be ignored.

The '*res' return parameter may be set to ERR_NCX_MULTIPLE_MATCHES in case there are multiple matching objects available. In this case the function will not return any of the object templates. To search with the highest precision for a specific object. use NCX_MATCH_EXACT value and set alt_names to FALSE.

There is an extended version of the previous API function:

obj_template_t *ncx_match_any_object_ex(const xmlChar *modname, const xmlChar *objname, boolean dataonly, ncx_name_match_t name_match, boolean alt_names, status_t *retres)

Match any object in any YANG module with double extra search options.

Check if an obj_template_t in in any module that matches the object name string; extended parameters

Use name_match to specify the type of name match desired Use alt_names to check objname as the alt-name for the object. This is usually only used in the CLI. Use dataonly to search only for datastore objects

Parameters
  • modname -- module name of object (may be NULL to search all)

  • objname -- object name to match

  • dataonly -- TRUE for data nodes only; FALSE for any object type

  • name_match -- name match mode enumeration

  • alt_names -- TRUE if alternate names should be checked after regular names; FALSE if not

  • retres -- address of return status

Return values

*retres -- return status

Returns

pointer to struct if present, NULL otherwise

status_t res = NO_ERR;
obj_template_t *topobj =
     ncx_match_any_object_ex(modname,
                             object_name,
                             dataonly,
                             NCX_MATCH_EXACT,
                             alt_names,
                             &res);

In the above example, the module name is optional; however it is recommended. If it is present the API function will search only within specified module and will not try to search through all the modules.

The 'dataonly' parameter specifies whether the search function should try to match only data nodes. Set to "false" to match any node.

Check For Child Nodes

In order to verify if the current object has any available children, use the following API function:

boolean obj_has_children(obj_template_t *obj)

Check if there are any accessible nodes within the object.

Parameters

obj -- obj_template to check

Returns

TRUE if there are any accessible children

FALSE if no datadb child nodes found

boolean has_children = obj_has_children(topobj);

If there are any accessible data nodes within the object the function returns "true".

Find a Specific Child Node

The following example code illustrates how to locate a specific child object of the current top level object. The following API function checks for accessible names only. That means child nodes of choice, case will be present instead of the choice name or case name:

obj_template_t *obj_find_child(obj_template_t *obj, const xmlChar *modname, const xmlChar *objname)

Find a child object with the specified Qname.

This is the main API for finding object child nodes

Parameters
  • obj -- obj_template_t to check

  • modname -- module name for the object (needed for augments) (may be NULL to match any 'objname' instance)

  • objname -- object name to find

Returns

pointer to obj_template_t or NULL if not found

/* get the child obj template */
obj_template_t *child_obj = obj_find_child(topobj, modname, objname);

Find Choice or Case Child Node

To locate choice or case objects as well as other accessible names, use the following API function.

This function checks not only for accessible names. That means the choice name or case name will be preferred instead of their child nodes:

obj_template_t *obj_find_child_choice_case(obj_template_t *obj, const xmlChar *modname, const xmlChar *objname)

Find a child object with the specified Qname.

Parameters
  • obj -- the obj_template_t to check

  • modname -- the module name that defines the obj_template_t if it is NULL and first match will be done, and the module ignored (Name instead of QName)

  • objname -- the object name to find

Returns

pointer to obj_template_t or NULL if not found

/* get the child obj template */
obj_template_t *child_obj =
    obj_find_child_choice_case(topobj, modname, objname);

There is also an extended version of the previous API function:

obj_template_t *obj_find_child_ex(obj_template_t *obj, const xmlChar *modname, const xmlChar *objname, ncx_name_match_t match_names, boolean alt_names, boolean dataonly, status_t *retres)

Find a child object with the specified Qname extended match modes.

Parameters
  • obj -- obj_template_t to check

  • modname -- module name for the object (needed for augments) (may be NULL to match any 'objname' instance)

  • objname -- object name to find

  • match_names -- enum for selected match names mode

  • alt_names --

    TRUE if alt-name should be checked in addition to the YANG node name

    FALSE to check YANG names only

  • dataonly --

    TRUE to check just data nodes

    FALSE to check all nodes

  • retres -- address of return status

Return values

*retres -- set to return status

Returns

pointer to struct if present, NULL otherwise

/* get the child obj template */
status_t res = NO_ERR;
obj_template_t *child_obj =
    obj_find_child_ex(topobj,
                      modname,
                      objname,
                      NCX_MATCH_FIRST,
                      alt_names,
                      dataonly,
                      &res);

Object Child Node Traversal

To traverse the child nodes of a parent node (container, list, choice, case), the following set of API functions are used.

To get the first child object of the current object, the following API function can be used. Note, that this function skips over augments and uses:

obj_template_t *obj_first_child(obj_template_t *obj)

Get the first child object if the specified object has any children.

!!!! SKIPS OVER AUGMENT AND USES AND DISABLED OBJECTS !!!!

Parameters

obj -- obj_template_t to check for children

Returns

pointer to first child obj_template_t or NULL if not found

obj_template_t *first_obj = obj_first_child(topobj);

Similarly, the following API function can be used to locate the first terminal object. Note, that this function also skips over augments and uses:

obj_template_t *obj_first_terminal_child(obj_template_t *obj)

Get the first child object if the specified object has any children; MUST BE A TERMINAL NODE!!!

!!!! SKIPS OVER AUGMENT AND USES AND DISABLED OBJECTS !!!!

Parameters

obj -- obj_template_t to check for children

Returns

pointer to first child obj_template_t or NULL if not found

obj_template_t *first_obj = obj_first_terminal_child(topobj);

In order to get the next, the last, parent or previous child object or the terminal child object the following API functions can be used:

obj_template_t *obj_next_child(obj_template_t *obj)

Get the next child object if the specified object has any children.

!!!! SKIPS OVER AUGMENT AND USES !!!!

Parameters

obj -- obj_template_t to check

Returns

pointer to next child obj_template_t or NULL if not found

obj_template_t *next_obj = obj_next_child(first_obj);
obj_template_t *obj_next_terminal_child(obj_template_t *obj)

Get the next child object if the specified object has any children; MUST BE TERMINAL NODE!!

!!!! SKIPS OVER AUGMENT AND USES !!!!

Parameters

obj -- obj_template_t to check

Returns

pointer to next terminal child obj_template_t or NULL if not found

obj_template_t *next_obj = obj_next_terminal_child(first_obj);
obj_template_t *obj_previous_child(obj_template_t *obj)

Get the previous child object if the specified object has any children.

!!!! SKIPS OVER AUGMENT AND USES !!!!

Parameters

obj -- obj_template_t to check

Returns

pointer to previous child obj_template_t or NULL if not found

obj_template_t *prev_obj = obj_previous_child(next_obj);
obj_template_t *obj_last_child(obj_template_t *obj)

Get the last child object if the specified object has any children.

!!!! SKIPS OVER AUGMENT AND USES !!!!

Parameters

obj -- obj_template_t to check

Returns

pointer to last child obj_template_t or NULL if not found

obj_template_t *last_obj = obj_last_child(topobj);
obj_template_t *obj_get_parent(obj_template_t *obj)

Get the parent of the current object.

Parameters

obj -- object to check

Returns

pointer to the parent of this object or NULL if none

obj_template_t *topobj = obj_get_parent(next_obj);

The following example shows how the child object nodes can be traversed in forward order:

/* check all the child nodes forward */
obj_template_t *chobj = obj_first_child(obj);
for (; chobj; chobj = obj_next_child(chobj)) {

    const xmlChar *modname = obj_get_mod_name(chobj);
    const xmlChar *objname = obj_get_name(chobj);

    /* process objects here */

}

The following example shows how the child object nodes can be traversed in reverse order:

/* check all the child nodes reverse */
obj_template_t *chobj = obj_last_child(obj);
for (; chobj; chobj = obj_prev_child(chobj)) {

    const xmlChar *modname = obj_get_mod_name(chobj);
    const xmlChar *objname = obj_get_name(chobj);

    /* process objects here */

}

Process Ancestor Nodes

In order to loop through ancestor entries and process them as required, the following code may be used:

boolean obj_is_root(const obj_template_t *obj)

Check if object is marked as a root object.

Parameters

obj -- obj_template to check

Returns

TRUE if object is marked as ncx:root; FALSE if not

/* go through the ancestor entries and process them as needed */
obj_template_t *testobj = obj_get_parent(chobj);
while (testobj) {
    /* process parent objects here */
    testobj = obj_get_parent(testobj);
    if (testobj && obj_is_root(testobj)) {
        testobj = NULL;
    }
}

The 'obj_is_root' API function signals when to stop. It is also possible to have a NULL pointer returned. That indicates you reached the top root container. This container must not be modified, accessed or changed in any manner.