sysrepo  2.12.0
YANG-based system repository for all-around configuration management.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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. More...
 
void sr_free_val (sr_val_t *value)
 Free sr_val_t structure and all memory allocated within it. More...
 
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). More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 

Detailed Description


Data Structure Documentation

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

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]connConnection to use.
[in]treelibyang data tree, ownership is passed to data in all cases.
[out]dataCreated SR data, free with sr_release_data().
Returns
Error code (SR_ERR_OK on success), even on error tree is freed and context released.
void sr_free_val ( sr_val_t value)

Free sr_val_t structure and all memory allocated within it.

Parameters
[in]valueValue to be freed.
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]valuesArray of values to be freed.
[in]countNumber of elements stored in the array.
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. /* 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]sessionSession (DS-specific) to use.
[in]xpathXPath selecting root nodes of subtrees to be retrieved.
[in]max_depthMaximum 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_msOperational callback timeout in milliseconds. If 0, default is used.
[in]optsOptions overriding default get behaviour.
[out]dataSR 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).
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]sessionSession (DS-specific) to use.
[in]pathPath of the data element to be retrieved.
[in]timeout_msOperational callback timeout in milliseconds. If 0, default is used.
[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_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]sessionSession (DS-specific) to use.
[in]xpathXPath of the data elements to be retrieved.
[in]timeout_msOperational callback timeout in milliseconds. If 0, default is used.
[in]optsOptions overriding default get behaviour.
[out]valuesArray of requested nodes, if any, 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_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]sessionSession (DS-specific) to use.
[in]pathPath of the data element to be retrieved.
[in]timeout_msOperational callback timeout in milliseconds. If 0, default is used.
[out]nodeSR 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).
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]sessionSession (DS-specific) to use.
[in]pathPath selecting the root node of the subtree to be retrieved.
[in]timeout_msOperational callback timeout in milliseconds. If 0, default is used.
[out]subtreeSR 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).
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]dataSR data to release and free.
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]sessionSession (not DS-specific) to use.
[in]treelibyang data tree, ownership is passed to data in all cases.
[out]dataCreated SR data, free with sr_release_data().
Returns
Error code (SR_ERR_OK on success), even on error tree is freed and context released.