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)
	Deprecated, use sr_filter_subtree2xpath().
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_del (int fd)
	Remove a subscription from being handled by the dispatched thread and close its FD.
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_read_notif_lyb (int fd, struct timespec timestamp, char lyb, uint32_t lyb_size)
	Read a notification without parsing it.
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_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_resync (uint32_t sub_id)
	Subscribe for receiving notifications according to 'ietf-subscribed-notifications' YANG.

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 333 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 )

Deprecated, use sr_filter_subtree2xpath().

◆ 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 runs until srsn_read_dispatch_destroy().

On success fd is owned by the dispatch, which closes it once the subscription terminates or when removed by srsn_read_dispatch_del(), so it must never be closed by the caller. On error fd is not registered and stays owned by the caller.

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, may be 0 while the dispatch thread is still running.

◆ srsn_read_dispatch_del()

int srsn_read_dispatch_del ( int fd )

Remove a subscription from being handled by the dispatched thread and close its FD.

Blocks until the dispatched thread is not processing any notification, so once this function returns, the callback is neither running for fd nor can be called for it again and the callback data of fd can be freed.

It is not an error to remove an FD that is no longer handled by the dispatched thread, which closes FDs of terminated subscriptions on its own without notifying the caller. So, calling this function is always the correct way of learning that the callback data of fd can be freed.

Parameters

[in] fd Subscription file descriptor previously added by srsn_read_dispatch_add(), closed unless the dispatched thread has already closed it after the subscription terminated, in which case its number must not have been reused for another dispatch FD, which would be removed instead.

Returns: Error code (SR_ERR_OK on success).

◆ 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.

The dispatch runs cb on a separate thread, so the callback and the FD it reads from are shared between that thread and the caller. To avoid data races, never close a dispatched FD directly and do not free its callback data while the FD is registered: use srsn_read_dispatch_del() to remove an FD, which closes it and blocks until the callback is no longer running for it, only then is it safe to free the callback data. The callback data must also stay valid and at a stable address for the whole time the FD is dispatched. Only srsn_read_dispatch_destroy() stops the thread.

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.

Never waits for a notification to arrive, call srsn_poll() first for that.

Parameters

[in]	fd	Pipe end opened by a subscription.
[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 no notification is available,; SR_ERR_UNSUPPORTED on end-of-file (subscription terminated, the write end was closed),; another error code on failure (logged).

◆ srsn_read_notif_lyb()

int srsn_read_notif_lyb	(	int	fd,
		struct timespec *	timestamp,
		char **	lyb,
		uint32_t *	lyb_size )

Read a notification without parsing it.

Never waits for a notification to arrive, call srsn_poll() first for that.

Parameters

[in]	fd	Pipe end opened by a subscription.
[out]	timestamp	Notification timestamp.
[out]	lyb	Notification in LYB format, free by the caller.
[out]	lyb_size	Size of `lyb`.

Returns: SR_ERR_OK on success,; SR_ERR_TIME_OUT if no notification is available,; SR_ERR_UNSUPPORTED on end-of-file (subscription terminated, the write end was closed),; another error code on failure (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_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_resync()

int srsn_yang_push_on_change_resync ( 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). */ 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-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). */ 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 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). */ 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);

/**

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).

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

◆ srsn_read_dispatch_destroy()

◆ srsn_read_dispatch_init()

◆ srsn_read_dispatch_start()

◆ srsn_read_notif()

◆ srsn_read_notif_lyb()

◆ srsn_resume()

◆ srsn_stream_collect_mods()

◆ srsn_suspend()

◆ srsn_terminate()

◆ srsn_yang_push_modify_on_change()

◆ srsn_yang_push_modify_periodic()

◆ srsn_yang_push_on_change_resync()

◆ 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