# \_ncs.events Module

Low level module for subscribing to NCS event notifications.

This module is used to connect to NCS and subscribe to certain events generated by NCS. The API to receive events from NCS is a socket based API whereby the application connects to NCS and receives events on a socket. See also the Notifications chapter in the User Guide. The program misc/notifications/confd\_notifications.c in the examples collection illustrates subscription and processing for all these events, and can also be used standalone in a development environment to monitor NCS events.

This documentation should be read together with the [confd\_lib\_events(3)](/guides/nso-6.6/resources/man/confd_lib_events.3.md) man page.

## Functions

### diff\_notification\_done

```python
diff_notification_done(sock, tctx) -> None
```

If the received event was NOTIF\_COMMIT\_DIFF it is important that we call this function when we are done reading the transaction diffs over MAAPI. The transaction is hanging until this function gets called. This function also releases memory associated to the transaction in the library.

Keyword arguments:

* sock -- a previously connected notification socket
* tctx -- a transaction context

### notifications\_connect

```python
notifications_connect(sock, mask, ip, port, path) -> None
```

This function creates a notification socket.

Keyword arguments:

* sock -- a Python socket instance
* mask -- a bitmask of one or several notification type values
* ip -- the ip address if socket is AF\_INET (optional)
* port -- the port if socket is AF\_INET (optional)
* path -- a filename if socket is AF\_UNIX (optional).

### notifications\_connect2

```python
notifications_connect2(sock, mask, data, ip, port, path) -> None
```

This variant of notifications\_connect is required if we wish to subscribe to NOTIF\_HEARTBEAT, NOTIF\_HEALTH\_CHECK, or NOTIF\_STREAM\_EVENT events.

Keyword arguments:

* sock -- a Python socket instance
* mask -- a bitmask of one or several notification type values
* data -- a \_events.NotificationsData instance
* ip -- the ip address if socket is AF\_INET (optional)
* port -- the port if socket is AF\_INET (optional)
* path -- a filename if socket is AF\_UNIX (optional)

### read\_notification

```python
read_notification(sock) -> dict
```

The application is responsible for polling the notification socket. Once data is available to be read on the socket the application must call read\_notification() to read the data from the socket. On success a dictionary containing notification information will be returned (see below).

Keyword arguments:

* sock -- a previously connected notification socket

On success the returned dict will contain information corresponding to the c struct confd\_notification. The notification type is accessible through the 'type' key. The remaining information will be different depending on which type of notification this is (described below).

Keys for type NOTIF\_AUDIT (struct confd\_audit\_notification):

* logno
* user
* msg
* usid

Keys for type NOTIF\_DAEMON, NOTIF\_NETCONF, NOTIF\_DEVEL, NOTIF\_JSONRPC, NOTIF\_WEBUI, or NOTIF\_TAKEOVER\_SYSLOG (struct confd\_syslog\_notification):

* prio
* logno
* msg

Keys for type NOTIF\_COMMIT\_SIMPLE (struct confd\_commit\_notification):

* database
* diff\_available
* flags
* uinfo

Keys for type NOTIF\_COMMIT\_DIFF (struct confd\_commit\_diff\_notification):

* database
* flags
* uinfo
* tctx
* label (optional)
* comment (optional)

Keys for type NOTIF\_USER\_SESSION (struct confd\_user\_sess\_notification):

* type
* uinfo
* database

Keys for type NOTIF\_HA\_INFO (struct confd\_ha\_notification):

* type (1)
* noprimary - if (1) is HA\_INFO\_NOPRIMARY
* secondary\_died - if (1) is HA\_INFO\_SECONDARY\_DIED (see below)
* secondary\_arrived - if (1) is HA\_INFO\_SECONDARY\_ARRIVED (see below)
* cdb\_initialized\_by\_copy - if (1) is HA\_INFO\_SECONDARY\_INITIALIZED
* besecondary\_result - if (1) is HA\_INFO\_BESECONDARY\_RESULT

If secondary\_died or secondary\_arrived is present they will in turn contain a dictionary with the following keys:

* nodeid
* af (1)
* ip4 - if (1) is AF\_INET
* ip6 - if (1) is AF\_INET6
* str - if (1) if AF\_UNSPEC

Keys for type NOTIF\_SUBAGENT\_INFO (struct confd\_subagent\_notification):

* type
* name

Keys for type NOTIF\_COMMIT\_FAILED (struct confd\_commit\_failed\_notification):

* provider (1)
* dbname
* port - if (1) is DP\_NETCONF
* af (2) - if (1) is DP\_NETCONF
* ip4 - if (2) is AF\_INET
* ip6 - if (2) is AF\_INET6
* daemon\_name - if (1) is DP\_EXTERNAL

Keys for type NOTIF\_SNMPA (struct confd\_snmpa\_notification):

