libnetconf's functions for handling NETCONF datastores. More information can be found at Datastores Usage page. More...

Collaboration diagram for Datastore operations:

Modules
	File Datastore
	Specific functions for NCDS_FILE_DS type of datastore implementation.

	Custom Datastore
	libnetconf's API to use a server-specific datastore implementation.

Macros
#define	NCDS_INTERNAL_ID 0
	Datastore ID to access libnetconf's internal datastores such as notifications, monitoring, etc. More...

#define	NCDS_RPC_NOT_APPLICABLE ((void*)(&error_area))
	Return value of ncds_apply_rpc2all() when the requested operation is not applicable to the datastore. More...

Typedefs
typedef int	ncds_id
	Datastore ID. More...

Enumerations
enum	NC_DATASTORE { NC_DATASTORE_ERROR, NC_DATASTORE_CONFIG, NC_DATASTORE_URL, NC_DATASTORE_RUNNING, NC_DATASTORE_STARTUP, NC_DATASTORE_CANDIDATE }
	Enumeration of the supported types of datastores defined by NETCONF. More...

enum	NCDS_TYPE { NCDS_TYPE_ERROR = -1, NCDS_TYPE_EMPTY, NCDS_TYPE_FILE, NCDS_TYPE_CUSTOM }
	Datastore implementation types provided by libnetconf. More...

Functions
int	ncds_add_model (const char *path)
	Add an configuration data model to the internal list of models. Such model is used to resolve imports, includes and uses statements in base models. More...

int	ncds_add_models_path (const char *path)
	Specify a directory path to the location where the required (imported or included) data models can be found. This function can be called repeatedly to specify multiple locations. More...

nc_reply *	ncds_apply_rpc2all (struct nc_session session, const nc_rpc rpc, ncds_id *ids[])
	Perform the requested RPC operation on the all datastores controlled by the libnetconf (created by ncdsd_new() and ncds_init()). More...

void	ncds_break_locks (const struct nc_session *session)
	Remove all the locks that the given session is holding. More...

int	ncds_consolidate (void)
	Consolidate all internal structures of created data stores and all data models. This function especially solves all YANG's `uses` and `augment` statements. More...

int	ncds_feature_disable (const char module, const char feature)
	Disable usage of the specified feature defined in the specified module By default, all features are disabled. More...

int	ncds_feature_enable (const char module, const char feature)
	Enable usage of the specified feature defined in the specified module. By default, all features are disabled. More...

int	ncds_feature_isenabled (const char module, const char feature)
	Check if the feature of the specified module is currently enabled or disabled. More...

int	ncds_features_disableall (const char *module)
	Disable usage of all features defined in the specified module. By default, all features are disabled. To disable only the specific feature(s), use ncds_feature_disable(). More...

int	ncds_features_enableall (const char *module)
	Enable usage of all features defined in the specified module. By default, all features are disabled. To enable only the specific feature(s), use ncds_feature_enable(). More...

void	ncds_free (struct ncds_ds *datastore)
	Close the specified datastore and free all the resources. More...

void	ncds_free2 (ncds_id datastore_id)
	Close specified datastore and free all the resources. More...

char *	ncds_get_model (ncds_id id, int base)
	Return a serialized XML containing the data model in the YIN format. More...

const char *	ncds_get_model_path (ncds_id id)
	Return path to the file containing the datastore datamodel. More...

ncds_id	ncds_init (struct ncds_ds *datastore)
	Activate datastore structure for use. More...

int	ncds_model_info (const char path, char name, char version, char ns, char prefix, char rpcs, char *notifs)
	Informational function to get basic information about configuration data model in the given file. More...

struct ncds_ds *	ncds_new (NCDS_TYPE type, const char model_path, char (get_state)(const char model, const char running, struct nc_err *e))
	Create a new datastore structure of the specified implementation type. More...

struct ncds_ds *	ncds_new2 (NCDS_TYPE type, const char model_path, xmlDocPtr(get_state)(const xmlDocPtr model, const xmlDocPtr running, struct nc_err **e))
	Create a new datastore structure of the specified implementation type with get_state function using libxml2. More...

int	ncds_rollback (ncds_id id)
	Undo the last change performed on the specified datastore. More...

