Loading...
Searching...
No Matches
Getting Data API

## Data Structures

struct | sr_data_t
| Structure that safely wraps libyang data and prevents unexpected context changes. More...

## Functions

int | sr_acquire_data (sr_conn_ctx_t *conn, struct lyd_node *tree, sr_data_t **data)
| Acquire libyang data tree together with its context lock in a SR data structure.
void | sr_free_val (sr_val_t *value)
| Free sr_val_t structure and all memory allocated within it.
void | sr_free_values (sr_val_t *values, size_t count)
| Free array of sr_val_t structures (and all memory allocated within of each array element).
int | sr_get_data (sr_session_ctx_t *session, const char *xpath, uint32_t max_depth, uint32_t timeout_ms, const sr_get_options_t opts, sr_data_t **data)
| Retrieve a tree whose root nodes match the provided XPath. Data are represented as libyang subtrees.
int | sr_get_item (sr_session_ctx_t *session, const char *path, uint32_t timeout_ms, sr_val_t **value)
| Retrieve a single data element selected by the provided path. Data are represented as sr_val_t structures.
int | sr_get_items (sr_session_ctx_t *session, const char *xpath, uint32_t timeout_ms, const sr_get_options_t opts, sr_val_t **values, size_t *value_cnt)
| Retrieve an array of data elements selected by the provided XPath. Data are represented as sr_val_t structures.
int | sr_get_node (sr_session_ctx_t *session, const char *path, uint32_t timeout_ms, sr_data_t **node)
| Retrieve a single value matching the provided XPath. Data are represented as a single libyang node.
int | sr_get_subtree (sr_session_ctx_t *session, const char *path, uint32_t timeout_ms, sr_data_t **subtree)
| Retrieve a single subtree whose root node is selected by the provided path. Data are represented as libyang subtrees.
void | sr_release_data (sr_data_t *data)
| Release SR data structure, whoch consists of freeing the data tree, releasing the context, and freeing the structure itself.
int | sr_session_acquire_data (sr_session_ctx_t *session, struct lyd_node *tree, sr_data_t **data)
| Acquire libyang data tree together with its context lock in a SR data structure.

## Detailed Description

## Data Structure Documentation

## sr_data_t

struct sr_data_t

Structure that safely wraps libyang data and prevents unexpected context changes.

Definition at line 200 of file sysrepo_types.h.

Data Fields
const sr_conn_ctx_t * | conn | Connection whose context was used for creating `tree`.
struct lyd_node * | tree | Arbitrary libyang data, it can be modified

## Function Documentation

## sr_acquire_data()

int sr_acquire_data | ( | sr_conn_ctx_t * | conn,
|  | struct lyd_node * | tree,
|  | sr_data_t ** | data )

Acquire libyang data tree together with its context lock in a SR data structure.

Similar functionality as sr_session_acquire_data().

Parameters

  [in] | conn | Connection to use.
  [in] | tree | libyang data tree, ownership is passed to `data` in all cases.
  [out] | data | Created SR data, free with sr_release_data().

Returns
  Error code (SR_ERR_OK on success), even on error `tree` is freed and context released.

## sr_free_val()

void sr_free_val | ( | sr_val_t * | value | ) |

Free sr_val_t structure and all memory allocated within it.

Parameters

  [in] | value | Value to be freed.

## sr_free_values()

void sr_free_values | ( | sr_val_t * | values,
|  | size_t | count )

Free array of sr_val_t structures (and all memory allocated within of each array element).

Parameters

  [in] | values | Array of values to be freed.
  [in] | count | Number of elements stored in the array.

## sr_get_data()

int sr_get_data | ( | sr_session_ctx_t * | session,
|  | const char * | xpath,
|  | uint32_t | max_depth,
|  | uint32_t | timeout_ms,
|  | const sr_get_options_t | opts,
|  | sr_data_t ** | data )

Retrieve a tree whose root nodes match the provided XPath. Data are represented as libyang subtrees.

Top-level trees are always returned so if an inner node is selected, all of its descendants and its direct parents (lists also with keys) are returned.

If the subtree selection process results in too many node overlaps, the cost of the operation may be unnecessarily big. As an example, a common XPath expression //. is normally used to select all nodes in a data tree, but for this operation it would result in an excessive duplication of data nodes. Since all the descendants of each matched node are returned implicitly, // in the XPath should never be used (i.e. /\asterisk is the correct XPath for all the nodes).

Required READ access, but if the access check fails, the module data are simply ignored without an error.

Parameters

  [in] | session | Session (DS-specific) to use.
  [in] | xpath | XPath selecting root nodes of subtrees to be retrieved.
  [in] | max_depth | Maximum depth of the selected subtrees. 0 is unlimited, 1 will not return any descendant nodes. If a list should be returned, its keys are always returned as well.
  [in] | timeout_ms | Operational callback timeout in milliseconds. If 0, default is used.
  [in] | opts | Options overriding default get behaviour.
  [out] | data | SR data with connected top-level data trees of all the requested data. NULL if none found.

