SNMP++  3.3.4
target.h
Go to the documentation of this file.
1 /*_############################################################################
2  _##
3  _## target.h
4  _##
5  _## SNMP++ v3.3
6  _## -----------------------------------------------
7  _## Copyright (c) 2001-2013 Jochen Katz, Frank Fock
8  _##
9  _## This software is based on SNMP++2.6 from Hewlett Packard:
10  _##
11  _## Copyright (c) 1996
12  _## Hewlett-Packard Company
13  _##
14  _## ATTENTION: USE OF THIS SOFTWARE IS SUBJECT TO THE FOLLOWING TERMS.
15  _## Permission to use, copy, modify, distribute and/or sell this software
16  _## and/or its documentation is hereby granted without fee. User agrees
17  _## to display the above copyright notice and this license notice in all
18  _## copies of the software and any documentation of the software. User
19  _## agrees to assume all liability for the use of the software;
20  _## Hewlett-Packard and Jochen Katz make no representations about the
21  _## suitability of this software for any purpose. It is provided
22  _## "AS-IS" without warranty of any kind, either express or implied. User
23  _## hereby grants a royalty-free license to any and all derivatives based
24  _## upon this software code base.
25  _##
26  _##########################################################################*/
27 /*===================================================================
28 
29  Copyright (c) 1999
30  Hewlett-Packard Company
31 
32  ATTENTION: USE OF THIS SOFTWARE IS SUBJECT TO THE FOLLOWING TERMS.
33  Permission to use, copy, modify, distribute and/or sell this software
34  and/or its documentation is hereby granted without fee. User agrees
35  to display the above copyright notice and this license notice in all
36  copies of the software and any documentation of the software. User
37  agrees to assume all liability for the use of the software; Hewlett-Packard
38  makes no representations about the suitability of this software for any
39  purpose. It is provided "AS-IS" without warranty of any kind,either express
40  or implied. User hereby grants a royalty-free license to any and all
41  derivatives based upon this software code base.
42 
43 
44  SNMP++ T A R G E T . H
45 
46  TARGET CLASS DEFINITION
47 
48  DESIGN + AUTHOR: Peter E Mellquist
49 
50  DESCRIPTION:
51  Target class defines target SNMP agents.
52 
53 =====================================================================*/
54 // $Id: target.h 2359 2013-05-09 20:07:01Z fock $
55 
56 #ifndef _TARGET
57 #define _TARGET
58 
59 //----[ includes ]-----------------------------------------------------
60 
61 #include "snmp_pp/config_snmp_pp.h"
62 #include "snmp_pp/address.h"
63 #include "snmp_pp/octet.h"
64 #include "snmp_pp/collect.h"
65 
66 #ifdef SNMP_PP_NAMESPACE
67 namespace Snmp_pp {
68 #endif
69 
70 
71 //----[ enumerated types for SNMP versions ]---------------------------
72 /**
73  * The SNMP version to use is passed with this enum.
74  */
76 {
77  version1, ///< (0) SNMPv1
78  version2c ///< (1) SNMPv2c
79 #ifdef _SNMPv3
80  ,version2stern, ///< (2) Dont use this!
81  version3 ///< (3) SNMPv3
82 #endif
83 };
84 
85 //----[ Target class ]-------------------------------------------------
86 /**
87  * Abstract class used to provide a virtual interface into Targets.
88  *
89  * @note Although it is possible to create an object of this class,
90  * you won't be happy with that...
91  */
93 {
94  public:
95 
96  /**
97  * Enum to identify a target object through SnmpTarget::get_type() method.
98  */
100  {
101  type_base, ///< It is a SnmpTarget object
102  type_ctarget, ///< It is a CTarget object
103  type_utarget ///< It is a Utarget object
104  };
105 
106  /**
107  * Create a SnmpTarget object with default values.
108  * The validity of the target will be false.
109  */
111  : validity(false), timeout(default_timeout), retries(default_retries),
112  version(version1), ttype(type_base) {};
113 
114  /**
115  * Create a SnmpTarget object with the given Address.
116  */
117  SnmpTarget(const Address &address)
118  : validity(false), timeout(default_timeout), retries(default_retries),
119  version(version1), ttype(type_base), my_address(address)
120  { if (my_address.valid()) validity = true; };
121 
122  /**
123  * Destructor that has nothing to do.
124  */
125  virtual ~SnmpTarget() {};
126 
127  /**
128  * Return the type of the target object.
129  *
130  * If a SNMP message is received through a callback (that only
131  * passes a SnmpTarget pointer to the callback function), this
132  * method can be used to check the type of the object before doing a
133  * cast to CTarget or UTarget.
134  */
135  target_type get_type() const { return ttype; };
136 
137  /**
138  * Returns the validity of the target object.
139  *
140  * @return true, if the target is valid.
141  */
142  bool valid() const { return validity;};
143 
144  /**
145  * Set the retry value.
146  *
147  * @param r - The number of retries if no response is received.
148  */
149  void set_retry(const int r) { retries = r; };
150 
151  /**
152  * Get the retry value.
153  *
154  * @return The number of retries on timeout.
155  */
156  int get_retry() const { return retries; };
157 
158 
159  /**
160  * Set the timeout for requests.
161  *
162  * The default timeout for requests is 1 second (100).
163  *
164  * @param t - Timeout in 10ms, so 100 will set the timeout to 1 second.
165  */
166  void set_timeout(const unsigned long t) { timeout = t; };
167 
168  /**
169  * Get the timeout.
170  *
171  * @return The timeout for requests sent using this target object.
172  */
173  unsigned long get_timeout() const { return timeout; };
174 
175  /**
176  * Change the default timeout.
177  *
178  * Changing the default timeout value will only have an effect for
179  * target objects that are created after setting this value.
180  *
181  * @param t - The new default timeout value
182  */
183  static void set_default_timeout(const unsigned long t)
184  { default_timeout = t; };
185 
186  /**
187  * Change the default retries vlaue.
188  *
189  * Changing the default retries value will only have an effect for
190  * target objects that are created after setting this value.
191  *
192  * @param r - The new retries value
193  */
194  static void set_default_retries(const int r) { default_retries = r; };
195 
196  /**
197  * Clone operator.
198  *
199  * Virtual clone operation for creating a new SnmpTarget from an existing
200  * SnmpTarget.
201  *
202  * @note The caller MUST use the delete operation on the return
203  * value when done.
204  *
205  * @return A pointer to the new object on success, 0 on failure.
206  */
207  virtual SnmpTarget *clone() const;
208 
209  /**
210  * Get the address object.
211  *
212  * @param address - GenAddress object to store the target address.
213  * @return true on success.
214  */
215  bool get_address(GenAddress &address) const;
216 
217  /**
218  * Get the address object.
219  *
220  * @return The target address.
221  */
222  const GenAddress &get_address() const { return my_address; };
223 
224  /**
225  * Set the address object.
226  *
227  * @param address - The address that this target should use.
228  * @return true on success.
229  */
230  virtual bool set_address(const Address &address);
231 
232  /**
233  * Get the SNMP version for this target.
234  *
235  * @return The SNMP version of this target object.
236  * @see enum snmp_version
237  */
238  snmp_version get_version() const { return version;};
239 
240  /**
241  * Set the SNMP version of this target.
242  *
243  * @param v - The SNMP version that should be used for sending messages.
244  */
245  void set_version(const snmp_version v) { version = v; };
246 
247  /**
248  * Overloeaded compare operator.
249  *
250  * Two SnmpTarget objects are considered equal, if all member
251  * variables are equal.
252  *
253  * @return 1 if targets are equal, 0 if not.
254  */
255  int operator==(const SnmpTarget &rhs) const;
256 
257  /**
258  * Reset the object.
259  */
260  virtual void clear();
261 
262  protected:
263  bool validity; ///< Validity of the object
264  unsigned long timeout; ///< xmit timeout in 10 milli secs
265  int retries; ///< number of retries
266  snmp_version version; ///< SNMP version to use
267  target_type ttype; ///< Type of the target
268  GenAddress my_address; ///< Address object
269 
270  static unsigned long default_timeout; ///< default timeout for new objects
271  static int default_retries; ///< default retries for new objects
272 };
273 
274 //----[ CTarget class ]----------------------------------------------
275 /**
276  * Community based target object.
277  * This target can be used for SNMPv1 and SNMPv2c messages.
278  */
279 class DLLOPT CTarget: public SnmpTarget
280 {
281  public:
282  /**
283  * Constructor with no args.
284  * The validity of the target will be false.
285  */
286  CTarget();
287 
288  /**
289  * Constructor with all args.
290  *
291  * @param address - Address of the target host (cann be any address object)
292  * @param read_community_name - Community for get requests
293  * @param write_community_name - Community for set requests
294  */
295  CTarget(const Address &address,
296  const char *read_community_name,
297  const char *write_community_name);
298 
299  /**
300  * Constructor with all args.
301  *
302  * @param address - Address of the target host (cann be any address object)
303  * @param read_community_name - Community for get requests
304  * @param write_community_name - Community for set requests
305  */
306  CTarget(const Address &address,
307  const OctetStr &read_community_name,
308  const OctetStr &write_community_name);
309 
310  /**
311  * Constructor with only address.
312  *
313  * The read and write community names will be set to "public".
314  *
315  * @param address - Address of the target host (cann be any address object)
316  */
317  CTarget(const Address &address);
318 
319  /**
320  * Constructor from existing CTarget.
321  */
322  CTarget(const CTarget &target);
323 
324  /**
325  * Destructor, that has nothing to do.
326  */
327  ~CTarget() {};
328 
329  /**
330  * Clone operator.
331  *
332  * Clone operation for creating a new CTarget from an existing
333  * CTarget.
334  *
335  * @note The caller MUST use the delete operation on the return
336  * value when done.
337  *
338  * @return A pointer to the new object on success, 0 on failure.
339  */
340  SnmpTarget *clone() const { return (SnmpTarget *) new CTarget(*this); };
341 
342  /**
343  * Get the read community name.
344  *
345  * @return C string of the read community.
346  */
347  const char * get_readcommunity() const
348  { return (const char *) read_community.get_printable(); };
349 
350  /**
351  * Get the read community name.
352  *
353  * @param oct - OctetStr that will be filled with the read community name.
354  */
355  void get_readcommunity(OctetStr& oct) const { oct = read_community; };
356 
357  /**
358  * Set the read community name.
359  *
360  * @param str - The new read community name
361  */
362  void set_readcommunity(const char * str) { read_community = str; };
363 
364  /**
365  * Set the read community name.
366  *
367  * @param oct - The new read community name
368  */
369  void set_readcommunity(const OctetStr& oct) { read_community = oct; };
370 
371  /**
372  * Get the write community name.
373  *
374  * @return C string of the write community.
375  */
376  const char * get_writecommunity() const
377  { return (const char *) write_community.get_printable(); };
378 
379  /**
380  * Get the write community name.
381  *
382  * @param oct - OctetStr that will be filled with the write community name.
383  */
384  void get_writecommunity(OctetStr &oct) const { oct = write_community; };
385 
386  /**
387  * Set the write community name.
388  *
389  * @param str - The new write community name
390  */
391  void set_writecommunity(const char *str) { write_community = str; };
392 
393  /**
394  * Set the write community name.
395  *
396  * @param oct - The new write community name
397  */
398  void set_writecommunity(const OctetStr &oct) { write_community = oct; };
399 
400  /**
401  * Overloaded assignment operator.
402  */
403  CTarget& operator=(const CTarget& target);
404 
405  /**
406  * Overloeaded compare operator.
407  *
408  * Two CTarget objects are considered equal, if all member variables
409  * and the base classes are equal.
410  *
411  * @return 1 if targets are equal, 0 if not.
412  */
413  int operator==(const CTarget &rhs) const;
414 
415  /**
416  * Get all values of a CTarget object.
417  *
418  * @param read_comm - Read community name
419  * @param write_comm - Write community name
420  * @param address - Address of the target
421  * @param t - Timeout value
422  * @param r - Retries value
423  * @param v - The SNMP version of this target
424  *
425  * @return true on success and FALSE on failure.
426  */
427  bool resolve_to_C(OctetStr& read_comm,
428  OctetStr& write_comm,
429  GenAddress &address,
430  unsigned long &t,
431  int &r,
432  unsigned char &v) const;
433 
434  /**
435  * Reset the object.
436  */
437  void clear();
438 
439  protected:
440  OctetStr read_community; // get community
441  OctetStr write_community; // set community
442 };
443 
444 // create OidCollection type
446 
447 #ifdef _SNMPv3
448 #define INITIAL_USER "initial"
449 #else
450 #define INITIAL_USER "public"
451 #endif
452 
453 //----[ UTarget class ]----------------------------------------------
454 /**
455  * User based Target.
456  *
457  * This class is used for SNMPv3 targets.
458  */
459 class DLLOPT UTarget: public SnmpTarget
460 {
461  public:
462  /**
463  * Constructor with no args.
464  * The validity of the target will be false.
465  */
466  UTarget();
467 
468  /**
469  * Constructor with all args.
470  *
471  * @param address - Address of the target host (cann be any address object)
472  * @param sec_name - The security name
473  * @param sec_model - The security model to use
474  */
475  UTarget(const Address &address,
476  const char *sec_name,
477  const int sec_model);
478 
479  /**
480  * Constructor with all args.
481  *
482  * @param address - Address of the target host (cann be any address object)
483  * @param sec_name - The security name
484  * @param sec_model - The security model to use
485  */
486  UTarget(const Address &address,
487  const OctetStr &sec_name,
488  const int sec_model);
489 
490  /**
491  * Constructor with only address.
492  *
493  * Assumes the following defaults: security_name: initial, version: SNMPv3,
494  * security_model: v3MP.
495  *
496  * @param address - Address of the target host (cann be any address object)
497  */
498  UTarget(const Address &address);
499 
500  /**
501  * Constructor from existing UTarget.
502  */
503  UTarget(const UTarget &target);
504 
505  /**
506  * Destructor, that has nothing to do.
507  */
508  ~UTarget() {};
509 
510  /**
511  * Clone operator.
512  *
513  * Clone operation for creating a new UTarget from an existing
514  * UTarget.
515  *
516  * @note The caller MUST use the delete operation on the return
517  * value when done.
518  *
519  * @return A pointer to the new object on success, 0 on failure.
520  */
521  SnmpTarget *clone() const { return (SnmpTarget *) new UTarget(*this); };
522 
523  /**
524  * Set the address object.
525  *
526  * This method is the same as in SnmpTarget, but it deletes engine_id.
527  *
528  * @param address - The address that this target should use.
529  * @return true on success.
530  */
531  bool set_address(const Address &address);
532 
533  /**
534  * Get the security name.
535  *
536  * @return A const reference to the security name.
537  */
538  const OctetStr& get_security_name() const { return security_name;} ;
539 
540  /**
541  * Get the security name.
542  *
543  * @param oct - OctetStr that will be filled with the security name.
544  */
545  void get_security_name(OctetStr& oct) const { oct = security_name; };
546 
547  /**
548  * Set the security name.
549  *
550  * @param str - The new security name
551  */
552  void set_security_name(const char * str) { security_name = str; };
553 
554  /**
555  * Set the security name.
556  *
557  * @param oct - The new security name
558  */
559  void set_security_name(const OctetStr& oct) { security_name = oct; };
560 
561 #ifdef _SNMPv3
562  /**
563  * Set the engine id.
564  *
565  * In most cases it is not necessary for the user to set the engine
566  * id as snmp++ performs engine id discovery. If the engine id is
567  * set by the user, no engine_id discovery is made, even if the
568  * engine id set by the user is wrong.
569  *
570  * @param str - The engine id to use
571  */
572  void set_engine_id(const char * str) { engine_id = str; };
573 
574  /**
575  * Set the engine id.
576  *
577  * In most cases it is not necessary for the user to set the engine
578  * id as snmp++ performs engine id discovery. If the engine id is
579  * set by the user, no engine_id discovery is made, even if the
580  * engine id set by the user is wrong.
581  *
582  * @param oct - The engine id to use
583  */
584  void set_engine_id(const OctetStr &oct) { engine_id = oct; };
585 
586  /**
587  * Get the engine id.
588  *
589  * @return A const reference to the enigne id of this target.
590  */
591  const OctetStr& get_engine_id() const { return engine_id; };
592 
593  /**
594  * Get the engine id.
595  *
596  * @param oct - OctetStr that will be filled with the engine id
597  */
598  void get_engine_id(OctetStr& oct) const { oct = engine_id; };
599 #endif
600 
601  /**
602  * Get the security_model.
603  *
604  * @return An integer representing the security_model of this target.
605  */
606  int get_security_model() const { return security_model; };
607 
608  /**
609  * Set the security_model.
610  *
611  * @param sec_model - The security model to use.
612  */
613  void set_security_model(int sec_model) { security_model = sec_model; };
614 
615  /**
616  * Overloaded assignment operator.
617  */
618  UTarget& operator=(const UTarget& target);
619 
620  /**
621  * Overloeaded compare operator.
622  *
623  * Two UTarget objects are considered equal, if all member variables
624  * (beside the engine id) and the base classes are equal.
625  *
626  * @return 1 if targets are equal, 0 if not.
627  */
628  virtual int operator==(const UTarget &rhs) const;
629 
630  /**
631  * Get all values of a UTarget object.
632  *
633  * @param sec_name - security name
634  * @param sec_model - security model
635  * @param address - Address of the target
636  * @param t - Timeout value
637  * @param r - Retries value
638  * @param v - The SNMP version of this target
639  *
640  * @return TRUE on success and FALSE on failure.
641  */
642  bool resolve_to_U(OctetStr& sec_name,
643  int &sec_model,
644  GenAddress &address,
645  unsigned long &t,
646  int &r,
647  unsigned char &v) const;
648 
649  /**
650  * Reset the object.
651  */
652  void clear();
653 
654  protected:
657 #ifdef _SNMPv3
659 #endif
660 };
661 
662 #ifdef SNMP_PP_NAMESPACE
663 } // end of namespace Snmp_pp
664 #endif
665 
666 #endif //_TARGET
void get_engine_id(OctetStr &oct) const
Get the engine id.
Definition: target.h:598
int retries
number of retries
Definition: target.h:265
GenAddress my_address
Address object.
Definition: target.h:268
OctetStr write_community
Definition: target.h:441
void set_engine_id(const char *str)
Set the engine id.
Definition: target.h:572
target_type ttype
Type of the target.
Definition: target.h:267
SnmpTarget(const Address &address)
Create a SnmpTarget object with the given Address.
Definition: target.h:117
target_type
Enum to identify a target object through SnmpTarget::get_type() method.
Definition: target.h:99
void set_writecommunity(const OctetStr &oct)
Set the write community name.
Definition: target.h:398
void set_security_name(const char *str)
Set the security name.
Definition: target.h:552
void set_version(const snmp_version v)
Set the SNMP version of this target.
Definition: target.h:245
bool validity
Validity of the object.
Definition: target.h:263
static void set_default_retries(const int r)
Change the default retries vlaue.
Definition: target.h:194
void set_timeout(const unsigned long t)
Set the timeout for requests.
Definition: target.h:166
unsigned long get_timeout() const
Get the timeout.
Definition: target.h:173
const char * get_writecommunity() const
Get the write community name.
Definition: target.h:376
int get_security_model() const
Get the security_model.
Definition: target.h:606
void set_engine_id(const OctetStr &oct)
Set the engine id.
Definition: target.h:584
OctetStr read_community
Definition: target.h:440
SnmpTarget()
Create a SnmpTarget object with default values.
Definition: target.h:110
Community based target object.
Definition: target.h:279
#define DLLOPT
static int default_retries
default retries for new objects
Definition: target.h:271
static unsigned long default_timeout
default timeout for new objects
Definition: target.h:270
It is a SnmpTarget object.
Definition: target.h:101
void set_security_name(const OctetStr &oct)
Set the security name.
Definition: target.h:559
Base class of all Address classes.
Definition: address.h:125
~UTarget()
Destructor, that has nothing to do.
Definition: target.h:508
void set_readcommunity(const char *str)
Set the read community name.
Definition: target.h:362
void set_retry(const int r)
Set the retry value.
Definition: target.h:149
void get_readcommunity(OctetStr &oct) const
Get the read community name.
Definition: target.h:355
snmp_version
The SNMP version to use is passed with this enum.
Definition: target.h:75
snmp_version version
SNMP version to use.
Definition: target.h:266
~CTarget()
Destructor, that has nothing to do.
Definition: target.h:327
void set_writecommunity(const char *str)
Set the write community name.
Definition: target.h:391
SnmpTarget * clone() const
Clone operator.
Definition: target.h:521
SnmpTarget * clone() const
Clone operator.
Definition: target.h:340
Definition: octet.h:67
int get_retry() const
Get the retry value.
Definition: target.h:156
(2) Dont use this!
Definition: target.h:80
const OctetStr & get_security_name() const
Get the security name.
Definition: target.h:538
bool valid() const
Returns the validity of the target object.
Definition: target.h:142
virtual ~SnmpTarget()
Destructor that has nothing to do.
Definition: target.h:125
OctetStr security_name
Definition: target.h:655
void get_writecommunity(OctetStr &oct) const
Get the write community name.
Definition: target.h:384
void set_security_model(int sec_model)
Set the security_model.
Definition: target.h:613
unsigned long timeout
xmit timeout in 10 milli secs
Definition: target.h:264
(1) SNMPv2c
Definition: target.h:78
void set_readcommunity(const OctetStr &oct)
Set the read community name.
Definition: target.h:369
const OctetStr & get_engine_id() const
Get the engine id.
Definition: target.h:591
int security_model
Definition: target.h:656
const GenAddress & get_address() const
Get the address object.
Definition: target.h:222
It is a CTarget object.
Definition: target.h:102
(0) SNMPv1
Definition: target.h:77
OctetStr engine_id
Definition: target.h:658
(3) SNMPv3
Definition: target.h:81
target_type get_type() const
Return the type of the target object.
Definition: target.h:135
SnmpCollection< SnmpTarget > TargetCollection
Definition: target.h:445
Abstract class used to provide a virtual interface into Targets.
Definition: target.h:92
static void set_default_timeout(const unsigned long t)
Change the default timeout.
Definition: target.h:183
snmp_version get_version() const
Get the SNMP version for this target.
Definition: target.h:238
User based Target.
Definition: target.h:459
void get_security_name(OctetStr &oct) const
Get the security name.
Definition: target.h:545
const char * get_readcommunity() const
Get the read community name.
Definition: target.h:347