multi-module notification subscription functions header More...

#include <sys/stat.h>
#include "sysrepo.h"

Include dependency graph for subscribed_notifications.h:

Data Structures
struct	srsn_state_sub_t
union	srsn_state_sub_t.__unnamed0__
struct	srsn_state_sub_t.__unnamed0__.sub_notif
struct	srsn_state_sub_t.__unnamed0__.yp_on_change
struct	srsn_state_sub_t.__unnamed0__.yp_periodic

Typedefs
typedef void(*	srsn_notif_cb) (const struct lyd_node notif, const struct timespec timestamp, void *cb_data)
	Callback for reading notifications.

Enumerations
enum	srsn_sub_type_t { SRSN_SUB_NOTIF , SRSN_YANG_PUSH_PERIODIC , SRSN_YANG_PUSH_ON_CHANGE }
	Type of the subscribed-notifications subscription. More...
enum	srsn_yp_change_t { SRSN_YP_CHANGE_INVALID = -1 , SRSN_YP_CHANGE_CREATE , SRSN_YP_CHANGE_DELETE , SRSN_YP_CHANGE_INSERT , SRSN_YP_CHANGE_MOVE , SRSN_YP_CHANGE_REPLACE , SRSN_COUNT_YP_CHANGE }

Functions
int	srsn_filter_subtree2xpath (const struct lyd_node subtree, sr_session_ctx_t session, char **xpath_filter)
	Transform a subtree filter into an XPath filter.
int	srsn_modify_stop_time (uint32_t sub_id, const struct timespec *stop_time)
	Modify a generic subscription stop-time.
int	srsn_modify_xpath_filter (uint32_t sub_id, const char *xpath_filter)
	Modify a generic subscription xpath-filter.
int	srsn_notif_sent (uint32_t sub_id)
	Increase the sent-notifications counter in case of additional manually-generated notifications (such as 'subscription-modified').
int	srsn_oper_data_streams_cb (sr_session_ctx_t session, uint32_t sub_id, const char module_name, const char path, const char request_xpath, uint32_t request_id, struct lyd_node *parent, void private_data)
	Sysrepo sr_oper_get_items_cb() providing data of the subtree '/ietf-subscribed-notification:streams'.
int	srsn_oper_data_sub (uint32_t sub_id, srsn_state_sub_t **sub)
	Get subscription state data of a single subscription.
int	srsn_oper_data_subscriptions (srsn_state_sub_t *subs, uint32_t count)
	Get subscription state data with most of the information in the subtree '/ietf-subscribed-notifications:subscriptions'.
void	srsn_oper_data_subscriptions_free (srsn_state_sub_t *subs, uint32_t count)
	Free subscription state data.
int	srsn_poll (int fd, uint32_t timeout_ms)
	Poll a file descriptor for data to read.
int	srsn_read_dispatch_add (int fd, void *cb_data)
	Add another subscription to be handled by the dispatched thread.
uint32_t	srsn_read_dispatch_count (void)
	Get the number of subscriptions currently handled by the dispatched thread.
int	srsn_read_dispatch_destroy (void)
	Stop the dispatched thread and clear all the used resources.
int	srsn_read_dispatch_init (sr_conn_ctx_t *conn, srsn_notif_cb cb)
	Init read dispatch for notifications, overwrites any previous parameters.
int	srsn_read_dispatch_start (int fd, sr_conn_ctx_t conn, srsn_notif_cb cb, void cb_data)
	Deprecated, came functionality as calling srsn_read_dispatch_init() and srsn_read_dispatch_add().
int	srsn_read_notif (int fd, const struct ly_ctx ly_ctx, struct timespec timestamp, struct lyd_node **notif)
	Read a notification.
int	srsn_resume (uint32_t sub_id)
	Resume a subscribed-notifications subscription.
int	srsn_stream_collect_mods (const char stream, const char xpath_filter, const struct ly_ctx ly_ctx, struct ly_set *mod_set)
	Collect modules to subscribe to.
