Loading...
Searching...
No Matches
Datastore Plugin API

## Data Structures

struct | srplg_ds_s
| Datastore plugin structure. More...

## Macros

#define | SRPLG_DATASTORE
| Macro to define datastore plugin information in external plugins.
#define | SRPLG_DS_API_VERSION 13
| Datastore plugin API version.

## Typedefs

typedef sr_error_info_t *(* | srds_access_check) (const struct lys_module *mod, sr_datastore_t ds, void *plg_data, int *read, int *write)
| Check whether the current user has the required access to datastore data.
typedef sr_error_info_t *(* | srds_access_get) (const struct lys_module *mod, sr_datastore_t ds, void *plg_data, char **owner, char **group, mode_t *perm)
| Get access permissions for datastore data of a module. This function is also used for sysrepo access control checks for the module when SR_DS_STARTUP is used.
typedef sr_error_info_t *(* | srds_access_set) (const struct lys_module *mod, sr_datastore_t ds, const char *owner, const char *group, mode_t perm, void *plg_data)
| Set access permissions for datastore data of a module.
typedef sr_error_info_t *(* | srds_candidate_modified) (const struct lys_module *mod, void *plg_data, int *modified)
| Learn whether the candidate datastore was modified and is different from running.
typedef sr_error_info_t *(* | srds_candidate_reset) (const struct lys_module *mod, void *plg_data)
| Reset candidate datastore to "no changes" - mirroring running.
typedef void(* | srds_conn_destroy) (sr_conn_ctx_t *conn, void *plg_data)
| Destroy (free) per-connection plugin data.
typedef sr_error_info_t *(* | srds_conn_init) (sr_conn_ctx_t *conn, void **plg_data)
| Initialize per-connection plugin data.
typedef sr_error_info_t *(* | srds_copy) (const struct lys_module *mod, sr_datastore_t trg_ds, sr_datastore_t src_ds, void *plg_data)
| Copy data of a module from source datastore to the target datastore.
typedef sr_error_info_t *(* | srds_data_version) (const struct lys_module *mod, sr_datastore_t ds, void *plg_data, uint32_t *version)
| Get the current datastore data version, optional callback.
typedef sr_error_info_t *(* | srds_init) (const struct lys_module *mod, sr_datastore_t ds, void *plg_data)
| Initialize data of a newly installed module.
typedef sr_error_info_t *(* | srds_install) (const struct lys_module *mod, sr_datastore_t ds, const char *owner, const char *group, mode_t perm, void *plg_data)
| Setup datastore of a newly installed module.
typedef sr_error_info_t *(* | srds_last_modif) (const struct lys_module *mod, sr_datastore_t ds, void *plg_data, struct timespec *mtime)
| Get the time when the datastore data of the module were last modified or 0 if the datastore data are not modified (see `ds`).
typedef sr_error_info_t *(* | srds_load) (const struct lys_module *mod, sr_datastore_t ds, sr_cid_t cid, uint32_t sid, const char **xpaths, uint32_t xpath_count, void *plg_data, struct lyd_node **mod_data)
| Load data of a module.
typedef sr_error_info_t *(* | srds_store_commit) (const struct lys_module *mod, sr_datastore_t ds, sr_cid_t cid, uint32_t sid, const struct lyd_node *mod_diff, const struct lyd_node *mod_data, void *plg_data)
| Store data for a module. Either a diff can be applied manually (if available) or full new data tree stored.
typedef sr_error_info_t *(* | srds_store_prepare) (const struct lys_module *mod, sr_datastore_t ds, sr_cid_t cid, uint32_t sid, const struct lyd_node *mod_diff, const struct lyd_node *mod_data, void *plg_data)
| Prepare to store data for a module. Either a diff can be applied manually (if available) or full new data tree store prepared.
typedef sr_error_info_t *(* | srds_uninstall) (const struct lys_module *mod, sr_datastore_t ds, void *plg_data)
| Destroy data of an uninstalled module.

## Detailed Description

## Data Structure Documentation

## srplg_ds_s

struct srplg_ds_s

Datastore plugin structure.

Definition at line 312 of file plugins_datastore.h.

