General functions

libnetconf's miscellaneous functions. More...

Enumerations
enum	NC_MSG_TYPE {   NC_MSG_UNKNOWN, NC_MSG_WOULDBLOCK, NC_MSG_NONE, NC_MSG_HELLO,   NC_MSG_RPC, NC_MSG_REPLY, NC_MSG_NOTIFICATION = -5 }
	Enumeration of NETCONF message types. More...
enum	NC_VERB_LEVEL { NC_VERB_ERROR, NC_VERB_WARNING, NC_VERB_VERBOSE, NC_VERB_DEBUG }
	Verbosity levels. More...

Functions
void	nc_callback_print (void(*func)(NC_VERB_LEVEL level, const char *msg))
	Set a callback function for printing libnetconf's messages.If the func parameter is NULL, the callback is set back to the default (no) function. More...
int	nc_close (void)
	Release libnetconf resources. Init flag is used to determine if close should be applied as system-wide (NC_INIT_MULTILAYER) or not (NC_INIT_SINGLELAYER). System-wide nc_close() closes all the shared structures if no other libnetconf participant is currently running. Local release of the calling instance from the shared structures is done in both cases. More...
time_t	nc_datetime2time (const char *datetime)
	Transform given string in RFC 3339 compliant format to the time_t (seconds since the epoch) accepted by most Linux functions. More...
struct nc_err *	nc_err_dup (const struct nc_err *error)
	Duplicate an error description structure. More...
void	nc_err_free (struct nc_err *err)
	Free NETCONF error structure. More...
const char *	nc_err_get (const struct nc_err *err, NC_ERR_PARAM param)
	Get value of the specified parameter of the NETCONF error structure. More...
struct nc_err *	nc_err_new (NC_ERR error)
	Create a new error description structure. More...
int	nc_err_set (struct nc_err *err, NC_ERR_PARAM param, const char *value)
	Set selected parameter of the NETCONF error structure to the specified value. More...
void	nc_hello_timeout (int timeout)
	Set <hello> timeout - how long libnetconf will wait for the <hello> message from the other side. Default value is -1 (infinite timeout). More...
int	nc_init (int flags)
	Initialize libnetconf for system-wide usage. This initialization is shared across all the processes. More...
int	nc_msgid_compare (const nc_msgid id1, const nc_msgid id2)
	Compare two message IDs if they are the same. More...
char *	nc_time2datetime (time_t time, const char *tz)
	Transform given time_t (seconds since the epoch) into the RFC 3339 format accepted by NETCONF functions. More...
void	nc_verb_error (const char *format,...)
	Function for logging error messages. More...
void	nc_verb_verbose (const char *format,...)
	Function for logging verbose messages. More...
void	nc_verb_warning (const char *format,...)
	Function for logging warning messages. More...
void	nc_verbosity (NC_VERB_LEVEL level)
	Set libnetconf's verbosity level. More...

Detailed Description

libnetconf's miscellaneous functions.

Enumeration Type Documentation

enum NC_MSG_TYPE

Enumeration of NETCONF message types.

Enumerator
NC_MSG_UNKNOWN	error state
NC_MSG_WOULDBLOCK	waiting for another message timed out
NC_MSG_NONE	no message at input or message was processed internally
NC_MSG_HELLO	<hello> message
NC_MSG_RPC	<rpc> message
NC_MSG_REPLY	<rpc-reply> message
NC_MSG_NOTIFICATION	<notification> message

enum NC_VERB_LEVEL

Verbosity levels.

Enumerator
NC_VERB_ERROR	Print only error messages.
NC_VERB_WARNING	Print error and warning messages.
NC_VERB_VERBOSE	Besides errors and warnings, print some other verbose messages.
NC_VERB_DEBUG	Print all messages including some development debug messages.

Function Documentation

void nc_callback_print

(

void(*)(NC_VERB_LEVEL level, const char *msg)

func

)

Set a callback function for printing libnetconf's messages.If the func parameter is NULL, the callback is set back to the default (no) function.

Parameters

[in]

func

Callback function to use.

int nc_close

(

void

)

Release libnetconf resources. Init flag is used to determine if close should be applied as system-wide (NC_INIT_MULTILAYER) or not (NC_INIT_SINGLELAYER). System-wide nc_close() closes all the shared structures if no other libnetconf participant is currently running. Local release of the calling instance from the shared structures is done in both cases.

Returns

-1 on error
0 on success
1 in case of system-wide when there is another participant using shared structures and system-wide close cannot be done.

time_t nc_datetime2time

(

const char *

datetime

)

Transform given string in RFC 3339 compliant format to the time_t (seconds since the epoch) accepted by most Linux functions.