int	srsn_subscribe (sr_session_ctx_t session, const char stream, const char xpath_filter, const struct timespec stop_time, const struct timespec start_time, int sub_no_thread, sr_subscription_ctx_t sub, struct timespec replay_start_time, int fd, uint32_t sub_id)
	Subscribe for receiving notifications according to 'ietf-subscribed-notifications' YANG.
int	srsn_suspend (uint32_t sub_id, const char *reason)
	Suspend a subscribed-notifications subscription.
int	srsn_terminate (uint32_t sub_id, const char *reason)
	Terminate a subscribed-notifications subscription.
int	srsn_yang_push_modify_on_change (uint32_t sub_id, uint32_t dampening_period_ms)
	Modify a yang-push on-change subscription.
int	srsn_yang_push_modify_periodic (uint32_t sub_id, uint32_t period_ms, const struct timespec *anchor_time)
	Modify a yang-push periodic subscription.
int	srsn_yang_push_on_change (sr_session_ctx_t session, sr_datastore_t ds, const char xpath_filter, uint32_t dampening_period_ms, int sync_on_start, int excluded_changes[SRSN_COUNT_YP_CHANGE], const struct timespec stop_time, int sub_no_thread, sr_subscription_ctx_t sub, int fd, uint32_t *sub_id)
	Subscribe for receiving notifications according to 'ietf-yang-push' YANG on-change subscriptions.
int	srsn_yang_push_on_change_resync (uint32_t sub_id)
	Resync a yang-push on-change subscription.
int	srsn_yang_push_periodic (sr_session_ctx_t session, sr_datastore_t ds, const char xpath_filter, uint32_t period_ms, const struct timespec anchor_time, const struct timespec stop_time, int fd, uint32_t sub_id)
	Subscribe for receiving notifications according to 'ietf-yang-push' YANG periodic subscriptions.

Detailed Description

multi-module notification subscription functions header

Author: Michal Vasko mvask.nosp@m.o@ce.nosp@m.snet..nosp@m.cz

Copyright: Copyright (c) 2023 - 2024 Deutsche Telekom AG. Copyright (c) 2023 - 2024 CESNET, z.s.p.o.

This source code is licensed under BSD 3-Clause License (the "License"). You may not use this file except in compliance with the License. You may obtain a copy of the License at

https://opensource.org/licenses/BSD-3-Clause

Definition in file subscribed_notifications.h.

Data Structure Documentation

◆ srsn_state_sub_t

struct srsn_state_sub_t

Definition at line 47 of file subscribed_notifications.h.

Data Fields
union srsn_state_sub_t.__unnamed0__	__unnamed__
uint32_t	excluded_count
uint32_t	sent_count
struct timespec	stop_time
uint32_t	sub_id
int	suspended
srsn_sub_type_t	type
char *	xpath_filter

◆ srsn_state_sub_t.unnamed0

union srsn_state_sub_t.__unnamed0__

Definition at line 57 of file subscribed_notifications.h.

Data Fields
struct srsn_state_sub_t.__unnamed0__.sub_notif	sub_notif
struct srsn_state_sub_t.__unnamed0__.yp_on_change	yp_on_change
struct srsn_state_sub_t.__unnamed0__.yp_periodic	yp_periodic

◆ srsn_state_sub_t.unnamed0.sub_notif

struct srsn_state_sub_t.__unnamed0__.sub_notif

Definition at line 58 of file subscribed_notifications.h.

Data Fields
struct timespec	start_time
char *	stream

◆ srsn_state_sub_t.unnamed0.yp_on_change

struct srsn_state_sub_t.__unnamed0__.yp_on_change

Definition at line 67 of file subscribed_notifications.h.

Data Fields
uint32_t	dampening_period
sr_datastore_t	ds
int	excluded_change[SRSN_COUNT_YP_CHANGE]
int	sync_on_start

◆ srsn_state_sub_t.unnamed0.yp_periodic

struct srsn_state_sub_t.__unnamed0__.yp_periodic

Definition at line 62 of file subscribed_notifications.h.

