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

   1 /*_############################################################################
   2   _##
   3   _##  oid.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++ O I D. H
  47
  48   OID CLASS DEFINITION
  49
  50   DESIGN + AUTHOR:   Peter E Mellquist
  51
  52   DESCRIPTION:
  53   This class is fully contained and does not rely on or any other
  54   SNMP libraries. This class is portable across any platform
  55   which supports C++.
  56
  57 =====================================================================*/
  58 // $Id: oid.h 1775 2010-07-11 09:59:28Z katz $
  59
  60 #ifndef _OID_H_
  61 #define _OID_H_
  62
  63 //------------------------------------------------------------------------
  64
  65 #include "snmp_pp/smival.h"                // derived class for all values
  66 #include "snmp_pp/collect.h"
  67
  68 #ifdef SNMP_PP_NAMESPACE
  69 namespace Snmp_pp {
  70 #endif
  71
  72
  73 /**
  74  * The Object Identifier Class.
  75  *
  76  * The Object Identification (Oid) class is the encapsulation of an
  77  * SMI object identifier. The SMI object is a data identifier for a
  78  * data element found in a Management Information Base (MIB), as
  79  * defined by a MIB definition. The SMI Oid, its related structures
  80  * and functions, are a natural fit for object orientation. In fact,
  81  * the Oid class shares many common features to the C++ String
  82  * class. For those of you familiar with the C++ String class or
  83  * Microsoft's Foundation Classes (MFC) CString class, the Oid class
  84  * will be familiar and easy to use. The Oid class is designed to be
  85  * efficient and fast. The Oid class allows definition and
  86  * manipulation of object identifiers.
  87  *
  88  * @note Oid holds two internal buffers for get_printable() functions.
  89  *       The buffer returned by get_printable() is valid until the
  90  *       Oid object is modified. The functions get_printable(len) and
  91  *       get_printable(start, len) share the same buffer which is
  92  *       freed and newly allocated for each call.
  93  */
  94 class DLLOPT Oid : public SnmpSyntax
  95 {
  96  public:
  97
  98   /**
  99    * Construct an invalid Oid.
 100    */
 101   Oid();
 102
 103   /**
 104    * Construct an Oid from a string.
 105    *
 106    * Depending on the second param, the oid_string can either be
 107    * - a dotted oid string (like "1.3.6.1.6"). An arbitrary part
 108    *   of the oid can be given as a string value enclosed in
 109    *   '$' characters. For example the oid string
 110    *   "1.3.6.1.6.1.12.1.3.$public0$" will result to the oid
 111    *   1.3.6.1.6.1.12.1.3.112.117.98.108.105.99.95.48
 112    * - a normal string (like "public"). The Oid will have the
 113    *   ASCII values of the string characters. So "public" will
 114    *   result to the oid 112.117.98.108.105.99
 115    *
 116    * @param oid_string - for example "1.3.1.6.1.10"
 117    * @param is_dotted_oid_string - Select format within oid_string
 118    */
 119   Oid(const char *oid_string, const bool is_dotted_oid_string = true);
 120
 121   /**
 122    * Constructor using another oid object (copy constructor).
 123    *
 124    * @param oid - Source Oid
 125    */
 126   Oid(const Oid &oid);
 127
 128   /**
 129    * Constructor from array.
 130    *
 131    * @param raw_oid - array of oid values
 132    * @param oid_len - length of array
 133    */
 134   Oid(const unsigned long *raw_oid, int oid_len);
 135
 136   /**
 137    * Destructor.
 138    */
 139   virtual ~Oid();
 140
 141   /**
 142    * Return the current syntax.
 143    *
 144    * @return always sNMP_SYNTAX_OID
 145    */
 146   SmiUINT32 get_syntax() const { return sNMP_SYNTAX_OID; };
 147
 148   /**
 149    * Assignment from a string.
 150    *
 151    * @param dotted_oid_string - New value (for example "1.3.6.1.6.0");
 152    */
 153   virtual Oid& operator=(const char *dotted_oid_string);
 154
 155   /**
 156    * Assign one Oid to another.
 157    */
 158   virtual Oid& operator=(const Oid &oid);
 159
 160   /**
 161    * Return the space needed for serialization.
 162    */
 163   int get_asn1_length() const;
 164
 165   /**
 166    * Overloaded equal operator.
 167    */
 168   DLLOPT friend int operator==(const Oid &lhs, const Oid &rhs);
 169
 170   /**
 171    * Overloaded not equal operator.
 172    */
 173   DLLOPT friend int operator!=(const Oid &lhs, const Oid &rhs)
 174       { return (!(lhs == rhs)); };  // just invert ==
 175
 176   /**
 177    * Overloaded less than < operator.
 178    */
 179   DLLOPT friend int operator<(const Oid &lhs, const Oid &rhs);
 180
 181   /**
 182    * Overloaded less than <= operator.
 183    */
 184   DLLOPT friend int operator<=(const Oid &lhs, const Oid &rhs)
 185       { return ((lhs < rhs) || (lhs == rhs)); };
 186
 187   /**
 188    * Overloaded greater than > operator.
 189    */
 190   DLLOPT friend int operator>(const Oid &lhs, const Oid &rhs)
 191       { return (!(lhs <= rhs)); };  // just invert existing <=
 192
 193   /**
 194    * Overloaded greater than >= operator.
 195    */
 196   DLLOPT friend int operator>=(const Oid &lhs, const Oid &rhs)
 197       { return (!(lhs < rhs)); };  // just invert existing <
 198
 199   /**
 200    * Overloaded equal operator operator.
 201    */
 202   DLLOPT friend int operator==(const Oid &lhs, const char *rhs);
 203
 204   /**
 205    * Overloaded not equal operator.
 206    */
 207   DLLOPT friend int operator!=(const Oid &lhs, const char *rhs);
 208
 209   /**
 210    * Overloaded less than < operator.
 211    */
 212   DLLOPT friend int operator<(const Oid &lhs, const char *rhs);
 213
 214   /**
 215    * Overloaded less than <= operator.
 216    */
 217   DLLOPT friend int operator<=(const Oid &lhs, char *rhs);
 218
 219   /**
 220    * Overloaded greater than > operator.
 221    */
 222   DLLOPT friend int operator>(const Oid &lhs, const char *rhs);
 223
 224   /**
 225    * Overloaded greater than >= operator.
 226    */
 227   DLLOPT friend int operator>=(const Oid &lhs, const char *rhs);
 228
 229   /**
 230    * Overloaded operator +, Concatenate two Oids.
 231    */
 232   DLLOPT friend Oid operator +(const Oid &lhs, const Oid &rhs)
 233     { Oid tmp(lhs); tmp += rhs; return tmp;};
 234
 235   /**
 236    * Append operator, appends the dotted oid string.
 237    *
 238    * @param a - dotted oid string, for example "5.192.14.6"
 239    */
 240   Oid& operator+=(const char *a);
 241
 242   /**
 243    * Appends an int.
 244    *
 245    * @param i - Value to add at the end of the Oid
 246    */
 247   Oid& operator+=(const unsigned long i);
 248
 249   /**
 250    * Appends an Oid.
 251    *
 252    * @param o - Oid to add at the end
 253    */
 254   Oid& operator+=(const Oid &o);
 255
 256   /**
 257    * Allows element access as an array.
 258    * This method behaves like real array: if your index
 259    * is out of bounds, you're lost!
 260    *
 261    * @param index - valid index -- 0 to (len() - 1)
 262    *
 263    * @return Value on the given index
 264    */
 265   unsigned long &operator[](const unsigned int index)
 266     { m_changed = true; return smival.value.oid.ptr[index]; };
 267
 268   /**
 269    * Allows element access as an array for const objects.
 270    * This method behaves like real array: if your index
 271    * is out of bounds, you're lost!
 272    *
 273    * @param index - valid index -- 0 to (len() - 1)
 274    *
 275    * @return Value on the given position
 276    */
 277   unsigned long operator[](const unsigned int index) const
 278     { return (index >= len()) ? 0 : smival.value.oid.ptr[index]; };
 279
 280   /**
 281    * Get the WinSnmp oid part.
 282    * @note This method returns a pointer to internal data.
 283    *       If it is modified, the Oid changes too.
 284    *
 285    * @return pointer to the internal oid structure.
 286    */
 287   SmiLPOID oidval() { return (SmiLPOID) &smival.value.oid; };
 288
 289   /**
 290    * Set the data from raw form.
 291    *
 292    * @param raw_oid - Array of new values
 293    * @param oid_len - Length of the array raw_oid
 294    */
 295   void set_data(const unsigned long *raw_oid, const unsigned int oid_len);
 296
 297   /**
 298    * Set the data from raw form.
 299    *
 300    * @param str     - Array of new values (a string)
 301    * @param str_len - Length of the array raw_oid
 302    */
 303   void set_data(const char *str, const unsigned int str_len);
 304
 305   /**
 306    * Get the length of the oid.
 307    */
 308   unsigned long len() const { return smival.value.oid.len; };
 309
 310   /**
 311    * Trim off the rightmost values of an oid.
 312    *
 313    * @param n - Trim off n values from the right (default is one)
 314    */
 315   void trim(const unsigned long n = 1);
 316
 317   /**
 318    * Compare two Oids from the left in direction left-to-right.
 319    *
 320    * @param n - Subvalues to compare
 321    * @param o - The Oid to compare with
 322    *
 323    * @return 0 if equal / -1 if less / 1 if greater
 324    */
 325   int nCompare(const unsigned long n, const Oid &o) const;
 326
 327   /**
 328    * Return validity of the object.
 329    */
 330   bool valid() const { return (smival.value.oid.ptr ? true : false); };
 331
 332   /**
 333    * Get a printable ASCII string of the whole value.
 334    *
 335    * @return Dotted oid string (for example "1.3.6.1.6.0")
 336    */
 337   const char *get_printable() const
 338     { return get_printable(1, smival.value.oid.len, (char*&)iv_str); };
 339
 340   /**
 341    * Get a printable ASCII string of the right part of the value.
 342    *
 343    * @param n - positions to print, counted from right.
 344    *
 345    * @return Dotted oid string (for example "6.0")
 346    */
 347   const char *get_printable(const unsigned long n) const
 348     { return get_printable(smival.value.oid.len - n + 1, n, (char*&)iv_part_str); };
 349
 350   /**
 351    * Get a printable ASCII string of a part of the value.
 352    *
 353    * @param start - First position to print, starting with 1 (not zero!)
 354    * @param n - positions to print.
 355    * @param buffer - pointer to the returned buffer
 356    *
 357    * @note If buffer is not NULL, this function calls "delete [] buffer",
 358    *       a new buffer is allocated using "new" and the caller has
 359    *       to delete it.
 360    *
 361    * @return Dotted oid string (for example "3.6.1.6")
 362    */
 363   const char *get_printable(const unsigned long start,
 364                             const unsigned long n,
 365                             char *&buffer) const;
 366
 367   /**
 368    * Get a printable ASCII string of a part of the value.
 369    *
 370    * @param start - First position to print, starting with 1 (not zero!)
 371    * @param n - positions to print.
 372    *
 373    * @return Dotted oid string (for example "3.6.1.6")
 374    */
 375   const char *get_printable(const unsigned long start,
 376                             const unsigned long n) const
 377     { return get_printable(start, n, (char*&)iv_part_str); };
 378
 379   /**
 380    * Clone this object.
 381    *
 382    * @return Pointer to the newly created object (allocated through new).
 383    */
 384   SnmpSyntax *clone() const { return (SnmpSyntax *) new Oid(*this); };
 385
 386   /**
 387    * Map other SnmpSyntax objects to Oid.
 388    */
 389   SnmpSyntax& operator=(const SnmpSyntax &val);
 390
 391   /**
 392    * Clear the Oid.
 393    */
 394   void clear() { delete_oid_ptr(); };
 395
 396  protected:
 397   /**
 398    * Convert a string to an smi oid.
 399    *
 400    * @param string - input string
 401    * @param dstOid - destination oid
 402    */
 403   virtual int StrToOid(const char *string, SmiLPOID dstOid) const;
 404
 405   /**
 406    * Clone an smi oid.
 407    *
 408    * @param srcOid - source oid
 409    * @param dstOid - destination oid
 410    */
 411   virtual int OidCopy(SmiLPOID srcOid, SmiLPOID dstOid) const;
 412
 413   /**
 414    * Convert an smi oid to its string representation.
 415    *
 416    * @param srcOid - source oid
 417    * @param size   - size of string
 418    * @param string - pointer to string
 419    */
 420   virtual int OidToStr(const SmiOID *srcOid,
 421                        SmiUINT32 size,
 422                        char *string) const;
 423
 424   /**
 425    * Free the internal oid pointer and set the pointer and the length to zero.
 426    */
 427   inline void delete_oid_ptr();
 428
 429   //----[ instance variables ]
 430
 431   SNMP_PP_MUTABLE char *iv_str;      // used for returning complete oid string
 432   SNMP_PP_MUTABLE char *iv_part_str; // used for returning part oid string
 433   SNMP_PP_MUTABLE bool m_changed;
 434 };
 435
 436 //-----------[ End Oid Class ]-------------------------------------
 437
 438 // create OidCollection type
 439 typedef SnmpCollection <Oid> OidCollection;
 440
 441 inline void Oid::delete_oid_ptr()
 442 {
 443   // delete the old value
 444   if (smival.value.oid.ptr)
 445   {
 446     delete [] smival.value.oid.ptr;
 447     smival.value.oid.ptr = 0;
 448   }
 449   smival.value.oid.len = 0;
 450   m_changed = true;
 451 }
 452
 453 #ifdef SNMP_PP_NAMESPACE
 454 } // end of namespace Snmp_pp
 455 #endif
 456
 457 #endif //_OID_H_