16. The Variable Binding Class

Object Modeling Technique (OMT) view of SNMP++ Variable Binding ( Vb) Class

The variable binding (Vb) class represents the encapsulation of a SNMP variable binding. A variable binding is the association of a SNMP object ID with its SMI value. In object oriented methodology, this is simply a has a relation. A Vb object has an Oid object and a SMI value. The Vb class allows the application programmer to instantiate Vb objects and assign the Oid portion (Vb::set_oid), and assign the value portion (Vb::set_value). Conversely, the Oid and value portions may be extracted using Vb::get_oid() and Vb::get_value() member functions. The public member functions Vb::set_value() and Vb::get_value() are overloaded to provide the ability to set or get different SMI values to the Vb binding. Variable binding lists in SNMP++ are represented as arrays of Vb objects. All SMI types are accommodated within the Vb Class. The Vb class provides full data hiding. The user does not need to know about SMI value types, Oid internal representations, or other related SNMP structures. The Vb class is fully portable using a standard ANSI C++ compiler.

16.1. Variable Binding Class Member Functions Overview

Variable Binding Class Member Functions	Description
Constructors
Vb( void);	Construct an empty Vb object.
Vb( const Oid &oid);	Construct a Vb with an Oid portion.
Vb( const Vb &vb);	Copy Constructor.
Destructor
~Vb();	Destroy a Vb, free up all resources.
Set Oid / Get Oid
void set_oid( const Oid &oid);	Set the Oid portion of a Vb.
void get_oid( Oid &oid) const;	Get the Oid portion.
Set Value
void set_value( const SMIValue &val);	Set the value to any other SmiValue.
void set_value( const int i);	Set the value to an integer.
void set_value( const long int i);	Set the value to a long integer.
void set_value( const unsigned long int i);	Set the value to an unsigned long integer.
void set_value( const char WINFAR * ptr);	Set the value to a null terminated string.
Get Value
int get_value( SMIValue &val);	Get the value, use any SmiValue.
int get_value( int &i);	Get an integer value.
int get_value( long int &i);	Get an signed long integer.
int get_value( unsigned long int &i);	Get an unsigned long integer.
int get_value( unsigned char WINFAR * ptr, unsigned long &len);	Get an unsigned char array, returns data and a len.
int get_value( unsigned char WINFAR * ptr, unsigned long &len, unsigned long maxlen);	Get a unsigned char array and a len, up to max len in size.
int get_value( char WINFAR *ptr);	Get a null terminated string.
Miscellaneous
SmiUINT32 get_syntax();	Returns SMI syntax.
char *get_printable_value();	Returns formatted value.
char *get_printable_oid();	Returns formatted Oid portion.
void set_null();	Sets a Vb object to hold a null value.
int valid();	Returns validity of a Vb.
Overloaded Operators
Vb& operator=( const Vb &vb);	Assign one Vb to another.

16.2. Vb Class Public Member Functions

The Vb class provides a variety of public member methods to access and modify Vb objects.

// A Vb object may be constructed with no arguments. In this case, the Oid and

// value portions must be set with subsequent member function calls.

// constructor with no arguments

// makes an Vb, un-initialized

Vb::Vb( void);

16.2.1.Vb Class Constructors & Destructors

// constructor to initialize the Oid

// makes a Vb with Oid portion initialized

Vb::Vb( const Oid oid);

Alternatively, a Vb object may be constructed with an Oid object as a construction parameter. This initializes the Oid part of the Vb object to the Oid passed in. The Vb object makes a copy of the Oid passed in. This saves the programmer from having to worry about the duration of the parameter Oid.

The destructor for a Vb object releases any memory and/or resources which were occupied. For statically defined objects, the destructor is called automatically when the object goes out of scope. Dynamically instantiated objects require usage of the delete construct to cause destruction.

// destructor

// if the Vb has a Oid or an octet string then

// the associated memory needs to be freed