Data Fields
struct timespec	anchor_time
sr_datastore_t	ds
uint32_t	period

Typedef Documentation

◆ srsn_notif_cb

typedef void(* srsn_notif_cb) (const struct lyd_node *notif, const struct timespec *timestamp, void *cb_data)

Callback for reading notifications.

Parameters

[in]	notif	Read notification.
[in]	timestamp	Notification timestamp.
[in]	cb_data	User callback data for the FD the `notif` was received from.

Definition at line 320 of file subscribed_notifications.h.

Enumeration Type Documentation

◆ srsn_sub_type_t

enum srsn_sub_type_t

Type of the subscribed-notifications subscription.

Enumerator
SRSN_SUB_NOTIF	standard subscribed-notifications subscription
SRSN_YANG_PUSH_PERIODIC	yang-push periodic subscription
SRSN_YANG_PUSH_ON_CHANGE	yang-push on-change subscription

Definition at line 31 of file subscribed_notifications.h.

◆ srsn_yp_change_t

enum srsn_yp_change_t

Enumerator
SRSN_YP_CHANGE_INVALID
SRSN_YP_CHANGE_CREATE
SRSN_YP_CHANGE_DELETE
SRSN_YP_CHANGE_INSERT
SRSN_YP_CHANGE_MOVE
SRSN_YP_CHANGE_REPLACE
SRSN_COUNT_YP_CHANGE

Definition at line 37 of file subscribed_notifications.h.

Function Documentation

◆ srsn_filter_subtree2xpath()

int srsn_filter_subtree2xpath	(	const struct lyd_node *	subtree,
		sr_session_ctx_t *	session,
		char **	xpath_filter )

Transform a subtree filter into an XPath filter.

Parameters

[in]	subtree	Subtree of the filter itself.
[in]	session	Optional session for storing errors.
[out]	xpath_filter	Generated XPath filter.

Returns: Error code (SR_ERR_OK on success).

◆ srsn_modify_stop_time()

int srsn_modify_stop_time	(	uint32_t	sub_id,
		const struct timespec *	stop_time )

Modify a generic subscription stop-time.

Does NOT generate the 'subscription-modified' notification.

Parameters

[in]	sub_id	Subscription ID of the subscription to modify.
[in]	stop_time	New stop-time of the subscription, NULL to unset the previous stop-time.

Returns: Error code (SR_ERR_OK on success).

◆ srsn_modify_xpath_filter()

int srsn_modify_xpath_filter	(	uint32_t	sub_id,
		const char *	xpath_filter )

Modify a generic subscription xpath-filter.

Does NOT generate the 'subscription-modified' notification.

Parameters

[in]	sub_id	Subscription ID of the subscription to modify.
[in]	xpath_filter	New XPath filter to use, NULL to remove any previous filter.

Returns: Error code (SR_ERR_OK on success).

◆ srsn_notif_sent()

int srsn_notif_sent ( uint32_t sub_id )

Increase the sent-notifications counter in case of additional manually-generated notifications (such as 'subscription-modified').

Parameters

[in] sub_id Subscription ID of the subscription.

Returns: Error code (SR_ERR_OK on success).

◆ srsn_oper_data_streams_cb()

int srsn_oper_data_streams_cb	(	sr_session_ctx_t *	session,
		uint32_t	sub_id,
		const char *	module_name,
		const char *	path,
		const char *	request_xpath,
		uint32_t	request_id,
		struct lyd_node **	parent,
		void *	private_data )

Sysrepo sr_oper_get_items_cb() providing data of the subtree '/ietf-subscribed-notification:streams'.

◆ srsn_oper_data_sub()

int srsn_oper_data_sub	(	uint32_t	sub_id,
		srsn_state_sub_t **	sub )

Get subscription state data of a single subscription.

Parameters

[in]	sub_id	Subscription ID.
[out]	sub	Subscription state.

Returns: Error code (SR_ERR_OK on success).

◆ srsn_oper_data_subscriptions()

int srsn_oper_data_subscriptions	(	srsn_state_sub_t **	subs,
		uint32_t *	count )

