updates

1 files changed, 194 insertions, 16 deletions

diff --git a/docs/pysnmp-tutorial.html b/docs/pysnmp-tutorial.html
index 37a7f2d..3d19594 100644
--- a/docs/pysnmp-tutorial.html
+++ b/docs/pysnmp-tutorial.html
@@ -1018,8 +1018,8 @@ initial names (e.g. OBJECT IDENTIFIER's)
 </P>
 
 <P>
-The <A HREF="#MibVariable">MibVariable</A> object is used on input to
-allow symbolic MIB table columns specification.
+	The <A HREF="#MibVariable">MibVariable</A> object is used on input to
+	allow symbolic MIB table columns specification.
 </P>
 
 <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=90% ALIGN=CENTER><TR><TD>
@@ -1081,8 +1081,8 @@ for as long as possible within user applicatin.
 </DL>
 
 <P>
-The following method of <STRONG>NotificationOriginator</STRONG> class instance 
-implements specific notifications types.
+All notifications are sent by in invocation of the following method:
+</P>
 </P>
 
 <A NAME="NotificationOriginator.sendNotification"></A>
@@ -1116,9 +1116,54 @@ unconfirmed notification or <STRONG>"inform"</STRONG> for a confirmed one.
 <P>
 The <STRONG>notificationType</STRONG> parameter indicates the kind of
 event to notify Manager about in form of SMI NOTIFICATION-TYPE object
-name. For instance, (('SNMPv2-MIB', 'coldStart'),) or (1,3,6,1,6,3,1,1,5,1)
-is a value of coldStart notification type as defined in SNMPv2-MIB module.
-</P>
+name. Either 
+<A HREF="http://pyasn1.sourceforge.net/#1.1.8">ObjectIdentifier</A> class
+instance, its initialization value (like '1.3.6.1.6.3.1.1.5.1') or
+<A HREF="#MibVariable">MibVariable</A> object can be used on input to
+allow MIB symbols references.
+For example, '1.3.6.1.6.3.1.1.5.1' or MibVariable('SNMPv2-MIB', 'coldStart')
+specify <I>SNMPv2-MIB::coldStart</I> type of trap.
+</P>
+
+<P>
+When sending SNMP v1 traps, the <STRONG>notificationType</STRONG>
+parameter encodes both <I>Generic</I> and <I>Specific</I> trap numbers
+hardwired into SNMP v1 TRAP PDU, but missing in SNMP v2c TRAP and INFORM
+PDUs.
+</P>
+
+<TABLE BORDER=1 WIDTH=90% ALIGN=CENTER>
+<TR>
+<TD>
+<STRONG>notificationType</STRONG>
+</TD>
+<TD>
+<I>GenericTrap</I>
+</TD>
+<TD>
+<I>SpecificTrap</I>
+</TD>
+</TR>
+<TR>
+<TD>1.3.6.1.6.3.1.1.5.1<TD>coldStart(0)<TD>0</TD>
+<TR>
+<TD>1.3.6.1.6.3.1.1.5.2<TD>warmStart(1)<TD>0</TD>
+<TR>
+<TD>1.3.6.1.6.3.1.1.5.3<TD>linkDown(2)<TD>0</TD>
+<TR>
+<TD>1.3.6.1.6.3.1.1.5.4<TD>linkUp(3)<TD>0</TD>
+<TR>
+<TD>1.3.6.1.6.3.1.1.5.5<TD>authenticationFailure(4)<TD>0</TD>
+<TR>
+<TD>1.3.6.1.6.3.1.1.5.6<TD>egpNeighborLoss(5)<TD>0</TD>
+<TR>
+<TD>1.3.6.1.6.3.1.1.5.0.1<TD>enterpriseSpecific(6)<TD>1</TD>
+<TR>
+<TD>1.3.6.1.6.3.1.1.5.0.999<TD>enterpriseSpecific(6)<TD>999</TD>
+<TR>
+<TD>1.3.6.1.6.3.1.1.5.0.N<TD>enterpriseSpecific(6)<TD>N</TD>
+</TR>
+</TABLE>
 
 <P>
 The <STRONG>*varBinds</STRONG> input parameter is a tuple of Managed
@@ -1133,11 +1178,31 @@ The <STRONG>sendNotification</STRONG> method returns an
 in <A HREF="#CommandGenerator.getCmd">getCmd</A> method.
 </P>
 
+<P>
+When sending SNMP traps to a SNMPv1 system, PDU parameters
+that are present in SNMPv1 PDU but are missing in SNMPv2c PDU
+are mapped one to another via special Managed Objects Inctance
+values in <STRONG>*varBinds</STRONG>.
+</P>
+
+<UL>
+<LI>SNMP v1 PDU <I>enterprise</I> parameter is passed as a value of
+1.3.6.1.6.3.1.1.4.3.0 Managed Object Instance in <STRONG>*varBinds</STRONG>.
+If not specified, the default value is 1.3.6.1.6.3.1.1.5. If <I>Generic</I>
+encoded in <STRONG>notificationType</STRONG> is <I>enterpriseSpecific</I>,
+the <I>enterprise</I> parameter is implicitly initialized into
+<STRONG>notificationType</STRONG> value minus trailing sub-OID.
+<LI>SNMP v1 PDU <I>agent-addr</I> parameter is passed as a value of
+1.3.6.1.6.3.18.1.3.0 Managed Object Instance in <STRONG>*varBinds</STRONG>.
+<LI>SNMP v1 PDU <I>time-stamp</I> parameter is passed as a value of
+1.3.6.1.2.1.1.3.0 Managed Object Instance in <STRONG>*varBinds</STRONG>.
+</UL>
+
 </DD>
 </DL>
 
 <P>
-The following code sends SNMP TRAP message:
+The following code sends SNMP v2c TRAP message:
 <UL>
 <LI>using SNMP v2c
 <LI>with community name 'public'
@@ -1166,6 +1231,43 @@ if errorIndication:
 </PRE>
 </TD></TR></TABLE>
 
+<P>
+The following code sends SNMP v1 TRAP message:
+<UL>
+<LI>using SNMP v1
+<LI>with community name 'public'
+<LI>over IPv4/UDP
+<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>include managed object information '1.3.6.1.2.1.1.1.0' = 'my system'
+</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.CommunityData('public', mpModel=0),
+    ntforg.UdpTransportTarget(('localhost', 162)),
+    'trap',
+    '1.3.6.1.4.1.20408.4.1.1.2.0.432',
+    ('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', rfc1902.OctetString('my system'))
+)
+
+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
@@ -1191,6 +1293,16 @@ All Command Generator Applications are implemented within a single class:
 <P>
 Create an asynchronous SNMP Command Generator object.
 </P>
