Loading...
Searching...
No Matches
Subscription API

## Functions

int | sr_get_event_pipe (sr_subscription_ctx_t *subscription, int *event_pipe)
| Get the event pipe of a subscription. Do not call unless SR_SUBSCR_NO_THREAD flag was used when subscribing! Event pipe can be used in select(), poll(), or similar functions to listen for new events. It will then be ready for reading.
uint32_t | sr_subscription_get_last_sub_id (const sr_subscription_ctx_t *subscription)
| Get the subscription ID of the last created subscription.
int | sr_subscription_get_suspended (sr_subscription_ctx_t *subscription, uint32_t sub_id, int *suspended)
| Learn the suspend state of a specific subscription.
int | sr_subscription_process_events (sr_subscription_ctx_t *subscription, sr_session_ctx_t *session, struct timespec *wake_up_in)
| Process any pending new events on a subscription. Should not be called unless SR_SUBSCR_NO_THREAD flag was used when subscribing! Usually called after this subscription's event pipe is ready for reading but can also be called periodically.
int | sr_subscription_resume (sr_subscription_ctx_t *subscription, uint32_t sub_id)
| Resume a previously suspended subscription. Special SR_EV_NOTIF_RESUMED notification is delivered for resumed notification subscriptions.
int | sr_subscription_suspend (sr_subscription_ctx_t *subscription, uint32_t sub_id)
| Suspend a specific subscription. Special SR_EV_NOTIF_SUSPENDED notification is delivered for suspended notification subscriptions.
int | sr_subscription_thread_notify (sr_subscription_ctx_t *subscription)
| Notify (wake up) a subscription thread signalling there is a new event to process. Useful, for example, when an event return SR_ERR_CALLBACK_SHELVE to signal that the event can now be fully processed.
int | sr_subscription_thread_resume (sr_subscription_ctx_t *subscription)
| Resume the default handler thread of a subscription structure that was suspended previously.
int | sr_subscription_thread_suspend (sr_subscription_ctx_t *subscription)
| Suspend the default handler thread of a subscription structure. Meaning it will stop handling any events on the subscription until it is resumed.
int | sr_unsubscribe (sr_subscription_ctx_t *subscription)
| Unsubscribe all the subscriptions in a subscription structure and free it.
int | sr_unsubscribe_sub (sr_subscription_ctx_t *subscription, uint32_t sub_id)
| Unsubscribe a specific or all the subscriptions in a subscription structure.
enum | sr_subscr_flag_t { SR_SUBSCR_DEFAULT = 0x00 , SR_SUBSCR_NO_THREAD = 0x01 , SR_SUBSCR_PASSIVE = 0x02 , SR_SUBSCR_DONE_ONLY = 0x04 , SR_SUBSCR_ENABLED = 0x08 , SR_SUBSCR_UPDATE = 0x10 , SR_SUBSCR_OPER_MERGE = 0x20 , SR_SUBSCR_THREAD_SUSPEND = 0x40 , SR_SUBSCR_OPER_POLL_DIFF = 0x80 , SR_SUBSCR_FILTER_ORIG = 0x0100 , SR_SUBSCR_CHANGE_ALL_MODULES = 0x0200 }
| Flags used to override default handling of subscriptions. More...
typedef struct sr_subscription_ctx_s | sr_subscription_ctx_t
| Sysrepo subscription context returned from sr_*_subscribe calls, it is supposed to be released by the caller using sr_unsubscribe call.
typedef uint32_t | sr_subscr_options_t
| Options overriding default behavior of subscriptions, it is supposed to be a bitwise OR-ed value of any sr_subscr_flag_t flags.

## Detailed Description

## Typedef Documentation

## sr_subscr_options_t

typedef uint32_t sr_subscr_options_t

Options overriding default behavior of subscriptions, it is supposed to be a bitwise OR-ed value of any sr_subscr_flag_t flags.

Definition at line 485 of file sysrepo_types.h.

## sr_subscription_ctx_t

typedef struct sr_subscription_ctx_s sr_subscription_ctx_t

Sysrepo subscription context returned from sr_*_subscribe calls, it is supposed to be released by the caller using sr_unsubscribe call.

Definition at line 479 of file sysrepo_types.h.

## Enumeration Type Documentation

## sr_subscr_flag_t

enum sr_subscr_flag_t

Flags used to override default handling of subscriptions.

Enumerator

SR_SUBSCR_DEFAULT

Default behavior of the subscription. In case of sr_module_change_subscribe call it means that:

