updates

1 files changed, 166 insertions, 101 deletions

diff --git a/docs/pysnmp-tutorial.html b/docs/pysnmp-tutorial.html
index 3d19594..2ff5f30 100644
--- a/docs/pysnmp-tutorial.html
+++ b/docs/pysnmp-tutorial.html
@@ -1060,7 +1060,7 @@ else:
 </H4>
 
 <P>
-Notification Originator Applications are implemented within a single class:
+The Notification Originator Application is implemented within a single class:
 </P>
 
 <DL>
@@ -1231,8 +1231,15 @@ if errorIndication:
 </PRE>
 </TD></TR></TABLE>
 
+<P>To send SNMP v1 traps using standard Notification Originator
+application API, one may need to pass, and possibly override some
+of defaulted, SNMP v1 PDU fields that are not present as such in SNMP 
+v2c PDU and thus in the API.
+</P>
+
 <P>
-The following code sends SNMP v1 TRAP message:
+The following example sends SNMP v1 TRAP message overriding implicit
+defaults:
 <UL>
 <LI>using SNMP v1
 <LI>with community name 'public'
@@ -1240,9 +1247,10 @@ The following code sends SNMP v1 TRAP message:
 <LI>send TRAP notification
 <LI>with Generic Trap #6 (enterpriseSpecific) and Specific Trap 432
 <LI>overriding local snmpEngine's Uptime with value 12345
-<LI>with Agent Address '127.0.0.1'
-<LI>with Enterprise OID 1.3.6.1.4.1.20408.4.1.1.2
+<LI>overriding Agent Address with '127.0.0.1'
+<LI>overriding Enterprise OID with 1.3.6.1.4.1.20408.4.1.1.2
 <LI>include managed object information '1.3.6.1.2.1.1.1.0' = 'my system'
+specified as an OID-value pair
 </UL>
 </P>
 <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD>
@@ -1268,6 +1276,38 @@ if errorIndication:
 </PRE>
 </TD></TR></TABLE>
 
+<P>
+The following code sends SNMP v2c INFORM message over SNMPv3:
+<UL>
+<LI>using SNMP v3
+<LI>with user 'usr-md5-des', auth: MD5, priv 3DES
+<LI>over IPv4/UDP
+<LI>send INFORM notification
+<LI>with TRAP ID 'warmStart' specified as a string OID
+<LI>include managed object information 1.3.6.1.2.1.1.5.0 = 'system name'
+specified as an OID-value pair
+</UL>
+</P>
+<TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD>
+<PRE>
+from pysnmp.entity.rfc3413.oneliner import ntforg
+from pysnmp.proto import rfc1902
+
+ntfOrg = ntforg.NotificationOriginator()
+
+errorIndication = ntfOrg.sendNotification(
+    ntforg.UsmUserData('usr-md5-des', 'authkey1', 'privkey1'),
+    ntforg.UdpTransportTarget(('localhost', 162)),
+    'inform',
+    '1.3.6.1.6.3.1.1.5.2',
+    ('1.3.6.1.2.1.1.5.0', rfc1902.OctetString('system name'))
+)
+
+if errorIndication:
+    print('Notification not sent: %s' % errorIndication)
+</PRE>
+</TD></TR></TABLE>
+
 <A NAME="ASYNCH-ONELINER-APPS"></A>
 <H4>
 2.1.2 Asynchronous One-line Applications
@@ -1282,11 +1322,15 @@ activities inside user's program while SNMP Application is waiting for
 input/output.
 </P>
 
+<A NAME="AsynCommandGenerator"></A>
+<H4>
+2.1.2.1 Asynchronous Command Generator
+</H4>
+
 <P>
 All Command Generator Applications are implemented within a single class:
 </P>
 
-<A NAME="AsynCommandGenerator"></A>
 <DL>
 <DT>class <STRONG>AsynCommandGenerator</STRONG>([<STRONG>snmpEngine</STRONG>])</DT>
 <DD>
@@ -1315,7 +1359,7 @@ asynchronous interface uses a callback function for delivering responses.
 
 <A NAME="AsynCommandGenerator.asyncGetCmd"></A>
 <DL>
