NETCONF Event Notifications

libnetconf's implementation of NETCONF asynchronous message delivery as defined in RFC 5277. More...

Typedefs
typedef struct nc_msg	nc_ntf
	Event notification message. More...

Enumerations
enum	NCNTF_EVENT {   NCNTF_ERROR = -1, NCNTF_GENERIC = 0, NCNTF_REPLAY_COMPLETE = 1, NCNTF_NTF_COMPLETE = 2,   NCNTF_BASE_CFG_CHANGE = 3, NCNTF_BASE_CPBLT_CHANGE = 4, NCNTF_BASE_SESSION_START = 5, NCNTF_BASE_SESSION_END = 6,   NCNTF_BASE_CONFIRMED_COMMIT = 7 }
	Enumeration of supported NETCONF event notifications. More...
enum	NCNTF_EVENT_BY { NCNTF_EVENT_BY_SERVER, NCNTF_EVENT_BY_USER }
	Enumeration of the possible source of events. More...

Functions
nc_rpc *	nc_rpc_subscribe (const char *stream, const struct nc_filter *filter, const time_t *start, const time_t *stop)
	Create <create-subsciption> NETCONF rpc message. More...
NC_MSG_TYPE	nc_session_recv_notif (struct nc_session *session, int timeout, nc_ntf **ntf)
	Receive a <notification> message from the specified NETCONF session. This function is supposed to be performed only by NETCONF clients. More...
int	nc_session_send_notif (struct nc_session *session, const nc_ntf *ntf)
	Send <notification> message from server to client. More...
long long int	ncntf_dispatch_receive (struct nc_session *session, void(*process_ntf)(time_t eventtime, const char *content))
	Subscribe for receiving notifications from the given session according to parameters in the given subscribtion RPC. Received notifications are processed by the given process_ntf callback function. Functions stops when the final notification <notificationComplete> is received or when the session is terminated. More...
long long int	ncntf_dispatch_send (struct nc_session *session, const nc_rpc *subscribe_rpc)
	Start sending notifications according to the given <create-subscription> NETCONF RPC request. All events from the specified stream are processed and sent to the client until the stop time is reached or until the session is terminated. More...
int	ncntf_event_new (time_t etime, NCNTF_EVENT event,...)
	Store a new event in the specified stream. Parameters are specific for different events. More...
nc_ntf *	ncntf_notif_create (time_t event_time, const char *content)
	Create a new <notification> message with the given eventTime and content. More...
void	ncntf_notif_free (nc_ntf *ntf)
	Free the notification message. More...
char *	ncntf_notif_get_content (const nc_ntf *notif)
	Get description of the event reported in the notification message. More...
time_t	ncntf_notif_get_time (const nc_ntf *notif)
	Get Time of the event reported in the notification message. More...
NCNTF_EVENT	ncntf_notif_get_type (const nc_ntf *notif)
	Get a specific notification type. More...
int	ncntf_session_get_active_subscription (struct nc_session *session)
	Check if a session has an active notification subscription. More...
char *	ncntf_status (void)
	Get the status data in xml form describing the currently used streams. More...
int	ncntf_stream_allow_events (const char *stream, const char *event)
	Set the rule to allow logging of the specified event on the given Notification stream. More...
int	ncntf_stream_info (const char *stream, char **desc, char **start)
	Get some more details about the specified NETCONF event notifications stream. More...
int	ncntf_stream_isavailable (const char *name)
	Test if the given stream is already created and available. More...
void	ncntf_stream_iter_finish (const char *stream)
	Clean all the structures used for iteration in the specified stream. This function must be called as a closing function to nc_ntf_stream_iter_start() More...
char *	ncntf_stream_iter_next (const char *stream, time_t start, time_t stop, time_t *event_time)
	Pop the next event record from the stream file. The iteration must be started by nc_ntf_stream_iter_start() function. More...
void	ncntf_stream_iter_start (const char *stream)
	Start iteration on the events in the specified stream file. Iteration starts on the first event in the first part of the stream file. More...
