Assume you know the name of the target object and your goal is to obtain its object template.
Assume the object is a top level object in the YANG module, in this case you cannot use obj_find_child or analogous API function that are using parent object to locate a child object.
In this scenario you have two options, use module structure to locate desired objects or search through all the modules and try to match the object name string.
If you know the module where the target object is located, the following retrieval function can be used:
...
/* get the top object node */
obj_template_t *topobj =
obj_find_template_top(mod,
module_name,
object_name);
if (!topobj) {
res = ERR_NCX_DEF_NOT_FOUND;
}
...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 *topobj = ncx_match_any_object(object_name, NCX_MATCH_FIRST, alt_names, &res); ...
In the above example, 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 acase-sensitive exact-length match |
| NCX_MATCH_EXACT_NOCASE | Try acase-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 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. If you want to search with the highest precision for a specific object you should consider NCX_MATCH_EXACT value and set alt_names to FALSE.
Alternatively, you can use the following extended version of the previous API function:
...
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 data only parameters pecifies whether the search function should try to match only data nodes or not. Set to TRUE if it should.
The*res 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. If you want to search with the highest precision for a specific object you should consider NCX_MATCH_EXACT value and set alt_names to FALSE.
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 actual child nodes of choice, case will be located instead of the choice name or case name:
...
/* get the child obj template */
obj_template_t *child_obj =
obj_find_child(topobj,
modname,
objname);
...In case you want to locate choice or case objects as well as other accessible names you may consider to 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:
...
/* get the child obj template */
obj_template_t *child_obj =
obj_find_child_choice_case(topobj,
modname,
objname);
...Alternatively, you can use the following extended version of the previous API functions:
...
/* get the child obj template */
obj_template_t *child_obj =
obj_find_child_ex(topobj,
modname,
objname,
NCX_MATCH_FIRST,
alt_names,
dataonly,
&res);
...