int	ncds_set_validation (struct ncds_ds ds, int enable, const char relaxng, const char *schematron)
	Set validators (or disable validation) on the specified datastore. More...

int	ncds_set_validation2 (struct ncds_ds ds, int enable, const char relaxng, const char schematron, int(valid_func)(const xmlDocPtr config, struct nc_err **err))
	Set validators (or disable validation) on the specified datastore. More...

Detailed Description

libnetconf's functions for handling NETCONF datastores. More information can be found at Datastores Usage page.

libnetconf's functions for handling NETCONF datastores.

Macro Definition Documentation

#define NCDS_INTERNAL_ID 0

Datastore ID to access libnetconf's internal datastores such as notifications, monitoring, etc.

#define NCDS_RPC_NOT_APPLICABLE ((void*)(&error_area))

Return value of ncds_apply_rpc2all() when the requested operation is not applicable to the datastore.

Typedef Documentation

typedef int ncds_id

Datastore ID.

Each datastore gets its ID after initialisation (ncds_init()). Only initialised datastores can be used to access the configuration data.

Enumeration Type Documentation

enum NC_DATASTORE

Enumeration of the supported types of datastores defined by NETCONF.

Enumerator
NC_DATASTORE_ERROR	error state of functions returning the datastore type
NC_DATASTORE_CONFIG	value describing that the datastore is set as config
NC_DATASTORE_URL	value describing that the datastore data should be given from the URL
NC_DATASTORE_RUNNING	base NETCONF's datastore containing the current device configuration
NC_DATASTORE_STARTUP	separated startup datastore as defined in Distinct Startup Capability
NC_DATASTORE_CANDIDATE	separated working datastore as defined in Candidate Configuration Capability

enum NCDS_TYPE

Datastore implementation types provided by libnetconf.

Enumerator
NCDS_TYPE_ERROR	virtual enum value for internal purposes
NCDS_TYPE_EMPTY	No real datastore. For read-only devices.
NCDS_TYPE_FILE	Datastores implemented as files
NCDS_TYPE_CUSTOM	User-defined datastore

Function Documentation

int ncds_add_model ( const char * path )

Add an configuration data model to the internal list of models. Such model is used to resolve imports, includes and uses statements in base models.

Parameters

[in] path Path to the YIN format of the configuration data model.

Returns: 0 on success, non-zero on error.

int ncds_add_models_path ( const char * path )

Specify a directory path to the location where the required (imported or included) data models can be found. This function can be called repeatedly to specify multiple locations.

Parameters

[in] path Directory path

Returns: 0 on success, non-zero on error.

nc_reply* ncds_apply_rpc2all	(	struct nc_session *	session,
		const nc_rpc *	rpc,
		ncds_id *	ids[]
	)

Perform the requested RPC operation on the all datastores controlled by the libnetconf (created by ncdsd_new() and ncds_init()).

This function IS NOT thread safety.

Parameters

[in]	session	NETCONF session (a dummy session is acceptable) where the <rpc> came from. Capabilities checks are done according to this session.
[in]	rpc	NETCONF <rpc> message specifying requested operation.
[out]	ids	Pointer to a static array containing list of datastore IDs where the RPC was successfully applied. The list is terminated by value a (ncds_id)(-1). The list is rewritten by any following call to ncds_apply_rpc2all().

Returns: NULL in case of a non-NC_RPC_DATASTORE_* operation type or invalid parameter session or rpc, else <rpc-reply> with <ok>, <data> or <rpc-error> according to the type and the result of the requested operation. When the requested operation is not applicable to any datastore (e.g. the namespace does not match none of the controlled datstores), NCDS_RPC_NOT_APPLICABLE is returned.

void ncds_break_locks ( const struct nc_session * session )

Remove all the locks that the given session is holding.

Parameters

[in] session Session holding locks to remove

int ncds_consolidate ( void )

Consolidate all internal structures of created data stores and all data models. This function especially solves all YANG's uses and augment statements.

Returns: 0 on success, non-zero on error.

int ncds_feature_disable	(	const char *	module,
		const char *	feature
	)

Disable usage of the specified feature defined in the specified module By default, all features are disabled.

Parameters

