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

   1 /*_############################################################################
   2   _##
   3   _##  vb.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++ V B . H
  47
  48   VARIABLE BINDING CLASS DEFINITION
  49
  50   DESCRIPTION:
  51   This module contains the class definition for the variable binding
  52   class. The VB class is an encapsulation of a SNMP VB. A VB object is
  53   composed of an SNMP++ Oid and an SMI value. The Vb class utilizes Oid
  54   objects and thus requires the Oid class. The Vb class may be used
  55   stand alone and does not require use of any other snmp library.
  56
  57   DESIGN + AUTHOR:  Peter E. Mellquist
  58
  59 =====================================================================*/
  60 // $Id: vb.h 1541 2009-05-29 11:29:22Z katz $
  61
  62 #ifndef _VB_CLS
  63 #define _VB_CLS
  64
  65 #include "snmp_pp/oid.h"                 // oid class def
  66 #include "snmp_pp/timetick.h"            // time ticks
  67 #include "snmp_pp/counter.h"             // counter
  68 #include "snmp_pp/gauge.h"               // gauge class
  69 #include "snmp_pp/ctr64.h"               // 64 bit counters
  70 #include "snmp_pp/octet.h"               // octet class
  71 #include "snmp_pp/address.h"             // address class def
  72 #include "snmp_pp/integer.h"             // integer class
  73 #include "snmp_pp/snmperrs.h"
  74
  75 #ifdef SNMP_PP_NAMESPACE
  76 namespace Snmp_pp {
  77 #endif
  78
  79
  80 //------------[ VB Class Def ]-------------------------------------
  81 /**
  82  * The Vb class is the encapsulation of the SNMP variable binding.
  83  *
  84  * Variable binding lists in SNMP++ are represented as arrays of Vb
  85  * objects. Vb objects are passed to and from SNMP objects to provide
  86  * getting or setting MIB values.  The vb class keeps its own memory
  87  * for objects and does not utilize pointers to external data
  88  * structures.
  89  */
  90 class DLLOPT Vb
  91 {
  92  //-----[ public members ]
  93  public:
  94
  95   //-----[ constructors / destructors ]-------------------------------
  96
  97   /**
  98    * Constructor with no arguments.
  99    *
 100    * This constructor creates an unitialized vb.
 101    */
 102   Vb() : iv_vb_value(0), exception_status(SNMP_CLASS_SUCCESS) {};
 103
 104   /**
 105    * Constructor to initialize the oid.
 106    *
 107    * This constructor creates a vb with oid portion initialized.
 108    */
 109   Vb(const Oid &oid)
 110     : iv_vb_oid(oid), iv_vb_value(0), exception_status(SNMP_CLASS_SUCCESS) {};
 111
 112   /**
 113    * Copy constructor.
 114    */
 115   Vb(const Vb &vb) : iv_vb_value(0) { *this = vb; };
 116
 117   /**
 118    * Destructor that frees all allocated memory.
 119    */
 120   ~Vb() { free_vb(); };
 121
 122   /**
 123    * Overloaded assignment operator.
 124    */
 125   Vb& operator=(const Vb &vb);
 126
 127   /**
 128    * Clone operator.
 129    */
 130   Vb *clone( ) const { return new Vb(*this); };
 131
 132   //-----[ set oid / get oid ]------------------------------------------
 133
 134   /**
 135    * Set the oid from another oid.
 136    */
 137   void set_oid(const Oid &oid) { iv_vb_oid = oid; };
 138
 139   /**
 140    * Get the oid portion.
 141    *
 142    * @note Check the validity of the object through Vb::valid() before
 143    *       calling this method.
 144    */
 145   void get_oid(Oid &oid) const { oid = iv_vb_oid; };
 146
 147   /**
 148    * Get the oid portion as a const.
 149    *
 150    * @note Check the validity of the object through Vb::valid() before
 151    *       calling this method.
 152    */
 153   const Oid &get_oid() const { return iv_vb_oid; };
 154
 155   //-----[ set value ]--------------------------------------------------
 156
 157   /**
 158    * Set the value using any SnmpSyntax object.
 159    */
 160   void set_value(const SnmpSyntax &val)
 161     { free_vb(); iv_vb_value = val.clone(); };
 162
 163   /**
 164    * Set the value with an int.
 165    *
 166    * The syntax of the Vb will be set to SMI INT32.
 167    */
 168   void set_value(const int i) { free_vb(); iv_vb_value = new SnmpInt32(i); };
 169
 170   /**
 171    * Set the value with an unsigned int.
 172    *
 173    * The syntax of the Vb will be set to SMI UINT32.
 174    */
 175   void set_value(const unsigned int i)
 176     { free_vb(); iv_vb_value = new SnmpUInt32(i); };
 177
 178   /**
 179    * Set the value with a long int.
 180    *
 181    * @note Even on 64 bit platforms, only 32 bits are used
 182    *
 183    * The syntax of the Vb will be set to SMI INT32.
 184    */
 185   void set_value(const long i)
 186     { free_vb(); iv_vb_value = new SnmpInt32(i); };
 187
 188   /**
 189    * Set the value with an unsigned long int.
 190    *
 191    * @note Even on 64 bit platforms, only 32 bits are used
 192    *
 193    * The syntax of the Vb will be set to SMI UINT32.
 194    */
 195   void set_value(const unsigned long i)
 196     { free_vb(); iv_vb_value = new SnmpUInt32(i); };
 197
 198   /**
 199    * Set value using a null terminated string.
 200    *
 201    * The syntax of the Vb will be set to SMI octet.
 202    */
 203   void set_value(const char *ptr)
 204     { free_vb(); iv_vb_value = new OctetStr(ptr); };
 205
 206   /**
 207    * Set value using a string and length.
 208    *
 209    * The syntax of the Vb will be set to SMI octet.
 210    */
 211   void set_value(const unsigned char *ptr, const unsigned int len)
 212     { free_vb(); iv_vb_value = new OctetStr(ptr, len); };
 213
 214   /**
 215    * Set the value portion of the vb to null, if its not already.
 216    */
 217   void set_null() { free_vb(); };
 218
 219   //----[ get value ]------------------------------------------------
 220
 221   /**
 222    * Get the value using a SnmpSyntax object.
 223    *
 224    * @param val - An object of a subclass of SnmpSyntax that will be
 225    *              assigned the value of the vb.
 226    *
 227    * @return SNMP_CLASS_SUCCESS if the vb value could be assigned to
 228    *         the passed SnmpSyntax object, else SNMP_CLASS_INVALID.
 229    */
 230   int get_value(SnmpSyntax &val) const;
 231
 232   /**
 233    * Get the value.
 234    *
 235    * This method will only return success if the value of the vb is SMI INT32.
 236    *
 237    * @param i - returned value
 238    *
 239    * @return SNMP_CLASS_SUCCESS on success, else SNMP_CLASS_INVALID.
 240    */
 241   int get_value(int &i) const;
 242
 243   /**
 244    * Get the value.
 245    *
 246    * This method will only return success if the value of the vb can
 247    * be mapped to an unsigned long (SMI types uint32, counter32, gauge
 248    * and timeticks).
 249    *
 250    * @param i - returned value
 251    *
 252    * @return SNMP_CLASS_SUCCESS on success, else SNMP_CLASS_INVALID.
 253    */
 254   int get_value(unsigned int &i) const;
 255
 256   /**
 257    * Get the value.
 258    *
 259    * This method will only return success if the value of the vb is SMI INT32.
 260    *
 261    * @param i - returned value
 262    *
 263    * @return SNMP_CLASS_SUCCESS on success, else SNMP_CLASS_INVALID.
 264    */
 265   int get_value(long &i) const;
 266
 267   /**
 268    * Get the value.
 269    *
 270    * This method will only return success if the value of the vb can
 271    * be mapped to an unsigned long (SMI types uint32, counter32, gauge
 272    * and timeticks).
 273    *
 274    * @param i - returned value
 275    *
 276    * @return SNMP_CLASS_SUCCESS on success, else SNMP_CLASS_INVALID.
 277    */
 278   int get_value(unsigned long &i) const;
 279
 280   /**
 281    * Get the value.
 282    *
 283    * This method will only return success if the value of the vb is SMI OCTET.
 284    *
 285    * @note The caller must provide a target string big enough to
 286    *       handle the vb string. No length checks are done within
 287    *       this method. The returned string will be null terminated.
 288    *
 289    * @param ptr - Pointer to already allocated space to hold the vb
 290    *              value. The first char will be set to zero on failure.
 291    * @param len - Returned length of the string. Will be set to 0 on failure.
 292    *
 293    * @return SNMP_CLASS_SUCCESS on success, else SNMP_CLASS_INVALID.
 294    */
 295   int get_value(unsigned char *ptr, unsigned long &len) const;
 296
 297   /**
 298    * Get the value.
 299    *
 300    * This method will only return success if the value of the vb is SMI OCTET.
 301    *
 302    * @note If the target space is not big enough to hold the complete
 303    *       string only part of the string is copied.
 304    *
 305    * @param ptr    - Pointer to already allocated space to hold the vb
 306    *                 value. The first char will be set to zero on failure.
 307    * @param len    - Returned length of the string. Will be set to 0
 308    *                 on failure.
 309    * @param maxlen - Maximum length of the space that ptr points to.
 310    * @param add_null_byte - Add a null byte at end of output string.
 311    *
 312    *
 313    * @return SNMP_CLASS_SUCCESS on success, else SNMP_CLASS_INVALID.
 314    */
 315   int get_value(unsigned char *ptr,
 316                 unsigned long &len,
 317                 const unsigned long maxlen,
 318                 const bool add_null_byte = false) const;
 319
 320   /**
 321    * Get the value.
 322    *
 323    * This method will only return success if the value of the vb is SMI OCTET.
 324    *
 325    * @note The caller must provide a target string big enough to
 326    *       handle the vb string. No length checks are done within
 327    *       this method. The returned string will be null terminated.
 328    *
 329    * @param ptr - Pointer to already allocated space to hold the vb
 330    *              value. The first char will be set to zero on failure.
 331    *
 332    * @return SNMP_CLASS_SUCCESS on success, else SNMP_CLASS_INVALID.
 333    */
 334   int get_value(char *ptr) const;
 335
 336   /**
 337    * Clone the value portion of the variable binding.
 338    *
 339    * The returned pointer must be deleted by the caller.
 340    *
 341    * @return
 342    *    a pointer to a clone of the value of the receiver.
 343    */
 344   SnmpSyntax* clone_value() const
 345       { return ((iv_vb_value) ? iv_vb_value->clone() : 0); };
 346
 347
 348   //-----[ misc]--------------------------------------------------------
 349
 350   /**
 351    * Return the syntax or the exception status.
 352    *
 353    * @return If the SNMPv2 exception status is set, it is returned.
 354    *         otherwise the syntax of the value object is returned.
 355    */
 356   SmiUINT32 get_syntax() const;
 357
 358   /**
 359    * Set the syntax.
 360    *
 361    * The Value portion of the Vb will be deleted and a new value portion
 362    * is allocated with it's default value (zero).
 363    *
 364    * @param syntax - The new syntax.
 365    */
 366   void set_syntax(const SmiUINT32 syntax);
 367
 368   /**
 369    * Set the exception status.
 370    *
 371    * @param status - the new SNMPv2 exception status.
 372    */
 373   void set_exception_status(const SmiUINT32 status)
 374     { exception_status = status; };
 375
 376   /**
 377    * Get the exception status.
 378    */
 379   SmiUINT32 get_exception_status() const { return exception_status; };
 380
 381   /**
 382    * Return a formatted version of the value.
 383    *
 384    * @return A null terminated string (empty if no value).
 385    */
 386   const char *get_printable_value() const;
 387
 388   /**
 389    * Return a formatted version of the Oid.
 390    *
 391    * @return A null terminated string (may be empty if no Oid has been set).
 392    */
 393   const char *get_printable_oid() const
 394     { return iv_vb_oid.get_printable(); };
 395
 396   /**
 397    * Return the validity of a Vb object.
 398    *
 399    * @return TRUE if oid and value have been set.
 400    */
 401   bool valid() const;
 402
 403   /**
 404    * Return the space needed for serialization.
 405    *
 406    * @return the length of the BER encoding of this Vb.
 407    */
 408   int get_asn1_length() const;
 409
 410   /**
 411    * Reset the object.
 412    */
 413   void clear() { free_vb(); iv_vb_oid.clear(); };
 414
 415  //-----[ protected members ]
 416  protected:
 417   Oid iv_vb_oid;               // a vb is made up of a oid
 418   SnmpSyntax *iv_vb_value;     // and a value...
 419   SmiUINT32 exception_status;  // are there any vb exceptions??
 420
 421   /**
 422    * Free the value portion.
 423    */
 424   void free_vb();
 425 };
 426
 427 #ifdef SNMP_PP_NAMESPACE
 428 } // end of namespace Snmp_pp
 429 #endif
 430
 431 #endif