- for every new subscription structure a thread is created that listens for new events (can be changed with SR_SUBSCR_NO_THREAD flag),
- the subscriber is the "owner" of the subscribed data tree and it will appear in the operational datastore while this subscription is alive (if not already, can be changed using SR_SUBSCR_PASSIVE flag),
- the callback will normally be called twice, once with SR_EV_CHANGE event and once with SR_EV_DONE event passed in (can be changed with SR_SUBSCR_DONE_ONLY flag),
- if a callback fails on SR_EV_CHANGE, all the previously succeeded callbacks will be called with SR_EV_ABORT (excluding the failed callback itself).

SR_SUBSCR_NO_THREAD | There will be no thread created for handling this subscription meaning no event will be processed! Use this flag when the application has its own event loop and it will listen for and process events manually (see sr_get_event_pipe and sr_subscription_process_events).
SR_SUBSCR_PASSIVE | The subscriber is not the "owner" of the subscribed data tree, just a passive watcher for changes. When this option is passed in to sr_module_change_subscribe, the subscription will have no effect on the presence of the subtree in the operational datastore.
SR_SUBSCR_DONE_ONLY | The subscriber does not support verification of the changes and wants to be notified only after the changes has been applied in the datastore, without the possibility to deny them (it will not receive SR_EV_CHANGE nor SR_EV_ABORT but only SR_EV_DONE events).

SR_SUBSCR_ENABLED

The subscriber wants to be notified about the current configuration at the moment of subscribing. It will receive SR_EV_ENABLED event, whose applying can fail causing the whole subscription to fail. On success this event will be followed by SR_EV_DONE. Be careful, SR_EV_ENABLED will be triggered even if there are no data so there will not be any changes! Also, this event callback is called as part of the subscribe call (in the same thread) unlike other events.

SR_SUBSCR_UPDATE

The subscriber will be called before any other subscribers for the particular module with an additional SR_EV_UPDATE event and is then allowed to modify the new module data. It can add new changes by calling standard set functions (such as sr_set_item_str) on the implicit callback session and returning. Note that you cannot subscribe more callbacks with this flag on one module with the same priority.

SR_SUBSCR_OPER_MERGE | Instead of removing any previous existing matching data before getting them from an operational subscription callback, keep them. Then the returned data are merged into the existing data. Accepted only for sr_oper_get_subscribe().
SR_SUBSCR_THREAD_SUSPEND | Suspend the default handler thread before adding the subscription if it is running. In case of the first subscription, start the handler thread suspended. Meaning any events will not be handled until sr_subscription_thread_resume() is called.
SR_SUBSCR_OPER_POLL_DIFF | On every data retrieval additionally compute diff with the previous data and report the changes to any operational data module change subscriptions. Accepted only for sr_oper_poll_subscribe().
SR_SUBSCR_FILTER_ORIG | Normally, XPath filter is applied by the listener (subscriber) for counting its statistics of filtered-out events. Using this option the event originator performs the filtering to unburden the subscriber of unnecessary event handling but results in 0 filtered-out changes returned by sr_module_change_sub_get_info(). Accepted only for sr_module_change_subscribe().

SR_SUBSCR_CHANGE_ALL_MODULES

If you call getters (sr_get_data()) in the module change callback for data from other modules than the one the callback subscribed for, use this flag. Normally, only the changes of the subscribed module are sent to the callback so it retrieves the old data of other modules. This flag does not affect SR_EV_DONE event because by then the changes of all the modules are written into the datastore (so it makes no sense to combine this flag with SR_SUBSCR_DONE_ONLY).

Definition at line 383 of file sysrepo_types.h.

## Function Documentation

## sr_get_event_pipe()

int sr_get_event_pipe | ( | sr_subscription_ctx_t * | subscription,
|  | int * | event_pipe )

Get the event pipe of a subscription. Do not call unless SR_SUBSCR_NO_THREAD flag was used when subscribing! Event pipe can be used in select(), poll(), or similar functions to listen for new events. It will then be ready for reading.

Parameters

  [in] | subscription | Subscription without a listening thread.
  [out] | event_pipe | Event pipe of the subscription, do not close! It will be closed when the subscription is unsubscribed.

Returns
  Error code (SR_ERR_OK on success).

## sr_subscription_get_last_sub_id()

uint32_t sr_subscription_get_last_sub_id | ( | const sr_subscription_ctx_t * | subscription | ) |

Get the subscription ID of the last created subscription.

Parameters

  [in] | subscription | Subscription context to read from.