char **	ncntf_stream_list (void)
	Get the list of NETCONF event notifications streams. More...
int	ncntf_stream_new (const char *name, const char *desc, int replay)
	Create a new NETCONF event stream. More...
nc_reply *	ncntf_subscription_check (const nc_rpc *subscribe_rpc)
	Check validity of <create-subscription> message. More...

Detailed Description

libnetconf's implementation of NETCONF asynchronous message delivery as defined in RFC 5277.

Typedef Documentation

typedef struct nc_msg nc_ntf

Event notification message.

Enumeration Type Documentation

enum NCNTF_EVENT

Enumeration of supported NETCONF event notifications.

Enumerator
NCNTF_ERROR	error return code
NCNTF_GENERIC	a generic notification not directly supported by libnetconf
NCNTF_REPLAY_COMPLETE	<replayComplete> notification announcing the end of Replaying the stream
NCNTF_NTF_COMPLETE	<notificationComplete> notification announcing the end of Notification stream
NCNTF_BASE_CFG_CHANGE	netconf-config-change (RFC 6470)
NCNTF_BASE_CPBLT_CHANGE	netconf-capability-change (RFC 6470)
NCNTF_BASE_SESSION_START	netconf-session-start (RFC 6470)
NCNTF_BASE_SESSION_END	netconf-session-end (RFC 6470)
NCNTF_BASE_CONFIRMED_COMMIT	netconf-configrmed-commit (RFC 6470)

enum NCNTF_EVENT_BY

Enumeration of the possible source of events.

Enumerator
NCNTF_EVENT_BY_SERVER	event is caused by a server
NCNTF_EVENT_BY_USER	event is caused by the user's action

Function Documentation

nc_rpc* nc_rpc_subscribe	(	const char *	stream,
		const struct nc_filter *	filter,
		const time_t *	start,
		const time_t *	stop
	)

Create <create-subsciption> NETCONF rpc message.

Detailed description of this operation can be found in RFC 5277, section 2.1.1.

Parameters

[in]	stream	Name of the stream of events that is of interest. Optional parameter (NULL is accepted), if not specified, the default NETCONF stream is subscribed.
[in]	filter	Specify the subset of all possible events to be received. Optional parameter (NULL is accepted).
[in]	start	Start time to trigger the replay feature from the specified time. Optional parameter (NULL is accepted). Format of the date is of the type dateTime according to RFC 3339.
[in]	stop	Stop time to stop the replay of event notifications. Optional parameter (NULL is accepted). Format of the date is of the type dateTime according to RFC 3339.

Returns

Created rpc message.

NC_MSG_TYPE nc_session_recv_notif	(	struct nc_session *	session,
		int	timeout,
		nc_ntf **	ntf
	)

Receive a <notification> message from the specified NETCONF session. This function is supposed to be performed only by NETCONF clients.

Parameters

[in]	session	NETCONF session to use.
[in]	timeout	Timeout in microseconds, -1 for infinite timeout, 0 for non-blocking
[out]	ntf	Received <notification> message

Returns

• NC_MSG_NOTIFICATION - success, *ntf points to the received <notification>
• NC_MSG_UNKNOWN - error occurred
• NC_MSG_REPLY - <rpc-reply> to some request received and enqueued to the internal queue until the nc_session_recv_reply() function is called. Caller is supposed to repeat the function call to receive another <notification> message.
• NC_MSG_WOULDBLOCK - receiving timeouted without any received message.

int nc_session_send_notif	(	struct nc_session *	session,
		const nc_ntf *	ntf
	)

Send <notification> message from server to client.

Parameters

[in]	session	NETCONF session to use.
[in]	ntf	<notification> message to send.

Returns

0 on success,
non-zero on error.

long long int ncntf_dispatch_receive	(	struct nc_session *	session,
		void(*)(time_t eventtime, const char *content)	process_ntf
	)

