* Asyncore and asyncio-based APIs reworked to become functions.

* Asyncio and Twisted API moved entirely into high-level domain to
  be aligned with other high-level APIs. This WILL BREAK backward
  compatibility for those apps that use Twisted API.

8 files changed, 372 insertions, 0 deletions

diff --git a/examples/hlapi/asyncore/sync/agent/ntforg/custom-contextengineid.py b/examples/hlapi/asyncore/sync/agent/ntforg/custom-contextengineid.py
new file mode 100644
index 0000000..2ccdafe
--- /dev/null
+++ b/examples/hlapi/asyncore/sync/agent/ntforg/custom-contextengineid.py
@@ -0,0 +1,48 @@
+"""
+INFORM with custom ContextEngineId
+++++++++++++++++++++++++++++++++++
+
+Send SNMP notification using the following options:
+
+* SNMPv3
+* with user 'usr-md5-none', MD5 auth, no priv
+* send INFORM notification
+* in behalf of contextEngineId 0x8000000004030201, contextName ''
+* over IPv4/UDP
+* with TRAP ID 'warmStart' specified as a string OID
+
+Sending SNMPv3 Notification in behalf of non-default ContextEngineId
+requires having a collection of Managed Objects registered under
+the ContextEngineId being used.
+
+Functionally similar to:
+
+| $ snmpinform -v3 -l authNoPriv -u usr-md5-none -A authkey1 \
+|              -E 0x8000000004030201
+|              demo.snmplabs.com \
+|              12345 \
+|              1.3.6.1.6.3.1.1.5.2
+
+"""#
+from pysnmp.hlapi import *
+
+errorIndication, errorStatus, errorIndex, varBinds = next(
+    sendNotification(SnmpEngine(),
+                     UsmUserData('usr-md5-none', 'authkey1'),
+                     UdpTransportTarget(('localhost', 162)),
+                     ContextData(OctetString(hexValue='8000000004030201')),
+                     'inform',
+                     NotificationType(ObjectIdentity('1.3.6.1.6.3.1.1.5.2')))
+)
+
+if errorIndication:
+    print(errorIndication)
+elif errorStatus:
+    print('%s at %s' % (
+            errorStatus.prettyPrint(),
+            errorIndex and varBinds[int(errorIndex)-1][0] or '?'
+        )
+    )
+else:
+    for varBind in varBinds:
+        print(' = '.join([ x.prettyPrint() for x in varBind ]))
diff --git a/examples/hlapi/asyncore/sync/agent/ntforg/custom-contextname.py b/examples/hlapi/asyncore/sync/agent/ntforg/custom-contextname.py
new file mode 100644
index 0000000..a087c7e
--- /dev/null
+++ b/examples/hlapi/asyncore/sync/agent/ntforg/custom-contextname.py
@@ -0,0 +1,48 @@
+"""
+INFORM with custom ContextName
+++++++++++++++++++++++++++++++
+
+Send SNMP notification using the following options:
+
+* SNMPv3
+* with user 'usr-md5-none', MD5 auth, no priv
+* send INFORM notification
+* in behalf of contextEngineId = SnmpEngineId, contextName 'my-context'
+* over IPv4/UDP
+* with TRAP ID 'warmStart' specified as a string OID
+
+Sending SNMPv3 Notification in behalf of non-default ContextName
+requires having a collection of Managed Objects registered under
+the ContextName being used.
+
+Functionally similar to:
+
+| $ snmpinform -v3 -l authNoPriv -u usr-md5-none -A authkey1 \
+|              -n my-context \
+|              demo.snmplabs.com \
+|              12345 \
+|              1.3.6.1.6.3.1.1.5.2
+
+"""#
+from pysnmp.hlapi import *
+
+errorIndication, errorStatus, errorIndex, varBinds = next(
+    sendNotification(SnmpEngine(),
+                     UsmUserData('usr-md5-none', 'authkey1'),
+                     UdpTransportTarget(('localhost', 162)),
+                     ContextData(contextName='my-context'),
+                     'inform',
+                     NotificationType(ObjectIdentity('1.3.6.1.6.3.1.1.5.2')))
+)
+
+if errorIndication:
+    print(errorIndication)
+elif errorStatus:
+    print('%s at %s' % (
+            errorStatus.prettyPrint(),
+            errorIndex and varBinds[int(errorIndex)-1][0] or '?'
+        )
+    )
+else:
+    for varBind in varBinds:
+        print(' = '.join([ x.prettyPrint() for x in varBind ]))
diff --git a/examples/hlapi/asyncore/sync/agent/ntforg/custom-v1-trap.py b/examples/hlapi/asyncore/sync/agent/ntforg/custom-v1-trap.py
new file mode 100644
index 0000000..768ad26
--- /dev/null
+++ b/examples/hlapi/asyncore/sync/agent/ntforg/custom-v1-trap.py
@@ -0,0 +1,50 @@
+"""
+Custom SNMPv1 TRAP
+++++++++++++++++++
+
+Send SNMPv1 TRAP through unified SNMPv3 message processing framework.
+
+Original v1 TRAP fields are mapped into dedicated variable-bindings,
+(see `RFC2576 <https://www.ietf.org/rfc/rfc2576.txt>`_) for details.
+
+* SNMPv1
+* with community name 'public'
+* over IPv4/UDP
+* send TRAP notification
+* with Generic Trap #6 (enterpriseSpecific) and Specific Trap 432
+* overriding Uptime value with 12345
+* overriding Agent Address with '127.0.0.1'
+* overriding Enterprise OID with 1.3.6.1.4.1.20408.4.1.1.2
+* include managed object information '1.3.6.1.2.1.1.1.0' = 'my system'
+
+Functionally similar to:
+
+| $ snmptrap -v1 -c public demo.snmplabs.com \
+|   1.3.6.1.4.1.20408.4.1.1.2 \
+|   127.0.0.1 \
+|   6 \
+|   432 \
+|   12345 \
+|   '1.3.6.1.2.1.1.1.0' s 'my system'
+
+"""#
+from pysnmp.hlapi import *
+
+errorIndication, errorStatus, errorIndex, varBinds = next(
+    sendNotification(SnmpEngine(),
+                     CommunityData('public', mpModel=0),
+                     UdpTransportTarget(('localhost', 162)),
+                     ContextData(),
+                     'trap',
+                     NotificationType(
+                         ObjectIdentity('1.3.6.1.4.1.20408.4.1.1.2.0.432'),
+                     ).addVarBinds(
+                         ('1.3.6.1.2.1.1.3.0', 12345),
+                         ('1.3.6.1.6.3.18.1.3.0', '127.0.0.1'),
+                         ('1.3.6.1.6.3.1.1.4.3.0', '1.3.6.1.4.1.20408.4.1.1.2'),
+                         ('1.3.6.1.2.1.1.1.0', OctetString('my system'))
+                     )
+    )
+)
+if errorIndication:
+    print(errorIndication)
diff --git a/examples/hlapi/asyncore/sync/agent/ntforg/default-v1-trap.py b/examples/hlapi/asyncore/sync/agent/ntforg/default-v1-trap.py
new file mode 100644
index 0000000..7d4a9d0
--- /dev/null
+++ b/examples/hlapi/asyncore/sync/agent/ntforg/default-v1-trap.py
@@ -0,0 +1,46 @@
+"""
+SNMPv1 TRAP with defaults
++++++++++++++++++++++++++
+
+Send SNMPv1 TRAP through unified SNMPv3 message processing framework
+using the following options:
+
+* SNMPv1
+* with community name 'public'
+* over IPv4/UDP
+* send TRAP notification
+* with Generic Trap #1 (warmStart) and Specific Trap 0
+* with default Uptime
+* with default Agent Address
+* with Enterprise OID 1.3.6.1.4.1.20408.4.1.1.2
+* include managed object information '1.3.6.1.2.1.1.1.0' = 'my system'
+
+Functionally similar to:
+
+| $ snmptrap -v1 -c public demo.snmplabs.com \
+|   1.3.6.1.4.1.20408.4.1.1.2 \
+|   0.0.0.0 \
+|   1 \
+|   0 \
+|   0
+|   '1.3.6.1.2.1.1.1.0' s 'my system'
+
+"""#
+from pysnmp.hlapi import *
+
+errorIndication, errorStatus, errorIndex, varBinds = next(
+    sendNotification(SnmpEngine(),
+                     CommunityData('public', mpModel=0),
+                     UdpTransportTarget(('localhost', 162)),
+                     ContextData(),
+                     'trap',
+                     NotificationType(
+                         ObjectIdentity('1.3.6.1.6.3.1.1.5.2')
+                     ).addVarBinds(
+                         ('1.3.6.1.6.3.1.1.4.3.0', '1.3.6.1.4.1.20408.4.1.1.2'),
+                         ('1.3.6.1.2.1.1.1.0', OctetString('my system'))
+                     )
+    )
+)
+if errorIndication:
+    print(errorIndication)
diff --git a/examples/hlapi/asyncore/sync/agent/ntforg/send-notification-with-additional-varbinds.py b/examples/hlapi/asyncore/sync/agent/ntforg/send-notification-with-additional-varbinds.py
new file mode 100644
index 0000000..17cf899
--- /dev/null
+++ b/examples/hlapi/asyncore/sync/agent/ntforg/send-notification-with-additional-varbinds.py
@@ -0,0 +1,49 @@
+"""
+Sending additional var-binds
+++++++++++++++++++++++++++++
+
+Send SNMP notification using the following options:
+
+* SNMPv2c
+* with community name 'public'
+* over IPv4/UDP
+* send INFORM notification
+* with TRAP ID 'coldStart' specified as a MIB symbol
+* include managed object information specified as a MIB symbol
+
+Functionally similar to:
+
+| $ snmpinform -v2c -c public 
+|              demo.snmplabs.com \
+|              12345 \
+|              1.3.6.1.6.3.1.1.5.1 \
+|              1.3.6.1.2.1.1.1.0 s 'my system'
+
+"""#
+from pysnmp.hlapi import *
+
+errorIndication, errorStatus, errorIndex, varBinds = next(
+    sendNotification(SnmpEngine(),
+                     CommunityData('public'),
+                     UdpTransportTarget(('localhost', 162)),
+                     ContextData(),
+                     'inform',
+                     NotificationType(
+                         ObjectIdentity('SNMPv2-MIB', 'coldStart')
+                     ).addVarBinds(
+                         ObjectType(ObjectIdentity('SNMPv2-MIB','sysName',0),
+                                                   'my system')
+                     ))
+)
+
+if errorIndication:
+    print(errorIndication)
+elif errorStatus:
+    print('%s at %s' % (
+            errorStatus.prettyPrint(),
+            errorIndex and varBinds[int(errorIndex)-1][0] or '?'
+        )
+    )
+else:
+    for varBind in varBinds:
+        print(' = '.join([ x.prettyPrint() for x in varBind ]))
diff --git a/examples/hlapi/asyncore/sync/agent/ntforg/v2c-trap-via-notification-type.py b/examples/hlapi/asyncore/sync/agent/ntforg/v2c-trap-via-notification-type.py
new file mode 100644
index 0000000..e5121b2
--- /dev/null
+++ b/examples/hlapi/asyncore/sync/agent/ntforg/v2c-trap-via-notification-type.py
@@ -0,0 +1,37 @@
+"""
+SNMPv2c TRAP via NOTIFICATION-TYPE
+++++++++++++++++++++++++++++++++++
+
+Initialize TRAP message contents from variables specified
+in *NOTIFICATION-TYPE* SMI macro.
+
+* SNMPv2c
+* with community name 'public'
+* over IPv4/UDP
+* send TRAP notification
+* with TRAP ID 'coldStart' specified as a MIB symbol
+* include managed object information specified as a MIB symbol
+
+Functionally similar to:
+
+| $ snmptrap -v2c -c public demo.snmplabs.com \
+|   12345
+|   1.3.6.1.4.1.20408.4.1.1.2
+
+"""#
+from pysnmp.hlapi import *
+
+errorIndication, errorStatus, errorIndex, varBinds = next(
+    sendNotification(SnmpEngine(),
+                     CommunityData('public'),
+                     UdpTransportTarget(('localhost', 162)),
+                     ContextData(),
+                     'trap',
+                     NotificationType(
+                         ObjectIdentity('SNMPv2-MIB', 'coldStart')
+                     )
+    )
+)
+
+if errorIndication:
+    print(errorIndication)
diff --git a/examples/hlapi/asyncore/sync/agent/ntforg/v3-inform.py b/examples/hlapi/asyncore/sync/agent/ntforg/v3-inform.py
new file mode 100644
index 0000000..39f5127
--- /dev/null
+++ b/examples/hlapi/asyncore/sync/agent/ntforg/v3-inform.py
@@ -0,0 +1,49 @@
+"""
+INFORM, auth: MD5 privacy: DES
+++++++++++++++++++++++++++++++
+
+Send SNMP INFORM notification using the following options:
+
+* SNMPv3
+* with user 'usr-md5-des', auth: MD5, priv DES
+* over IPv4/UDP
+* send INFORM notification
+* with TRAP ID 'warmStart' specified as a string OID
+* include managed object information 1.3.6.1.2.1.1.5.0 = 'system name'
+
+Functionally similar to:
+
+| $ snmpinform -v3 -l authPriv -u usr-sha-aes -A authkey1 -X privkey1 \
+|              demo.snmplabs.com \
+|              12345 \
+|              1.3.6.1.4.1.20408.4.1.1.2 \
+|              '1.3.6.1.2.1.1.1.0' s 'my system'
+
+"""#
+from pysnmp.hlapi import *
+
+errorIndication, errorStatus, errorIndex, varBinds = next(
+    sendNotification(SnmpEngine(),
+                     UsmUserData('usr-md5-des', 'authkey1', 'privkey1'),
+                     UdpTransportTarget(('localhost', 162)),
+                     ContextData(),
+                     'inform',
+                     NotificationType(
+                         ObjectIdentity('1.3.6.1.6.3.1.1.5.2')
+                     ).addVarBinds(
+                         ObjectType(ObjectIdentity('1.3.6.1.2.1.1.5.0'),
+                                    'system name')
+                     ))
+)
+
+if errorIndication:
+    print(errorIndication)
+elif errorStatus:
+    print('%s at %s' % (
+            errorStatus.prettyPrint(),
+            errorIndex and varBinds[int(errorIndex)-1][0] or '?'
+        )
+    )
+else:
+    for varBind in varBinds:
+        print(' = '.join([ x.prettyPrint() for x in varBind ]))
diff --git a/examples/hlapi/asyncore/sync/agent/ntforg/v3-trap.py b/examples/hlapi/asyncore/sync/agent/ntforg/v3-trap.py
new file mode 100644
index 0000000..ba62b39
--- /dev/null
+++ b/examples/hlapi/asyncore/sync/agent/ntforg/v3-trap.py
@@ -0,0 +1,45 @@
+"""
+SNMPv3 TRAP: auth SHA, privacy: AES128
+++++++++++++++++++++++++++++++++++++++
+
+Send SNMP notification using the following options:
+
+* SNMPv3
+* with local snmpEngineId = 0x8000000001020304 (must configure at Receiver)
+* with user 'usr-sha-aes128', auth: SHA, priv: AES128
+* over IPv4/UDP
+* send TRAP notification
+* with TRAP ID 'authenticationFailure' specified as a MIB symbol
+* do not include any additional managed object information
+
+SNMPv3 TRAPs requires pre-sharing the Notification Originator's
+value of SnmpEngineId with Notification Receiver. To facilitate that
+we will use static (e.g. not autogenerated) version of snmpEngineId.
+
+Functionally similar to:
+
+| $ snmptrap -v3 -l authPriv -u usr-sha-aes -A authkey1 -X privkey1 \
+|            -a SHA -x AES \
+|            demo.snmplabs.com \
+|            12345 \
+|            1.3.6.1.4.1.20408.4.1.1.2 \
+|            '1.3.6.1.2.1.1.1.0' s 'my system'
+
+"""#
+from pysnmp.hlapi import *
+
+errorIndication, errorStatus, errorIndex, varBinds = next(
+    sendNotification(SnmpEngine(OctetString(hexValue='8000000001020304')),
+                     UsmUserData('usr-sha-aes128', 'authkey1', 'privkey1',
+                                 authProtocol=usmHMACSHAAuthProtocol,
+                                 privProtocol=usmAesCfb128Protocol),
+                     UdpTransportTarget(('localhost', 162)),
+                     ContextData(),
+                     'trap',
+                     NotificationType(
+                         ObjectIdentity('SNMPv2-MIB', 'authenticationFailure')
+                     )
+    )
+)
+if errorIndication:
+    print(errorIndication)