From 73be9eb5e4d92d0b92fd3cb015fc8a9318a84bb7 Mon Sep 17 00:00:00 2001 From: elie Date: Thu, 17 Sep 2015 23:16:45 +0000 Subject: asynchronous notification originator documented + fixes here and there --- .../agent/ntforg/async-notification-originator.rst | 9 ++ .../asyncore/oneliner/agent/ntforg/contents.rst | 15 ++- pysnmp/entity/rfc3413/oneliner/cmdgen.py | 9 +- pysnmp/entity/rfc3413/oneliner/ntforg.py | 118 ++++++++++++++++++++- pysnmp/entity/rfc3413/oneliner/sync/ntforg.py | 2 +- 5 files changed, 146 insertions(+), 7 deletions(-) create mode 100644 docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/async-notification-originator.rst diff --git a/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/async-notification-originator.rst b/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/async-notification-originator.rst new file mode 100644 index 0000000..51d20bf --- /dev/null +++ b/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/async-notification-originator.rst @@ -0,0 +1,9 @@ + +Asynchronous Notification Originator +==================================== + +.. toctree:: + :maxdepth: 2 + +.. autoclass:: pysnmp.entity.rfc3413.oneliner.ntforg.AsyncNotificationOriginator + :members: diff --git a/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/contents.rst b/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/contents.rst index 80966d7..cde3050 100644 --- a/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/contents.rst +++ b/docs/source/docs/v3arch/asyncore/oneliner/agent/ntforg/contents.rst @@ -3,10 +3,23 @@ Synchronous Notification Originator =================================== Functions dscribed in this section return generators that perform -blocking SNMP queries. See :RFC:`3413#section-3.2` for more information +blocking SNMP queries. See :RFC:`3413#section-3.3` for more information on the Notification Originator Applications. .. toctree:: :maxdepth: 2 /docs/v3arch/asyncore/oneliner/agent/ntforg/notification + +Asynchronous Notification Originator +==================================== + +Implementation described in this section geared towards sending +multiple simulataneous SNMP notifications on top of asynchronous +I/O framework. Otherwise it is very similar to the Synchronous +version. + +.. toctree:: + :maxdepth: 2 + + /docs/v3arch/asyncore/oneliner/agent/ntforg/async-notification-originator diff --git a/pysnmp/entity/rfc3413/oneliner/cmdgen.py b/pysnmp/entity/rfc3413/oneliner/cmdgen.py index 31a4e45..b950e97 100644 --- a/pysnmp/entity/rfc3413/oneliner/cmdgen.py +++ b/pysnmp/entity/rfc3413/oneliner/cmdgen.py @@ -28,10 +28,11 @@ class AsyncCommandGenerator: Datastore (:RFC:`2271#section-3.4.2`) management. Typically, users instantiate `AsyncCommandGenerator` and call its commmand-specific methods passing them canned Security, - Transport and SNMP Context parameters along with MIB variables - to deal with. `AsyncCommandGenerator` will manage LCD by - applying user-supplied configuratoin parameters and running - requested operation. + Transport and SNMP Context parameters along with + :py:class:`~pysnmp.smi.rfc1902.ObjectType` object carrying + MIB variables to include with SNMP request. `AsyncCommandGenerator` + will manage LCD by applying user-supplied configuratoin parameters + and running requested operation. See :RFC:`3413#section-3.1` for more information on SNMP Command Generator purpose, design and supported operations. diff --git a/pysnmp/entity/rfc3413/oneliner/ntforg.py b/pysnmp/entity/rfc3413/oneliner/ntforg.py index 96a8456..992777c 100644 --- a/pysnmp/entity/rfc3413/oneliner/ntforg.py +++ b/pysnmp/entity/rfc3413/oneliner/ntforg.py @@ -15,6 +15,24 @@ SnmpEngine = engine.SnmpEngine nextID = nextid.Integer(0xffffffff) class AsyncNotificationOriginator: + """Creates asyncore-based SNMP Notification Originator object. + + This is a high-level wrapper around pure Notification Originator + impementation that aims at simplyfing + :py:class:`pysnmp.entity.engine.SnmpEngine`'s Local Configuration + Datastore (:RFC:`2271#section-3.4.2`) management. Typically, + users instantiate `AsyncNotificationOriginator` and call its + commmand-specific methods passing them canned Security, + Transport and SNMP Context parameters along with + :py:class:`~pysnmp.smi.rfc1902.NotificationType` object carrying + MIB variables to include with Notification. `AsyncNotificationOriginator` + will manage LCD by applying user-supplied configuratoin parameters + and running requested operation. + + See :RFC:`3413#section-3.2` for more information on SNMP + Notification Originator purpose, design and supported operations. + + """ def __init__(self): self.__asyncCmdGen = cmdgen.AsyncCommandGenerator() @@ -133,7 +151,105 @@ class AsyncNotificationOriginator: varBinds, cbInfo=(None, None), lookupMib=False): - + """Send SNMP notification. + + Based on passed parameters, prepares SNMP TRAP or INFORM + notification (:RFC:`1905#section-4.2.6`) and schedules its + transmission by I/O framework at a later point of time. + + Parameters + ---------- + snmpEngine : :py:class:`~pysnmp.entity.engine.SnmpEngine` + Class instance representing SNMP engine. + + authData : :py:class:`~pysnmp.entity.rfc3413.oneliner.auth.CommunityData` or :py:class:`~pysnmp.entity.rfc3413.oneliner.auth.UsmUserData` + Class instance representing SNMP credentials. + + transportTarget : :py:class:`~pysnmp.entity.rfc3413.oneliner.target.UdpTransportTarget` or :py:class:`~pysnmp.entity.rfc3413.oneliner.target.Udp6TransportTarget` + Class instance representing transport type along with SNMP peer + address. + + contextData : :py:class:`~pysnmp.entity.rfc3413.oneliner.ctx.ContextData` + Class instance representing SNMP ContextEngineId and ContextName + values. + + notifyType : str + Indicates type of notification to be sent. Recognized literal + values are *trap* or *inform*. + + varBinds: tuple + Single :py:class:`~pysnmp.smi.rfc1902.NotificationType` class + instance representing a minimum sequence of MIB variables + required for particular notification type. Alternatively, + a sequence of :py:class:`~pysnmp.smi.rfc1902.ObjectType` + objects could be passed instead. In the latter case it is up to + the user to ensure proper Notification PDU contents. + + cbInfo : tuple + + * `cbFun` - user-supplied callable that is invoked to pass + SNMP response to *INFORM* notification or error to user at + a later point of time. The `cbFun` callable is never invoked + for *TRAP* notifications. + * `cbCtx` - user-supplied object passing additional parameters + to/from `cbFun`. Default is `None`. + + Other Parameters + ---------------- + lookupMib : bool + `lookupMib` - load MIB and resolve response MIB variables at + the cost of slightly reduced performance. Default is `True`. + + Notes + ----- + User-supplied `cbFun` callable must have the following call + signature: + + * snmpEngine (:py:class:`~pysnmp.entity.engine.SnmpEngine`): + Class instance representing SNMP engine. + * sendRequestHandle (int): Unique request identifier. Can be used + for matching multiple ongoing *INFORM* notifications with received + responses. + * errorIndication (str): True value indicates SNMP engine error. + * errorStatus (str): True value indicates SNMP PDU error. + * errorIndex (int): Non-zero value refers to `varBinds[errorIndex-1]` + * varBinds (tuple): A sequence of + :py:class:`~pysnmp.smi.rfc1902.ObjectType` class instances + representing MIB variables returned in SNMP response in exactly + the same order as `varBinds` in request. + * `cbCtx` : Original user-supplied object. + + Returns + ------- + sendRequestHandle : int + Unique request identifier. Can be used for matching received + responses with ongoing *INFORM* requests. Returns `None` for + *TRAP* notifications. + + Raises + ------ + PySnmpError + Or its derivative indicating that an error occurred while + performing SNMP operation. + + Examples + -------- + >>> from pysnmp.entity.rfc3413.oneliner.ntforg import * + >>> + >>> snmpEngine = SnmpEngine() + >>> n = AsyncNotificationOriginator() + >>> n.sendNotification( + ... snmpEngine, + ... CommunityData('public'), + ... UdpTransportTarget(('demo.snmplabs.com', 162)), + ... ContextData(), + ... 'trap', + ... NotificationType(ObjectIdentity('SNMPv2-MIB', 'coldStart')), + ... ) + >>> snmpEngine.transportDispatcher.runDispatcher() + >>> + + """ def __cbFun(snmpEngine, sendRequestHandle, errorIndication, errorStatus, errorIndex, varBinds, cbCtx): lookupMib, cbFun, cbCtx = cbCtx diff --git a/pysnmp/entity/rfc3413/oneliner/sync/ntforg.py b/pysnmp/entity/rfc3413/oneliner/sync/ntforg.py index 93e047e..03fab16 100644 --- a/pysnmp/entity/rfc3413/oneliner/sync/ntforg.py +++ b/pysnmp/entity/rfc3413/oneliner/sync/ntforg.py @@ -9,7 +9,7 @@ def sendNotification(snmpEngine, authData, transportTarget, contextData, """Creates a generator to send one or more SNMP notifications. On each iteration, new SNMP TRAP or INFORM notification is send - (:RFC:`3413#section-3.3`). The iterator blocks waiting for + (:RFC:`1905#section-4,2,6`). The iterator blocks waiting for INFORM acknowlegement to arrive or error to occur. Parameters -- cgit v1.2.1