* pdu\_type (1)
* request\_id
* error\_status
* error\_index
* port
* af (2)
* ip4 - if (3) is AF\_INET
* ip6 - if (3) is AF\_INET6
* vb (optional)
* generic\_trap - if (1) is SNMPA\_PDU\_V1TRAP
* specific\_trap - if (1) is SNMPA\_PDU\_V1TRAP
* time\_stamp - if (1) is SNMPA\_PDU\_V1TRAP
* enterprise - if (1) is SNMPA\_PDU\_V1TRAP (optional)

Keys for type NOTIF\_FORWARD\_INFO (struct confd\_forward\_notification):

* type
* target
* uinfo

Keys for type NOTIF\_CONFIRMED\_COMMIT (struct confd\_confirmed\_commit\_notification):

* type
* timeout
* uinfo

Keys for type NOTIF\_UPGRADE\_EVENT (struct confd\_upgrade\_notification):

* event

Keys for type NOTIF\_COMPACTION (struct confd\_compaction\_notification):

* dbfile (1) - name of the compacted file
* type - automatic or manual
* fsize\_start - size at start (bytes)
* fsize\_end - size at end (bytes)
* fsize\_last - size at end of last compaction (bytes)
* time\_start - start time (microseconds)
* duration - duration (microseconds)
* ntrans - number of transactions written to (1) since last compaction

Keys for type NOTIF\_COMMIT\_PROGRESS and NOTIF\_PROGRESS (struct confd\_progress\_notification):

* type (1)
* timestamp
* duration if (1) is CONFD\_PROGRESS\_STOP
* trace\_id (optional)
* span\_id
* parent\_span\_id (optional)
* usid
* tid
* datastore
* context (optional)
* subsystem (optional)
* msg (optional)
* annotation (optional)
* num\_attributes
* attributes (optional)
* num\_links
* links (optional)

Keys for type NOTIF\_STREAM\_EVENT (struct confd\_stream\_notification):

* type (1)
* error - if (1) is STREAM\_REPLAY\_FAILED
* event\_time - if (1) is STREAM\_NOTIFICATION\_EVENT
* values - if (1) is STREAM\_NOTIFICATION\_EVENT

Keys for type NOTIF\_CQ\_PROGRESS (struct ncs\_cq\_progress\_notification):

* type
* timestamp
* cq\_id
* cq\_tag
* label
* completed\_devices (optional)
* transient\_devices (optional)
* failed\_devices (optional)
* failed\_reasons - if failed\_devices is present
* completed\_services (optional)
* completed\_services\_completed\_devices - if completed\_services is present
* failed\_services (optional)
* failed\_services\_completed\_devices - if failed\_services is present
* failed\_services\_failed\_devices - if failed\_services is present

Keys for type NOTIF\_CALL\_HOME\_INFO (struct ncs\_call\_home\_notification):

* type (1)
* device - if (1) is CALL\_HOME\_DEVICE\_CONNECTED or CALL\_HOME\_DEVICE\_DISCONNECTED
* af (2)
* ip4 - if (2) is AF\_INET
* ip6 - if (2) is AF\_INET6
* port
* ssh\_host\_key
* ssh\_key\_alg

### sync\_audit\_network\_notification

```python
sync_audit_network_notification(sock, usid) -> None
```

If the received event was NOTIF\_AUDIT\_NETWORK, and we are subscribing to notifications with the flag NOTIF\_AUDIT\_NETWORK\_SYNC, this function must be called when we are done processing the notification. The user session is hanging until this function gets called.

Keyword arguments:

* sock -- a previously connected notification socket
* usid -- the user session id

### sync\_audit\_notification

```python
sync_audit_notification(sock, usid) -> None
```

If the received event was NOTIF\_AUDIT, and we are subscribing to notifications with the flag NOTIF\_AUDIT\_SYNC, this function must be called when we are done processing the notification. The user session is hanging until this function gets called.

Keyword arguments:

* sock -- a previously connected notification socket
* usid -- the user session id

### sync\_ha\_notification

```python
sync_ha_notification(sock) -> None
```

If the received event was NOTIF\_HA\_INFO, and we are subscribing to notifications with the flag NOTIF\_HA\_INFO\_SYNC, this function must be called when we are done processing the notification. All HA processing is blocked until this function gets called.

Keyword arguments:

* sock -- a previously connected notification socket

## Classes

### *class* **Notification**

This is a placeholder for the c-type struct confd\_notification.

Notification cannot be directly instantiated from Python.

Members:

*None*

### *class* **NotificationsData**

This type represents the c-type struct confd\_notifications\_data.

The contructor for this type has the following signature:

NotificationsData(hearbeat\_interval, health\_check\_interval, stream\_name, start\_time, stop\_time, xpath\_filter, usid, verbosity) -> object

Keyword arguments:

* heartbeat\_interval -- time in milli seconds (int)
* health\_check\_interval -- time in milli seconds (int)
* stream\_name -- name of the notification stream (string)
* start\_time -- the start time (Value)
* stop\_time -- the stop time (Value)
* xpath\_filter -- XPath filter for the stream (string) - optional
* usid -- user session id for AAA restriction (int) - optional
* verbosity -- progress verbosity level (int) - optional