Subscribe for receiving notifications from the given session according to parameters in the given subscribtion RPC. Received notifications are processed by the given process_ntf callback function. Functions stops when the final notification <notificationComplete> is received or when the session is terminated.

Parameters

[in]	session	NETCONF session where the notifications will be sent.
[in]	process_ntf	Callback function to process content of the notification. If NULL, content of the notification is printed on stdout.

Returns

number of received notifications, -1 on error.

long long int ncntf_dispatch_send	(	struct nc_session *	session,
		const nc_rpc *	subscribe_rpc
	)

Start sending notifications according to the given <create-subscription> NETCONF RPC request. All events from the specified stream are processed and sent to the client until the stop time is reached or until the session is terminated.

Parameters

[in]	session	NETCONF session where the notifications will be sent.
[in]	subscribe_rpc	<create-subscription> RPC, if any other RPC is given, -1 is returned.

Returns

number of sent notifications (including 0), -1 on error.

int ncntf_event_new	(	time_t	etime,
		NCNTF_EVENT	event,
			...
	)

Store a new event in the specified stream. Parameters are specific for different events.

Event parameters:

• NCNTF_GENERIC
  • const char* content Content of the notification as defined in RFC 5277. eventTime is added automatically. The string should be XML-formatted.
• NCNTF_BASE_CFG_CHANGE
  • NC_DATASTORE datastore Specify which datastore has changed.
  • NCNTF_EVENT_BY changed_by Specify the source of the change.
    • If the value is set to NCNTF_EVENT_BY_USER, the following parameter is required:
  • const struct nc_session* session Session that required the configuration change.
• NCNTF_BASE_CPBLT_CHANGE
  • const struct nc_cpblts* old Old list of capabilities.
  • const struct nc_cpblts* new New list of capabilities.
  • NCNTF_EVENT_BY changed_by Specify the source of the change.
    • If the value is set to NCNTF_EVENT_BY_USER, the following parameter is required:
  • const struct nc_session* session Session that required the configuration change.
• NCNTF_BASE_SESSION_START
  • const struct nc_session* session Started session (NC_SESSION_STATUS_DUMMY session is also allowed).
• NCNTF_BASE_SESSION_END
  • const struct nc_session* session Finished session (NC_SESSION_STATUS_DUMMY session is also allowed).
  • NC_SESSION_TERM_REASON reason Session termination reason.
    • If the value is set to NC_SESSION_TERM_KILLED, the following parameter is required.
  • const char* killed-by-sid The ID of the session that directly caused the session termination. If the session was terminated by a non-NETCONF process unknown to the server, use NULL as the value.

Examples:

• ncntf_event_new(-1, NCNTF_GENERIC, "<event>something happened</event>");
• ncntf_event_new(-1, NCNTF_BASE_CFG_CHANGE, NC_DATASTORE_RUNNING, NCNTF_EVENT_BY_USER, my_session);
• ncntf_event_new(-1, NCNTF_BASE_CPBLT_CHANGE, old_cpblts, new_cpblts, NCNTF_EVENT_BY_SERVER);
• ncntf_event_new(-1, NCNTF_BASE_SESSION_START, my_session);
• ncntf_event_new(-1, NCNTF_BASE_SESSION_END, my_session, NC_SESSION_TERM_KILLED, "123456");

Parameters

[in]	etime	Time of the event, if set to -1, the current time is used.
[in]	event	Event type to distinguish the following parameters.
[in]	...	Specific parameters for different event types as described above.

Returns

0 for success, non-zero value else.

nc_ntf* ncntf_notif_create	(	time_t	event_time,
		const char *	content
	)

Create a new <notification> message with the given eventTime and content.

Parameters

[in]	event_time	Time of the event.
[in]	content	Description of the event in the XML form.

Returns

Created notification message.

void ncntf_notif_free

(

nc_ntf *

ntf

)

Free the notification message.

Parameters

[in]

ntf

notification message to free.

char* ncntf_notif_get_content