Data Fields
srds_access_check | access_check_cb | callback for checking user access to module data
srds_access_get | access_get_cb | callback for getting access rights for module data
srds_access_set | access_set_cb | callback for setting access rights for module data
srds_candidate_modified | candidate_modified_cb | callback for checking whether candidate was modified
srds_candidate_reset | candidate_reset_cb | callback for resetting candidate to running
srds_conn_destroy | conn_destroy_cb | callback for per-connection data destroy
srds_conn_init | conn_init_cb | callback for per-connection data initialization
srds_copy | copy_cb | callback for copying stored module data from one datastore to another
srds_data_version | data_version_cb | optional callback for checking data version
srds_init | init_cb | callback for after-boot initialization of a module
srds_install | install_cb | callback for installing a new module
srds_last_modif | last_modif_cb | callback for getting the time of last modification
srds_load | load_cb | callback for loading stored module data
const char * | name | name of the datastore implementation plugin by which it is referenced
srds_store_commit | store_commit_cb | callback for storing module data (called with module WRITE lock)
srds_store_prepare | store_prepare_cb | callback for preparing to store module data (called with module READ UPGR or higher lock)
srds_uninstall | uninstall_cb | callback for uninstalling a removed module

## Macro Definition Documentation

## SRPLG_DATASTORE

#define SRPLG_DATASTORE

Value:
uint32_t srpds_apiver__ = SRPLG_DS_API_VERSION; \
const struct srplg_ds_s srpds__
srplg_ds_s
Datastore plugin structure.
Definition plugins_datastore.h:312
SRPLG_DS_API_VERSION
#define SRPLG_DS_API_VERSION
Datastore plugin API version.
Definition plugins_datastore.h:43

Macro to define datastore plugin information in external plugins.

Use as follows: SRPLG_DATASTORE = {<filled information of srplg_ds_s>};

Definition at line 338 of file plugins_datastore.h.

## SRPLG_DS_API_VERSION

#define SRPLG_DS_API_VERSION 13

Datastore plugin API version.

Definition at line 43 of file plugins_datastore.h.

## Typedef Documentation

## srds_access_check

typedef sr_error_info_t *(* srds_access_check) (const struct lys_module *mod, sr_datastore_t ds, void *plg_data, int *read, int *write)

Check whether the current user has the required access to datastore data.

Parameters

  [in] | mod | Specific module.
  [in] | ds | Specific datastore.
  [in] | plg_data | Plugin data.
  [out] | read | Optional, whether the read permission was granted or not.
  [out] | write | Optional, whether the write permission was granted or not.

Returns
  NULL on success;
  Sysrepo error info on error.

Definition at line 269 of file plugins_datastore.h.

## srds_access_get

typedef sr_error_info_t *(* srds_access_get) (const struct lys_module *mod, sr_datastore_t ds, void *plg_data, char **owner, char **group, mode_t *perm)

Get access permissions for datastore data of a module. This function is also used for sysrepo access control checks for the module when SR_DS_STARTUP is used.

Parameters

  [in] | mod | Specific module.
  [in] | ds | Specific datastore.
  [in] | plg_data | Plugin data.
  [out] | owner | Optional owner of the module data.
  [out] | group | Optional group of the module data.
  [out] | perm | Optional permissions of the module data.

Returns
  NULL on success;
  Sysrepo error info on error.

Definition at line 255 of file plugins_datastore.h.

## srds_access_set

typedef sr_error_info_t *(* srds_access_set) (const struct lys_module *mod, sr_datastore_t ds, const char *owner, const char *group, mode_t perm, void *plg_data)

Set access permissions for datastore data of a module.

Parameters

  [in] | mod | Specific module.
  [in] | ds | Specific datastore.
  [in] | owner | Optional new owner of the module data.
  [in] | group | Optional new group of the module data.
  [in] | perm | Optional new permissions of the module data, execute bits are never set.
  [in] | plg_data | Plugin data.

Returns
  NULL on success;
  Sysrepo error info on error.

Definition at line 239 of file plugins_datastore.h.

## srds_candidate_modified

typedef sr_error_info_t *(* srds_candidate_modified) (const struct lys_module *mod, void *plg_data, int *modified)

Learn whether the candidate datastore was modified and is different from running.

Parameters

  [in] | mod | Specific module.
  [in] | plg_data | Plugin data.
  [out] | modified | Whether the candidate datastore data were modified or not.

Returns
  NULL on success;
  Sysrepo error info on error.

Definition at line 215 of file plugins_datastore.h.

## srds_candidate_reset

typedef sr_error_info_t *(* srds_candidate_reset) (const struct lys_module *mod, void *plg_data)

Reset candidate datastore to "no changes" - mirroring running.

Parameters

  [in] | mod | Specific module.
  [in] | plg_data | Plugin data.

Returns
  NULL on success;
  Sysrepo error info on error.

Definition at line 225 of file plugins_datastore.h.

## srds_conn_destroy

typedef void(* srds_conn_destroy) (sr_conn_ctx_t *conn, void *plg_data)

Destroy (free) per-connection plugin data.

Is called for every connection srds_conn_init was called.

Parameters

  [in] | conn | Connection.
  [in] | plg_data | Plugin data to free.

Definition at line 111 of file plugins_datastore.h.

