1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
<HTML>
<HEAD>
<TITLE>PySNMP: I/O engine: Asynchronous</TITLE>
</HEAD>
<BODY BGCOLOR="#ffffff" TEXT="#000000"
LINK="#0000bb" VLINK="#551a8b" ALINK="#ff0000">
<H3>
Asynchronous I/O engine
</H3>
<P>
The <STRONG>pysnmp.asynrole</STRONG> module defines the <STRONG>manager</STRONG>
and <STRONG>agent</STRONG> classes, representing SNMP manager and agent roles
in a SNMP system. These classes implement network client (manager) and server
(agent) built on top of Sam Rushing's
<A HREF="http://www.nightmare.com/medusa/index.html">asyncore</A> framework.
</P>
<P>
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 suspended I/O operation.
</P>
<P>
The <STRONG>pysnmp.asynrole</STRONG> code is a pure network transport
facility -- it deals with abstract data items and has nothing to know about
SNMP context. In order to build a complete SNMP entity, a SNMP message
processing code should be used along. See SNMP protocol modules
(<A HREF="v2c.html">v2c</A>, <A HREF="v1.html">v1</A>) for that.
</P>
<P>
The <STRONG>pysnmp.asynrole</STRONG> module defines the only class:
</P>
<DL>
<DT>class <STRONG>manager</STRONG>(<STRONG>cb_fun</STRONG>[, <STRONG>cb_ctx</STRONG>[, <STRONG>dst</STRONG>[, <STRONG>iface</STRONG>]]])</DT>
<DD>
<P>
Returns a new instance of the <STRONG>manager</STRONG> class, representing
asynchronous I/O client (optionally connected to a network server running at
<STRONG>dst</STRONG> address) to be used to talk to one or more servers over its
own, single BSD socket.
</P>
<P>
The <STRONG>dst</STRONG> argument, whenever given, must follow the
<STRONG>socket</STRONG> module notation -- ('<STRONG>hostname</STRONG>',
<STRONG>port</STRONG>) where hostname a string and port is an integer.
</P>
<P>
The default for <STRONG>dst</STRONG> is None what means no default destination,
so user would unconditionally have to specify destination to each
<STRONG>manager.send()</STRONG> method (see below).
</P>
<P>
Once a default <STRONG>dst</STRONG> is specified, specific destination
may not be given to the <STRONG>manager.send()</STRONG> method.
</P>
<P>
The <STRONG>iface</STRONG> parameter, if given, specifies the interface and
port on local machine to <STRONG>bind()</STRONG> to. This argument must also
follow the <STRONG>socket</STRONG> module notation. All further requests would
then be originated from the given interface/port.
</P>
<P>
The default for <STRONG>iface</STRONG> is ('0.0.0.0', 0)) stands for binding
to a primary interface at the local machine.
</P>
<P>
The <STRONG>cb_fun</STRONG> argument must be a reference to a callback
function to be invoked by <STRONG>asyncore</STRONG> on data arrival. This
function will be passed the following parameters:
</P>
<P>
<STRONG>cb_fun</STRONG>(<STRONG>cb_ctx</STRONG>, (<STRONG>src</STRONG>,
<STRONG>rsp</STRONG>), (<STRONG>exc_type</STRONG>, <STRONG>exc_value</STRONG>,
<STRONG>exc_traceback</STRONG>))
</P>
<P>
where:
</P>
<UL>
<LI><STRONG>cb_ctx</STRONG> is a reference to the same Python object as passed
by user on <STRONG>asynrole.manager</STRONG> class instaniation
<LI>(<STRONG>src</STRONG>, <STRONG>rsp</STRONG>) is a request tuple holding
source address (in <STRONG>socket</STRONG> module notation) and response data
<STRONG>rsp</STRONG> (string) respectively
<LI>(<STRONG>exc_type</STRONG>, <STRONG>exc_value</STRONG>,
<STRONG>exc_traceback</STRONG>) parameters represent exception details,
whenever happened, as provided by the <STRONG>sys</STRONG> module.
</UL>
<P>
The <STRONG>cb_fun</STRONG>() function will always be invoked by asyncore
following each <STRONG>manager.send</STRONG>() call to either return
server reply on successful data exchange, or exception details on error.
</P>
</DD>
</DL>
<DL>
<DT>class <STRONG>agent</STRONG>(<STRONG>cb_fun</STRONG>[, <STRONG>cb_ctx</STRONG>[,
<STRONG>ifaces</STRONG>]])</DT>
<DD>
<P>
Returns a new instance of the <STRONG>agent</STRONG> class, representing
asynchronous I/O server optionally bound to specific network interfaces/ports
<STRONG>ifaces</STRONG> at the local machine. One instance of the
<STRONG>agent</STRONG> class would talk to many clients over a single BSD socket.
</P>
<P>
The <STRONG>ifaces</STRONG> argument, whenever given, must be a list of
('<STRONG>ifacename</STRONG>', <STRONG>port</STRONG>) tuples
(<STRONG>socket</STRONG> module notation).
</P>
<P>
The default for the <STRONG>ifaces</STRONG> is to listen on the loopback
interface, port 161/UDP, so the default value is [('127.0.0.1', 161)].
</P>
<P>
The <STRONG>cb_fun</STRONG> argument must be a reference to a callback
function to be invoked by <STRONG>asyncore</STRONG> on data arrival. This
function will be passed the following parameters:
</P>
<P>
<STRONG>cb_fun</STRONG>(<STRONG>cb_ctx</STRONG>, (<STRONG>src</STRONG>,
<STRONG>req</STRONG>), (<STRONG>exc_type</STRONG>, <STRONG>exc_value</STRONG>,
<STRONG>exc_traceback</STRONG>))
</P>
<P>
where:
</P>
<UL>
<LI><STRONG>cb_ctx</STRONG> is a reference to the same Python object as passed
by user on <STRONG>asynrole.agent</STRONG> class instaniation
<LI>(<STRONG>src</STRONG>, <STRONG>req</STRONG>) is a request tuple holding
source address (in <STRONG>socket</STRONG> module notation) and request data
<STRONG>req</STRONG> (string) respectively
<LI>(<STRONG>exc_type</STRONG>, <STRONG>exc_value</STRONG>,
<STRONG>exc_traceback</STRONG>) parameters represent exception details,
whenever happened, as provided by the <STRONG>sys</STRONG> module.
</UL>
<P>
The <STRONG>cb_fun</STRONG>() function will be invoked by asyncore
on each data arrival as well as on error.
</P>
</DD>
</DL>
<DL>
<DT>exception <STRONG>Error</STRONG></DT>
<DD>
<P>
Exception raised on any error in the <STRONG>pysnmp.asynrole</STRONG> module,
as well as in its base (<STRONG>pysnmp.role</STRONG>) and derivative modules.
This exception class is a subclass of the <STRONG>pysnmp.role</STRONG> class.
</P>
<P>
See documentation on the <A HREF="error.html">error.General</A> base class for
usage details.
</P>
</DD>
</DL>
<P>
The following exceptions are derived from this class:
</P>
<DL>
<DT>exception <STRONG>BadArgument</STRONG></DT>
<DD>
<P>
Bad parameters given.
</P>
</DD>
</DL>
<HR><STRONG>Subsections</STRONG>
<P>
<UL>
<LI>Objects of the <A HREF="asynrole-objects-manager.html">asynrole.manager</A>
class
<LI>Objects of the <A HREF="asynrole-objects-agent.html">asynrole.agent</A>
class
</UL>
</P>
<HR>
<ADDRESS>
ilya@glas.net
</ADDRESS>
</BODY>
</HTML>
|