Vb::~Vb();

16.2.2.Vb Class Get Oid / Set Oid Member Functions

The get and set Oid member functions allow getting or setting the Oid part of a Vb object. When doing SNMP gets or sets, the variable is identified by setting the Oid value of the Vb via the Vb::set_oid( Oid oid). Conversely, the Oid portion may be extracted via the Vb::get_oid( Oid &oid) member function. The get_oid member function is particularly useful when doing SNMP get next.

The Oid portion of a Vb object can be set with an already constructed Oid object

// set value Oid only with another Oid

void Vb::set_oid( const Oid &oid);

// get Oid portion

void Vb::get_oid( Oid &oid);

The Oid portion may be retrieved by providing a target Oid object. This destroys the previous value of the Oid object.

16.2.3.Vb Class Get Value / Set Value Member Functions

The get_value, set_value member functions allow getting or setting the value portion of a Vb object. These member functions are overloaded to provide getting or setting different types. The internal hidden mechanisms of getting or setting Vb’s handles all memory allocation/de-allocation. This frees the programmer from having to worry about SMI-value structures and their management. Get value member functions are typically used to get the value of a Vb object after having done a SNMP get. Set value member functions are useful when wishing to set values of Vb’s when doing a SNMP set. The get_value member functions return a -1 if the get does not match what the Vb is holding.

Set the value portion of a Vb object to an integer. This maps to an SMI INT.

// set the value with an int

void Vb::set_value( const int i);

Set the value portion of a Vb Object to a long integer. This maps to an SMI INT32.

// set the value with a long signed int

void Vb::set_value( const long int i);

Set the value portion of a Vb object to an unsigned long integer. This maps to an SMI UNIT32.

// set the value with an unsigned long int

void Vb::set_value( const unsigned long int i);

Set the value portion of a Vb to Gauge32 object. This maps to an SMI 32 bit gauge.

// set the value with a 32 bit gauge

void Vb::set_value( const Gauge32 gauge);

Set the value portion of a Vb object to a TimeTicks object. This maps to an SMI time ticks variable.

// set the value with a TimeTicks

void Vb::set_value( const TimeTicks timeticks);

Set the value portion of a Vb object to a Counter32 object. This maps to an SMI 32 bit counter.

// set value with a 32 bit counter

void Vb::set_value( const Counter32 counter);

Set the value portion of a Vb object to a Counter64 object. This is used for SMI 64 bit counters comprised of a hi and low 32 bit portion.

// set value to a 64 bit counter

void Vb::set_value( const Counter64 c64);

Set the value portion of a Vb object to an Oid.

// set value for setting an Oid

// creates own space for an Oid which

// needs to be freed when destroyed

void Vb::set_value( const Oid &varoid);

Set the value portion of a Vb object to a char string. Really, this internally uses the SMI value portion of an octet string but makes it easier to use when it is an ASCII string. (eg system descriptor)

// set value on a string

// makes the string an octet

// this must be a null terminates string

void Vb::set_value( const char * ptr);

Set the value portion of a Vb to an IP address object. This member function utilizes the Address class. IP address is a explicit SMI value type.

// set an IPAddress object as a value

void Vb::set_value ( const IpAddress ipaddr);

Set the value portion of a Vb to an IPX address object. This member function utilizes the Address class. IPX address is treated as an octet SMI value type.

// set an IPXaddress object as a value

void Vb::set_value ( const IpxAddress ipxaddr);

Set the value portion of a Vb to an MAC address object. This member function utilizes the Address class. MAC address is treated as an octet SMI value type.

// set an MAC address object as a value

void Vb::set_value ( const MacAddress macaddr);

16.2.4.Set the value to a GenAdress object.

// set an GenAddress object as a value

void Vb::set_value ( const GenAddress genaddr);

16.2.5.Set the value to a UdpAdress object.

// set an UdpAddress object as a value

void Vb::set_value ( const UdpAddress udpaddr);