Get subscription state data with most of the information in the subtree '/ietf-subscribed-notifications:subscriptions'.

Parameters

[out]	subs	Array of subscriptions.
[out]	count	Count of `subs`.

Returns: Error code (SR_ERR_OK on success).

◆ srsn_oper_data_subscriptions_free()

void srsn_oper_data_subscriptions_free	(	srsn_state_sub_t *	subs,
		uint32_t	count )

Free subscription state data.

Parameters

[in]	subs	Array of subscriptions.
[in]	count	Count of `subs`.

◆ srsn_poll()

int srsn_poll	(	int	fd,
		uint32_t	timeout_ms )

Poll a file descriptor for data to read.

Parameters

[in]	fd	File descriptor to poll.
[in]	timeout_ms	Timeout for the poll.

Returns: SR_ERR_OK on data to read,; SR_ERR_TIME_OUT if there were no data to read in the specified timeout,; SR_ERR_UNSUPPORTED on end-of-file (subscription terminated, the write end was closed),; SR_ERR_SYS on another error (logged).

◆ srsn_read_dispatch_add()

int srsn_read_dispatch_add	(	int	fd,
		void *	cb_data )

Add another subscription to be handled by the dispatched thread.

The thread is automatically started on the first fd and terminated when the last one is closed.

Parameters

[in]	fd	Subscription file descriptor to read from.
[in]	cb_data	User `cb` callback data for the `fd`.

Returns: Error code (SR_ERR_OK on success).

◆ srsn_read_dispatch_count()

uint32_t srsn_read_dispatch_count ( void )

Get the number of subscriptions currently handled by the dispatched thread.

Returns: Number of handled subscriptions, 0 means the dispatch thread is not running.

◆ srsn_read_dispatch_destroy()

int srsn_read_dispatch_destroy ( void )

Stop the dispatched thread and clear all the used resources.

Returns: Error code (SR_ERR_OK on success).

◆ srsn_read_dispatch_init()

int srsn_read_dispatch_init	(	sr_conn_ctx_t *	conn,
		srsn_notif_cb	cb )

Init read dispatch for notifications, overwrites any previous parameters.

Parameters

[in]	conn	Connection that must not be terminated while the notifications are being processed.
[in]	cb	Callback to be called for each notification.

Returns: Error code (SR_ERR_OK on success).

◆ srsn_read_dispatch_start()

int srsn_read_dispatch_start	(	int	fd,
		sr_conn_ctx_t *	conn,
		srsn_notif_cb	cb,
		void *	cb_data )

Deprecated, came functionality as calling srsn_read_dispatch_init() and srsn_read_dispatch_add().

◆ srsn_read_notif()

int srsn_read_notif	(	int	fd,
		const struct ly_ctx *	ly_ctx,
		struct timespec *	timestamp,
		struct lyd_node **	notif )

Read a notification.

Parameters

[in]	fd	Opened file descriptor to read from, may be non-blocking.
[in]	ly_ctx	Libyang context to use for parsing the notification.
[out]	timestamp	Notification timestamp.
[out]	notif	Parsed notification.

Returns: SR_ERR_OK on success,; SR_ERR_TIME_OUT if reading would block,; SR_ERR_UNSUPPORTED on end-of-file (subscription terminated, the write end was closed),; SR_ERR_SYS on another error (logged).

◆ srsn_resume()

int srsn_resume ( uint32_t sub_id )

Resume a subscribed-notifications subscription.

Generates the 'subscription-resumed' notification.

Parameters

[in] sub_id Subscription ID of the subscription to resume.

Returns: Error code (SR_ERR_OK on success).

◆ srsn_stream_collect_mods()

int srsn_stream_collect_mods	(	const char *	stream,
		const char *	xpath_filter,
		const struct ly_ctx *	ly_ctx,
		struct ly_set **	mod_set )

Collect modules to subscribe to.

Parameters

[in]	stream	Notification stream.
[in]	xpath_filter	XPath filter, if any.
[in]	ly_ctx	Context to use.
[out]	mod_set	Set with modules to subscribe to.

