Notification Subscription API

Functions
int	sr_notif_send (sr_session_ctx_t *session, const char *path, const sr_val_t *values, const size_t values_cnt, uint32_t timeout_ms, int wait)
	Send a notification. Data are represented as sr_val_t structures. In case there are particularly many notifications send on a session (100 notif/s or more) and all of them are stored for replay, consider using sr_session_notif_buffer(). More...
int	sr_notif_send_tree (sr_session_ctx_t *session, struct lyd_node *notif, uint32_t timeout_ms, int wait)
	Send a notification. Data are represented as libyang subtrees. In case there are particularly many notifications send on a session (100 notif/s or more) and all of them are stored for replay, consider using sr_session_notif_buffer(). More...
int	sr_notif_sub_get_info (sr_subscription_ctx_t *subscription, uint32_t sub_id, const char **module_name, const char **xpath, struct timespec *start_time, struct timespec *stop_time, uint32_t *filtered_out)
	Get information about an existing notification subscription. More...
int	sr_notif_sub_modify_stop_time (sr_subscription_ctx_t *subscription, uint32_t sub_id, const struct timespec *stop_time)
	Modify an existing notification subscription by changing its stop time. Special SR_EV_NOTIF_MODIFIED notification is delivered. More...
int	sr_notif_sub_modify_xpath (sr_subscription_ctx_t *subscription, uint32_t sub_id, const char *xpath)
	Modify an existing notification subscription by changing its XPath filter. Special SR_EV_NOTIF_MODIFIED notification is delivered. More...
int	sr_notif_subscribe (sr_session_ctx_t *session, const char *module_name, const char *xpath, const struct timespec *start_time, const struct timespec *stop_time, sr_event_notif_cb callback, void *private_data, sr_subscr_options_t opts, sr_subscription_ctx_t **subscription)
	Subscribe for the delivery of a notification(s). Data are represented as sr_val_t structures. More...
int	sr_notif_subscribe_tree (sr_session_ctx_t *session, const char *module_name, const char *xpath, const struct timespec *start_time, const struct timespec *stop_time, sr_event_notif_tree_cb callback, void *private_data, sr_subscr_options_t opts, sr_subscription_ctx_t **subscription)
	Subscribes for the delivery of a notification(s). Data are represented as libyang subtrees. More...
enum	sr_ev_notif_type_t {   SR_EV_NOTIF_REALTIME, SR_EV_NOTIF_REPLAY, SR_EV_NOTIF_REPLAY_COMPLETE, SR_EV_NOTIF_TERMINATED,   SR_EV_NOTIF_MODIFIED, SR_EV_NOTIF_SUSPENDED, SR_EV_NOTIF_RESUMED, SR_EV_NOTIF_STOP_TIME }
	Type of the notification passed to the sr_event_notif_cb and sr_event_notif_tree_cb callbacks. More...
typedef void(*	sr_event_notif_cb )(sr_session_ctx_t *session, uint32_t sub_id, const sr_ev_notif_type_t notif_type, const char *xpath, const sr_val_t *values, const size_t values_cnt, struct timespec *timestamp, void *private_data)
	Callback to be called for the delivery of a notification. Data are represented as sr_val_t structures. More...
typedef void(*	sr_event_notif_tree_cb )(sr_session_ctx_t *session, uint32_t sub_id, const sr_ev_notif_type_t notif_type, const struct lyd_node *notif, struct timespec *timestamp, void *private_data)
	Callback to be called for the delivery of a notification. Data are represented as libyang subtrees. More...

Detailed Description

Typedef Documentation

typedef void(* sr_event_notif_cb)(sr_session_ctx_t *session, uint32_t sub_id, const sr_ev_notif_type_t notif_type, const char *xpath, const sr_val_t *values, const size_t values_cnt, struct timespec *timestamp, void *private_data)

Callback to be called for the delivery of a notification. Data are represented as sr_val_t structures.

Note

