sysrepo  3.0.0
YANG-based system repository for all-around configuration management.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Value Manipulation Utilities

Set of functions facilitating simplified manipulation with sysrepo values. It is not necessary to use these functions in any scenario, values can be allocated and initialized manually (just remember to set all uninitialized members to zero!). More...

Functions

int sr_dup_val (const sr_val_t *value, sr_val_t **value_dup)
 Duplicate value (with or without Sysrepo memory context) into a new instance with memory context. More...
 
int sr_dup_values (const sr_val_t *values, size_t count, sr_val_t **values_dup)
 Duplicate values (with or without Sysrepo memory context) into a new array with memory context. More...
 
int sr_equal_val (const sr_val_t *value1, const sr_val_t *value2)
 Check if two sr_val_t values are equal. They are considered unequal if their type, origin, xpath, default flag, or actual value differ. More...
 
int sr_new_val (const char *xpath, sr_val_t **value)
 Allocate an instance of Sysrepo value. More...
 
int sr_new_values (size_t value_cnt, sr_val_t **values)
 Allocate an array of sysrepo values. More...
 
int sr_print_val (const sr_val_t *value)
 Print sysrepo value to STDOUT. More...
 
int sr_print_val_fd (int fd, const sr_val_t *value)
 Print sysrepo value to the specified file descriptor. More...
 
int sr_print_val_mem (char **mem_p, const sr_val_t *value)
 Print sysrepo value into a newly allocated memory buffer. The caller is expected to eventually free the returned string. More...
 
int sr_print_val_stream (FILE *stream, const sr_val_t *value)
 Print sysrepo value to the specified output file stream. More...
 
int sr_realloc_values (size_t old_value_cnt, size_t new_value_cnt, sr_val_t **values)
 Reallocate an array of sysrepo values. More...
 
int sr_tree_to_val (const struct lyd_node *data, const char *path, sr_val_t **value)
 Finds single node from given struct lyd_node type data tree and converts it to sr_val_t. More...
 
int sr_tree_to_values (const struct lyd_node *data, const char *xpath, sr_val_t **values, size_t *value_cnt)
 Finds subtree from given struct lyd_node type data tree and converts it to sr_val_t. More...
 
int sr_val_build_str_data (sr_val_t *value, sr_val_type_t type, const char *format,...)
 Store data of string type into the Sysrepo value data. The actual data will be built from the a format string and a variable arguments list. More...
 
int sr_val_build_xpath (sr_val_t *value, const char *format,...)
 Set/change xpath of a Sysrepo value to a new one, built from a format string and a variable arguments list. More...
 
int sr_val_set_str_data (sr_val_t *value, sr_val_type_t type, const char *string_val)
 Store data of string type into the Sysrepo value data. More...
 
int sr_val_set_xpath (sr_val_t *value, const char *xpath)
 Set/change xpath of a Sysrepo value. More...
 
int sr_val_to_buff (const sr_val_t *value, char buffer[], size_t size)
 Converts value to string and prints it to the provided buffer including terminating NULL byte. More...
 
char * sr_val_to_str (const sr_val_t *value)
 Converts value to string representation. More...
 

Detailed Description

Set of functions facilitating simplified manipulation with sysrepo values. It is not necessary to use these functions in any scenario, values can be allocated and initialized manually (just remember to set all uninitialized members to zero!).

Using these utilities, however, has several benefits. Firstly, all the memory allocations associated with creating values and setting their attributes get hidden behind these functions. The "old-way" was (and still is) to set xpath and string values using strdup, which may repeat in applications communicating with sysrepo very often and becomes very annoying to write. Secondly, the programmer may actually forget to copy or give-up on the ownership of a string passed to sysrepo value which will then get unexpectedly deallocated in sr_free_val or sr_free_values.

Note
It is best not to use sr_val_t at all and use struct lyd_node instead. Then the full libyang API is available.

Function Documentation

int sr_dup_val ( const sr_val_t value,
sr_val_t **  value_dup 
)

Duplicate value (with or without Sysrepo memory context) into a new instance with memory context.

Parameters
[in]valueSysrepo value to duplicate
[out]value_dupReturned duplicate of the input value.
int sr_dup_values ( const sr_val_t values,
size_t  count,
sr_val_t **  values_dup 
)

Duplicate values (with or without Sysrepo memory context) into a new array with memory context.

Parameters
[in]valuesArray of sysrepo values to duplicate
[in]countSize of the array to duplicate.
[out]values_dupReturned duplicate of the input array.
int sr_equal_val ( const sr_val_t value1,
const sr_val_t value2 
)

Check if two sr_val_t values are equal. They are considered unequal if their type, origin, xpath, default flag, or actual value differ.

Parameters
[in]value1Sysrepo value to compare
[in]value2Sysrepo value to compare
Returns
1 if equal, 0 otherwise
int sr_new_val ( const char *  xpath,
sr_val_t **  value 
)

