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

   1 /*_############################################################################
   2   _##
   3   _##  octet.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 C T E T . H
  47
  48   OCTETSTR 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 // $Id: octet.h 1824 2010-08-29 19:47:08Z katz $
  58
  59 #ifndef _OCTET_CLS
  60 #define _OCTET_CLS
  61
  62 #include "snmp_pp/smival.h"
  63
  64 #ifdef SNMP_PP_NAMESPACE
  65 namespace Snmp_pp {
  66 #endif
  67
  68 //------------[ SNMP++ OCTETSTR CLASS DEF  ]-----------------------------
  69 class DLLOPT OctetStr: public  SnmpSyntax
  70 {
  71  public:
  72
  73   /**
  74    * Enum for setting the hex output format.
  75    */
  76   enum OutputType
  77   {
  78     OutputHexAndClear,
  79     OutputHex,
  80     OutputClear
  81   };
  82
  83   //-----------[ Constructors and Destrucotr ]----------------------
  84
  85   /**
  86    * Constructs a valid OctetStr with zero length.
  87    */
  88   OctetStr();
  89
  90   /**
  91    * Constructs a OctetStr with the given value.
  92    * The OctetStr will be valid unless a call to new fails.
  93    *
  94    * @param str - Null terminated string
  95    */
  96   OctetStr(const char *str);
  97
  98   /**
  99    * Constructs a OctetStr with the given value.
 100    * The OctetStr will be valid unless a call to new fails.
 101    *
 102    * @param str - string that may contain null bytes
 103    * @param len - length of the string
 104    */
 105   OctetStr(const unsigned char *str, unsigned long len);
 106
 107   /**
 108    * Construct a OctetStr from another OctetStr.
 109    * The OctetStr will be valid unless a call to new fails.
 110    *
 111    * @param octet - Value for the new object
 112    */
 113   OctetStr(const OctetStr &octet);
 114
 115   /**
 116    * Destructor, frees allocated space.
 117    */
 118   ~OctetStr();
 119
 120   //-----------[ Overloaded operators ]----------------------
 121
 122   /**
 123    * Assign a char string to a OctetStr.
 124    */
 125   OctetStr& operator=(const char *str);
 126
 127   /**
 128    * Assign a OctetStr to a OctetStr.
 129    */
 130   OctetStr& operator=(const OctetStr &octet);
 131
 132   /**
 133    * Equal operator for two OctetStr.
 134    */
 135   DLLOPT friend int operator==(const OctetStr &lhs, const OctetStr &rhs);
 136
 137   /**
 138    * Not equal operator for two OctetStr.
 139    */
 140   DLLOPT friend int operator!=(const OctetStr &lhs, const OctetStr &rhs);
 141
 142   /**
 143    * Not equal operator for two OctetStr.
 144    */
 145   DLLOPT friend int operator<(const OctetStr &lhs, const OctetStr &rhs);
 146
 147   /**
 148    * Less than operator for two OctetStr.
 149    */
 150   DLLOPT friend int operator<=(const OctetStr &lhs,const OctetStr &rhs);
 151
 152   /**
 153    * Greater than operator for two OctetStr.
 154    */
 155   DLLOPT friend int operator>(const OctetStr &lhs, const OctetStr &rhs);
 156
 157   /**
 158    * Greater than or equal operator for two OctetStr.
 159    */
 160   DLLOPT friend int operator>=(const OctetStr &lhs, const OctetStr &rhs);
 161
 162   /**
 163    * Equal operator for OctetStr and char string.
 164    */
 165   DLLOPT friend int operator==(const OctetStr &lhs, const char *rhs);
 166
 167   /**
 168    * Not equal operator for OctetStr and char string.
 169    */
 170   DLLOPT friend int operator!=(const OctetStr &lhs, const char *rhs);
 171
 172   /**
 173    * Less than operator for OctetStr and char string.
 174    */
 175   DLLOPT friend int operator<(const OctetStr &lhs, const char *rhs);
 176
 177   /**
 178    * Less than or equal operator for OctetStr and char string.
 179    */
 180   DLLOPT friend int operator<=(const OctetStr &lhs, const char *rhs);
 181
 182   /**
 183    * Greater than operator for OctetStr and char string.
 184    */
 185   DLLOPT friend int operator>(const OctetStr &lhs, const char *rhs);
 186
 187   /**
 188    * Greater than or equal operator for OctetStr and char string.
 189    */
 190   DLLOPT friend int operator>=(const OctetStr &lhs, const char *rhs);
 191
 192   /**
 193    * Append a char string to this OctetStr.
 194    */
 195   OctetStr& operator+=(const char *a);
 196
 197   /**
 198    * Append a single char to this OctetStr.
 199    */
 200   OctetStr& operator+=(const unsigned char c);
 201
 202   /**
 203    * Append another OctetStr to this OctetStr.
 204    */
 205   OctetStr& operator+=(const OctetStr& octet);
 206
 207   /**
 208    * Allow access as if it was an array.
 209    *
 210    * @note The given param is not checked for validity.
 211    */
 212   unsigned char &operator[](int i)
 213     { m_changed = true; return smival.value.string.ptr[i]; };
 214
 215   /**
 216    * Allow access as if it was an array for const OctetStr objects.
 217    *
 218    * @note The given param is not checked for validity.
 219    */
 220   unsigned char operator[](int i) const { return smival.value.string.ptr[i]; };
 221
 222   /**
 223    * Return the syntax.
 224    *
 225    * @return This method always returns sNMP_SYNTAX_OCTETS.
 226    */
 227   SmiUINT32 get_syntax() const { return sNMP_SYNTAX_OCTETS; };
 228
 229   /**
 230    * Return the space needed for serialization.
 231    */
 232   int get_asn1_length() const;
 233
 234   /**
 235    * Return validity of the object.
 236    */
 237   bool valid() const { return validity; };
 238
 239   /**
 240    * Clone this object.
 241    *
 242    * @return Pointer to the newly created object (allocated through new).
 243    */
 244   SnmpSyntax *clone() const { return (SnmpSyntax *) new OctetStr(*this); };
 245
 246   /**
 247    * Map other SnmpSyntax objects to OctetStr.
 248    */
 249   SnmpSyntax& operator=(const SnmpSyntax &val);
 250
 251   /**
 252    * Get a printable ASCII value of the string.
 253    *
 254    * @note Depending on the selected output format, this method will
 255    *       return get_printable_hex() or get_printable_clear() if the
 256    *       string contains not printable characters.
 257    *
 258    * @return Printable, null terminated string
 259    */
 260   const char *get_printable() const;
 261
 262   /**
 263    * Get an ASCII formatted hex dump of the contents.
 264    * If the output format was set to OctetStr::OutputHexAndClear,
 265    * the produced string of this method will look like this:
 266    *                                                                     <pre>
 267    * 09 4F 63 74 65 74 53 74 72 3A 3A 67 65 74 5F 70    .OctetStr::get_p
 268    * 72 69 6E 74 61 62 6C 65 5F 68 65 78 28 29          rintable_hex()
 269    *                                                                     </pre>
 270    * If the output format was set to OctetStr::OutputHex the
 271    * produced string will look like this:
 272    *                                                                     <pre>
 273    * 09 4F 63 74 65 74 53 74 72 3A 3A 67 65 74 5F 70
 274    * 72 69 6E 74 61 62 6C 65 5F 68 65 78 28 29
 275    *                                                                     </pre>
 276    * @return Printable, null terminated string.
 277    */
 278   const char *get_printable_hex() const;
 279
 280   /**
 281    * Get the contents with all non printable characters replaced.
 282    *
 283    * @return Printable, null terminated string.
 284    */
 285   const char *get_printable_clear() const;
 286
 287   /**
 288    * Set the output format for get_pritable_hex().
 289    */
 290   static void set_hex_output_type(const enum OutputType ot)
 291     { hex_output_type = ot; };
 292
 293   /**
 294    * Set the char get_printable_hex() and get_printable_clear()
 295    * will use for non printable characters.
 296    */
 297   static void set_np_char(const char np) { nonprintable_char = np; };
 298
 299   /**
 300    * Set the data on an already constructed OctetStr.
 301    * The given string is copied to an internal member var, so the
 302    * params can be destroyed afterwards.
 303    *
 304    * @param str - The new string value
 305    * @param len - Length of the given string
 306    */
 307   void set_data(const unsigned char *str, unsigned long len);
 308
 309   /**
 310    * Get the length of the string.
 311    */
 312   unsigned long len() const { return smival.value.string.len; };
 313
 314   /**
 315    * Get a pointer to internal data.
 316    */
 317   unsigned char *data() const { return smival.value.string.ptr; };
 318
 319   // compare n elements of an octet
 320   int nCompare(const unsigned long n, const OctetStr &o) const;
 321
 322   /**
 323    * Build an OctetStr from a hex string.
 324    * Called with "5465  737469 6e672074686973206D657468 6f 64 21"
 325    * the returned value will be "Testing this method!"
 326    *
 327    * @param hex_string - The hex string (may contain spaces)
 328    * @return created string
 329    */
 330   static OctetStr from_hex_string(const OctetStr &hex_string);
 331
 332   /**
 333    * Set the character for linefeeds in get_printable() functions.
 334    *
 335    * The default linefeeds are \n for Unix and \r\n on other systems.
 336    *
 337    * @param lf_chars - string less than 3 bytes
 338    * @return true on success
 339    */
 340   static bool set_linefeed_chars(const char* lf_chars);
 341
 342   /**
 343    * Null out the contents of the string. The string will be empty
 344    * after calling this method
 345    */
 346   void clear();
 347
 348   /**
 349    * Append or shorten the internal data buffer.
 350    *
 351    * The buffer will either be shortened or extended. In the second case
 352    * zeroes are added to the end of the string.
 353    *
 354    * @param new_len - The new length for the string
 355    * @return true on success
 356    */
 357   bool set_len(const unsigned long new_len);
 358
 359  protected:
 360
 361   enum OutputFunction
 362   {
 363       OutputFunctionDefault,
 364       OutputFunctionHex,
 365       OutputFunctionClear
 366   };
 367
 368   SNMP_PP_MUTABLE char *output_buffer;   // formatted Octet value
 369   SNMP_PP_MUTABLE unsigned int output_buffer_len; // allocated space for string
 370   SNMP_PP_MUTABLE bool m_changed;
 371   SNMP_PP_MUTABLE enum OutputType output_last_type;
 372   SNMP_PP_MUTABLE char output_last_np_char;
 373   SNMP_PP_MUTABLE enum OutputFunction output_last_function;
 374
 375
 376   bool validity;                         // validity boolean
 377
 378   static enum OutputType hex_output_type;
 379   static char nonprintable_char;
 380   static char linefeed_chars[3];
 381 };
 382
 383 //-----------[ End OctetStr Class ]-------------------------------------
 384
 385 /**
 386  * The OpaqueStr class represents the Opaque SNMP type. It is derived from
 387  * the SNMP++ class OctetStr and has the same interfaces and behavior,
 388  * except that its syntax is sNMP_SYNTAX_OPAQUE.
 389  */
 390 class OpaqueStr: public OctetStr
 391 {
 392  public:
 393   /**
 394    * Constructor creating a valid zero length OpaqueStr.
 395    */
 396   OpaqueStr(): OctetStr()
 397     { smival.syntax = sNMP_SYNTAX_OPAQUE; };
 398
 399   /**
 400    * Constructs a OpaqueStr with the given value.
 401    * The OpaqueStr will be valid unless a call to new fails.
 402    *
 403    * @param str - Null terminated string
 404    */
 405   OpaqueStr(const char *str) : OctetStr(str)
 406     { smival.syntax = sNMP_SYNTAX_OPAQUE; };
 407
 408   /**
 409    * Constructs a OpaqueStr with the given value.
 410    * The OpaqueStr will be valid unless a call to new fails.
 411    *
 412    * @param str - string that may contain null bytes
 413    * @param len - length of the string
 414    */
 415   OpaqueStr(const unsigned char *str, unsigned long length)
 416     : OctetStr(str, length) { smival.syntax = sNMP_SYNTAX_OPAQUE; };
 417
 418   /**
 419    * Construct a OpaqueStr from an OctetStr.
 420    * The OpaqueStr will be valid unless a call to new fails.
 421    *
 422    * @param octet - Value for the new object
 423    */
 424   OpaqueStr(const OctetStr &octet) : OctetStr(octet)
 425     { smival.syntax = sNMP_SYNTAX_OPAQUE; };
 426
 427   /**
 428    * Construct a OpaqueStr from another OpaqueStr.
 429    * The OpaqueStr will be valid unless a call to new fails.
 430    *
 431    * @param opaque - Value for the new object
 432    */
 433   OpaqueStr(const OpaqueStr& opaque) : OctetStr(opaque)
 434     { smival.syntax = sNMP_SYNTAX_OPAQUE; };
 435
 436   /**
 437    * Clone this object.
 438    *
 439    * @return Pointer to the newly created object (allocated through new).
 440    */
 441   virtual SnmpSyntax *clone() const { return new OpaqueStr(*this); }
 442
 443   /**
 444    * Return the syntax.
 445    *
 446    * @return This method always returns sNMP_SYNTAX_OPAQUE.
 447    */
 448   virtual SmiUINT32 get_syntax() const { return sNMP_SYNTAX_OPAQUE; };
 449
 450   /**
 451    * Map other SnmpSyntax objects to OpaqueStr.
 452    */
 453   SnmpSyntax& operator=(const SnmpSyntax &val)
 454    { return OctetStr::operator=(val); }
 455
 456 };
 457
 458 #ifdef SNMP_PP_NAMESPACE
 459 } // end of namespace Snmp_pp
 460 #endif
 461
 462 #endif // _OCTET_CLS