// set an IpxSockAddress object as a value

void Vb::set_value ( const IpxSockAddress ipxsockaddr);

16.2.6.Set the value to a IpxSockAdress object.

16.2.7.Set the value portion of a Vb to an Octet object.

// set the value portion to a SNMP++ Octet object

void Vb::set_value( const OctetStr octet);

16.2.8.Vb Class Get Value Member Functions

All Vb::get_value member functions modify the parameter passed in. If a Vb object does not contain the requested parameter type, the parameter will not be modified and a SNMP_CLASS_INVALID will be returned. Otherwise on success, a SNMP_CLASS_SUCCESS status is returned.

Get an integer value from a Vb object.

// get value int

// returns 0 on success and value

int Vb::get_value( int &i);

Get a long integer from a Vb object.

// get the signed long int

int Vb::get_value( long int &i);

Get an unsigned long integer value from a Vb.

// get the unsigned long int

int Vb::get_value( unsigned long int &i);

// get a Gauge32

int Vb::get_value( Gauge32 &gauge);

Get a Gauge32 from a Vb object.

// get a TimeTicks from a Vb

int Vb:get_value( TimeTicks &timeticks);

Get a TimeTicks from a Vb object.

Get a Counter32 from a Vb object.

// get a counter from a Vb

int Vb::get_value(Counter32 &counter);

// get a 64 bit counter

int Vb::get_value( Counter64 &counter64);

Get a 64 bit counter from a Vb object.

Get an Oid object from a Vb object.

// get the Oid value

// free the existing Oid value

// copy in the new Oid value

int Vb::get_value( Oid &varoid);

Get an unsigned char string value from a Vb object ( Octet string).

// get a unsigned char string value

// destructive, copies into given ptr of up

// to len length

int Vb::get_value( unsigned char * ptr, unsigned long &len);

Get a char string from a Vb object. This grabs the octet string portion and pads it with a null.

// get a char * from an octet string

// the user must provide space or

// memory will be stepped on

int Vb::get_value( char *ptr);

Get a IP address Object from a Vb object. IpAddress is defined as an Address object.

// get an IPAddress

int Vb::get_value( IpAddress &ipaddr);

// get an IPXAddress

int Vb::get_value( IpxAddress &ipxaddr);

Get a IPX address Object from a Vb object. IpxAddress is defined as an Address object.

Get a MAC address Object from a Vb object. MacAddress is defined as an Address object.

// get an MAC address

int Vb::get_value( MacAddress &MACaddr);

Get a GenAddress Object from a Vb object. GenAddress is defined as an Address object.

// get an gen address

int Vb::get_value( GenAddress &genaddr);

Get a UdpAddress Object from a Vb object. UdpAddress is defined as an Address object.

// get an Udp address

int Vb::get_value( UdpAddress &Udpaddr);

Get a IpxSockAddress Object from a Vb object. IpxSockAddress is defined as an Address object.

// get an IpxSockAddress

int Vb::get_value( IpxSockAddress &IpxSockAddr);

Get an Octet Object from a Vb Object.

// get an Octet object from a Vb

int Vb::get_value( OctetStr, &octet);

16.2.9.Vb Object Get Syntax Member Function

// return the current syntax

// This method violates the OO paradigm but may be useful if

// the caller has a Vb object and does not know what it is.

// This would be useful in the implementation of a browser.

SmiUINT32 get_syntax();

This method violates the object oriented paradigm. An object knows what it is. By having a method which returns the id of an object violates its data hiding. Putting that aside, there are times when it may be necessary to know what value a Vb is holding to allow extracting that value. For example, when implementing a browser it would be necessary to grab a Vb, ask it what it has and then pull out whatever it may hold. Returned syntax values are SMI syntax value.

16.2.10. Vb Object Validation Check

An instantiated Vb object may be checked to determine if it is valid by invoking the Vb::valid() member functions. Valid Vbs are those which have been assigned an Oid.