Allocate an instance of Sysrepo value.

Parameters
[in]xpathXpath to set for the newly allocated value. Can be NULL.
[out]valueReturned newly allocated value.
int sr_new_values ( size_t  value_cnt,
sr_val_t **  values 
)

Allocate an array of sysrepo values.

Parameters
[in]value_cntLength of the array to allocate.
[out]valuesReturned newly allocated array of values.
int sr_print_val ( const sr_val_t value)

Print sysrepo value to STDOUT.

Parameters
[in]valueSysrepo value to print.
int sr_print_val_fd ( int  fd,
const sr_val_t value 
)

Print sysrepo value to the specified file descriptor.

Parameters
[in]fdFile descriptor to print the value into.
[in]valueSysrepo value to print.
int sr_print_val_mem ( char **  mem_p,
const sr_val_t value 
)

Print sysrepo value into a newly allocated memory buffer. The caller is expected to eventually free the returned string.

Parameters
[in]mem_pPointer to store the resulting dump.
[in]valueSysrepo value to print.
int sr_print_val_stream ( FILE *  stream,
const sr_val_t value 
)

Print sysrepo value to the specified output file stream.

Parameters
[in]streamOutput file stream to print the value into.
[in]valueSysrepo value to print.
int sr_realloc_values ( size_t  old_value_cnt,
size_t  new_value_cnt,
sr_val_t **  values 
)

Reallocate an array of sysrepo values.

Parameters
[in]old_value_cntCurrent length of the value array.
[in]new_value_cntDesired length of the value array.
[in,out]valuesReturned newly allocated/enlarged array of values.
int sr_tree_to_val ( const struct lyd_node *  data,
const char *  path,
sr_val_t **  value 
)

Finds single node from given struct lyd_node type data tree and converts it to sr_val_t.

Helps to achive better performance by avoiding multiple sr_get_item calls, Applications can get running data tree beforehand and use this API multiple times to get sr_val_t type value.

Parameters
[in]dataRoot node of a data tree in which to search for and return value.
[in]pathPath of the data element to be retrieved.
[out]valueRequested node, allocated dynamically (free using sr_free_val).
Returns
Error code (SR_ERR_OK on success, SR_ERR_INVAL_ARG if multiple nodes match the path, SR_ERR_NOT_FOUND if no nodes match the path).
int sr_tree_to_values ( const struct lyd_node *  data,
const char *  xpath,
sr_val_t **  values,
size_t *  value_cnt 
)

Finds subtree from given struct lyd_node type data tree and converts it to sr_val_t.

Helps to achive better performance by avoiding multiple sr_get_items calls, Applications can get running data tree beforehand and use this API multiple times to get sr_val_t type values.

Parameters
[in]dataRoot node of a data tree in which to search for and return value.
[in]xpathXPath of the data elements to be retrieved.
[out]valuesArray of requested nodes, allocated dynamically (free using sr_free_values).
[out]value_cntNumber of returned elements in the values array.
Returns
Error code (SR_ERR_OK on success).
int sr_val_build_str_data ( sr_val_t value,
sr_val_type_t  type,
const char *  format,
  ... 
)

Store data of string type into the Sysrepo value data. The actual data will be built from the a format string and a variable arguments list.

Parameters
[in]valueSysrepo value to edit.
[in]typeExact type of the data.
[in]formatFormat string used to build the data.
int sr_val_build_xpath ( sr_val_t value,
const char *  format,
  ... 
)

Set/change xpath of a Sysrepo value to a new one, built from a format string and a variable arguments list.

Parameters
[in]valueSysrepo value to change the xpath of.
[in]formatFormat string used to build XPath.
int sr_val_set_str_data ( sr_val_t value,
sr_val_type_t  type,
const char *  string_val 
)

Store data of string type into the Sysrepo value data.

Parameters
[in]valueSysrepo value to edit.
[in]typeExact type of the data.
[in]string_valString value to set.
int sr_val_set_xpath ( sr_val_t value,
const char *  xpath 
)

Set/change xpath of a Sysrepo value.

Parameters
[in]valueSysrepo value to change the xpath of.
[in]xpathXPath to set.
int sr_val_to_buff ( const sr_val_t value,
char  buffer[],
size_t  size 
)

Converts value to string and prints it to the provided buffer including terminating NULL byte.

Parameters
[in]value
[in]buffer- buffer provided by caller where the data will be printed
[in]size- the size of the buffer
Returns
number of characters that was written in case of success, otherwise number of characters which would have been written if enough space had been available (excluding terminating NULL byte)
Note
In case of SR_DECIMAL64_T type, number of fraction digits doesn't have to correspond to schema.
char* sr_val_to_str ( const sr_val_t value)

Converts value to string representation.

Parameters
[in]value
Returns
allocated string representation of value (must be freed by caller), NULL in case of error
Note
In case of SR_DECIMAL64_T type, number of fraction digits doesn't have to correspond to schema.