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
subscribed_notifications.h File Reference

multi-module notification subscription functions header More...

#include <sys/stat.h>
#include "sysrepo.h"
Include dependency graph for subscribed_notifications.h:

Go to the source code of this file.

Data Structures

struct  srsn_state_sub_t
 
union  srsn_state_sub_t.__unnamed__
 
struct  srsn_state_sub_t.__unnamed__.sub_notif
 
struct  srsn_state_sub_t.__unnamed__.yp_on_change
 
struct  srsn_state_sub_t.__unnamed__.yp_periodic
 

Typedefs

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

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. More...
 
int srsn_modify_stop_time (uint32_t sub_id, const struct timespec *stop_time)
 Modify a generic subscription stop-time. More...
 
int srsn_modify_xpath_filter (uint32_t sub_id, const char *xpath_filter)
 Modify a generic subscription xpath-filter. More...
 
int srsn_notif_sent (uint32_t sub_id)
 Increase the sent-notifications counter in case of additional manually-generated notifications (such as 'subscription-modified'). More...
 
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'. More...
 
int srsn_oper_data_sub (uint32_t sub_id, srsn_state_sub_t **sub)
 Get subscription state data of a single subscription. More...
 
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'. More...
 
void srsn_oper_data_subscriptions_free (srsn_state_sub_t *subs, uint32_t count)
 Free subscription state data. More...
 
int srsn_poll (int fd, uint32_t timeout_ms)
 Poll a file descriptor for data to read. More...
 
int srsn_read_dispatch_add (int fd, void *cb_data)
 Add another subscription to be handled by the dispatched thread. More...
 
uint32_t srsn_read_dispatch_count (void)
 Get the number of subscriptions currently handled by the dispatched thread. More...
 
int srsn_read_dispatch_destroy (void)
 Stop the dispatched thread and clear all the used resources. More...
 
int srsn_read_dispatch_init (sr_conn_ctx_t *conn, srsn_notif_cb cb)
 Init read dispatch for notifications, overwrites any previous parameters. More...
 
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(). More...
 
int srsn_read_notif (int fd, const struct ly_ctx *ly_ctx, struct timespec *timestamp, struct lyd_node **notif)
 Read a notification. More...
 
int srsn_resume (uint32_t sub_id)
 Resume a subscribed-notifications subscription. More...
 
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. More...
 
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. More...
 
int srsn_suspend (uint32_t sub_id, const char *reason)
 Suspend a subscribed-notifications subscription. More...
 
int srsn_terminate (uint32_t sub_id, const char *reason)
 Terminate a subscribed-notifications subscription. More...
 
int srsn_yang_push_modify_on_change (uint32_t sub_id, uint32_t dampening_period_ms)
 Modify a yang-push on-change subscription. More...
 
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. More...
 
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. More...
 
int srsn_yang_push_on_change_resync (uint32_t sub_id)
 Resync a yang-push on-change subscription. More...
 
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. More...
 

Detailed Description

multi-module notification subscription functions header

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

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

struct srsn_state_sub_t

Definition at line 47 of file subscribed_notifications.h.

Data Fields
union srsn_state_sub_t __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
union srsn_state_sub_t.__unnamed__

Definition at line 57 of file subscribed_notifications.h.

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

Definition at line 58 of file subscribed_notifications.h.

Data Fields
struct timespec start_time
char * stream
struct srsn_state_sub_t.__unnamed__.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
struct srsn_state_sub_t.__unnamed__.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

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

Callback for reading notifications.

Parameters
[in]notifRead notification.
[in]timestampNotification timestamp.
[in]cb_dataUser callback data for the FD the notif was received from.

Definition at line 320 of file subscribed_notifications.h.

Enumeration Type Documentation

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.

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

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]subtreeSubtree of the filter itself.
[in]sessionOptional session for storing errors.
[out]xpath_filterGenerated XPath filter.
Returns
Error code (SR_ERR_OK on success).
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_idSubscription ID of the subscription to modify.
[in]stop_timeNew stop-time of the subscription, NULL to unset the previous stop-time.
Returns
Error code (SR_ERR_OK on success).
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_idSubscription ID of the subscription to modify.
[in]xpath_filterNew XPath filter to use, NULL to remove any previous filter.
Returns
Error code (SR_ERR_OK on success).
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_idSubscription ID of the subscription.
Returns
Error code (SR_ERR_OK on success).
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.

Parameters
[in]sub_idSubscription ID.
[out]subSubscription state.
Returns
Error code (SR_ERR_OK on success).
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]subsArray of subscriptions.
[out]countCount of subs.
Returns
Error code (SR_ERR_OK on success).
void srsn_oper_data_subscriptions_free ( srsn_state_sub_t subs,
uint32_t  count 
)

