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

   1 /*_############################################################################
   2   _##
   3   _##  pdu.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++ P D U . H
  47
  48   PDU CLASS DEFINITION
  49
  50   DESIGN + AUTHOR:  Peter E Mellquist
  51
  52   DESCRIPTION:
  53   Pdu class definition. Encapsulation of an SMI Protocol
  54   Data Unit (PDU) in C++.
  55
  56 =====================================================================*/
  57 // $Id: pdu.h 288 2007-03-22 22:37:09Z katz $
  58
  59 #ifndef _PDU_CLS
  60 #define _PDU_CLS
  61
  62 #include "snmp_pp/config_snmp_pp.h"
  63 #include "snmp_pp/address.h"
  64 #include "snmp_pp/timetick.h"
  65 #include "snmp_pp/octet.h"
  66 #include "snmp_pp/oid.h"
  67
  68 #ifdef SNMP_PP_NAMESPACE
  69 namespace Snmp_pp {
  70 #endif
  71
  72 class Vb;
  73
  74 #define PDU_MAX_RID 32767         ///< max request id to use
  75 #define PDU_MIN_RID 1000          ///< min request id to use
  76
  77 //=======================================================================
  78 //                   Pdu Class
  79 //=======================================================================
  80 /**
  81  * Pdu class...
  82  */
  83 class DLLOPT Pdu
  84 {
  85  public:
  86
  87   /**
  88    * Constructor no args.
  89    *
  90    * This constructor creates a valid empty Pdu object.
  91    */
  92   Pdu();
  93
  94   /**
  95    * Constructor with vbs.
  96    *
  97    * The Pdu class does not take ownership of the array and the Vb
  98    * objects, so if these were allocated with new, they must be freed
  99    * by te user with delete.
 100    *
 101    * @param pvbs      - Array of pointers to Vb objects
 102    * @param pvb_count - Length of the array
 103    */
 104   Pdu(Vb* pvbs, const int pvb_count);
 105
 106   /**
 107    * Constructor with another Pdu instance.
 108    *
 109    * @param pdu - source pdu object
 110    */
 111   Pdu(const Pdu &pdu) : vbs(0), vbs_size(0), vb_count(0) { *this = pdu; };
 112
 113   /**
 114    * Destructor
 115    */
 116   virtual ~Pdu();
 117
 118   /**
 119    * Overloaded assignment operator.
 120    *
 121    * @param pdu - Pdu that should be assigned to this object
 122    */
 123   Pdu& operator=(const Pdu &pdu);
 124
 125   /**
 126    * Append a vb to the pdu.
 127    *
 128    * @param vb - The Vb that should be added (as last vb) to the pdu
 129    */
 130   Pdu& operator+=(const Vb &vb);
 131
 132   /**
 133    * Clone a Pdu object.
 134    *
 135    * @return Pointer to a newly created Pdu object, that is identical to this
 136    */
 137   Pdu *clone() const { return new Pdu(*this); };
 138
 139   /**
 140    * Get Pointers to all Vbs from Pdu.
 141    *
 142    * The caller has to allocate the array. The returned pointers point
 143    * to the Vb objects that are internally used by the pdu. So any
 144    * changes to the returned Vb objects will change the pdu. If the
 145    * pdu is modified (e.g. through Pdu::trim()) afterwards, the
 146    * returned array will contain invalid pointers.
 147    *
 148    * @param pvbs - Array of empty pointers of size pvb_count
 149    * @param pvb_count - Amount of Vb pointers to get
 150    *
 151    * @return TRUE on success
 152    */
 153   int get_vblist(Vb* pvbs, const int pvb_count) const;
 154
 155   /**
 156    * Deposit all Vbs to Pdu.
 157    *
 158    * The vb objects of the pdu will be freed and the objects from the
 159    * array will be cloned and added to the pdu. If this method returns
 160    * FALSE, the pdu will not conatin any Vb objects.
 161    *
 162    * @param pvbs - Array of valid pointers of size pvb_count
 163    * @param pvb_count - Amount of Vb pointers i the array
 164    *
 165    * @return TRUE on success
 166    */
 167   int set_vblist(Vb* pvbs, const int pvb_count);
 168
 169   /**
 170    * Get a particular Vb.
 171    *
 172    * @param vb - Object to store the vb
 173    * @param index - The vb to get (zero is the first vb)
 174    *
 175    * @return TRUE on success
 176    */
 177   int get_vb(Vb &vb, const int index) const;
 178
 179   /**
 180    * Return a reference to a particular Vb.
 181    *
 182    * @note Before calling this method, make sure that there
 183    *       is a Vb using get_vb_count().
 184    *
 185    * @param index - The Vb to return starting with 0.
 186    * @return A const reference to the Vb
 187    */
 188   const Vb &get_vb(const int index) const { return *vbs[index]; };
 189
 190   /**
 191    * Set a particular vb.
 192    *
 193    * If this method returns FALSE, the pdu has not been modified.
 194    *
 195    * @param vb - Source vb
 196    * @param index - The vb to set (zero is the first vb)
 197    *
 198    * @return TRUE on success
 199    */
 200   int set_vb(Vb &vb, const int index);
 201
 202   /**
 203    * Get the number of vbs.
 204    *
 205    * @return The number of Vb objects within the pdu.
 206    */
 207   int get_vb_count() const { return vb_count; };
 208
 209   /**
 210    * Get a Vb.
 211    *
 212    * @note The index has to be checked by the caller.
 213    *
 214    * @param i zero based index
 215    */
 216   Vb& operator[](const int i) { return *vbs[i]; };
 217
 218   /**
 219    * Get the error status.
 220    *
 221    * @return The SNMP error status
 222    */
 223   int get_error_status() const { return error_status; };
 224
 225   /**
 226    * Set the error status.
 227    *
 228    * @param err - The new SNMP error status.
 229    */
 230   void set_error_status(const int err) {  error_status = err; };
 231
 232   /**
 233    * Clear the error status.
 234    */
 235   void clear_error_status() { error_status = 0; };
 236
 237   /**
 238    * Get the error index.
 239    *
 240    * @return The SNMP error index
 241    */
 242   int get_error_index() const { return error_index; };
 243
 244   /**
 245    * Set the error index.
 246    *
 247    * @param err - The new SNMP error index.
 248    */
 249   void set_error_index(const int index) { error_index = index; };
 250
 251   /**
 252    * Clear the error index.
 253    */
 254   void clear_error_index() { error_index = 0; };
 255
 256   /**
 257    * Clear error status and error index.
 258    */
 259   void clear_error() { set_error_status(0); set_error_index(0); }
 260
 261   /**
 262    * Get the request id.
 263    *
 264    * @return The SNMP request id
 265    */
 266   unsigned long get_request_id() const { return request_id; };
 267
 268   /**
 269    * Set the request id.
 270    *
 271    * @param rid - The new SNMP request id
 272    */
 273   void set_request_id(const unsigned long rid) { request_id = rid; };
 274
 275   /**
 276    * Get the pdu type.
 277    */
 278   unsigned short get_type() const { return pdu_type; };
 279
 280   /**
 281    * Set the pdu type.
 282    */
 283   void set_type(unsigned short type) { pdu_type = type; };
 284
 285   /**
 286    * Returns validity of Pdu instance.
 287    */
 288   bool valid() const { return validity; };
 289
 290   /**
 291    * Trim off vbs.
 292    *
 293    * @param count - number of vbs to trim of, starting with the last
 294    * @return TRUE on success, FALSE if nothing was done
 295    */
 296   int trim(const int count=1);
 297
 298   /**
 299    * Delete a Vb anywhere within the Pdu.
 300    *
 301    * @param position - Delete the Vb at this position (starting with 0)
 302    * @return TRUE on success
 303    */
 304   int delete_vb(const int position);
 305
 306   /**
 307    * Set notify timestamp.
 308    */
 309   void set_notify_timestamp(const TimeTicks &ts) { notify_timestamp = ts; };
 310
 311   /**
 312    * Get notify timestamp.
 313    */
 314   void get_notify_timestamp(TimeTicks &ts) const { ts = notify_timestamp; };
 315
 316   /**
 317    * Set the notify id.
 318    *
 319    * @return true if the set succeeded.
 320    */
 321   bool set_notify_id(const Oid &id)
 322     { notify_id = id; return (notify_id.len() == id.len()); };
 323
 324   /**
 325    * Get the notify id.
 326    *
 327    * @return true if the get succeeded.
 328    */
 329   bool get_notify_id(Oid &id) const
 330     { id = notify_id; return (notify_id.len() == id.len()); };
 331
 332   /**
 333    * Set the notify enterprise.
 334    *
 335    * @return true if the set succeeded.
 336    */
 337   bool set_notify_enterprise(const Oid &e)
 338     { notify_enterprise = e; return (notify_enterprise.len() == e.len()); };
 339
 340   /**
 341    * Get the notify enterprise.
 342    *
 343    * @return true if the get succeeded.
 344    */
 345   bool get_notify_enterprise(Oid & e) const
 346     { e = notify_enterprise;  return (notify_enterprise.len() == e.len()); };
 347
 348 #ifdef _SNMPv3
 349   /**
 350    * Set the security level that should be used when this Pdu is sent.
 351    * The default security level of a Pdu is SNMP_SECURITY_LEVEL_NOAUTH_NOPRIV.
 352    *
 353    * @param level - One of SNMP_SECURITY_LEVEL_NOAUTH_NOPRIV,
 354    *                SNMP_SECURITY_LEVEL_AUTH_NOPRIV,
 355    *                SNMP_SECURITY_LEVEL_AUTH_PRIV
 356    */
 357   void set_security_level(const int level) { security_level = level; };
 358
 359   /**
 360    * Return the security level of the Pdu.
 361    *
 362    * @return - the security level
 363    */
 364   int get_security_level() const { return security_level; };
 365
 366   /**
 367    * Set the context name of the Pdu.
 368    *
 369    * @param name - The context name
 370    */
 371   bool set_context_name(const OctetStr &name)
 372     { context_name = name; return (context_name.valid() && name.valid()); };
 373
 374   /**
 375    * Set the context name of the Pdu.
 376    *
 377    * @param name - The context name
 378    */
 379   bool set_context_name(const char *name)
 380     { context_name = name; return context_name.valid(); };
 381
 382   /**
 383    * Get the context name of the Pdu.
 384    *
 385    * @param name - Object fot the context name
 386    */
 387   bool get_context_name(OctetStr &name) const
 388     { name = context_name; return (context_name.valid() && name.valid()); };
 389
 390   /**
 391    * Get the context name of the Pdu.
 392    *
 393    * @return - Return the context name as an OctetStr
 394    */
 395   const OctetStr& get_context_name() const { return context_name; };
 396
 397   /**
 398    * Set the context engine id of the Pdu.
 399    *
 400    * @param id - The new context engine id
 401    */
 402   bool set_context_engine_id(const OctetStr &id) { context_engine_id = id;
 403     return (context_engine_id.valid() && id.valid()); };
 404
 405   /**
 406    * Set the context engine id of the Pdu.
 407    *
 408    * @param id - The new context engine id
 409    */
 410   bool set_context_engine_id(const char *id)
 411     { context_engine_id = id; return context_engine_id.valid(); };
 412
 413   /**
 414    * Get the context engine id of the Pdu.
 415    *
 416    * @param id - Object for the context engine
 417    */
 418   bool get_context_engine_id(OctetStr &id) const { id = context_engine_id;
 419     return (context_engine_id.valid() && id.valid()); };
 420
 421   /**
 422    * Get the context engine id of the Pdu.
 423    *
 424    * @return - Return the context engine id as an OctetStr
 425    */
 426   const OctetStr& get_context_engine_id() const { return context_engine_id; };
 427
 428   /**
 429    * Set the SNMPv3 message id (msgID)
 430    *
 431    * @param msg_id - the message id of the received message
 432    */
 433   void set_message_id(const unsigned long msg_id) { message_id = msg_id; }
 434
 435   /**
 436    * Get the SNMPv3 message id (msgID)
 437    *
 438    * @return - the message id of the received message
 439    */
 440   unsigned long get_message_id() const { return message_id; }
 441
 442   /**
 443    * Set the maximum size of the scoped pdu to be included in a
 444    * possible response message.
 445    *
 446    * @param l - the maximum size
 447    */
 448   void set_maxsize_scopedpdu(unsigned long l) { maxsize_scopedpdu = l; };
 449
 450   /**
 451    * Get the maximum size of the scoped pdu to be included in a
 452    * possible response message.
 453    *
 454    * @return - the maximum size
 455    */
 456   unsigned long get_maxsize_scopedpdu() const { return maxsize_scopedpdu; };
 457
 458 #endif // _SNMPv3
 459
 460   /**
 461    * Get the SNMPv1 trap address
 462    */
 463   int get_v1_trap_address(GenAddress &address) const;
 464
 465   /**
 466    * Set the SNMPv1 trap address
 467    */
 468   int set_v1_trap_address(const Address &address);
 469
 470   /**
 471    * Return the length of the encoded vbs with pdu header.
 472    *
 473    * @note this method wll not work for v1 traps.
 474    */
 475   int get_asn1_length() const;
 476
 477   /**
 478    * Clear the Pdu contents (destruct and construct in one go)
 479    */
 480   void clear();
 481
 482   /**
 483    * Does the type of response match the type of request.
 484    */
 485   static bool match_type(const int request, const int response);
 486
 487   //-------------[ protected members ]--------------------------
 488  protected:
 489
 490   /**
 491    * Extend the vbs array.
 492    *
 493    * @return true on success
 494    */
 495   bool extend_vbs();
 496
 497   Vb **vbs;                    // pointer to array of Vbs
 498   int vbs_size;                // Size of array
 499   int vb_count;                // count of Vbs
 500   int error_status;            // SMI error status
 501   int error_index;             // SMI error index
 502   bool validity;               // valid boolean
 503   unsigned long request_id;      // SMI request id
 504   unsigned short pdu_type;       // derived at run time based on request type
 505   // for notify Pdu objects only
 506   // traps & notifies
 507   TimeTicks notify_timestamp;      // a timestamp associated with an infor
 508   Oid notify_id;                   // an id
 509   Oid notify_enterprise;
 510   GenAddress v1_trap_address;      // address object
 511   int        v1_trap_address_set;
 512 #ifdef _SNMPv3
 513   // specific Objects for SNMPv3
 514   int security_level;            // the securityLevel with which this Pdu
 515                                  // should be sent or was received
 516   unsigned long message_id;
 517   unsigned long maxsize_scopedpdu;
 518   OctetStr context_name;
 519   OctetStr context_engine_id;
 520 #endif // _SNMPv3
 521 };
 522
 523 #ifdef SNMP_PP_NAMESPACE
 524 } // end of namespace Snmp_pp
 525 #endif
 526
 527 #endif //_PDU_CLS