## srds_conn_init

typedef sr_error_info_t *(* srds_conn_init) (sr_conn_ctx_t *conn, void **plg_data)

Initialize per-connection plugin data.

If there is any module using the DS plugin, for each new connection this callback is called. Its purpose is to allow preparing per-process data. Since processes with running connections cannot be forked, the data will not be forked either.

Parameters

  [in] | conn | New connection.
  [out] | plg_data | Arbitrary DS plugin data.

Returns
  NULL on success;
  Sysrepo error info on error.

Definition at line 101 of file plugins_datastore.h.

## srds_copy

typedef sr_error_info_t *(* srds_copy) (const struct lys_module *mod, sr_datastore_t trg_ds, sr_datastore_t src_ds, void *plg_data)

Copy data of a module from source datastore to the target datastore.

Called only if this plugin is used for both datastores of a module.

Read/write access rights do not have to be checked, srds_access_check() is called before this callback.

Parameters

  [in] | mod | Specific module.
  [in] | trg_ds | Target datastore.
  [in] | src_ds | Source datastore.
  [in] | plg_data | Plugin data.

Returns
  NULL on success;
  Sysrepo error info on error.

Definition at line 203 of file plugins_datastore.h.

## srds_data_version

typedef sr_error_info_t *(* srds_data_version) (const struct lys_module *mod, sr_datastore_t ds, void *plg_data, uint32_t *version)

Get the current datastore data version, optional callback.

The function must return a higher `version` (number) than previously in case the data has changed in the meantime. This callback needs to be defined in case the data can be changed by other sources than sysrepo, to make sure any cached data are invalidated and current data loaded instead.

Note
  The srds_last_modif callback could be used to implement this callback but the reason it is not used directly is that, in general, the (file) system does not guarantee that file modification time is updated on every file change. Specifically, the timestamp for this purpose may be cached and if a change happens right after a previous change, the timestamp written may be the same, which is a CRITICAL problem because the old data would be considered current.

Parameters

  [in] | mod | Specific module.
  [in] | ds | Specific datastore, set always to SR_DS_RUNNING.
  [in] | plg_data | Plugin data.
  [out] | version | Current data version, different than the previous if data changed since then.

Returns
  NULL on success;
  Sysrepo error info on error.

Definition at line 306 of file plugins_datastore.h.

## srds_init

typedef sr_error_info_t *(* srds_init) (const struct lys_module *mod, sr_datastore_t ds, void *plg_data)

Initialize data of a newly installed module.

Init is called after fresh reboot of the system for every module for each datastore. Also, right after srds_install is called and afterwards the data of the module must be valid meaning any following srds_load must return the stored data (may be empty).

Parameters

  [in] | mod | Specific module.
  [in] | ds | Specific datastore.
  [in] | plg_data | Plugin data.

Returns
  NULL on success;
  Sysrepo error info on error.

Definition at line 87 of file plugins_datastore.h.

## srds_install

typedef sr_error_info_t *(* srds_install) (const struct lys_module *mod, sr_datastore_t ds, const char *owner, const char *group, mode_t perm, void *plg_data)

Setup datastore of a newly installed module.

Install is called once for every new installed module for each enabled datastore. Right after that srds_init is called.

Parameters

  [in] | mod | Specific module.
  [in] | ds | Specific datastore.
  [in] | owner | Optional initial owner of the module data, process user by default.
  [in] | group | Optional initial group of the module data, process group by default.
  [in] | perm | Initial permissions of the module data, execute bits are never set.
  [in] | plg_data | Plugin data.

Returns
  NULL on success;
  Sysrepo error info on error.

Definition at line 60 of file plugins_datastore.h.

## srds_last_modif

typedef sr_error_info_t *(* srds_last_modif) (const struct lys_module *mod, sr_datastore_t ds, void *plg_data, struct timespec *mtime)

Get the time when the datastore data of the module were last modified or 0 if the datastore data are not modified (see `ds`).

Parameters

  [in] | mod | Specific module.
  [in] | ds | Specific datastore. For SR_DS_CANDIDATE and SR_DS_OPERATIONAL, in case there and no data/changes stored, `mtime` should be set to 0.
  [in] | plg_data | Plugin data.
  [out] | mtime | Time of last modification, or 0 when it is unknown.

Returns
  NULL on success;
  Sysrepo error info on error.

Definition at line 284 of file plugins_datastore.h.

## srds_load

typedef sr_error_info_t *(* srds_load) (const struct lys_module *mod, sr_datastore_t ds, sr_cid_t cid, uint32_t sid, const char **xpaths, uint32_t xpath_count, void *plg_data, struct lyd_node **mod_data)

Load data of a module.