[in]	module	Name of the module where the feature is defined. Module must be accessible - added via ncds_add_model() or present in a directory specified via ncds_add_models_path() function.
[in]	feature	Name of the feature to be disabled.

Returns: 0 on success, non-zero on error.

int ncds_feature_enable	(	const char *	module,
		const char *	feature
	)

Enable usage of the specified feature defined in the specified module. By default, all features are disabled.

Parameters

[in]	module	Name of the module where the feature is defined. Module must be accessible - added via ncds_add_model() or present in a directory specified via ncds_add_models_path() function.
[in]	feature	Name of the feature to be enabled.

Returns: 0 on success, non-zero on error.

int ncds_feature_isenabled	(	const char *	module,
		const char *	feature
	)

Check if the feature of the specified module is currently enabled or disabled.

Returns

negative value in case of error
0 if feature is disabled
1 if feature is enabled

int ncds_features_disableall ( const char * module )

Disable usage of all features defined in the specified module. By default, all features are disabled. To disable only the specific feature(s), use ncds_feature_disable().

Parameters

[in] module Name of the module where the features are defined. Module must be accessible - added via ncds_add_model() or present in a directory specified via ncds_add_models_path() function.

Returns: 0 on success, non-zero on error.

int ncds_features_enableall ( const char * module )

Enable usage of all features defined in the specified module. By default, all features are disabled. To enable only the specific feature(s), use ncds_feature_enable().

Parameters

[in] module Name of the module where the features are defined. Module must be accessible - added via ncds_add_model() or present in a directory specified via ncds_add_models_path() function.

Returns: 0 on success, non-zero on error.

void ncds_free ( struct ncds_ds * datastore )

Close the specified datastore and free all the resources.

Equivalent function to ncds_free2().

Parameters

[in] datastore Datastore to be closed.

void ncds_free2 ( ncds_id datastore_id )

Close specified datastore and free all the resources.

Equivalent function to ncds_free().

Parameters

[in] datastore_id ID of the datastore to be closed.

char* ncds_get_model	(	ncds_id	id,
		int	base
	)

Return a serialized XML containing the data model in the YIN format.

Parameters

[in]	id	ID of the datastore whose data model we want
[in]	base	Set 1 to get only base model without any modification. Use 0 value to get complete data model including augmentation, substituted uses statements and removed disabled features of the model. In this case, returned string contains modified YIN format - there are <augment> elements inside the model including information about its namespace and module name.

Returns: String containing YIN model. Caller must free the memory after use.

const char* ncds_get_model_path ( ncds_id id )

Return path to the file containing the datastore datamodel.

Parameters

[in] id ID of the datastore whose data model we want

Returns: String containing the path to the file containing the datastore datamodel. The caller must NOT free the memory.

ncds_id ncds_init ( struct ncds_ds * datastore )

Activate datastore structure for use.

The datastore configuration is checked and if everything is correct, datastore gets its unique ID.

Parameters

[in] datastore Datastore to be initiated.

Returns

Positive integer with the datastore ID on success, negative value on error.

-1 Invalid datastore
-2 Type-specific initialization failed
-3 Unsupported datastore type
-4 Memory allocation problem

int ncds_model_info	(	const char *	path,
		char **	name,
		char **	version,
		char **	ns,
		char **	prefix,
		char ***	rpcs,
		char ***	notifs
	)

Informational function to get basic information about configuration data model in the given file.

Parameters

[in] path Path to the *.yin file with the configuration data model in YIN format.

Caller is responsible to free returned strings and arrays of strings. If a caller is not interested in a specific return value, NULL pointer can be set as parameter and the value of such a parameter will not be returned.

Parameters

[out]	name	Name of the data model
[out]	version	Version of the data model
[out]	ns	Namespace for the data model
[out]	prefix	Prefix for the data model
[out]	rpcs	Null terminated list of names of RPCs defined in the data model
[out]	notifs	Null terminated list of names of Notifications defined in the data model

Returns: EXIT_SUCCESS or EXIT_FAILURE on error.

struct ncds_ds* ncds_new	(	NCDS_TYPE	type,
		const char *	model_path,
		char ()(const char model, const char running, struct nc_err **e)	get_state
	)

Create a new datastore structure of the specified implementation type.

