updates

1 files changed, 282 insertions, 82 deletions

diff --git a/docs/pysnmp-tutorial.html b/docs/pysnmp-tutorial.html
index 36fb2d3..5ecfa31 100644
--- a/docs/pysnmp-tutorial.html
+++ b/docs/pysnmp-tutorial.html
@@ -640,45 +640,62 @@ Those found in response are bound by position to Managed Object names passed in
 </P>
 
 <P>
-If <STRONG>lookupNames</STRONG> parameter evaluates to True, PySNMP will attempt to gather more
-information on <A HREF="#MANAGED-OBJECT-NAME-VALUE">Managed Objects</A> returned in
-<STRONG>varBinds</STRONG> by searching for relevant MIB module and looking up there. Instance of
-<A HREF="#MIB-VARIABLE">MibVariable</A> class will be returned as Managed Object names.
+If <STRONG>lookupNames</STRONG> parameter evaluates to True, PySNMP will
+attempt to gather more information on
+<A HREF="#MANAGED-OBJECT-NAME-VALUE">Managed Objects</A> returned in
+<STRONG>varBinds</STRONG> by searching for relevant MIB module and looking
+up there. Instance of
+<A HREF="#MibVariable">MibVariable</A> class will be returned as Managed
+Object names.
 </P>
 
 <P>
-If <STRONG>lookupValues</STRONG> parameter evaluates to True, Managed Objects Instances values
-returned in <STRONG>varBinds</STRONG> may be converted into a more precise type (employing
+If <STRONG>lookupValues</STRONG> parameter evaluates to True, Managed Objects
+Instances values
+returned in <STRONG>varBinds</STRONG> may be converted into a more precise
+type (employing
 <A HREF="#TEXTUAL-CONVENTION-AS-A-TYPE">TEXTUAL-CONVENTION</A> data
-from MIB) if PySNMP has relevant MIB loaded. Otherwise response values will belong to
-protocol-level <A HREF="#MANAGED-OBJECT-NAME-VALUE">Managed Object Instance value types</A>.
+from MIB) if PySNMP has relevant MIB loaded. Otherwise response values will
+belong to protocol-level
+<A HREF="#MANAGED-OBJECT-NAME-VALUE">Managed Object Instance value types</A>.
 </P>
 
 </DD>
 </DL>
 
 <P>
-The following code performs SNMP GET operation over SNMPv2c:
+The following code performs SNMP GET operation using SNMP v2c with
+community name 'public' over IPv4/UDP against SNMP Agent at
+localhost (UDP port 161) requesting current values for two Managed Objects
+specified in string form.
 </P>
 
 <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=100%><TR><TD>
 <PRE>