+
+<P>
+Although instantiation of this class is cheap, in the course of its further
+use, SNMP engine configuration is built and maintained though methods 
+invocation.
+Therefore it is advised to keep and reuse CommandGenerator instance 
+(or <STRONG>snmpEngine</STRONG> instance if passed as an initializer) 
+for as long as possible within user applicatin.
+</P>
+
 </DD>
 </DL>
 
@@ -1220,7 +1332,7 @@ Prepare SNMP GET request to be dispatched. Return the
 
 <P>
 The <STRONG>cbFun</STRONG> parameter is a reference to a callable object
-(such as Python function) that takes the following parameters:
+(such as a Python function) having the following signature:
 </P>
 
 <DL>
@@ -1254,13 +1366,10 @@ have the same meaning as in <A HREF="#CommandGenerator.getCmd">getCmd</A>
 method.
 </P>
 
-<P>
-If <STRONG>cbFun</STRONG> has no more requests pending and want to complete, 
-it must return a true value. Otherwise, it returns false.
-</P>
 </DD>
 </DL>
 
+
 <P>
 The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>,
 <STRONG>varNames</STRONG>, <STRONG>lookupNames</STRONG> and
@@ -1278,6 +1387,71 @@ matching subsequent response to this request.
 </DD>
 </DL>
 
+<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:
+<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
+</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, varBinds, cbCtx):
+    if errorIndication:
+        print(errorIndication)
+        return
+    if errorStatus:
+        print('%s at %s' % (errorStatus.prettyPrint(),
+                            errorIndex and varBinds[int(errorIndex)-1] or '?')
+        )
+        return
+    
+    for oid, val in varBinds:
+        if val is None:
+            print(oid.prettyPrint())
+        else:
+            print('%s = %s' % (oid.prettyPrint(), val.prettyPrint()))
+
+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)) ):
+    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.snmpEngine.transportDispatcher.runDispatcher()
+</PRE>
+</TABLE>
+
+<P>
+It is trivial to modify the above code to make it using different
+SNMP versions, credentials and query different Managed Objects Instances
+per each target.
+</P>
+
+<P>
+All queries are made in parallel, so with default timeout and retries
+settings, the above code will terminate in 6 seconds regardless of 
+Agents avialability and responsiveness.
+</P>
+
 <A NAME="AsynCommandGenerator.asyncSetCmd"></A>
 <DL>
 <DT><STRONG>asyncSetCmd</STRONG>(
@@ -1299,7 +1473,7 @@ 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
+<A HREF="#CommandGenerator.setCmd">setCmd</A> method except that
 <STRONG>varBinds</STRONG> is passed as a sequence, not as individual
 Managed Objects Instances.
 </P>
@@ -1343,6 +1517,10 @@ Managed Objects Instances names.
 The <STRONG>cbFun</STRONG> and <STRONG>cbCtx</STRONG> parameters
 have the same meaning as in <A HREF="#AsynCommandGenerator.asyncGetCmd">
 AsynCommandGenerator.asyncGetCmd</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
+False.
 </P>
 
 <P>
@@ -1384,8 +1562,8 @@ 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.
+have the same meaning as in <A HREF="#AsynCommandGenerator.asyncNextCmd">
+AsynCommandGenerator.asyncNextCmd</A> method.
 </P>
 
 </DD>