PySNMP: I/O engine: asyncore binding

### PySNMP binding to asyncore module

The pysnmp.mapping.udp.asynrole module implements the Manager and Agent classes, representing SNMP manager and agent roles in a SNMP entity. These classes implement network client (manager) and server (agent) built on top of Sam Rushing's asyncore framework, which is a part of Python distribution these days.

The most important feature of an asynchronous I/O engine is that it can exchange data over many BSD sockets (not necessarily SNMP parties) without blocking on a temporarily delayed I/O operation.

The asynrole code is a pure network transport facility -- it deals with abstract data chunks and has nothing to know about SNMP context. In order to build a complete SNMP entity, SNMP protocol processing code should be added. See (SNMP protocol modules for that.

The pysnmp.asynrole module defines the following classes which derive from asyncore.dispatcher base:

class Manager((cbFun, cbCtx)[, dstAddr[, iface]])

  Returns a new instance of the Manager class, representing asynchronous I/O client (optionally connected to a network server running at dstAddr address) to be used to talk to one or more servers over its own, single BSD socket.

  The cbFun and cbCtx parameters are described at the Manager.send method section. Do not pass your cbFun and cbCtx from here, better set it to (None, None). This interface exists for compatibility reasons.

  The dstAddr argument, whenever given, must follow the socket module notation -- ('hostname', port) where hostname a string and port is an integer.

  The default for dstAddr is (None, None) what means no default destination, so user would unconditionally have to specify destination to each Manager.send() method (see below).

  Once a default dstAddr is specified, specific destination may not be given to the Manager.send() method.

  The iface parameter, if given, specifies the interface and port on local machine to bind() to. This argument must also follow the socket module notation. All further messages would then be originated from the given interface/port.

  The default for iface is ('0.0.0.0', 0) stands for binding to a primary interface at the local machine.

class Agent((cbFun, cbCtx)[,ifaces]])

  Returns a new instance of the Agent class, representing asynchronous I/O server optionally bound to specific network interfaces/ports ifaces at the local machine. One instance of the Agent class would talk to many clients over a single BSD socket.

  The cbFun argument must be a reference to a callback function to be invoked by asyncore on data arrival. This function must support the following API:

  cbFun(cbCtx, (srcAddr, reqMsg), (excType, excValue, excTraceback))

  where:

  - cbCtx is a reference to the same Python object as passed by user on asynrole.Agent class instaniation
  - (srcAddr, reqMsg) is a request tuple holding source address (in socket module notation) and request data reqMsg (string) respectively
  - (excType, excValue, excTraceback) parameters represent exception details, whenever happened, as provided by the sys module.

  The cbFun() function will be invoked by asyncore on data arrival as well as on error.

  The ifaces argument, whenever given, must be a list of ('ifacename', port) tuples (socket module notation).

  The default for the ifaces is to listen on the loopback interface, port 161/UDP, so the default value is [('127.0.0.1', 161)].

exception Error

  Exception raised on any error in the pysnmp.asynrole module, as well as in its base (pysnmp.role) and derivative modules. This exception class is a subclass of the pysnmp.role class.

Subsections

- Objects of the asynrole.Manager class
- Objects of the asynrole.Agent class