->>> from pysnmp.entity.rfc3413.oneliner import cmdgen           
->>> cmdGen = cmdgen.CommandGenerator()
->>> errorIndication, errorStatus, errorIndex, varBinds = cmdGen.getCmd(
-... cmdgen.CommunityData('public'),
-... cmdgen.UdpTransportTarget(('localhost', 161)),
-... '1.3.6.1.2.1.1.1.0',
-... '1.3.6.1.2.1.1.2.0'
-... )
->>> print(errorIndication)
-None
->>> print(errorStatus)
-0
->>> print(varBinds)
-[(ObjectName(1.3.6.1.2.1.1.1.0), OctetString('Linux saturn 2.6.37.6-smp 
-    #2 SMP Sat Apr 9 23:39:07 CDT 2011 i686')), 
-(ObjectName(1.3.6.1.2.1.1.2.0), ObjectIdentifier(1.3.6.1.4.1.8072.3.2.10))]
+from pysnmp.entity.rfc3413.oneliner import cmdgen
+
+cmdGen = cmdgen.CommandGenerator()
+
+errorIndication, errorStatus, errorIndex, varBinds = cmdGen.getCmd(
+    cmdgen.CommunityData('public'),
+    cmdgen.UdpTransportTarget(('localhost', 161)),
+    '1.3.6.1.2.1.1.1.0',
+    '1.3.6.1.2.1.1.6.0'
+)
+
+# Check for errors and print out results
+if errorIndication:
+    print(errorIndication)
+else:
+    if errorStatus:
+        print('%s at %s' % (
+            errorStatus.prettyPrint(),
+            errorIndex and varBinds[int(errorIndex)-1] or '?'
+            )
+        )
+    else:
+        for name, val in varBinds:
+            print('%s = %s' % (name.prettyPrint(), val.prettyPrint()))
 </PRE>
 </TD></TR></TABLE>
 
@@ -722,24 +739,47 @@ having the same meaning as in <A HREF="#CommandGenerator.getCmd">getCmd</A> meth
 </DL>
 
 <P>
-The following code performs SNMP SET operation over SNMPv1:
+The following code performs SNMP SET operation
+<UL>
+<LI>using SNMP v3
+<LI>with username 'usr-md5-des', MD5 authentication and DES privacy protocols
+<LI>over IPv4/UDP
+<LI>against an Agent listening at localhost (UDP port 161)
+<LI>setting SNMPv2-MIB::sysName.0 object to a new value
+</UL>
+</P>
+<P>
+The <A HREF="#MibVariable">MibVariable</A> object is used on input to
+allow symbolic Managed Object Instance name specification. Response values
+are requested to be returned also in form of a MibVariable object.
 </P>
 
 <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=100%><TR><TD>
 <PRE>
->>> from pysnmp.entity.rfc3413.oneliner import cmdgen
->>> from pysnmp.proto import rfc1902
->>> errorIndication, errorStatus, errorIndex, varBinds = cmdgen.CommandGenerator().setCmd(
-... cmdgen.CommunityData('public', mpModel=0),
-... cmdgen.UdpTransportTarget(('localhost', 161)),
-... ('1.3.6.1.2.1.1.1.0', rfc1902.OctetString('my system description'))
-... )
->>> print(errorIndication)
-None
->>> print(errorStatus)
-17
->>> print(errorStatus.prettyPrint())
-notWritable(17)
+from pysnmp.entity.rfc3413.oneliner import cmdgen
+
+cmdGen = cmdgen.CommandGenerator()
+
+errorIndication, errorStatus, errorIndex, varBinds = cmdGen.setCmd(
+    cmdgen.UsmUserData('usr-md5-des', 'authkey1', 'privkey1'),
+    cmdgen.UdpTransportTarget(('localhost', 161)),
+    (cmdgen.MibVariable('SNMPv2-MIB', 'sysName', 0), 'my new value'),
+    lookupNames=True, lookupValues=True
+)
+
+# Check for errors and print out results
+if errorIndication:
+    print(errorIndication)
+else:
+    if errorStatus:
+        print('%s at %s' % (
+            errorStatus.prettyPrint(),
+            errorIndex and varBinds[int(errorIndex)-1] or '?'
+            )
+        )
+    else:
+        for name, val in varBinds:
+            print('%s = %s' % (name.prettyPrint(), val.prettyPrint()))
 </PRE>
 </TD></TR></TABLE>
 
@@ -1590,9 +1630,8 @@ Optional <STRONG>mpModel</STRONG> parameter indicates whether SNMPv2c
 </H4>
 <P>
 Transport configuration object is Transport domain specific.
-<STRONG>UdpTransportTarget</STRONG> class represents a pair of
-network endpoints (remote and optionally local addresses) of a
-UDP-over-IPv4 transport.
+<STRONG>UdpTransportTarget</STRONG> class represents a remote
+network endpoint of a UDP-over-IPv4 transport.
 </P>
 
 <A NAME="UdpTransportTarget"></A>
@@ -1609,17 +1648,42 @@ SNMP entities through a UDP/IPv4 socket.
 </P>
 <P>
 Mandatory <STRONG>transportAddr</STRONG> parameter indicates remote address
-in form of tuple of <STRONG>FQDN</STRONG>, <STRONG>port</STRONG>
-where <STRONG>FQDN</STRONG> is a string and <STRONG>port</STRONG> is an 
+in form of a tuple of <STRONG>FQDN</STRONG>, <STRONG>port</STRONG>
+where <STRONG>FQDN</STRONG> is a string representing either hostname
+or IPv4 address in quad-dotted form, <STRONG>port</STRONG> is an 
+integer.
+</P>
+<P>
+Optional <STRONG>timeout</STRONG> and <STRONG>retries</STRONG> parameters
+may be used to modify default response timeout (1 second) and number 
+of succesive request retries (5 times).
+</P>
+</DD>
+</DL>
+
+<A NAME="Udp6TransportTarget"></A>
+<DL>
+<DT>class <STRONG>Udp6TransportTarget</STRONG>(
+<STRONG>transportAddr</STRONG>,
+<STRONG>timeout=1</STRONG>,
+<STRONG>retries=5</STRONG>
+)</DT>
+<DD>
+<P>
+Create an object representing a network path connecting two
+SNMP entities through a UDP/IPv6 socket.
+</P>
+<P>
+Mandatory <STRONG>transportAddr</STRONG> parameter indicates remote address
+in form of a tuple of <STRONG>FQDN</STRONG>, <STRONG>port</STRONG>
+where <STRONG>FQDN</STRONG> is a string representing either hostname
+or IPv6 address in semicolon-separated form, <STRONG>port</STRONG> is an 
 integer.
 </P>
 <P>
 Optional <STRONG>timeout</STRONG> and <STRONG>retries</STRONG> parameters
 may be used to modify default response timeout (1 second) and number 
-of succesive request retries (5 times). Optional <STRONG>localAddr</STRONG>
-parameter may be used for sending queries from specific local interface.
-The syntax of <STRONG>localAddr</STRONG> is the same as the syntax of
-<STRONG>transportAddr</STRONG>.
+of succesive request retries (5 times).
 </P>
 </DD>
 </DL>
@@ -1630,45 +1694,185 @@ The syntax of <STRONG>localAddr</STRONG> is the same as the syntax of
 </H4>
 
 <A NAME="OIDVAL-IMPL">
+On the protocol level, a Managed Object Instance is represented by a pair
+of Name and Value items collectively called a <STRONG>Variable-Binding</STRONG>.
+In PySNMP one-liner API, a Managed Object Instance is represented by a
+two-component sequence of two objects -- one represents Managed Object Name
+or Managed Object Instance Name, and the other - Managed Object Instance
+Value. The types of these objects may vary, details follow.
+</P>
+
+<A NAME="OID-IMPL"></A>
+<H4>
+2.2.1 Managed Objects Names
+</H4>
 <P>
-At the protocol level, each <A HREF="#MANAGED-OBJECTS">Managed Object</A>
-instance is represented by a pair of Name and Value collectively called
-a <STRONG>Variable-Binding</STRONG>.
+Managed Object or Managed Object Instance Name is an instance of
+<STRONG>ObjectName</STRONG> class which is derived from PyASN1
+<A HREF="http://pyasn1.sourceforge.net/#1.1.8">ObjectIdentifier</A>.
+In most cases, PySNMP one-liner API will automatically create an instance of
+<STRONG>ObjectName</STRONG> class from its initialization value which
+can be:
 </P>
 
+<ul>
+<li>a plain string of dot-separated numbers, e.g. '1.3.6.1.2.1.1.1.0'
+<li>a tuple of integers e.g., (1, 3, 6, 1, 2, 1, 1, 1, 0)
+<li>an instance of <A HREF="http://pyasn1.sourceforge.net/#1.1.8">ObjectIdentifier</A> class or its derivative such as <STRONG>ObjectName</STRONG>
+</ul>
+
+
+<A NAME="MibVariable"></A>
 <P>
-In PySNMP programming context, at the high-level API, each Managed Object is
-represented by a tuple of two class instances -- one represents Managed 
-Object Instance Name, and another -- its value.
+In order to make use of additional information related to Managed Objects,
+such as their human-friendly representation, associated value type, description
+of intended use and other details contained in MIBs, the 
+<STRONG>MibVariable</STRONG> class instances may be used interchangeably 
+instead of <STRONG>ObjectName</STRONG> objects.
 </P>
 
-<A NAME="OID-IMPL">
+<DL>
+<DT>class <STRONG>MibVariable</STRONG>(
+<STRONG>varName</STRONG>
+)</DT>
+<DD>
+
 <P>
-Managed Object Name is an instance of <STRONG>ObjectName</STRONG> class,
-which is derived from PyASN1
-<A HREF="http://pyasn1.sourceforge.net/#1.1.8">ObjectIdentifier</A>.
-In most cases, PySNMP APIs will automatically create an instance of
-ObjectIdentifier class from its initialization value. Therefore it's
-allowed to use a plain string of dot-separated numbers or a tuple of
-integers as a Managed Object Name.
+Create an object representing a varying amount of Managed Object Name
+information. As a bare minimum <STRONG>MibVariable</STRONG> object
+will only hold an OBJECT IDENTIFIER that identifies particular
+Managed Object. However more information on Managed Object may be 
+gathered by PySNMP during the course of SNMP request processing.
+All the extra information comes through a lookup at a MIB where particular
+Managed Object is specified.
 </P>
 
-<A NAME="MIB-VARIABLE">
 <P>
-In order to make use of additional information related to Managed Objects,
-such as their human-friendly representation, associated value type, description
-and other details contained in MIBs, the <A HREF="#MIB-VARIABLE-IMPL">MibVariable</A>
-class instances may be used interchangeably instead of <STRONG>ObjectName</STRONG>
-objects.
+The mandatory <STRONG>varName</STRONG> argument must hold a valid
+initializer for
+<A HREF="http://pyasn1.sourceforge.net/#1.1.8">ObjectIdentifier</A>
+kind of objects. 
 </P>
 
-<A NAME="VAL-IMPL">
+</DD>
+
+<P>or</P>
+
+<DT>class <STRONG>MibVariable</STRONG>(
+<STRONG>mibName</STRONG>,
+<STRONG>symName</STRONG>,
+*<STRONG>indices</STRONG>
+)</DT>
+<DD>
+
+<P>
+Create an object potentially representing all MIB information
+on particular Managed Object. By the moment of instantiation
+no additional information is acquired, but during the later stages
+of SNMP request processing, PySNMP will attempt to lookup additional
+information at the MIB named <STRONG>mibName</STRONG> for the object
+registered there under name <STRONG>symName</STRONG>.
+</P>
+
+<P>
+If requested MIB or symbol can not be found, the <STRONG>PySnmpError</STRONG>
+exception will be thrown.
+</P>
+
+<P>
+The mandatory <STRONG>mibName</STRONG> and <STRONG>symName</STRONG>
+arguments refer to the names under which particular Managed Object
+is specified in the MIB (e.g. 'IF-MIB' and 'ifTable' respectively).
+Both parameters are Python strings.
+</P>
+
+<P>
+The optional <STRONG>indices</STRONG> sequence semantics depend on the
+type of MIB Object refered by <STRONG>mibName</STRONG> and 
+<STRONG>symName</STRONG> parameters.
+</P>
+
+<UL>
+<LI>For <STRONG>MibTableColumn</STRONG> objects <STRONG>indices</STRONG>
+are a sequence of Conceptual Table Instance ID in a human-friendly
+form (e.g. "127.0.0.1"-indexed element of a IP-MIB::ipAdEntAddr column)
+<LI>For <STRONG>MibScalar</STRONG> objects <STRONG>indices</STRONG>
+are interpreted as an sub-OBJECT IDENTIFIER
+</UL>
+
+</DD>
+
+<P>
+Methods of the <STRONG>MibVariable</STRONG> objects are as follows:
+</P>
+
+<A NAME="MibVariable.getMibSymbol"></A>
+<DL>
+<DT><STRONG>getMibSymbol</STRONG>(
+)</DT>
+
+<DD>
+<P>
+Return a sequence of <STRONG>mibName</STRONG>, <STRONG>symName</STRONG>
+and <STRONG>indices</STRONG> identifying arbitrary Managed Object.
+</P>
+</DD>
+
+<A NAME="MibVariable.getOid"></A>
+<DT><STRONG>getOid</STRONG>(
+)</DT>
+
+<DD>
+<P>
+Return Managed Object Name in form of <A HREF="http://pyasn1.sourceforge.net/#1.1.8">ObjectIdentifier</A> object.
+</P>
+</DD>
+
+<A NAME="MibVariable.getMibNode"></A>
+<DT><STRONG>getMibNode</STRONG>(
+)</DT>
+
+<DD>
+<P>
+Return MIB information in form of a
+<A HREF="#DATA-MODEL-MANAGED-OBJECTS">Managed Object</A>
+identified by this particular name.
+</P>
+</DD>
+
+<A NAME="MibVariable.isFullyResolved"></A>
+<DT><STRONG>isFullyResolved</STRONG>(
+)</DT>
+
+<DD>
+<P>
+Return <STRONG>True</STRONG> if MIB lookup for initial initializers was
+successful and complete MIB information is available.
+</P>
+</DD>
+
+</DL>
+
+<A NAME="VAL-IMPL"></A>
+<H4>
+2.2.2 Managed Objects Values
+</H4>
 <P>
 Managed Object Instance Value is an instance of some
 <A HREF="http://pyasn1.sf.net">PyASN1</A> class or its
 SNMP-specific derivative. The latter case reflects SNMP-specific
-<A HREF="#ASN1">ASN.1</A> sub-type. The list of Managed Object 
-Instance Value classes follow.
+<A HREF="#ASN1">ASN.1</A> sub-type.
+</P>
+
+<P>
+PySNMP implementation of SNMPv3 architecture always exposes, <A HREF="#SMI">SMIv2</A> definitions for
+Managed Objects are always used regardless of the underlying SNMP protocol
+version being talked with a peer. For instance, an SNMPv3 Manager will always 
+report SMIv2 types even when working to SNMPv1 Agent (which is SMIv1-compliant).
+</P>
+
+<P>
+The list of Managed Object Instance Value classes follows.
 </P>
 
 <A NAME="INTEGER-IMPL"></A>
@@ -1849,19 +2053,15 @@ PyASN1 <A HREF="http://pyasn1.sourceforge.net/#1.1.7">OctetString</A>.
 All the above types are directly used by SNMP protocol and can be exchanged
 between user application and PySNMP in the course of SNMP engine operations
 through PySNMP APIs. However, by SNMP design, some additional information
-on specific Managed Objects Instances value ranges and human-friendly representation
-can be carried by MIBs in form of <STRONG>TEXTUAL-CONVENTION</STRONG> SMI constructs.
-PySNMP implements this feature in form of <STRONG>TextualConvention</STRONG> class
-which is actually a derivative of one of the above Managed Objects Instance Value
-classes so objects of these classes can be used interchangeably in all PySNMP APIs.
+on specific Managed Objects Instances value ranges and human-friendly 
+representation can be carried by MIBs in form of 
+<STRONG>TEXTUAL-CONVENTION</STRONG> SMI constructs. PySNMP implements this
+feature in form of <STRONG>TextualConvention</STRONG> class which is
+actually a derivative of one of the above Managed Objects Instance Value
+classes so objects of these classes can be used interchangeably in all 
+PySNMP APIs.
 </P>
 
-<P>
-With PySNMP's SNMPv3 architecture, <A HREF="#SMI">SMIv2</A> definitions for Managed
-Objects are always used regardless of the underlying SNMP protocol version being talked
-with a peer. For instance, an SNMPv3 Manager will always report SMIv2 types even when 
-working to SNMPv1 Agent (which is SMIv1-compliant).
-</P>
 
 <P>
 For more information on SNMP Managed Value objects properties,