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   11
	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, const char **xpaths, uint32_t xpath_count, void *plg_data, struct lyd_node **mod_data)
	Load data of a module. More...
typedef void(*	srds_recover )(const struct lys_module *mod, sr_datastore_t ds, void *plg_data)
	Recover module data when a crash occurred while they were being written. More...
typedef sr_error_info_t *(*	srds_store )(const struct lys_module *mod, sr_datastore_t ds, 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 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 290 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_recover	recover_cb	callback for stored module data recovery
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__

Macro to define datastore plugin information in external plugins.

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

Definition at line 316 of file plugins_datastore.h.

#define SRPLG_DS_API_VERSION   11

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]	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 247 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]	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 233 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]	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 217 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]	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 193 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]	mod	Specific module.
[in]	plg_data	Plugin data.

Returns

NULL on success;

Sysrepo error info on error.

Definition at line 203 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]	conn	Connection.
[in]	plg_data	Plugin 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]	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.

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 181 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]	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 284 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]	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.

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.

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 262 of file plugins_datastore.h.

typedef sr_error_info_t*(* srds_load)(const struct lys_module *mod, sr_datastore_t ds, 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]	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.

Returns

NULL on success;

Sysrepo error info on error.

Definition at line 164 of file plugins_datastore.h.

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

Recover module data when a crash occurred while they were being written.

Parameters

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

Definition at line 145 of file plugins_datastore.h.

typedef sr_error_info_t*(* srds_store)(const struct lys_module *mod, sr_datastore_t ds, 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 or full new data tree stored.

If ds is SR_DS_OPERATIONAL, it is actually an edit data tree that is being stored. That means that data nodes with their operations (metadata) need to be stored and even opaque nodes with attributes. For this datastore mod_diff is never provided.

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]	mod	Specific module.
[in]	ds	Specific datastore.
[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.
[in]	plg_data	Plugin data.

Returns

NULL on success;

Sysrepo error info on error.

Definition at line 135 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]	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.