This is a reverse function to nc_time2datetime().

Parameters

[in]

datetime

Time structure returned e.g. by localtime().

Returns

time_t value of the given string.

struct nc_err* nc_err_dup

(

const struct nc_err *

error

)

Duplicate an error description structure.

Parameters

[in]

error

Existing NETCONF error description structure to be duplicated.

Returns

Duplicated NETCONF error structure on success, NULL on an error.

void nc_err_free

(

struct nc_err *

err

)

Free NETCONF error structure.

Parameters

err	NETCONF error structure to free.

const char* nc_err_get	(	const struct nc_err *	err,
		NC_ERR_PARAM	param
	)

Get value of the specified parameter of the NETCONF error structure.

Parameters

err	NETCONF error structure from which the value will be read.
param	NETCONF error structure's parameter to be returned.

Returns

Constant string value of the requested parameter, NULL if the specified parameter is not set.

struct nc_err* nc_err_new

(

NC_ERR

error

)

Create a new error description structure.

Parameters

[in]

error

Predefined NETCONF error (according to RFC 6241 Appendix A).

Returns

Created NETCONF error structure on success, NULL on an error.

int nc_err_set	(	struct nc_err *	err,
		NC_ERR_PARAM	param,
		const char *	value
	)

Set selected parameter of the NETCONF error structure to the specified value.

Parameters

err	NETCONF error structure to be modified.
param	NETCONF error structure's parameter to be modified.
value	New value for the specified parameter.

Returns

0 on success
non-zero on error

void nc_hello_timeout

(

int

timeout

)

Set <hello> timeout - how long libnetconf will wait for the <hello> message from the other side. Default value is -1 (infinite timeout).

Parameters

[in]

timeout

Timeout in milliseconds, -1 for infinite timeout, 0 for non-blocking.

int nc_init

(

int

flags

)

Initialize libnetconf for system-wide usage. This initialization is shared across all the processes.

Parameters

[in]

flags

ORed flags for libnetconf initialization. Must include NC_INIT_CLIENT, NC_INIT_MULTILAYER, or NC_INIT_SINGLELAYER with other accepted values including: NC_INIT_LIBSSH_PTHREAD The application uses libssh and pthread threads NC_INIT_ALL Enable all available subsystems NC_INIT_MONITORING Enable ietf-netconf-monitoring module NC_INIT_WD Enable With-default capability NC_INIT_NOTIF Enable Notification subsystem NC_INIT_NACM Enable NETCONF Access Control subsystem

Clients call init just for libssh initialization, if it is used. The difference between the multi-layer and single-layer flag is strictly in the behaviour when cleaning shared library resources, either during nc_close() or if the calling process crashed before (equals did not call nc_close()). On multi-layer crash/close, if it was/is the only running libnetconf application, full cleanup is performed, unlike single-layer crash, when this situation is reflected just in the return flag or single-layer close, when only the local resources are released.

Returns

-1 on fatal error
0 on success with some possible flags:
NC_INITRET_NOTFIRST when someone else already called nc_init() since last system-wide nc_close() or system reboot.
NC_INITRET_RECOVERY when after last init and before this init this application crashed (based on same commands - executable binary names).

int nc_msgid_compare	(	const nc_msgid	id1,
		const nc_msgid	id2
	)

Compare two message IDs if they are the same.

Parameters

[in]	id1	First message ID to compare.
[in]	id2	Second message ID to compare.

Returns

0 if both IDs are the same.

char* nc_time2datetime	(	time_t	time,
		const char *	tz
	)

Transform given time_t (seconds since the epoch) into the RFC 3339 format accepted by NETCONF functions.

This is a reverse function to nc_datetime2time().

Parameters

[in]	time	time_t type value returned e.g. by time().
[in]	tz	timezone name for the result. See tzselect(1) for list of correct values. If not specified (NULL), the result is provided in UTC (Zulu).

Returns

Printed string in a format compliant to RFC 3339. It is up to the caller to free the returned string.

void nc_verb_error	(	const char *	format,
			...
	)

Function for logging error messages.

Parameters

[in]	format	printf's format string
[in]	...	list of arguments specified in format

void nc_verb_verbose	(	const char *	format,
			...
	)

Function for logging verbose messages.

Parameters

[in]	format	printf's format string
[in]	...	list of arguments specified in format

void nc_verb_warning	(	const char *	format,
			...
	)

Function for logging warning messages.

Parameters

[in]	format	printf's format string
[in]	...	list of arguments specified in format

void nc_verbosity

(

NC_VERB_LEVEL

level

)

Set libnetconf's verbosity level.

Parameters

[in]

level

Enabled verbosity level (includes all the levels with higher priority).