Parameters

[in]	type	Datastore implementation type for the new datastore structure.
[in]	model_path	Base name of the configuration data model files. libnetconf expects model_path.yin as a data model, model_path.rng for grammar and data types validation, model_path.dsrl for default values validation and model_path.sch for semantic validation.
[in]	get_state	Pointer to a callback function that returns a serialized XML document containing the state configuration data of the device. The parameters it receives are a serialized configuration data model in YIN format and the current content of the running datastore. If NULL is set, <get> operation is performed in the same way as <get-config>.

Returns: Prepared (not configured) datastore structure. To configure the structure, caller must use the parameter setters of the specific datastore implementation type. Then, the datastore can be initiated (ncds_init()) and used to access the configuration data.

struct ncds_ds* ncds_new2	(	NCDS_TYPE	type,
		const char *	model_path,
		xmlDocPtr()(const xmlDocPtr model, const xmlDocPtr running, struct nc_err *e)	get_state
	)

Create a new datastore structure of the specified implementation type with get_state function using libxml2.

To make this function available, you have to include libnetconf_xml.h.

Parameters

[in]	type	Datastore implementation type for the new datastore structure.
[in]	model_path	Base name of the configuration data model files. libnetconf expects model_path.yin as a data model, model_path.rng for grammar and data types validation, model_path.dsrl for default values validation and model_path.sch for semantic validation.
[in]	get_state	Pointer to a callback function that returns a XML document containing the state data of the device. The parameters it receives are a configuration data model in YIN format and the current content of the running datastore. If NULL is set, <get> operation is performed in the same way as <get-config>.

Returns: Prepared (not configured) datastore structure. To configure the structure, caller must use the parameter setters of the specific datastore implementation type. Then, the datastore can be initiated (ncds_init()) and used to access the configuration data.

int ncds_rollback ( ncds_id id )

Undo the last change performed on the specified datastore.

Parameters

[in] id ID of the datastore where the rollback will be performed.

Returns: 0 on success, non-zero on error.

int ncds_set_validation	(	struct ncds_ds *	ds,
		int	enable,
		const char *	relaxng,
		const char *	schematron
	)

Set validators (or disable validation) on the specified datastore.

Parameters

[in]	ds	Datastore structure to be configured.
[in]	enable	1 to enable validation on the datastore according to the following parameters, 0 to disable validation (following parameters will be ignored as well as automatically or previously set validators).
[in]	relaxng	Path to the Relax NG schema for validation of the datastore content syntax. To generate it, use the lnctool(1) script. NULL if syntactic validation is not required.
[in]	schematron	Path to the Schematron XSLT stylesheet for validation of the datastore content semantics. To generate it, use the lnctool(1) script. NULL if semantic validation is not required.

Returns: EXIT_SUCCESS or EXIT_FAILURE

int ncds_set_validation2	(	struct ncds_ds *	ds,
		int	enable,
		const char *	relaxng,
		const char *	schematron,
		int()(const xmlDocPtr config, struct nc_err *err)	valid_func
	)

Set validators (or disable validation) on the specified datastore.

To make this function available, you have to include libnetconf_xml.h.

Parameters

[in]	ds	Datastore structure to be configured.
[in]	enable	1 to enable validation on the datastore according to the following parameters, 0 to disable validation (following parameters will be ignored as well as automatically or previously set validators).
[in]	relaxng	Path to the Relax NG schema for validation of the datastore content syntax. To generate it, use the lnctool(1) script. NULL if syntactic validation not required.
[in]	schematron	Path to the Schematron XSLT stylesheet for validation of the datastore content semantics. To generate it, use the lnctool(1) script. NULL if semantic validation not required.
[in]	valid_func	Pointer to a callback function that is used for additional validation of the configuration data in the datastore. It can perform any specific check for the datastore (e.g. check for presence of referred files). If no such check is needed, parameter can be set to NULL. Validation callback function receives configuration data as a libxml2's xmlDocPtr. As a result it returns EXIT_SUCCESS if validation checks passed and EXIT_FAILURE when an error occurred. An error description may be returned via the `err` parameter.

Returns: EXIT_SUCCESS or EXIT_FAILURE

Modules

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation