sysrepo  3.0.0
YANG-based system repository for all-around configuration management.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Macros | Typedefs
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. More...
 
#define SRPLG_DS_API_VERSION   12
 Datastore plugin API version. More...
 

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. More...
 
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. More...
 
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. More...
 
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. More...
 
typedef sr_error_info_t *(* srds_candidate_reset )(const struct lys_module *mod, void *plg_data)
 Reset candidate datastore to "no changes" - mirroring running. More...
 
typedef void(* srds_conn_destroy )(sr_conn_ctx_t *conn, void *plg_data)
 Destroy (free) per-connection plugin data. More...
 
typedef sr_error_info_t *(* srds_conn_init )(sr_conn_ctx_t *conn, void **plg_data)
 Initialize per-connection plugin data. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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). More...
 
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. More...
 
typedef sr_error_info_t *(* srds_store )(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. More...
 
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. More...
 

Detailed Description

Data Structure Documentation

struct srplg_ds_s

Datastore plugin structure.

Definition at line 282 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 store_cb

callback for storing module data

srds_uninstall uninstall_cb

callback for uninstalling a removed module

Macro Definition Documentation

#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:282
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 307 of file plugins_datastore.h.

#define SRPLG_DS_API_VERSION   12

Datastore plugin API version.

Definition at line 43 of file plugins_datastore.h.

Typedef Documentation

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]modSpecific module.
[in]dsSpecific datastore.
[in]plg_dataPlugin data.
[out]readOptional, whether the read permission was granted or not.
[out]writeOptional, whether the write permission was granted or not.
Returns
NULL on success;
Sysrepo error info on error.

Definition at line 239 of file plugins_datastore.h.

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]modSpecific module.
[in]dsSpecific datastore.
[in]plg_dataPlugin data.
[out]ownerOptional owner of the module data.
[out]groupOptional group of the module data.
[out]permOptional permissions of the module data.
Returns
NULL on success;
Sysrepo error info on error.

Definition at line 225 of file plugins_datastore.h.

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]modSpecific module.
[in]dsSpecific datastore.
[in]ownerOptional new owner of the module data.
[in]groupOptional new group of the module data.
[in]permOptional new permissions of the module data, execute bits are never set.
[in]plg_dataPlugin data.
Returns
NULL on success;
Sysrepo error info on error.

Definition at line 209 of file plugins_datastore.h.

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]modSpecific module.
[in]plg_dataPlugin data.
[out]modifiedWhether the candidate datastore data were modified or not.
Returns
NULL on success;
Sysrepo error info on error.

Definition at line 185 of file plugins_datastore.h.

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]modSpecific module.
[in]plg_dataPlugin data.
Returns
NULL on success;
Sysrepo error info on error.

Definition at line 195 of file plugins_datastore.h.

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]connConnection.
[in]plg_dataPlugin data to free.

Definition at line 111 of file plugins_datastore.h.

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]connNew connection.
[out]plg_dataArbitrary DS plugin data.
Returns
NULL on success;
Sysrepo error info on error.

Definition at line 101 of file plugins_datastore.h.

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]modSpecific module.
[in]trg_dsTarget datastore.
[in]src_dsSource datastore.
[in]plg_dataPlugin data.
Returns
NULL on success;
Sysrepo error info on error.

Definition at line 173 of file plugins_datastore.h.

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]modSpecific module.
[in]dsSpecific datastore, set always to SR_DS_RUNNING.
[in]plg_dataPlugin data.
[out]versionCurrent data version, different than the previous if data changed since then.
Returns
NULL on success;
Sysrepo error info on error.

Definition at line 276 of file plugins_datastore.h.

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]modSpecific module.
[in]dsSpecific datastore.
[in]plg_dataPlugin data.
Returns
NULL on success;
Sysrepo error info on error.

Definition at line 87 of file plugins_datastore.h.

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]modSpecific module.
[in]dsSpecific datastore.
[in]ownerOptional initial owner of the module data, process user by default.
[in]groupOptional initial group of the module data, process group by default.
[in]permInitial permissions of the module data, execute bits are never set.
[in]plg_dataPlugin data.
Returns
NULL on success;
Sysrepo error info on error.

Definition at line 60 of file plugins_datastore.h.

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]modSpecific module.
[in]dsSpecific 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_dataPlugin data.
[out]mtimeTime of last modification, or 0 when it is unknown.
Returns
NULL on success;
Sysrepo error info on error.

Definition at line 254 of file plugins_datastore.h.

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]modSpecific module.
[in]dsSpecific datastore.
[in]cidID of the connection of the session, relevant for ds SR_DS_OPERATIONAL.
[in]sidID of the session whose data to load, relevant for ds SR_DS_OPERATIONAL.
[in]xpathsArray of XPaths selecting the required data, NULL if all the module data are needed.
[in]xpath_countNumber of xpaths.
[in]plg_dataPlugin data.
[out]mod_dataLoaded module data.
Returns
NULL on success;
Sysrepo error info on error.

Definition at line 156 of file plugins_datastore.h.

typedef sr_error_info_t*(* srds_store)(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.

Parameters
[in]modSpecific module.
[in]dsSpecific datastore.
[in]cidID of the connection storing the data, relevant for ds SR_DS_OPERATIONAL.
[in]sidID of the session storing the data, relevant for ds SR_DS_OPERATIONAL.
[in]mod_diffDiff of currently stored module data and the new mod_data. Not always available.
[in]mod_dataNew 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_dataPlugin data.
Returns
NULL on success;
Sysrepo error info on error.

Definition at line 134 of file plugins_datastore.h.

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]modSpecific module.
[in]dsSpecific datastore.
[in]plg_dataPlugin data.
Returns
NULL on success;
Sysrepo error info on error.

Definition at line 72 of file plugins_datastore.h.