Loading...
Searching...
No Matches
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.__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_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 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_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).