Returns
  Error code (SR_ERR_OK on success, SR_ERR_NOT_FOUND if xpath is invalid - no nodes will ever match it).

## sr_get_item()

int sr_get_item | ( | sr_session_ctx_t * | session,
|  | const char * | path,
|  | uint32_t | timeout_ms,
|  | sr_val_t ** | value )

Retrieve a single data element selected by the provided path. Data are represented as sr_val_t structures.

If the path identifies an empty leaf, a list or a container, the value has no data filled in and its type is set properly (SR_LEAF_EMPTY_T / SR_LIST_T / SR_CONTAINER_T / SR_CONTAINER_PRESENCE_T).

Required READ access, but if the access check fails, the module data are simply ignored without an error.

See also
  Use sr_get_items for retrieving larger chunks of data from the datastore. Since it retrieves the data from datastore in larger chunks, it can work much more efficiently than multiple sr_get_item calls.

Parameters

  [in] | session | Session (DS-specific) to use.
  [in] | path | Path of the data element to be retrieved.
  [in] | timeout_ms | Operational callback timeout in milliseconds. If 0, default is used.
  [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_get_items()

int sr_get_items | ( | sr_session_ctx_t * | session,
|  | const char * | xpath,
|  | uint32_t | timeout_ms,
|  | const sr_get_options_t | opts,
|  | sr_val_t ** | values,
|  | size_t * | value_cnt )

Retrieve an array of data elements selected by the provided XPath. Data are represented as sr_val_t structures.

All data elements are transferred within one message from the datastore, which is more efficient that calling multiple sr_get_item calls.

Required READ access, but if the access check fails, the module data are simply ignored without an error.

Parameters

  [in] | session | Session (DS-specific) to use.
  [in] | xpath | XPath of the data elements to be retrieved.
  [in] | timeout_ms | Operational callback timeout in milliseconds. If 0, default is used.
  [in] | opts | Options overriding default get behaviour.
  [out] | values | Array of requested nodes, if any, 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_get_node()

int sr_get_node | ( | sr_session_ctx_t * | session,
|  | const char * | path,
|  | uint32_t | timeout_ms,
|  | sr_data_t ** | node )

Retrieve a single value matching the provided XPath. Data are represented as a single libyang node.

Compared to sr_get_data() or sr_get_subtree() this function is a bit more efficient because it returns only the selected node which is disconnected from its parents.

Required READ access, but if the access check fails, the module data are simply ignored without an error.

Parameters

  [in] | session | Session (DS-specific) to use.
  [in] | path | Path of the data element to be retrieved.
  [in] | timeout_ms | Operational callback timeout in milliseconds. If 0, default is used.
  [out] | node | SR data with the found node. NULL if none found.

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_get_subtree()

int sr_get_subtree | ( | sr_session_ctx_t * | session,
|  | const char * | path,
|  | uint32_t | timeout_ms,
|  | sr_data_t ** | subtree )

Retrieve a single subtree whose root node is selected by the provided path. Data are represented as libyang subtrees.

The functions returns values and all associated information stored under the root node and all its descendants. While the same data can be obtained using sr_get_items in combination with the expressive power of XPath addressing, the recursive nature of the output data type also preserves the hierarchical relationships between data elements.

Required READ access, but if the access check fails, the module data are simply ignored without an error.

Parameters

  [in] | session | Session (DS-specific) to use.
  [in] | path | Path selecting the root node of the subtree to be retrieved.
  [in] | timeout_ms | Operational callback timeout in milliseconds. If 0, default is used.
  [out] | subtree | SR data with the requested subtree. NULL if none found.

Returns
  Error code (SR_ERR_OK on success, SR_ERR_INVAL_ARG if multiple nodes match the path, SR_ERR_NOT_FOUND if path is invalid - no nodes will ever match it).

## sr_release_data()

void sr_release_data | ( | sr_data_t * | data | ) |

Release SR data structure, whoch consists of freeing the data tree, releasing the context, and freeing the structure itself.

Parameters

  [in] | data | SR data to release and free.

## sr_session_acquire_data()

int sr_session_acquire_data | ( | sr_session_ctx_t * | session,
|  | struct lyd_node * | tree,
|  | sr_data_t ** | data )

Acquire libyang data tree together with its context lock in a SR data structure.

Before a libyang data tree used in sysrepo can be created, sr_acquire_context() must be called to get the connection context. If the created libyang data tree is then passed to this function, it will handle the full cleanup of releasing the context and freeing the data.

Parameters

  [in] | session | Session (not DS-specific) to use.
  [in] | tree | libyang data tree, ownership is passed to `data` in all cases.
  [out] | data | Created SR data, free with sr_release_data().

Returns
  Error code (SR_ERR_OK on success), even on error `tree` is freed and context released.