sysrepo  1.4.58
YANG datastore
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Subscription API

Typedefs

typedef enum sr_subscr_flag_e sr_subscr_flag_t
 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. More...
 
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. More...
 

Enumerations

enum  sr_subscr_flag_e {
  SR_SUBSCR_DEFAULT = 0, SR_SUBSCR_CTX_REUSE = 1, SR_SUBSCR_NO_THREAD = 2, SR_SUBSCR_PASSIVE = 4,
  SR_SUBSCR_DONE_ONLY = 8, SR_SUBSCR_ENABLED = 16, SR_SUBSCR_UPDATE = 32, SR_SUBSCR_UNLOCKED = 64,
  SR_SUBSCR_OPER_MERGE = 128
}
 Flags used to override default handling of subscriptions. More...
 

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. More...
 
int sr_process_events (sr_subscription_ctx_t *subscription, sr_session_ctx_t *session, time_t *stop_time_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. More...
 
int sr_unsubscribe (sr_subscription_ctx_t *subscription)
 Unsubscribes from a subscription acquired by any of sr_*_subscribe calls and releases all subscription-related data. More...
 

Detailed Description

Typedef Documentation

Flags used to override default handling of subscriptions.

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 1193 of file sysrepo.h.

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 1199 of file sysrepo.h.

Enumeration Type Documentation

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:

SR_SUBSCR_CTX_REUSE 

This option enables the application to re-use an already existing subscription context previously returned from any sr_*_subscribe call instead of requesting the creation of a new one. In that case a single sr_unsubscribe call unsubscribes from all subscriptions filed within the context.

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_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!

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 flags on one module with the same priority.

SR_SUBSCR_UNLOCKED 

The subscriber wants to modify other subscriptions in its callback. Normally, this would cause deadlock but with this flag it is possible. But, there are some limitations. The callback MUST not subscribe to the same RPC/module DS changes it is processing (would change subscription count and cause invalid memory access) and MUST not subscribe on the same sr_subscription_ctx_t subscription (would cause a deadlock). Accepted only for RPC/action and change subscriptions, it makes no sense for others.

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 operational subscriptions.

Definition at line 1113 of file sysrepo.h.

Function Documentation

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]subscriptionSubscription without a listening thread.
[out]event_pipeEvent pipe of the subscription, do not close! It will be closed when the subscription is unsubscribed.
Returns
Error code (SR_ERR_OK on success).
int sr_process_events ( sr_subscription_ctx_t subscription,
sr_session_ctx_t session,
time_t *  stop_time_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]subscriptionSubscription without a listening thread with some new events.
[in]sessionOptional session for storing errors.
[out]stop_time_inOptional seconds until the nearest notification subscription stop time is elapsed and this function should be called. If there are no subscriptions with stop time in future, it is set to 0.
Returns
Error code (SR_ERR_OK on success).
int sr_unsubscribe ( sr_subscription_ctx_t subscription)

Unsubscribes from a subscription acquired by any of sr_*_subscribe calls and releases all subscription-related data.

In case that the same subscription context was used to subscribe for multiple subscriptions, unsubscribes from all of them.

Note
Subscription will no longer work even on error.
Parameters
[in]subscriptionSubscription context acquired by any of sr_*_subscribe calls.
Returns
Error code (SR_ERR_OK on success).