1 // NAME
2 // $RCSfile: SnmpContextBasisFace.java,v $
3 // DESCRIPTION
4 // [given below in javadoc format]
5 // DELTA
6 // $Revision: 3.9 $
7 // CREATED
8 // $Date: 2006/11/29 16:25:19 $
9 // COPYRIGHT
10 // Westhawk Ltd
11 // TO DO
12 //
13
14 /*
15 * Copyright (C) 2000 - 2006 by Westhawk Ltd
16 * <a href="www.westhawk.co.uk">www.westhawk.co.uk</a>
17 *
18 * Permission to use, copy, modify, and distribute this software
19 * for any purpose and without fee is hereby granted, provided
20 * that the above copyright notices appear in all copies and that
21 * both the copyright notice and this permission notice appear in
22 * supporting documentation.
23 * This software is provided "as is" without express or implied
24 * warranty.
25 * author <a href="mailto:snmp@westhawk.co.uk">Tim Panton</a>
26 */
27
28 package uk.co.westhawk.snmp.stack;
29
30 /*-
31 * ╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲
32 * SNMP Java Client
33 * ჻჻჻჻჻჻
34 * Copyright 2023 MetricsHub, Westhawk
35 * ჻჻჻჻჻჻
36 * This program is free software: you can redistribute it and/or modify
37 * it under the terms of the GNU Lesser General Public License as
38 * published by the Free Software Foundation, either version 3 of the
39 * License, or (at your option) any later version.
40 *
41 * This program is distributed in the hope that it will be useful,
42 * but WITHOUT ANY WARRANTY; without even the implied warranty of
43 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
44 * GNU General Lesser Public License for more details.
45 *
46 * You should have received a copy of the GNU General Lesser Public
47 * License along with this program. If not, see
48 * <http://www.gnu.org/licenses/lgpl-3.0.html>.
49 * ╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱
50 */
51 import uk.co.westhawk.snmp.event.*;
52 import uk.co.westhawk.snmp.net.*;
53
54 /**
55 * This interface contains the SNMP context interface that is needed
56 * by every PDU to send a SNMP v1, v2c and v3 request. The context also
57 * provides functionality to receive incoming PDUs.
58 *
59 * @see SnmpContext
60 * @see SnmpContextv2c
61 * @see SnmpContextv3
62 *
63 * @author <a href="mailto:snmp@westhawk.co.uk">Tim Panton</a>
64 * @version $Revision: 3.9 $ $Date: 2006/11/29 16:25:19 $
65 */
66 public interface SnmpContextBasisFace {
67 static final String version_id = "@(#)$Id: SnmpContextBasisFace.java,v 3.9 2006/11/29 16:25:19 birgit Exp $ Copyright Westhawk Ltd";
68
69 /**
70 * The default port number where SNMP requests are sent to (161).
71 */
72 public final static int DEFAULT_PORT = 161;
73 /**
74 * The Standard Socket type.
75 */
76 public final static String STANDARD_SOCKET = "Standard";
77 /**
78 * The TCP Socket type.
79 */
80 public final static String TCP_SOCKET = "TCP";
81
82 /**
83 * The Maximum number of outstanding PDUs one context can handle at a
84 * given moment in time.
85 */
86 final static int MAXPDU = 20; // if you have more than 20 oustanding PDUS
87 // change the algorythm :-)
88 /**
89 * The Maximum size of a message in octets (1300).
90 */
91 final static int MSS = 1300; // maximum recv size;
92
93 /**
94 * Returns the SNMP version of the context.
95 *
96 * @see SnmpConstants#SNMP_VERSION_1
97 * @see SnmpConstants#SNMP_VERSION_2c
98 * @see SnmpConstants#SNMP_VERSION_3
99 *
100 * @return The version
101 */
102 public int getVersion();
103
104 /**
105 * Returns the host.
106 *
107 * @return The host
108 */
109 public String getHost();
110
111 /**
112 * Returns the port number.
113 *
114 * @return The port no
115 */
116 public int getPort();
117
118 /**
119 * Returns the local bind address.
120 * If bindAddress is null, then the system will pick up a valid local
121 * address to bind the socket.
122 *
123 * @return The local bind address
124 * @since 4_14
125 */
126 public String getBindAddress();
127
128 /**
129 * Returns the type of socket.
130 *
131 * @see #STANDARD_SOCKET
132 * @see #TCP_SOCKET
133 * @return The type of socket
134 */
135 public String getTypeSocket();
136
137 /**
138 * Returns the IP address string
139 * aaa.bbb.ccc.ddd (IPv4) or a:b:c:d:e:f:g:h (IPv6)
140 * of the host the packets where sent to.
141 *
142 * @return The IP address of the host the packets where sent to.
143 * @see ContextSocketFace#getSendToHostAddress
144 * @since 4_14
145 */
146 public String getSendToHostAddress();
147
148 /**
149 * Returns the IP address string
150 * aaa.bbb.ccc.ddd (IPv4) or a:b:c:d:e:f:g:h (IPv6)
151 * of the (latest) host the packets where received from.
152 *
153 * @return The IP address of the (latest) host the packets where received from.
154 * @see ContextSocketFace#getReceivedFromHostAddress
155 * @since 4_14
156 */
157 public String getReceivedFromHostAddress();
158
159 /**
160 * Adds a PDU to the context. This is for internal use only and should
161 * NOT be called by the developer.
162 * This is called by the the Pdu itself and is added to the interface to
163 * cover the different kind of Contexts.
164 *
165 * @param pdu the PDU
166 * @return whether the PDU has been successfully added
167 */
168 public boolean addPdu(Pdu pdu)
169 throws java.io.IOException, PduException;
170
171 /**
172 * Removes a PDU from the context. This is for internal use only and should
173 * NOT be called by the developer.
174 * This is called by the the PDU itself and is added to the interface to
175 * cover the different kind of Contexts.
176 *
177 * @param requestId the PDU request id
178 * @return whether the PDU has been successfully removed
179 */
180 public boolean removePdu(int requestId);
181
182 /**
183 * Encodes a PDU. This is for internal use only and should
184 * NOT be called by the developer.
185 * This is called by the the PDU itself and is added to the interface to
186 * cover the different kind of Contexts.
187 *
188 * @param msg_type The message type
189 * @param rId The message id
190 * @param errstat The error status
191 * @param errind The error index
192 * @param ve The varbind list
193 * @param obj Additional object (only used in SNMPv3)
194 * @return The encoded packet
195 */
196 public byte[] encodePacket(byte msg_type, int rId, int errstat, int errind,
197 java.util.Enumeration ve, Object obj)
198 throws java.io.IOException, EncodingException;
199
200 /**
201 * Sends an encoded PDU. This is for internal use only and should
202 * NOT be called by the developer.
203 * This is called by the the PDU itself and is added to the interface to
204 * cover the different kind of Contexts.
205 *
206 * @param packet The encoded packet
207 */
208 public void sendPacket(byte[] packet);
209
210 /**
211 * Removes the resouces held by this context. Should be called by the
212 * user/developer when the context is no longer needed.
213 */
214 public void destroy();
215
216 /**
217 * Returns whether or not this context has been destroyed.
218 *
219 * @since 4_14
220 */
221 public boolean isDestroyed();
222
223 /**
224 * Adds the specified trap listener to receive traps on the default trap
225 * port <em>162</em> from the host that matches this context.
226 *
227 * <p>
228 * The ListeningContext class will do the actual listening for traps.
229 * This context will add itself to a ListeningContextPool object and
230 * will only pass the event to its listeners if the pdu matches this
231 * context and is a trap pdu.
232 * </p>
233 *
234 * @param l The trap listener
235 * @see #addTrapListener(TrapListener, int)
236 * @see ListeningContextFace#DEFAULT_TRAP_PORT
237 */
238 public void addTrapListener(TrapListener l) throws java.io.IOException;
239
240 /**
241 * Removes the specified trap listener from listening for packets on
242 * the default trap port <em>162</em>.
243 *
244 * <p>
245 * The listener will not be removed from all ListeningContext objects
246 * that are in the ListeningContextPool. In order to do that, use
247 * ListeningContextPool.removeTrapListenerFromPool()
248 * </p>
249 *
250 * @param l The trap listener
251 * @see #removeTrapListener(TrapListener, int)
252 * @see ListeningContextFace#DEFAULT_TRAP_PORT
253 */
254 public void removeTrapListener(TrapListener l) throws java.io.IOException;
255
256 /**
257 * Adds the specified trap listener to receive traps on the specified
258 * port from the host that matches this context.
259 *
260 * <p>
261 * The ListeningContext class will do the actual listening for traps.
262 * This context will add itself to a ListeningContextPool object and
263 * will only pass the event to its listeners if the pdu matches this
264 * context and is a trap pdu.
265 * </p>
266 *
267 * @see ListeningContextPool#ListeningContextPool(int, String, String)
268 * @see ListeningContextPool#addRawPduListener(RawPduListener)
269 *
270 * @param l The trap listener
271 * @param port The port the traps are received on
272 * @since 4_14
273 */
274 public void addTrapListener(TrapListener l, int port) throws java.io.IOException;
275
276 /**
277 * Removes the specified trap listener from listening for packets on the
278 * specified port.
279 *
280 * <p>
281 * The listener will not be removed from all ListeningContext objects
282 * that are in the ListeningContextPool. In order to do that, use
283 * ListeningContextPool.removeTrapListenerFromPool()
284 * </p>
285 *
286 * @see ListeningContextPool#ListeningContextPool(int, String, String)
287 * @see ListeningContextPool#removeRawPduListener(RawPduListener)
288 * @see ListeningContextPool#removeRawPduListenerFromPool(RawPduListener)
289 *
290 * @param l The trap listener
291 * @param port The port the traps are received on
292 * @since 4_14
293 */
294 public void removeTrapListener(TrapListener l, int port) throws java.io.IOException;
295
296 /**
297 * Adds the specified trap listener to receive traps on the specified
298 * listening context that matches this context.
299 *
300 * <p>
301 * The ListeningContext class will do the actual listening for traps.
302 * This context will add itself to a ListeningContextPool object and
303 * will only pass the event to its listeners if the pdu matches this
304 * context and is a trap pdu.
305 * </p>
306 *
307 * @see ListeningContextPool#ListeningContextPool(int, String, String)
308 * @see ListeningContextPool#addRawPduListener(RawPduListener)
309 *
310 * @param l The trap listener
311 * @param lcontext The listening context
312 * @since 4_14
313 */
314 public void addTrapListener(TrapListener l, ListeningContextPool lcontext) throws java.io.IOException;
315
316 /**
317 * Removes the specified trap listener from listening for packets on the
318 * specified listening context.
319 *
320 * <p>
321 * The listener will not be removed from all ListeningContext objects
322 * that are in the ListeningContextPool. In order to do that, use
323 * ListeningContextPool.removeTrapListenerFromPool()
324 * </p>
325 *
326 * @see ListeningContextPool#ListeningContextPool(int, String, String)
327 * @see ListeningContextPool#removeRawPduListener(RawPduListener)
328 * @see ListeningContextPool#removeRawPduListenerFromPool(RawPduListener)
329 *
330 * @param l The trap listener
331 * @param lcontext The listening context
332 * @since 4_14
333 */
334 public void removeTrapListener(TrapListener l, ListeningContextPool lcontext) throws java.io.IOException;
335
336 /**
337 * Adds the specified request pdu listener to receive PDUs on the
338 * default request pdu port <em>161</em> from the host that matches
339 * this context.
340 *
341 * <p>
342 * The ListeningContext class will do the actual listening for PDUs.
343 * This context will add itself to a ListeningContextPool object and
344 * will only pass the event to its listeners if the pdu matches this
345 * context and is a request pdu.
346 * </p>
347 *
348 * <p>
349 * Don't use the TCP_SOCKET when listening for request PDUs. It doesn't
350 * provide functionality to send a response back.
351 * </p>
352 *
353 * @see #addRequestPduListener(RequestPduListener, int)
354 * @see SnmpContextBasisFace#DEFAULT_PORT
355 *
356 * @param l The request PDU listener
357 * @since 4_14
358 */
359 public void addRequestPduListener(RequestPduListener l) throws java.io.IOException;
360
361 /**
362 * Removes the specified request pdu listener from listening for packets
363 * on the default request pdu port <em>161</em>.
364 *
365 * <p>
366 * The listener will not be removed from all ListeningContext objects
367 * that are in the ListeningContextPool. In order to do that, use
368 * ListeningContextPool.removeRequestPduListenerFromPool()
369 * </p>
370 *
371 * @see #removeRequestPduListener(RequestPduListener, int)
372 * @see SnmpContextBasisFace#DEFAULT_PORT
373 *
374 * @param l The request PDU listener
375 * @since 4_14
376 */
377 public void removeRequestPduListener(RequestPduListener l) throws java.io.IOException;
378
379 /**
380 * Adds the specified request pdu listener to receive PDUs on the specified
381 * port from the host that matches this context.
382 *
383 * <p>
384 * The ListeningContext class will do the actual listening for PDUs.
385 * This context will add itself to a ListeningContextPool object and
386 * will only pass the event to its listeners if the pdu matches this
387 * context and is a request pdu.
388 * </p>
389 *
390 * <p>
391 * Don't use the TCP_SOCKET when listening for request PDUs. It doesn't
392 * provide functionality to send a response back.
393 * </p>
394 *
395 * @see ListeningContextPool#ListeningContextPool(int, String, String)
396 * @see ListeningContextPool#addRawPduListener(RawPduListener)
397 *
398 * @param l The request PDU listener
399 * @param port The port the request PDUs are received on
400 * @since 4_14
401 */
402 public void addRequestPduListener(RequestPduListener l, int port) throws java.io.IOException;
403
404 /**
405 * Removes the specified request pdu listener from listening for packets
406 * on the specified port.
407 *
408 * <p>
409 * The listener will not be removed from all ListeningContext objects
410 * that are in the ListeningContextPool. In order to do that, use
411 * ListeningContextPool.removeRequestPduListenerFromPool()
412 * </p>
413 *
414 * @see ListeningContextPool#ListeningContextPool(int, String, String)
415 * @see ListeningContextPool#removeRawPduListener(RawPduListener)
416 * @see ListeningContextPool#removeRawPduListenerFromPool(RawPduListener)
417 *
418 * @param l The request PDU listener
419 * @param port The port the request PDUs are received on
420 * @since 4_14
421 */
422 public void removeRequestPduListener(RequestPduListener l, int port) throws java.io.IOException;
423
424 /**
425 * Adds the specified request pdu listener to receive PDUs on the
426 * specified listening context that matches this context.
427 *
428 * <p>
429 * The ListeningContext class will do the actual listening for PDUs.
430 * This context will add itself to a ListeningContextPool object and
431 * will only pass the event to its listeners if the pdu matches this
432 * context and is a request pdu.
433 * </p>
434 *
435 * <p>
436 * Don't use the TCP_SOCKET when listening for request PDUs. It doesn't
437 * provide functionality to send a response back.
438 * </p>
439 *
440 * @see ListeningContextPool#ListeningContextPool(int, String, String)
441 * @see ListeningContextPool#addRawPduListener(RawPduListener)
442 *
443 * @param l The request PDU listener
444 * @param lcontext The listening context
445 * @since 4_14
446 */
447 public void addRequestPduListener(RequestPduListener l, ListeningContextPool lcontext) throws java.io.IOException;
448
449 /**
450 * Removes the specified request pdu listener from listening for packets
451 * on the specified listening context.
452 *
453 * <p>
454 * The listener will not be removed from all ListeningContext objects
455 * that are in the ListeningContextPool. In order to do that, use
456 * ListeningContextPool.removeRequestPduListenerFromPool()
457 * </p>
458 *
459 * @see ListeningContextPool#ListeningContextPool(int, String, String)
460 * @see ListeningContextPool#removeRawPduListener(RawPduListener)
461 * @see ListeningContextPool#removeRawPduListenerFromPool(RawPduListener)
462 *
463 * @param l The request PDU listener
464 * @param lcontext The listening context
465 * @since 4_14
466 */
467 public void removeRequestPduListener(RequestPduListener l, ListeningContextPool lcontext)
468 throws java.io.IOException;
469
470 /**
471 * Processes an incoming PDU. The context will try to process the
472 * incoming PDU, using the SNMP version and other security
473 * parameters. If any of these do not correspond, a DecodingException
474 * will be thrown.
475 */
476 public Pdu processIncomingPdu(byte[] message)
477 throws DecodingException, java.io.IOException;
478
479 /**
480 * Returns a clone of this SnmpContext.
481 *
482 * @since 4_14
483 * @exception CloneNotSupportedException Thrown when the constructor
484 * generates an IOException or when in one
485 * of the Pool classes.
486 */
487 public Object clone() throws CloneNotSupportedException;
488
489 /**
490 * Returns the hash key. This key is built out of all properties.
491 *
492 * @since 4_14
493 * @return The hash key
494 */
495 public String getHashKey();
496 }