Loading...
Searching...
No Matches
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.
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.
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.
int | sr_new_val (const char *xpath, sr_val_t **value)
| Allocate an instance of Sysrepo value.
int | sr_new_values (size_t value_cnt, sr_val_t **values)
| Allocate an array of sysrepo values.
int | sr_print_val (const sr_val_t *value)
| Print sysrepo value to STDOUT.
int | sr_print_val_fd (int fd, const sr_val_t *value)
| Print sysrepo value to the specified file descriptor.
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.
int | sr_print_val_stream (FILE *stream, const sr_val_t *value)
| Print sysrepo value to the specified output file stream.
int | sr_realloc_values (size_t old_value_cnt, size_t new_value_cnt, sr_val_t **values)
| Reallocate an array of sysrepo 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.
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.
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.
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.
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.
int | sr_val_set_xpath (sr_val_t *value, const char *xpath)
| Set/change xpath of a Sysrepo value.
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.
char * | sr_val_to_str (const sr_val_t *value)
| Converts value to string representation.

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

## sr_dup_val()

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] | value | Sysrepo value to duplicate
  [out] | value_dup | Returned duplicate of the input value.

## sr_dup_values()

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] | values | Array of sysrepo values to duplicate
  [in] | count | Size of the array to duplicate.
  [out] | values_dup | Returned duplicate of the input array.

## sr_equal_val()

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] | value1 | Sysrepo value to compare
  [in] | value2 | Sysrepo value to compare

Returns
  1 if equal, 0 otherwise

## sr_new_val()

int sr_new_val | ( | const char * | xpath,
|  | sr_val_t ** | value )

Allocate an instance of Sysrepo value.

Parameters

  [in] | xpath | Xpath to set for the newly allocated value. Can be NULL.
  [out] | value | Returned newly allocated value.

## sr_new_values()

int sr_new_values | ( | size_t | value_cnt,
|  | sr_val_t ** | values )

Allocate an array of sysrepo values.

Parameters

  [in] | value_cnt | Length of the array to allocate.
  [out] | values | Returned newly allocated array of values.

## sr_print_val()

int sr_print_val | ( | const sr_val_t * | value | ) |

Print sysrepo value to STDOUT.

Parameters

  [in] | value | Sysrepo value to print.

## sr_print_val_fd()

int sr_print_val_fd | ( | int | fd,
|  | const sr_val_t * | value )

Print sysrepo value to the specified file descriptor.

Parameters

  [in] | fd | File descriptor to print the value into.
  [in] | value | Sysrepo value to print.

## sr_print_val_mem()

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_p | Pointer to store the resulting dump.
  [in] | value | Sysrepo value to print.

## sr_print_val_stream()

int sr_print_val_stream | ( | FILE * | stream,
|  | const sr_val_t * | value )

Print sysrepo value to the specified output file stream.

Parameters

  [in] | stream | Output file stream to print the value into.
  [in] | value | Sysrepo value to print.

## sr_realloc_values()

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_cnt | Current length of the value array.
  [in] | new_value_cnt | Desired length of the value array.
  [in,out] | values | Returned newly allocated/enlarged array of values.

## sr_tree_to_val()

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] | data | Root node of a data tree in which to search for and return value.
  [in] | path | Path of the data element to be retrieved.
  [out] | value | Requested 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).

## sr_tree_to_values()

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] | data | Root node of a data tree in which to search for and return value.
  [in] | xpath | XPath of the data elements to be retrieved.
  [out] | values | Array of requested nodes, allocated dynamically (free using sr_free_values).
  [out] | value_cnt | Number of returned elements in the values array.

Returns
  Error code (SR_ERR_OK on success).

## sr_val_build_str_data()

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] | value | Sysrepo value to edit.
  [in] | type | Exact type of the data.
  [in] | format | Format string used to build the data.

## sr_val_build_xpath()

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] | value | Sysrepo value to change the xpath of.
  [in] | format | Format string used to build XPath.

## sr_val_set_str_data()

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] | value | Sysrepo value to edit.
  [in] | type | Exact type of the data.
  [in] | string_val | String value to set.

## sr_val_set_xpath()

int sr_val_set_xpath | ( | sr_val_t * | value,
|  | const char * | xpath )

Set/change xpath of a Sysrepo value.

Parameters

  [in] | value | Sysrepo value to change the xpath of.
  [in] | xpath | XPath to set.

## sr_val_to_buff()

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.

## sr_val_to_str()

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.