Loading...
Searching...
No Matches
Operational Data Subscription API

## Functions

int | sr_oper_get_subscribe (sr_session_ctx_t *session, const char *module_name, const char *path, sr_oper_get_items_cb callback, void *private_data, sr_subscr_options_t opts, sr_subscription_ctx_t **subscription)
| Register for providing operational data at the given path.
int | sr_oper_poll_subscribe (sr_session_ctx_t *session, const char *module_name, const char *path, uint32_t valid_ms, sr_subscr_options_t opts, sr_subscription_ctx_t **subscription)
| Start periodic retrieval and caching of operational data at the given path.
typedef int(* | sr_oper_get_items_cb) (sr_session_ctx_t *session, uint32_t sub_id, const char *module_name, const char *path, const char *request_xpath, uint32_t operation_id, struct lyd_node **parent, void *private_data)
| Callback to be called when operational data at the selected xpath are requested. Data are represented as libyang subtrees.

## Detailed Description

## Typedef Documentation

## sr_oper_get_items_cb

typedef int(* sr_oper_get_items_cb) (sr_session_ctx_t *session, uint32_t sub_id, const char *module_name, const char *path, const char *request_xpath, uint32_t operation_id, struct lyd_node **parent, void *private_data)

Callback to be called when operational data at the selected xpath are requested. Data are represented as libyang subtrees.

When the callback is called, the data parent is provided. Any parent children (selected by `path`) are removed and should be provided by the callback instead, if they exist. Callback handler can provide any data matching the `path` but in case there are other nested subscriptions, they will be called after this one (and when they are called, their parent children will again be removed which can result in nodes provided by the original callback being lost).

Note
  Callback must not modify the same module operational subscriptions, it would result in a deadlock.

Parameters

  [in] | session | Implicit session (do not stop) with information about the event originator session IDs.
  [in] | sub_id | Subscription ID.
  [in] | module_name | Name of the affected module.
  [in] | path | Path identifying the subtree that is supposed to be provided, same as the one used for the subscription.
  [in] | request_xpath | XPath as requested by a client. Can be NULL.
  [in] | operation_id | Operation ID of the current operation used for all the callbacks and events.
  [in,out] | parent | Pointer to an existing parent of the requested nodes. Is NULL for top-level nodes. Caller is supposed to append the requested nodes to this data subtree and return either the original parent or a top-level node.
  [in] | private_data | Private context opaque to sysrepo, as passed to sr_oper_get_subscribe call.

Returns
  User error code (SR_ERR_OK on success).

Definition at line 696 of file sysrepo_types.h.

## Function Documentation

## sr_oper_get_subscribe()

int sr_oper_get_subscribe | ( | sr_session_ctx_t * | session,
|  | const char * | module_name,
|  | const char * | path,
|  | sr_oper_get_items_cb | callback,
|  | void * | private_data,
|  | sr_subscr_options_t | opts,
|  | sr_subscription_ctx_t ** | subscription )

Register for providing operational data at the given path.

Usual behaviour is only ONE subscription for ONE XPath. When subscribing to the same XPath that was used in some previous subscription, SR_SUBSCR_OPER_MERGE flag has to be used. Every such subscription (for the same XPath) has its internal priority based on the order in which it was subscribed. This priority influences merging the operational data from multiple subscriptions with the same XPath. Operational data returned by later subscriptions overwrite the same data from any previous subscriptions. When retrieving data all subscription callbacks with the same XPath are called simultaneously (to actually achieve this, `subscription` should be different for each subscription so that there are separate threads listening for each of the events, otherwise the thread will call the callback sequentially).

Required WRITE access.

Note
  Be aware of some specific threading limitations.

Parameters

  [in] | session | Session (not DS-specific) to use.
  [in] | module_name | Name of the affected module.
  [in] | path | Path identifying the subtree (not strictly required, all list/leaf-list instances are also valid, for example) which the provider is able to provide. Predicates can be used to provide only specific instances of nodes. Before calling this callback, any existing data matching this path are deleted (unless modified by `opts`).
  [in] | callback | Callback to be called when the operational data for the given xpath are requested.
  [in] | private_data | Private context passed to the callback function, opaque to sysrepo.
  [in] | opts | Options overriding default behavior of the subscription, it is supposed to be a bitwise OR-ed value of any sr_subscr_flag_t flags.
  [in,out] | subscription | Subscription context, zeroed for first subscription, freed by sr_unsubscribe.

Returns
  Error code (SR_ERR_OK on success).

## sr_oper_poll_subscribe()

int sr_oper_poll_subscribe | ( | sr_session_ctx_t * | session,
|  | const char * | module_name,
|  | const char * | path,
|  | uint32_t | valid_ms,
|  | sr_subscr_options_t | opts,
|  | sr_subscription_ctx_t ** | subscription )

Start periodic retrieval and caching of operational data at the given path.

The operational data are cached in the connection of `session`. When any session created on this connection requires data of the cached operational get subscriptions at `path`, the callback is not called and the cached data are used instead. Additionally, if `opts` include SR_SUBSCR_OPER_POLL_DIFF, any changes detected on cache data refresh are reported to corresponding subscribers.

Required READ access.

Note
  For every operational get subscription, make sure there is only a single operational poll subscription with the SR_SUBSCR_OPER_POLL_DIFF flag.
  As soon as the poll subscription is created, the operational data are cached even if there are no matching oper get subscriptions to cache. Meaning if the oper get subscription(s) are created after the oper poll subscription, the correct data are cached only after the next cache period elapses, empty data are used until then. Best to avoid this scenario by first creating oper get subscriptions and only then corresponding oper poll subscriptions.
  Be aware of some specific threading limitations. Especially note that you cannot have an operational poll subscription in the same `subscription` structure as the operational get subscription being cached because a dead-lock would occur on cache update.

Parameters

  [in] | session | Session (not DS-specific) to use.
  [in] | module_name | Name of the affected module.
  [in] | path | Path of the subtree with operational get subscription(s) to poll. Any oper get subscriptions matching `path` or nested in the path are cached.
  [in] | valid_ms | Time the retrieved data are stored in cache until being considered invalid.
  [in] | opts | Options overriding default behavior of the subscription, it is supposed to be a bitwise OR-ed value of any sr_subscr_flag_t flags.
  [in,out] | subscription | Subscription context, zeroed for first subscription, freed by sr_unsubscribe.

Returns
  Error code (SR_ERR_OK on success).