Callback must not modify the same module notification 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]	notif_type	Type of the notification.
[in]	xpath	Full operation xpath identifying the exact notification executed.
[in]	values	Array of all nodes that hold some data in event notification subtree.
[in]	values_cnt	Number of items inside the values array.
[in]	timestamp	Time when the notification was generated
[in]	private_data	Private context opaque to sysrepo, as passed to sr_notif_subscribe call.

Definition at line 633 of file sysrepo_types.h.

typedef void(* sr_event_notif_tree_cb)(sr_session_ctx_t *session, uint32_t sub_id, const sr_ev_notif_type_t notif_type, const struct lyd_node *notif, struct timespec *timestamp, void *private_data)

Callback to be called for the delivery of a notification. Data are represented as libyang subtrees.

Note

Callback must not modify the same module notification 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]	notif_type	Type of the notification.
[in]	notif	Notification data tree. Always points to the notification itself, even for nested ones.
[in]	timestamp	Time when the notification was generated
[in]	private_data	Private context opaque to sysrepo, as passed to sr_notif_subscribe_tree call.

Definition at line 648 of file sysrepo_types.h.

Enumeration Type Documentation

enum sr_ev_notif_type_t

Type of the notification passed to the sr_event_notif_cb and sr_event_notif_tree_cb callbacks.

Enumerator
SR_EV_NOTIF_REALTIME	Real-time notification.
SR_EV_NOTIF_REPLAY	Replayed notification.
SR_EV_NOTIF_REPLAY_COMPLETE	Not a real notification, just a signal that the notification replay has completed (all the stored notifications from the given time interval have been delivered).
SR_EV_NOTIF_TERMINATED	Not a real notification, just a signal that the subscription was terminated, for whatever reason, it is the last notification the subscription receives.
SR_EV_NOTIF_MODIFIED	Not a real notification, just a signal that the subscription parameters were modified.
SR_EV_NOTIF_SUSPENDED	Not a real notification, just a signal that the subscription was suspended.
SR_EV_NOTIF_RESUMED	Not a real notification, just a signal that the subscription was resumed after previously suspended.
SR_EV_NOTIF_STOP_TIME	Not a real notification, just a signal that the subscription was terminated because its stop time has been reached, it is the last notification the subscription receives.

Definition at line 603 of file sysrepo_types.h.

Function Documentation

int sr_notif_send	(	sr_session_ctx_t *	session,
		const char *	path,
		const sr_val_t *	values,
		const size_t	values_cnt,
		uint32_t	timeout_ms,
		int	wait
	)

Send a notification. Data are represented as sr_val_t structures. In case there are particularly many notifications send on a session (100 notif/s or more) and all of them are stored for replay, consider using sr_session_notif_buffer().

Required WRITE access. If the module does not support replay, required READ access.

Note

Notification must be valid in (is validated against) the operational datastore context.

Parameters

[in]	session	Session (not DS-specific) to use.
[in]	path	Path identifying the notification.
[in]	values	Array of all nodes that hold some data in event notification subtree (same as sr_get_items would return).
[in]	values_cnt	Number of items inside the values array.
[in]	timeout_ms	Notification callback timeout in milliseconds. If 0, default is used. Relevant only if wait is set.
[in]	wait	Whether to wait until all (if any) notification callbacks were called (synchronous delivery) or just publish the notification without waiting for its processing (asynchronous delivery).

Returns

Error code (SR_ERR_OK on success).

int sr_notif_send_tree	(	sr_session_ctx_t *	session,
		struct lyd_node *	notif,
		uint32_t	timeout_ms,
		int	wait
	)

Send a notification. Data are represented as libyang subtrees. In case there are particularly many notifications send on a session (100 notif/s or more) and all of them are stored for replay, consider using sr_session_notif_buffer().

Required WRITE access. If the module does not support replay, required READ access.

Note

Notification must be valid in (is validated against) the operational datastore context.

Parameters