Free subscription state data.

Parameters
[in]subsArray of subscriptions.
[in]countCount of subs.
int srsn_poll ( int  fd,
uint32_t  timeout_ms 
)

Poll a file descriptor for data to read.

Parameters
[in]fdFile descriptor to poll.
[in]timeout_msTimeout 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).
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]fdSubscription file descriptor to read from.
[in]cb_dataUser cb callback data for the fd.
Returns
Error code (SR_ERR_OK on success).
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.
int srsn_read_dispatch_destroy ( void  )

Stop the dispatched thread and clear all the used resources.

Returns
Error code (SR_ERR_OK on success).
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]connConnection that must not be terminated while the notifications are being processed.
[in]cbCallback to be called for each notification.
Returns
Error code (SR_ERR_OK on success).
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.

Parameters
[in]fdOpened file descriptor to read from, may be non-blocking.
[in]ly_ctxLibyang context to use for parsing the notification.
[out]timestampNotification timestamp.
[out]notifParsed 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).
int srsn_resume ( uint32_t  sub_id)

Resume a subscribed-notifications subscription.

Generates the 'subscription-resumed' notification.

Parameters
[in]sub_idSubscription ID of the subscription to resume.
Returns
Error code (SR_ERR_OK on success).
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]streamNotification stream.
[in]xpath_filterXPath filter, if any.
[in]ly_ctxContext to use.
[out]mod_setSet with modules to subscribe to.
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-subscribed-notifications' YANG.

Parameters
[in]sessionSession to use for SR subscriptions.
[in]streamStream to subscribe to.
[in]xpath_filterOptional XPath filter to use.
[in]stop_timeOptional stop-time of the subscription. Once reached, the `subscription-terminated' notification is generated.
[in]start_timeOptional start-time of the subscription, requires the 'replay' feature.
[in]sub_no_threadSet if the created subscriptions should not create a separate handling thread.
[in,out]subOptional subscription structure to use and add SR subscriptions to.
[out]replay_start_timeOptional replay-start-time of the subscription if start-time was set.
[out]fdPipe end for reading the generated notifications. Needs to be closed.
[out]sub_idUnique subscribed-notifications ID.
Returns
Error code (SR_ERR_OK on success).
int srsn_suspend ( uint32_t  sub_id,
const char *  reason 
)

Suspend a subscribed-notifications subscription.

Generates the 'subscription-suspended' notification.

Parameters
[in]sub_idSubscription ID of the subscription to suspend.
[in]reasonReason for the suspension as an identityref value. If not set, no notification is generated.
Returns
Error code (SR_ERR_OK on success).
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_idSubscription ID of the subscription to terminate.
[in]reasonReason 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.
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_idSubscription ID of the subscription to modify.
[in]dampening_period_msDampening period in ms to set.
Returns
Error code (SR_ERR_OK on success).
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_idSubscription ID of the subscription to modify.
[in]period_msPeriod in ms to set.
[in]anchor_timeAnchor time of the period to set, NULL to unset.
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 
)

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

Parameters
[in]sessionSession to use for SR subscriptions.
[in]dsDatastore to subscribe to.
[in]xpath_filterOptional XPath filter to use.
[in]dampening_period_msOptional notification dampening period in ms.
[in]sync_on_startWhether to start the subscription with a full datastore content notification.
[in]excluded_changesOptional 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_timeOptional stop-time of the subscription. Once reached, the `subscription-terminated' notification is generated.
[in]sub_no_threadSet if the created subscriptions should not create a separate handling thread.
[in,out]subOptional subscription structure to use and add SR subscriptions to.
[out]fdPipe end for reading the generated notifications. Needs to be closed.
[out]sub_idUnique subscribed-notifications ID.
Returns
Error code (SR_ERR_OK on success).
int srsn_yang_push_on_change_resync ( uint32_t  sub_id)

Resync a yang-push on-change subscription.

Parameters
[in]sub_idSubscription ID of the subscription to resync.
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 periodic subscriptions.

Parameters
[in]sessionSession to use for SR operations.
[in]dsDatastore to subscribe to.
[in]xpath_filterOptional XPath filter to use.
[in]period_msNotification period in ms.
[in]anchor_timeOptional anchor time of the period.
[in]stop_timeOptional stop-time of the subscription. Once reached, the `subscription-terminated' notification is generated.
[out]fdPipe end for reading the generated notifications. Needs to be closed.
[out]sub_idUnique subscribed-notifications ID.
Returns
Error code (SR_ERR_OK on success).