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