[in]	session	Session (not DS-specific) to use.
[in,out]	notif	Notification data tree to send in session connection libyang context, is validated.
[in]	timeout_ms	Notification callback timeout in milliseconds. If 0, default is used. Relevant only if wait is set.
[in]	wait	Whether to wait until all (if any) notification callbacks were called (synchronous delivery) or just publish the notification without waiting for its processing (asynchronous delivery).

Returns

Error code (SR_ERR_OK on success).

int sr_notif_sub_get_info	(	sr_subscription_ctx_t *	subscription,
		uint32_t	sub_id,
		const char **	module_name,
		const char **	xpath,
		struct timespec *	start_time,
		struct timespec *	stop_time,
		uint32_t *	filtered_out
	)

Get information about an existing notification subscription.

Parameters

[in]	subscription	Subscription structure to use.
[in]	sub_id	Subscription ID of the specific subscription.
[out]	module_name	Optional name of the module whose notifications were subscribed.
[out]	xpath	Optional XPath filter of the subscription.
[out]	start_time	Optional start time of the subscription.
[out]	stop_time	Optional stop time of the subscription.
[out]	filtered_out	Optional number of filtered-out notifications of the subscription.

Returns

Error code (SR_ERR_OK on success).

int sr_notif_sub_modify_stop_time	(	sr_subscription_ctx_t *	subscription,
		uint32_t	sub_id,
		const struct timespec *	stop_time
	)

Modify an existing notification subscription by changing its stop time. Special SR_EV_NOTIF_MODIFIED notification is delivered.

Parameters

[in]	subscription	Subscription structure to use.
[in]	sub_id	Subscription ID of the specific subscription to modify.
[in]	stop_time	New stop time of the subscription, may be NULL for none.

Returns

Error code (SR_ERR_OK on success).

int sr_notif_sub_modify_xpath	(	sr_subscription_ctx_t *	subscription,
		uint32_t	sub_id,
		const char *	xpath
	)

Modify an existing notification subscription by changing its XPath filter. Special SR_EV_NOTIF_MODIFIED notification is delivered.

Parameters

[in]	subscription	Subscription structure to use.
[in]	sub_id	Subscription ID of the specific subscription to modify.
[in]	xpath	New XPath filter to use by the subscription.

Returns

Error code (SR_ERR_OK on success).

int sr_notif_subscribe	(	sr_session_ctx_t *	session,
		const char *	module_name,
		const char *	xpath,
		const struct timespec *	start_time,
		const struct timespec *	stop_time,
		sr_event_notif_cb	callback,
		void *	private_data,
		sr_subscr_options_t	opts,
		sr_subscription_ctx_t **	subscription
	)

Subscribe for the delivery of a notification(s). Data are represented as sr_val_t structures.

Required WRITE access.

Parameters

[in]	session	Session (not DS-specific) to use.
[in]	module_name	Name of the module whose notifications to subscribe to.
[in]	xpath	Optional XPath further filtering received notifications.
[in]	start_time	Optional start time of the subscription. Used for replaying stored notifications.
[in]	stop_time	Optional stop time ending the notification subscription.
[in]	callback	Callback to be called when the event notification is delivered.
[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).

int sr_notif_subscribe_tree	(	sr_session_ctx_t *	session,
		const char *	module_name,
		const char *	xpath,
		const struct timespec *	start_time,
		const struct timespec *	stop_time,
		sr_event_notif_tree_cb	callback,
		void *	private_data,
		sr_subscr_options_t	opts,
		sr_subscription_ctx_t **	subscription
	)

Subscribes for the delivery of a notification(s). Data are represented as libyang subtrees.

Required WRITE access.

Parameters

[in]	session	Session (not DS-specific) to use.
[in]	module_name	Name of the module whose notifications to subscribe to.
[in]	xpath	Optional XPath further filtering received notifications.
[in]	start_time	Optional start time of the subscription. Used for replaying stored notifications.
[in]	stop_time	Optional stop time ending the notification subscription.
[in]	callback	Callback to be called when the event notification is delivered.
[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).