Returns
  Unique subscription ID.

## sr_subscription_get_suspended()

int sr_subscription_get_suspended | ( | sr_subscription_ctx_t * | subscription,
|  | uint32_t | sub_id,
|  | int * | suspended )

Learn the suspend state of a specific subscription.

Parameters

  [in] | subscription | Subscription context to use.
  [in] | sub_id | Subscription ID of the subscription to check.
  [out] | suspended | Whether the subscription is suspended or not.

Returns
  Error code (SR_ERR_OK on success).

## sr_subscription_process_events()

int sr_subscription_process_events | ( | sr_subscription_ctx_t * | subscription,
|  | sr_session_ctx_t * | session,
|  | struct timespec * | wake_up_in )

Process any pending new events on a subscription. Should not be called unless SR_SUBSCR_NO_THREAD flag was used when subscribing! Usually called after this subscription's event pipe is ready for reading but can also be called periodically.

Parameters

  [in] | subscription | Subscription without a listening thread with some new events.
  [in] | session | Optional session for storing errors.
  [out] | wake_up_in | Optional time when a scheduled event occurs and this function should be called again. It can be the nearest notification subscription stop time or operational poll subscription cache update. If there are no scheduled events in future, it is zeroed.

Returns
  Error code (SR_ERR_OK on success).

## sr_subscription_resume()

int sr_subscription_resume | ( | sr_subscription_ctx_t * | subscription,
|  | uint32_t | sub_id )

Resume a previously suspended subscription. Special SR_EV_NOTIF_RESUMED notification is delivered for resumed notification subscriptions.

Parameters

  [in] | subscription | Subscription context to use.
  [in] | sub_id | Subscription ID of the specific subscription to resume.

Returns
  Error code (SR_ERR_OK on success).

## sr_subscription_suspend()

int sr_subscription_suspend | ( | sr_subscription_ctx_t * | subscription,
|  | uint32_t | sub_id )

Suspend a specific subscription. Special SR_EV_NOTIF_SUSPENDED notification is delivered for suspended notification subscriptions.

Parameters

  [in] | subscription | Subscription context to use.
  [in] | sub_id | Subscription ID of the specific subscription to suspend.

Returns
  Error code (SR_ERR_OK on success).

## sr_subscription_thread_notify()

int sr_subscription_thread_notify | ( | sr_subscription_ctx_t * | subscription | ) |

Notify (wake up) a subscription thread signalling there is a new event to process. Useful, for example, when an event return SR_ERR_CALLBACK_SHELVE to signal that the event can now be fully processed.

Parameters

  [in] | subscription | Subscription context with a handler thread.

Returns
  Error code (SR_ERR_OK on success).

## sr_subscription_thread_resume()

int sr_subscription_thread_resume | ( | sr_subscription_ctx_t * | subscription | ) |

Resume the default handler thread of a subscription structure that was suspended previously.

Parameters

  [in] | subscription | Subscription context with a handler thread.

Returns
  Error code (SR_ERR_OK on success).

## sr_subscription_thread_suspend()

int sr_subscription_thread_suspend | ( | sr_subscription_ctx_t * | subscription | ) |

Suspend the default handler thread of a subscription structure. Meaning it will stop handling any events on the subscription until it is resumed.

Parameters

  [in] | subscription | Subscription context with a handler thread.

Returns
  Error code (SR_ERR_OK on success).

## sr_unsubscribe()

int sr_unsubscribe | ( | sr_subscription_ctx_t * | subscription | ) |

Unsubscribe all the subscriptions in a subscription structure and free it.

Note
  On SR_ERR_TIME_OUT the function should be retried and must eventually succeed.

Parameters

  [in] | subscription | Subscription context to free.

Returns
  Error code (SR_ERR_OK on success).

## sr_unsubscribe_sub()

int sr_unsubscribe_sub | ( | sr_subscription_ctx_t * | subscription,
|  | uint32_t | sub_id )

Unsubscribe a specific or all the subscriptions in a subscription structure.

If all subscriptions are being unsubscribed, the subscription structure can still be used normally until sr_unsubscribe() is called, even if there are no actual subscriptions left in it. This is useful for preventing dead locks if using the subscription in a custom event loop.

Note
  On SR_ERR_TIME_OUT the function should be retried and must eventually succeed.

Parameters

  [in] | subscription | Subscription context to use.
  [in] | sub_id | Subscription ID of the subscription to unsubscribe, 0 for all the subscriptions.

Returns
  Error code (SR_ERR_OK on success).