Returns: Error code (SR_ERR_OK on success).

◆ srsn_subscribe()

int srsn_subscribe	(	sr_session_ctx_t *	session,
		const char *	stream,
		const char *	xpath_filter,
		const struct timespec *	stop_time,
		const struct timespec *	start_time,
		int	sub_no_thread,
		sr_subscription_ctx_t **	sub,
		struct timespec *	replay_start_time,
		int *	fd,
		uint32_t *	sub_id )

Subscribe for receiving notifications according to 'ietf-subscribed-notifications' YANG.

Parameters

[in]	session	Session to use for SR subscriptions.
[in]	stream	Stream to subscribe to.
[in]	xpath_filter	Optional XPath filter to use.
[in]	stop_time	Optional stop-time of the subscription. Once reached, the ‘subscription-terminated’ notification is generated.
[in]	start_time	Optional start-time of the subscription, requires the 'replay' feature.
[in]	sub_no_thread	Set if the created subscriptions should not create a separate handling thread.
[in,out]	sub	Optional subscription structure to use and add SR subscriptions to.
[out]	replay_start_time	Optional replay-start-time of the subscription if start-time was set.
[out]	fd	Pipe end for reading the generated notifications. Needs to be closed.
[out]	sub_id	Unique subscribed-notifications ID.

Returns: Error code (SR_ERR_OK on success).

◆ srsn_suspend()

int srsn_suspend	(	uint32_t	sub_id,
		const char *	reason )

Suspend a subscribed-notifications subscription.

Generates the 'subscription-suspended' notification.

Parameters

[in]	sub_id	Subscription ID of the subscription to suspend.
[in]	reason	Reason for the suspension as an identityref value. If not set, no notification is generated.

Returns: Error code (SR_ERR_OK on success).

◆ srsn_terminate()

int srsn_terminate	(	uint32_t	sub_id,
		const char *	reason )

Terminate a subscribed-notifications subscription.

Generates the 'subscription-terminated' notification. After this function returns, in case the dispatch thread is running, srsn_notif_cb() will not be called for notifications on this subscription.

Parameters

[in]	sub_id	Subscription ID of the subscription to terminate.
[in]	reason	Reason for the termination as an identityref value. If not set, no notification is generated.

Returns: SR_ERR_OK on success,; SR_ERR_NOT_FOUND if a subscription with sub_id was not found.

◆ srsn_yang_push_modify_on_change()

int srsn_yang_push_modify_on_change	(	uint32_t	sub_id,
		uint32_t	dampening_period_ms )

Modify a yang-push on-change subscription.

Does NOT generate the 'subscription-modified' notification.

Parameters

[in]	sub_id	Subscription ID of the subscription to modify.
[in]	dampening_period_ms	Dampening period in ms to set.

Returns: Error code (SR_ERR_OK on success).

◆ srsn_yang_push_modify_periodic()

int srsn_yang_push_modify_periodic	(	uint32_t	sub_id,
		uint32_t	period_ms,
		const struct timespec *	anchor_time )

Modify a yang-push periodic subscription.

Does NOT generate the 'subscription-modified' notification.

Parameters

[in]	sub_id	Subscription ID of the subscription to modify.
[in]	period_ms	Period in ms to set.
[in]	anchor_time	Anchor time of the period to set, NULL to unset.

Returns: Error code (SR_ERR_OK on success).

◆ srsn_yang_push_on_change()

int srsn_yang_push_on_change	(	sr_session_ctx_t *	session,
		sr_datastore_t	ds,
		const char *	xpath_filter,
		uint32_t	dampening_period_ms,
		int	sync_on_start,
		int	excluded_changes[SRSN_COUNT_YP_CHANGE],
		const struct timespec *	stop_time,
		int	sub_no_thread,
		sr_subscription_ctx_t **	sub,
		int *	fd,
		uint32_t *	sub_id )

Subscribe for receiving notifications according to 'ietf-yang-push' YANG on-change subscriptions.