Members:

*None*

## Predefined Values

```python

ABORT_COMMIT = 3
CALL_HOME_DEVICE_CONNECTED = 1
CALL_HOME_DEVICE_DISCONNECTED = 3
CALL_HOME_UNKNOWN_DEVICE = 2
COMPACTION_AUTOMATIC = 1
COMPACTION_A_CDB = 1
COMPACTION_MANUAL = 2
COMPACTION_O_CDB = 2
COMPACTION_S_CDB = 3
CONFIRMED_COMMIT = 1
CONFIRMING_COMMIT = 2
DP_CDB = 1
DP_EXTERNAL = 3
DP_JAVASCRIPT = 5
DP_NETCONF = 2
DP_SNMPGW = 4
FORWARD_INFO_DOWN = 2
FORWARD_INFO_FAILED = 3
FORWARD_INFO_UP = 1
HA_INFO_BESECONDARY_RESULT = 7
HA_INFO_BESLAVE_RESULT = 7
HA_INFO_IS_MASTER = 5
HA_INFO_IS_NONE = 6
HA_INFO_IS_PRIMARY = 5
HA_INFO_NOMASTER = 1
HA_INFO_NOPRIMARY = 1
HA_INFO_SECONDARY_ARRIVED = 3
HA_INFO_SECONDARY_DIED = 2
HA_INFO_SECONDARY_INITIALIZED = 4
HA_INFO_SLAVE_ARRIVED = 3
HA_INFO_SLAVE_DIED = 2
HA_INFO_SLAVE_INITIALIZED = 4
NCS_CQ_ITEM_COMPLETED = 4
NCS_CQ_ITEM_DELETED = 6
NCS_CQ_ITEM_EXECUTING = 2
NCS_CQ_ITEM_FAILED = 5
NCS_CQ_ITEM_LOCKED = 3
NCS_CQ_ITEM_WAITING = 1
NCS_NOTIF_AUDIT_NETWORK = 268435456
NCS_NOTIF_AUDIT_NETWORK_SYNC = 536870912
NCS_NOTIF_CALL_HOME_INFO = 33554432
NCS_NOTIF_CQ_PROGRESS = 4194304
NCS_NOTIF_PACKAGE_RELOAD = 2097152
NOTIF_AUDIT = 1
NOTIF_AUDIT_SYNC = 131072
NOTIF_COMMIT_DIFF = 16
NOTIF_COMMIT_FAILED = 256
NOTIF_COMMIT_FLAG_CONFIRMED = 1
NOTIF_COMMIT_FLAG_CONFIRMED_EXTENDED = 2
NOTIF_COMMIT_PROGRESS = 65536
NOTIF_COMMIT_SIMPLE = 8
NOTIF_COMPACTION = 1073741824
NOTIF_CONFIRMED_COMMIT = 16384
NOTIF_DAEMON = 2
NOTIF_DEVEL = 4096
NOTIF_FORWARD_INFO = 1024
NOTIF_HA_INFO = 64
NOTIF_HA_INFO_SYNC = 1048576
NOTIF_HEALTH_CHECK = 262144
NOTIF_HEARTBEAT = 8192
NOTIF_JSONRPC = 67108864
NOTIF_NETCONF = 2048
NOTIF_PROGRESS = 16777216
NOTIF_REOPEN_LOGS = 8388608
NOTIF_SNMPA = 512
NOTIF_STREAM_EVENT = 524288
NOTIF_SUBAGENT_INFO = 128
NOTIF_SYSLOG = 2
NOTIF_SYSLOG_TAKEOVER = 6
NOTIF_TAKEOVER_SYSLOG = 4
NOTIF_UPGRADE_EVENT = 32768
NOTIF_USER_SESSION = 32
NOTIF_WEBUI = 134217728
PROGRESS_ATTRIBUTE_NUMBER = 2
PROGRESS_ATTRIBUTE_STRING = 1
STREAM_NOTIFICATION_COMPLETE = 2
STREAM_NOTIFICATION_EVENT = 1
STREAM_REPLAY_COMPLETE = 3
STREAM_REPLAY_FAILED = 4
SUBAGENT_INFO_DOWN = 2
SUBAGENT_INFO_UP = 1
UPGRADE_ABORTED = 5
UPGRADE_COMMITED = 4
UPGRADE_INIT_STARTED = 1
UPGRADE_INIT_SUCCEEDED = 2
UPGRADE_PERFORMED = 3
USER_SESS_LOCK = 3
USER_SESS_START = 1
USER_SESS_START_TRANS = 5
USER_SESS_STOP = 2
USER_SESS_STOP_TRANS = 6
USER_SESS_UNLOCK = 4
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nso-docs.cisco.com/guides/nso-6.6/developer-reference/pyapi/_ncs.events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.