(

const nc_ntf *

notif

)

Get description of the event reported in the notification message.

Parameters

[in]

notif

Notification message.

Returns

Content of the event description (serialized XML).

time_t ncntf_notif_get_time

(

const nc_ntf *

notif

)

Get Time of the event reported in the notification message.

Parameters

[in]

notif

Notification message.

Returns

Time of the event (as number of seconds since the epoch).

NCNTF_EVENT ncntf_notif_get_type

(

const nc_ntf *

notif

)

Get a specific notification type.

Parameters

[in]

notif

Notification message to explore.

Returns

The same types as for ncntf_event_new() can be returned. If the notification is unknown, the NCNTF_GENERIC is returned.

int ncntf_session_get_active_subscription

(

struct nc_session *

session

)

Check if a session has an active notification subscription.

Parameters

[in]

session

NETCONF session to check.

Returns

0 if there is no active subscription, non-0 otherwise.

char* ncntf_status

(

void

)

Get the status data in xml form describing the currently used streams.

Returns

Text containing streams status data in xml form (urn:ietf:params:xml:ns:netmod:notification in RFC 5277).

int ncntf_stream_allow_events	(	const char *	stream,
		const char *	event
	)

Set the rule to allow logging of the specified event on the given Notification stream.

Parameters

[in]	stream	Name of the stream where to allow event logging
[in]	event	Name of the event which to allow on the given stream

Returns

0 on success, non-zero on error

int ncntf_stream_info	(	const char *	stream,
		char **	desc,
		char **	start
	)

Get some more details about the specified NETCONF event notifications stream.

Parameters

[in]	stream	Name of the stream.
[out]	desc	Pointer to a description string is returned.
[out]	start	Pointer to a time string of the stream start time is returned.

Returns

0 on success, non-zero on error (desc and start are not returned in such a case).

int ncntf_stream_isavailable

(

const char *

name

)

Test if the given stream is already created and available.

Parameters

[in]

name

Name of the stream to check.

Returns

0 - the stream is not present,
1 - the stream is present

void ncntf_stream_iter_finish

(

const char *

stream

)

Clean all the structures used for iteration in the specified stream. This function must be called as a closing function to nc_ntf_stream_iter_start()

Parameters

[in]

stream

Name of the iterated stream.

char* ncntf_stream_iter_next	(	const char *	stream,
		time_t	start,
		time_t	stop,
		time_t *	event_time
	)

Pop the next event record from the stream file. The iteration must be started by nc_ntf_stream_iter_start() function.

Parameters

[in]	stream	Name of the stream to iterate.
[in]	start	Time of the first event the caller is interested in.
[in]	stop	Time of the last event the caller is interested in.
[out]	event_time	Time of the returned event, NULL if caller does not care.

Returns

Content of the next event in the stream.

void ncntf_stream_iter_start

(

const char *

stream

)

Start iteration on the events in the specified stream file. Iteration starts on the first event in the first part of the stream file.

Parameters

[in]

stream

Name of the stream to iterate.

char** ncntf_stream_list

(

void

)

Get the list of NETCONF event notifications streams.

Returns

NULL terminated list of stream names. It is up to the caller to free the list

int ncntf_stream_new	(	const char *	name,
		const char *	desc,
		int	replay
	)

Create a new NETCONF event stream.

Parameters

[in]	name	Name of the stream.
[in]	desc	Description of the stream.
[in]	replay	Specify if the replay is allowed (1 for yes, 0 for no).

Returns

0 on success, non-zero value else.

nc_reply* ncntf_subscription_check

(

const nc_rpc *

subscribe_rpc

)

Check validity of <create-subscription> message.

This check is done by ncntf_dispatch_send() which returns -1 when test does not pass. However, it can be sometimes useful to run this test before calling ncntf_dispatch_send().

Parameters

[in]

subscribe_rpc

<create-subscription> RPC.

Returns

Reply message to the subscription - ok if tests passed and reply-error with problem description if any of the tests fails.