-<DT><STRONG>asyncGetCmd</STRONG>(
+<DT><STRONG>getCmd</STRONG>(
 <STRONG>authData</STRONG>,
 <STRONG>transportTarget</STRONG>,
 <STRONG>varNames</STRONG>,
@@ -1349,12 +1393,12 @@ The <STRONG>cbFun</STRONG> parameter is a reference to a callable object
 <P>
 Where <STRONG>sendRequestHandle</STRONG> is an integer value used for matching
 response to request. Its counterpart is returned on request submission by 
-the <STRONG>asyncGetCmd</STRONG> method.
+the <STRONG>getCmd</STRONG> method.
 </P>
 
 <P>
 The <STRONG>cbCtx</STRONG> parameter is a reference to the
-<STRONG>cbCtx</STRONG> object being passed to <STRONG>asyncGetCmd</STRONG> 
+<STRONG>cbCtx</STRONG> object being passed to <STRONG>getCmd</STRONG> 
 method. Its purpose is to carry opaque application's state from request 
 through response methods.
 </P>
@@ -1369,7 +1413,6 @@ method.
 </DD>
 </DL>
 
-
 <P>
 The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>,
 <STRONG>varNames</STRONG>, <STRONG>lookupNames</STRONG> and
@@ -1380,7 +1423,7 @@ Managed Objects Instances names.
 </P>
 
 <P>
-The <STRONG>asyncGetCmd</STRONG> method returns unique
+The <STRONG>getCmd</STRONG> method returns unique
 <STRONG>sendRequestHandle</STRONG> integer value used for
 matching subsequent response to this request.
 </P>
@@ -1389,15 +1432,15 @@ matching subsequent response to this request.
 
 <P>
 The following code performs multiple, simultaneous SNMP GET operations
-against distinct Agents identified by their transport addresses.
-Authentication information and queried Managed Objects Instances used in 
-this example are the same for all targets. So the GET operation is performed:
+for multiple Managed Objects Instances to a single Agent.
+Authentication information used in this example are the same for all targets.
+So the GET operation is performed:
 <UL>
 <LI>using SNMP v2c
 <LI>with SNMPv2c community 'public'
 <LI>over IPv4/UDP
-<LI>against an Agents listening at 127.0.0.1, 127.0.0.2, 127.0.0.3 (port 161)
-<LI>for the SNMPv2-MIB::sysDescr.0 and SNMPv2-MIB::sysLocation.0 objects
+<LI>against an Agent listening at 127.0.0.1
+<LI>for the SNMPv2-MIB::sysDescr.0, SNMPv2-MIB::sysLocation.0 and SNMPv2-MIB::sysName.0 objects
 </UL>
 </P>
 
@@ -1423,17 +1466,14 @@ def cbFun(sendRequestHandle, errorIndication, errorStatus, errorIndex, varBinds,
 
 cmdGen  = cmdgen.AsynCommandGenerator()
 
-for transportTarget in ( cmdgen.UdpTransportTarget(('127.0.0.1', 161)),
-                         cmdgen.UdpTransportTarget(('127.0.0.2', 161)),
-                         cmdgen.UdpTransportTarget(('127.0.0.3', 161)) ):
+for varName in ( cmdgen.MibVariable('SNMPv2-MIB', 'sysDescr', 0),
+                 cmdgen.MibVariable('SNMPv2-MIB', 'sysLocation', 0),
+                 cmdgen.MibVariable('SNMPv2-MIB', 'sysName', 0) ):
     cmdGen.getCmd(
         cmdgen.CommunityData('public'),
-        cmdgen.UdpTransportTarget(('localhost', 161)),
-        ( cmdgen.MibVariable('SNMPv2-MIB', 'sysDescr', 0),
-          cmdgen.MibVariable('SNMPv2-MIB', 'sysLocation', 0) ),
-        # User-space callback function and its context
-        (cbFun, None),
-        lookupNames=True, lookupValues=True
+        cmdgen.UdpTransportTarget(('127.0.0.1', 161)),
+        (varName,),
+        (cbFun, None)
     )
 
 cmdGen.snmpEngine.transportDispatcher.runDispatcher()
@@ -1454,7 +1494,7 @@ Agents avialability and responsiveness.
 
 <A NAME="AsynCommandGenerator.asyncSetCmd"></A>
 <DL>
-<DT><STRONG>asyncSetCmd</STRONG>(
+<DT><STRONG>setCmd</STRONG>(
 <STRONG>authData</STRONG>,
 <STRONG>transportTarget</STRONG>,
 <STRONG>varBinds</STRONG>,
@@ -1473,15 +1513,13 @@ Prepare SNMP SET request to be dispatched. Return the
 The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>,
 <STRONG>varNames</STRONG>, <STRONG>lookupNames</STRONG> and
 <STRONG>lookupValues</STRONG> parameters have the same meaning as in
-<A HREF="#CommandGenerator.setCmd">setCmd</A> method except that
-<STRONG>varBinds</STRONG> is passed as a sequence, not as individual
-Managed Objects Instances.
+<A HREF="#AsynCommandGenerator.setCmd">setCmd</A>.
 </P>
 
 <P>
 The <STRONG>cbFun</STRONG> and <STRONG>cbCtx</STRONG> parameters
 have the same meaning as in <A HREF="#AsynCommandGenerator.asyncGetCmd">
-AsynCommandGenerator.asyncGetCmd</A> method.
+AsynCommandGenerator.getCmd</A> method.
 </P>
 
 </DD>
@@ -1489,7 +1527,7 @@ AsynCommandGenerator.asyncGetCmd</A> method.
 
 <A NAME="AsynCommandGenerator.asyncNextCmd"></A>
 <DL>
-<DT><STRONG>asyncNextCmd</STRONG>(
+<DT><STRONG>nextCmd</STRONG>(
 <STRONG>authData</STRONG>,
 <STRONG>transportTarget</STRONG>,
 <STRONG>varNames</STRONG>,
@@ -1516,7 +1554,7 @@ Managed Objects Instances names.
 <P>
 The <STRONG>cbFun</STRONG> and <STRONG>cbCtx</STRONG> parameters
 have the same meaning as in <A HREF="#AsynCommandGenerator.asyncGetCmd">
-AsynCommandGenerator.asyncGetCmd</A> method.
+AsynCommandGenerator.getCmd</A> method.
 Appliction can indicate to GETNEXT SNMP Application that it is no more
 interested in further information from Agent and wishes to stop by
 returning True from the <STRONG>cbFun</STRONG>. Otherwise it should return
@@ -1531,9 +1569,62 @@ except that here it is passed in as a tuple.
 </DD>
 </DL>
 
+<P>
+The following code performs multiple, simultaneous SNMP GETNEXT operations
+against distinct Agents identified by their transport addresses.
+Authentication information and queried Managed Objects Instances used in 
+this example are the same for all targets. So the GETNEXT operation is performed:
+<UL>
+<LI>using SNMP v3
+<LI>with SNMPv3 with user 'usr-md5-des', MD5 auth and DES privacy protocols
+<LI>over IPv4/UDP
+<LI>against an Agents listening at 127.0.0.1, 192.168.1.1, 10.40.1.1 (port 161)
+<LI>for the SNMPv2-MIB::system subtree
+</UL>
+</P>
+
+<TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD>
+<PRE>
+from pysnmp.entity.rfc3413.oneliner import cmdgen
+
+def cbFun(sendRequestHandle, errorIndication, errorStatus, errorIndex, varBindTable, cbCtx):
+    if errorIndication:
+        print(errorIndication)
+        return
+    if errorStatus:
+        print('%s at %s' % (errorStatus.prettyPrint(),
+                            errorIndex and varBindTable[-1][int(errorIndex)-1] or '?')
+        )
+        return
+    
+    for varBindRow in varBindTable:
+        for oid, val in varBindRow:
+            if val is None:
+                return    # stop table retrieval
+            else:
+                print('%s = %s' % (oid.prettyPrint(), val.prettyPrint()))
+
+    return True  # continue table retrieval
+
+cmdGen  = cmdgen.AsynCommandGenerator()
+
+for transportTarget in ( cmdgen.UdpTransportTarget(('127.0.0.1', 161)),
+                         cmdgen.UdpTransportTarget(('192.168.1.1', 161)),
+                         cmdgen.UdpTransportTarget(('10.40.1.1', 161)) ):
+    cmdGen.nextCmd(
+        cmdgen.UsmUserData('usr-md5-des', 'authkey1', 'privkey1'),
+        transportTarget,
+        ( cmdgen.MibVariable('SNMPv2-MIB', 'system'), ),
+        (cbFun, None)
+    )
+
+cmdGen.snmpEngine.transportDispatcher.runDispatcher()
+</PRE>
+</TABLE>
+
 <A NAME="AsynCommandGenerator.asyncBulkCmd"></A>
 <DL>
-<DT><STRONG>asyncBulkCmd</STRONG>(
+<DT><STRONG>bulkCmd</STRONG>(
 <STRONG>authData</STRONG>,
 <STRONG>transportTarget</STRONG>,
 <STRONG>nonRepeaters</STRONG>,
@@ -1563,7 +1654,7 @@ Managed Objects Instances names.
 <P>
 The <STRONG>cbFun</STRONG> and <STRONG>cbCtx</STRONG> parameters
 have the same meaning as in <A HREF="#AsynCommandGenerator.asyncNextCmd">
-AsynCommandGenerator.asyncNextCmd</A> method.
+AsynCommandGenerator.nextCmd</A> method.
 </P>
 
 </DD>
@@ -1594,48 +1685,15 @@ The <STRONG>runDispatcher</STRONG>() method terminates when no pending requests
 left for running Applications.
 </P>
 
-<P>
-The following code performs SNMP GET operation asynchronously through
-SNMPv3:
-</P>
-
-<TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD>
-<PRE>
->>> from pysnmp.entity.rfc3413.oneliner import cmdgen
->>>
->>> def cbFun(sendRequestHandle, errorIndication, errorStatus, errorIndex, varBinds, cbCtx):
-...     print('sendRequestHandle = %d' % sendRequestHandle)
-...     print('errorIndication = %s' % errorIndication)
-...     print('errorStatus = %s' % errorStatus)
-...     print('varBinds = %s' % (varBinds,))
-...     print('cbCtx = %s' % cbCtx)
-...
->>> asynCommandGenerator = cmdgen.AsynCommandGenerator()
->>> # This is a non-blocking call
->>> sendRequestHandle = asynCommandGenerator.asyncGetCmd(
-... cmdgen.UsmUserData('my-user', 'my-authkey', 'my-privkey'), 
-... cmdgen.UdpTransportTarget(('localhost', 161)), 
-... ('1.3.6.1.2.1.1.1.0',), 
-... (cbFun, None))
->>> print(sendRequestHandle)
-1
->>> asynCommandGenerator.snmpEngine.transportDispatcher.runDispatcher()
-sendRequestHandle = 1
-errorIndication = None
-errorStatus = 0
-varBinds = [(ObjectName('1.3.6.1.2.1.1.1.0'), OctetString("'Linux saturn 
-     2.6.21 #2 Mon Mar 19 17:07:18 MSD 2006 i686'"))]
-cbCtx = None
->>>
-</PRE>
-</TD></TR></TABLE>
+<A NAME="AsynNotificationOriginator"></A>
+<H4>
+2.1.2.2 Asynchronous Notification Originator
+</H4>
 
 <P>
-The <STRONG>AsynNotificationOriginator</STRONG> class implements specific 
-notification types.
+The Notification Originator Application is implemented within a single class:
 </P>
 
-<A NAME="AsynNotificationOriginator"></A>
 <DL>
 <DT>class <STRONG>AsynNotificationOriginator</STRONG>([<STRONG>snmpContext</STRONG>])</DT>
 <DD>
@@ -1655,7 +1713,7 @@ are used.
 
 <A NAME="AsynNotificationOriginator.asyncSendNotification"></A>
 <DL>
-<DT><STRONG>asyncSendNotification</STRONG>(
+<DT><STRONG>sendNotification</STRONG>(
 <STRONG>authData</STRONG>,
 <STRONG>transportTarget</STRONG>,
 <STRONG>notifyType</STRONG>,
@@ -1688,7 +1746,7 @@ The <STRONG>cbFun</STRONG> parameter is a reference to a callable object
 Where the <STRONG>sendRequestHandle</STRONG>, <STRONG>errorIndication</STRONG>
 and <STRONG>cbCtx</STRONG> parameters have the same meaning as in 
 callback function in 
-<A HREF="#AsynCommandGenerator.asyncGetCmd">AsynCommandGenerator.asynGetCmd</A> method.
+<A HREF="#AsynCommandGenerator.asyncGetCmd">AsynCommandGenerator.getCmd</A> method.
 </P>
 
 </DD>
@@ -1696,7 +1754,7 @@ callback function in
 
 <P>
 The <STRONG>cbCtx</STRONG> parameter has the same meaning as in 
-<A HREF="#AsynCommandGenerator.asyncGetCmd">AsynCommandGenerator.asyncGetCmd</A> method.
+<A HREF="#AsynCommandGenerator.asyncGetCmd">AsynCommandGenerator.getCmd</A> method.
 </P>
 
 <P>
@@ -1708,7 +1766,7 @@ except that here it is passed in as a tuple.
 </P>
 
 <P>
-The <STRONG>asyncSendNotification</STRONG> method returns unique
+The <STRONG>sendNotification</STRONG> method returns unique
 <STRONG>sendRequestHandle</STRONG> integer value used for
 matching subsequent delivery confirmation response to arbitrary notification.
 </P>
@@ -1742,37 +1800,44 @@ notifications left for running Applications.
 </P>
 
 <P>
-The following code sends SNMP INFORM notification asynchronously through
-SNMPv3:
+The following code sends multiple, simultaneous SNMP INFORM messages
+to multiple Managers. Authentication information used in this example is
+the same for all targets.
+<UL>
+<LI>using SNMP v2c
+<LI>with SNMPv2c community 'public'
+<LI>over IPv4/UDP
+<LI>against an Agents listening at 127.0.0.1, 127.0.0.2, 127.0.0.3 (port 162)
+</UL>
 </P>
 
 <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD>
 <PRE>
->>> from pysnmp.entity.rfc3413.oneliner import cmdgen, ntforg
->>> from pysnmp.proto.api import v2c
->>>
->>> def cbFun(sendRequestHandle, errorIndication, cbCtx):
-...     print('sendRequestHandle = %d' % sendRequestHandle)
-...     print('errorIndication = %s' % errorIndication)
-...     print('cbCtx = %s' % (cbCtx,))
-...
->>> asynNotificationOriginator = ntforg.AsynNotificationOriginator()
->>> # This is a non-blocking call
->>> sendRequestHandle = asynNotificationOriginator.asyncSendNotification(
-... cmdgen.UsmUserData('my-user', 'my-authkey', 'my-privkey'),
-... cmdgen.UdpTransportTarget(('localhost', 162)),
-... 'inform',
-... cmdgen.MibVariable('SNMPv2-MIB', 'coldStart'),
-... ('1.3.6.1.2.1.1.1.0', v2c.TimeTicks(44100)),
-... (cbFun, None))
->>> print(sendRequestHandle)
-1
->>> asynNotificationOriginator.snmpEngine.transportDispatcher.runDispatcher()
-sendRequestHandle = 1
-errorIndication = None
-cbCtx = None
->>>
+from pysnmp.entity.rfc3413.oneliner import ntforg
+
+def cbFun(sendRequestHandle, errorIndication, cbCtx):
+    if errorIndication:
+        print(errorIndication)
+    else:
+        print('INFORM %s delivered' % sendRequestHandle)
+
+ntfOrg = ntforg.AsynNotificationOriginator()
+
+for target in ( ntforg.UdpTransportTarget(('127.0.0.1', 162)),
+                ntforg.UdpTransportTarget(('127.0.0.2', 162)),
+                ntforg.UdpTransportTarget(('127.0.0.3', 162)) ):
+    ntfOrg.sendNotification(
+        ntforg.CommunityData('public'),
+        target,
+        'inform',
+        '1.3.6.1.6.3.1.1.5.2',
+        ( ntforg.MibVariable('SNMPv2-MIB', 'coldStart'), ),
+        (cbFun, None)
+    )
+
+ntforg.snmpEngine.transportDispatcher.runDispatcher()
 </PRE>
+</TABLE>
 </TD></TR></TABLE>
 
 <A NAME="SECURITY-CONFIGURATION"></A>