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