This callback will be called with `ds` SR_DS_CANDIDATE only if the datastore is modified, otherwise SR_DS_RUNNING is used directly. May be called simultanously but with unique `mod` and `ds` pairs.

Read access rights do not have to be checked, srds_access_check() is called before this callback.

Parameters

  [in] | mod | Specific module.
  [in] | ds | Specific datastore.
  [in] | cid | ID of the connection of the session, relevant for `ds` SR_DS_OPERATIONAL.
  [in] | sid | ID of the session whose data to load, relevant for `ds` SR_DS_OPERATIONAL.
  [in] | xpaths | Array of XPaths selecting the required data, NULL if all the module data are needed.
  [in] | xpath_count | Number of `xpaths`.
  [in] | plg_data | Plugin data.
  [out] | mod_data | Loaded module data using the context of `mod`.

Returns
  NULL on success;
  Sysrepo error info on error.

Definition at line 186 of file plugins_datastore.h.

## srds_store_commit

typedef sr_error_info_t *(* srds_store_commit) (const struct lys_module *mod, sr_datastore_t ds, sr_cid_t cid, uint32_t sid, const struct lyd_node *mod_diff, const struct lyd_node *mod_data, void *plg_data)

Store data for a module. Either a diff can be applied manually (if available) or full new data tree stored.

If `ds` is SR_DS_CANDIDATE and it has not been modified (srds_candidate_modified() returns 0) then `mod_diff` is actually the difference between previous SR_DS_RUNNING contents and the new SR_DS_CANDIDATE contents.

May be called simultaneously but with unique `mod` and `ds` pairs.

Write access rights do not have to be checked, srds_access_check() is called before this callback.

Module WRITE locks are expected to be held for this operation.

Parameters

  [in] | mod | Specific module.
  [in] | ds | Specific datastore.
  [in] | cid | ID of the connection storing the data, relevant for `ds` SR_DS_OPERATIONAL.
  [in] | sid | ID of the session storing the data, relevant for `ds` SR_DS_OPERATIONAL.
  [in] | mod_diff | Diff of currently stored module data and the new `mod_data`. Not always available. (e.g. when deleting all push operational data).
  [in] | mod_data | New module data tree to store. If `ds` SR_DS_OPERATIONAL, every node may have a metadata instance of 'ietf-origin:origin' that needs to be stored. Also, top-level 'discard-items' opaque nodes may be present.
  [in] | plg_data | Plugin data.

Returns
  NULL on success;
  Sysrepo error info on error.

Definition at line 164 of file plugins_datastore.h.

## srds_store_prepare

typedef sr_error_info_t *(* srds_store_prepare) (const struct lys_module *mod, sr_datastore_t ds, sr_cid_t cid, uint32_t sid, const struct lyd_node *mod_diff, const struct lyd_node *mod_data, void *plg_data)

Prepare to store data for a module. Either a diff can be applied manually (if available) or full new data tree store prepared.

If `ds` is SR_DS_CANDIDATE and it has not been modified (srds_candidate_modified() returns 0) then `mod_diff` is actually the difference between previous SR_DS_RUNNING contents and the new SR_DS_CANDIDATE contents.

May be called simultaneously but with unique `mod` and `ds` pairs.

Write access rights do not have to be checked, srds_access_check() is called before this callback.

This callback must only prepare to store the data in a next step by calling srds_store_commit(). Module READ-UPGRADE lock or higher is acquired before calling srds_store_prepare() callback. So, the callback should not rely on having a WRITE lock.

Parameters

  [in] | mod | Specific module.
  [in] | ds | Specific datastore.
  [in] | cid | ID of the connection storing the data, relevant for `ds` SR_DS_OPERATIONAL.
  [in] | sid | ID of the session storing the data, relevant for `ds` SR_DS_OPERATIONAL.
  [in] | mod_diff | Diff of currently stored module data and the new `mod_data`. Not always available.
  [in] | mod_data | New module data tree to store. If `ds` SR_DS_OPERATIONAL, every node may have a metadata instance of 'ietf-origin:origin' that needs to be stored. Also, top-level 'discard-items' opaque nodes may be present.
  [in] | plg_data | Plugin data.

Returns
  NULL on success;
  Sysrepo error info on error.

Definition at line 138 of file plugins_datastore.h.

## srds_uninstall

typedef sr_error_info_t *(* srds_uninstall) (const struct lys_module *mod, sr_datastore_t ds, void *plg_data)

Destroy data of an uninstalled module.

Parameters

  [in] | mod | Specific module.
  [in] | ds | Specific datastore.
  [in] | plg_data | Plugin data.

Returns
  NULL on success;
  Sysrepo error info on error.

Definition at line 72 of file plugins_datastore.h.