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

   1 /*_############################################################################
   2   _##
   3   _##  v3.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 // $Id: v3.h 288 2007-03-22 22:37:09Z katz $
  30
  31 #ifndef _V3_H
  32 #define _V3_H
  33
  34 #include <stdio.h>
  35 #include <stdarg.h>
  36
  37 #include "snmp_pp/config_snmp_pp.h"
  38
  39 #ifdef SNMP_PP_NAMESPACE
  40 namespace Snmp_pp {
  41 #endif
  42
  43 class OctetStr;
  44
  45 #ifndef TRUE
  46 #define TRUE 1
  47 #endif
  48
  49 #ifndef FALSE
  50 #define FALSE 0
  51 #endif
  52
  53 /** @name SNMPv3 Security Model values
  54  */
  55 //@{
  56 #define SNMP_SECURITY_MODEL_ANY  0 //!< Not used in SNMP++.
  57 #define SNMP_SECURITY_MODEL_V1   1 //!< Can be used for SNMPv1 only.
  58 #define SNMP_SECURITY_MODEL_V2   2 //!< Can be used for SNMPv2 only.
  59 #define SNMP_SECURITY_MODEL_USM  3 //!< Can be used for SNMPv3 only.
  60 //@}
  61
  62 /**
  63  * Set the amount of log messages you want to get. To disable all
  64  * messages, set the level to -1
  65  *
  66  * @param db_level - New level
  67  */
  68 DLLOPT void debug_set_level(const int db_level);
  69
  70 #ifdef _DEBUG
  71
  72 /**
  73  * SNMP++ logging function.
  74  *
  75  * The default is to log all messages with a level < 19. To change
  76  * that either edit v3.cpp or use a "extern unsigned int debug_level"
  77  * to change the level.
  78  *
  79  * @param db_level - Priority of the message (0 = high)
  80  * @param format   - Just like printf
  81  */
  82 DLLOPT void debugprintf(int db_level, const char *format, ...);
  83
  84 /**
  85  * SNMP++ logging function for hex strings.
  86  *
  87  * @param db_level - Priority of the message (0 = high)
  88  * @param comment  - Comment printed before the hex dump (may be 0)
  89  * @param data     - pointer to the hex data
  90  * @param len      - length of the hex data
  91  */
  92 DLLOPT void debughexcprintf(int db_level, const char* comment,
  93                             const unsigned char *data, const unsigned int len);
  94
  95 //! Wrapper for debughexcprintf() without comment.
  96 #define debughexprintf(db_level, data, len) \
  97                       debughexcprintf(db_level, NULL, data, len);
  98
  99 #else
 100
 101 #ifndef _MSC_VER
 102 #if defined(__GNUC__) && !defined(__STRICT_ANSI__)
 103 #define debugprintf(db_level,format...)
 104 #else
 105 void debugprintf(int db_level, const char *format, ...);
 106 #endif
 107 #else
 108 // disable any warning for wrong number of arguments in macro
 109 #pragma warning(disable:4002)
 110 #define debugprintf(db_level,format)
 111 #endif //_MSC_VER
 112
 113 #define debughexprintf( db_level,          data, len)
 114 #define debughexcprintf(db_level, comment, data, len)
 115
 116 #endif
 117
 118 #ifdef _SNMPv3
 119
 120 #define MAXLENGTH_ENGINEID       32
 121 #define MAXLENGTH_CONTEXT_NAME   32
 122 #define MAXLENGTH_FILENAME       255
 123 #define MAXLENGTH_GLOBALDATA     42 // (2 + 1) + 7 + 7 + 3 + 7 + security
 124
 125 #define oidV3SnmpEngine                 "1.3.6.1.6.3.10.2.1"
 126 #define oidV3SnmpEngineID               "1.3.6.1.6.3.10.2.1.1.0"
 127 #define oidV3SnmpEngineBoots            "1.3.6.1.6.3.10.2.1.2.0"
 128 #define oidV3SnmpEngineTime             "1.3.6.1.6.3.10.2.1.3.0"
 129 #define oidV3SnmpEngineMaxMessageSize   "1.3.6.1.6.3.10.2.1.4.0"
 130
 131 // also defined in agent++/include/vacm.h
 132 #ifndef oidSnmpUnavailableContexts
 133 #define oidSnmpUnavailableContexts        "1.3.6.1.6.3.12.1.4.0"
 134 #define oidSnmpUnknownContexts            "1.3.6.1.6.3.12.1.5.0"
 135 #endif
 136
 137 /** @name Error codes (storing engineBoots)
 138  *
 139  * These values are returned by getBootCounter() and saveBootCounter().
 140  */
 141 //@{
 142 #define SNMPv3_OK                 0 //!< No error
 143 #define SNMPv3_NO_ENTRY_ERROR    -1 //!< No line for the engine id found
 144 #define SNMPv3_FILEOPEN_ERROR    -2 //!< Unable to open file
 145 #define SNMPv3_TOO_LONG_ERROR    -3 //!< The given engineID is too long
 146 #define SNMPv3_FILE_ERROR        -4 //!< The given file contains a wrong line
 147 #define SNMPv3_FILECREATE_ERROR  -5 //!< The File could not be created
 148 #define SNMPv3_FILERENAME_ERROR  -6 //!< Error renaming the temporary file
 149 //@}
 150
 151 /**
 152  * Compare two strings.
 153  *
 154  * @param str1    - The first byte array
 155  * @param ptr1len - Length of first array
 156  * @param str2    - The second byte array
 157  * @param ptr2len - Length of second array
 158  *
 159  * @return 1 if the strings are identical, 0 if not.
 160  */
 161 DLLOPT int unsignedCharCompare(const unsigned char *str1,
 162                                const long int ptr1len,
 163                                const unsigned char *str2,
 164                                const long int ptr2len);
 165
 166 /**
 167  * String copy function.
 168  *
 169  * @note The returned string has to be deleted with "delete []".
 170  *
 171  * @param src    - Source string
 172  * @param srclen - Length of source string
 173  *
 174  * @return Pointer to a null terminated copy of src (or 0 on error).
 175  */
 176 DLLOPT unsigned char *v3strcpy(const unsigned char *src, const int srclen);
 177
 178 /**
 179  * Encode the given string into the output buffer. For each byte
 180  * of the string two bytes in the output buffer are used. The
 181  * output buffer will contain chars from 0x64 to 0x79.
 182  *
 183  * @param in        - The string (for example engine id) to encode
 184  * @param in_length - The length of the engineID
 185  * @param out       - The output buffer for the encoded string, must have
 186  *                    lenth 2 * in_length
 187  */
 188 DLLOPT void encodeString(const unsigned char* in, const int in_length,
 189                          char* out);
 190
 191 /**
 192  * Decode the given encoded string into the output buffer.
 193  *
 194  * @param in        - The encoded string
 195  * @param in_length - The length of the encoded string
 196  * @param out       - Buffer for the decoded string (half size of input
 197  *                    string). The String will be null terminated.
 198  */
 199 DLLOPT void decodeString(const unsigned char* in, const int in_length,
 200                          char* out);
 201
 202 /**
 203  * Read the bootCounter of the given engineID stored in the given file.
 204  *
 205  * @param fileName - The name of the file
 206  * @param engineId - Read the bootCounter for this enigneID
 207  * @param boot     - OUT: the bootCounter that was read
 208  *
 209  * @return One of SNMPv3_OK, SNMPv3_TOO_LONG_ERROR, SNMPv3_FILE_ERROR,
 210  *         SNMPv3_NO_ENTRY_ERROR, SNMPv3_FILEOPEN_ERROR
 211  *
 212  */
 213 DLLOPT int getBootCounter(const char *fileName,
 214                           const OctetStr &engineId, unsigned int &boot);
 215
 216 /**
 217  * Store the bootCounter of the given engineID in the given file.
 218  *
 219  * @param fileName - The name of the file
 220  * @param engineId - Store the bootCounter for this enigneID
 221  * @param boot     - The bootCounter
 222  *
 223  * @return One of SNMPv3_OK, SNMPv3_FILEOPEN_ERROR, SNMPv3_FILECREATE_ERROR,
 224  *         SNMPv3_FILERENAME_ERROR.
 225  *
 226  */
 227 DLLOPT int saveBootCounter(const char *fileName,
 228                            const OctetStr &engineId, const unsigned int boot);
 229
 230
 231 #endif // _SNMPv3
 232
 233 /**
 234  * Tool class for easy allocation of buffer space.
 235  */
 236 template <class T> class Buffer
 237 {
 238  public:
 239     /// Constructor: Allocate a buffer for size objects.
 240     Buffer(const unsigned int size)
 241     {
 242         ptr = new T[size];
 243         if (ptr)
 244           len = size;
 245         else
 246           len = 0;
 247     }
 248
 249     /// Destructor: Free allocated buffer
 250     ~Buffer()
 251      {
 252          if (ptr) delete [] ptr;
 253      }
 254
 255     /// Get the buffer pointer
 256     T *get_ptr()
 257     {
 258         return ptr;
 259     }
 260
 261     /// Overwrite the buffer space with zero.
 262     void clear()
 263     {
 264         if (ptr)
 265             memset(ptr, 0, len * sizeof(T));
 266     }
 267
 268  private:
 269     T *ptr;
 270     unsigned int len;
 271 };
 272
 273 // only for compatibility do not use these values:
 274 #define SecurityModel_any SNMP_SECURITY_MODEL_ANY
 275 #define SecurityModel_v1  SNMP_SECURITY_MODEL_V1
 276 #define SecurityModel_v2  SNMP_SECURITY_MODEL_V2
 277 #define SecurityModel_USM SNMP_SECURITY_MODEL_USM
 278
 279 #ifdef SNMP_PP_NAMESPACE
 280 } // end of namespace Snmp_pp
 281 #endif
 282
 283 #endif // _V3_H