// determine if a Vb object is valid

int Vb::valid();

16.2.11. Vb Object Assignment to Other Vb Objects

Vb objects may be assigned to one another using the overloaded assignment operator, =. This allows for easy assignment of one Vb object to another without having to interrogate a Vb object for its contents and then assign them manually to the target Vb object.

// overloaded Vb assignment

// assignment to another Vb object overloaded

Vb& operator=( const &Vb vb);

16.2.12. Vb Object Errors

When getting data from a variable binding object, Vb::get_value(), an error can occur based on the value the Vb has and the type of value you are requesting. For example, assume a Vb object has an OctetStr and you are attempting to get a TimeTicks object out of it. The Vb::get_value() will fail since a TimeTicks object cannot be returned. In the event an error occurs, the caller mat utilize Vb::get_syntax() to interrogate the Vb for its actual value or exception value.

Vb::get_value() return value	Description
SNMP_CLASS_SUCCESS	Success, requested value was returned.
SNMP_CLASS_INVALID	Error, Vb value does not hold requested value.

16.3. Vb Class Examples

#include “oid.h”

#include “vb.h”

vb_test()

{

// -------[Ways to construct Vb objects ]-------

// construct a single Vb object

Vb vb1;

// construct a Vb object with an Oid object

// this sets the Oid portion of the Vb

Oid d1(“1.3.6.1.4.12”);

Vb vb2(d1);

// construct a Vb object with a dotted string

Vb vb3( (Oid) “1.2.3.4.5.6”);

// construct an array of ten Vbs

Vb vbs[10];

//------[Ways to set and get the Oid portion of Vb objects ]

// set and get the Oid portion

Oid d2((Oid)“1.2.3.4.5.6”);

vb1.set_oid(d2);

Oid d3;

vb1.get_oid(d3);

if (d2==d3) cout << “They better be equal!!\n”;

Vb ten_vbs[10];

int z;

for (z=0;z<10;z++)

ten_vbs[0].set_oid((Oid)“1.2.3.4.5”);

//-------[ ways to set and get values ]

// set & get ints

int x,y;

x=5;

vb1.set_value(x);

vb1.get_value(y);

if ( x == y) cout << “x equals y\n”;

// set and get long ints

long int a,b;

a=100;

The following examples show different ways in which to use the Vb class. The Vb class does not require or depend on any other libraries or modules other than the Oid class. The following C++ code is ANSI compatible.

Vb Class Example Continued..

//-------[ ways to set and get values ]

if ( a == b) cout << “a equals b\n”;

// set & get unsigned long ints

unsigned long int c,d;

c = 1000;

vbs[0].set_value( c); vbs[0].get_value( d);

if ( c == d) cout << “c equals d\n”;

// set a 64 bit counter

Counter64 c64(1000,1001);

vbs[1].set_value( c64);

// get and set an oid as a value

Oid o1, o2;

o1 = “1.2.3.4.5.6”;

vbs[2].set_value( o1); vbs[2].get_value( o2);

if ( o1 == o2) cout << “o1 equals o2\n”;

// set and get an octet string

unsigned char data[4],outdata[4];

unsigned long len,outlen;

len =4; data[0] = 10; data[1] = 12; data[2] = 12; data[3] = 13;

OctetStr octetstr(data,len);

vbs[3].set_value( octetstr);

vbs[3].get_value( octetstr);

// get & set a string

char beer[80]; char good_beer[80];

strcpy( beer,”Sierra Nevada Pale Ale”);

vbs[4].set_value( beer);

vbs[4].get_value( good_beer);

printf(“Good Beer = %s\n”,good_beer);

// get and set an ip an address

IpAddress ipaddress1, ipaddress2;

ipaddress1 = “10.4.8.5”;

vbs[5].set_value( ipaddress1);

vbs[5].get_value( ipaddress2);

cout << ipaddress2;

} // end vb example