Parameters

[in]	session	Session to use for SR subscriptions.
[in]	ds	Datastore to subscribe to.
[in]	xpath_filter	Optional XPath filter to use.
[in]	dampening_period_ms	Optional notification dampening period in ms.
[in]	sync_on_start	Whether to start the subscription with a full datastore content notification.
[in]	excluded_changes	Optional array of changes to be excluded. Set index of a srsn_yp_change_t to 1 for it to be excluded, to 0 to be included.
[in]	stop_time	Optional stop-time of the subscription. Once reached, the ‘subscription-terminated’ notification is generated.
[in]	sub_no_thread	Set if the created subscriptions should not create a separate handling thread.
[in,out]	sub	Optional subscription structure to use and add SR subscriptions to.
[out]	fd	Pipe end for reading the generated notifications. Needs to be closed.
[out]	sub_id	Unique subscribed-notifications ID.

Returns: Error code (SR_ERR_OK on success).

◆ srsn_yang_push_on_change_resync()

int srsn_yang_push_on_change_resync ( uint32_t sub_id )

Resync a yang-push on-change subscription.

Parameters

[in] sub_id Subscription ID of the subscription to resync.

Returns: Error code (SR_ERR_OK on success).

◆ srsn_yang_push_periodic()

int srsn_yang_push_periodic	(	sr_session_ctx_t *	session,
		sr_datastore_t	ds,
		const char *	xpath_filter,
		uint32_t	period_ms,
		const struct timespec *	anchor_time,
		const struct timespec *	stop_time,
		int *	fd,
		uint32_t *	sub_id )

Subscribe for receiving notifications according to 'ietf-yang-push' YANG periodic subscriptions.

Parameters

[in]	session	Session to use for SR operations.
[in]	ds	Datastore to subscribe to.
[in]	xpath_filter	Optional XPath filter to use.
[in]	period_ms	Notification period in ms.
[in]	anchor_time	Optional anchor time of the period.
[in]	stop_time	Optional stop-time of the subscription. Once reached, the ‘subscription-terminated’ notification is generated.
[out]	fd	Pipe end for reading the generated notifications. Needs to be closed.
[out]	sub_id	Unique subscribed-notifications ID.

Returns: Error code (SR_ERR_OK on success).

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ srsn_state_sub_t

◆ srsn_state_sub_t.__unnamed0__

◆ srsn_state_sub_t.__unnamed0__.sub_notif

◆ srsn_state_sub_t.__unnamed0__.yp_on_change

◆ srsn_state_sub_t.__unnamed0__.yp_periodic

Typedef Documentation

◆ srsn_notif_cb

Enumeration Type Documentation

◆ srsn_sub_type_t

◆ srsn_yp_change_t

Function Documentation

◆ srsn_filter_subtree2xpath()

◆ srsn_modify_stop_time()

◆ srsn_modify_xpath_filter()

◆ srsn_notif_sent()

◆ srsn_oper_data_streams_cb()

◆ srsn_oper_data_sub()

◆ srsn_oper_data_subscriptions()

◆ srsn_oper_data_subscriptions_free()

◆ srsn_poll()

◆ srsn_read_dispatch_add()

◆ srsn_read_dispatch_count()

◆ srsn_read_dispatch_destroy()

◆ srsn_read_dispatch_init()

◆ srsn_read_dispatch_start()

◆ srsn_read_notif()

◆ srsn_resume()

◆ srsn_stream_collect_mods()

◆ srsn_subscribe()

◆ srsn_suspend()

◆ srsn_terminate()

◆ srsn_yang_push_modify_on_change()

◆ srsn_yang_push_modify_periodic()

◆ srsn_yang_push_on_change()

◆ srsn_yang_push_on_change_resync()

◆ srsn_yang_push_periodic()

◆ srsn_state_sub_t.unnamed0

◆ srsn_state_sub_t.unnamed0.sub_notif

◆ srsn_state_sub_t.unnamed0.yp_on_change

◆ srsn_state_sub_t.unnamed0.yp_periodic