3rdparty/snmp++/include/snmp_pp/target.h

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