The Variable Objects

Introduction

SNMP and AgentX are all about variables, and how to obtain or alter their values. In agentXcpp, variables are represented by objects which implement the AbstractVariable interface. The library provides some classes such as IntegerVariable and OctetStringVariable, all implementing AbstractVariable. These classes can directly be instantiated to serve as read-only variables (they do not support SNMP Set requests), and their value can be obtained with value() and altered with setValue().

However, it is normally more useful to derive from these classes and reimplement perform_get(), so that the value can be obtained in the moment a Get request occurs. Also, the perform_testset(), perform_commitset(), perform_undoset() and perform_cleanupset() methods can be reimplemented to add write support.

How SNMP Get requests are served

Each variable has an internal member to store its value, e.g. IntegerVariable::v. This value can be read with value() and set with setValue(). The perform_get() method is called by the library when an SNMP Get is requested for the variable. This method should then update the value to reflect the current state. The default perform_get() implementation does nothing and thus allows to read the value as set by the last call to setValue(). This makes it possible to use the Variable class without inheriting.

Note

It is currently not possible to inhibit Get requests, i.e. it is not possible to implement write-only variables.

How Get requests are handled internally

When the MasterProxy object receives a Get (or GetNext) request, it looks up the variable registered with the requested OID. This works even for variables which are part of a table, because the Table class registers its variables like any other variable. Then the MasterProxy invokes the variable's AbstractVariable::handle_get() method to update the value of the variable. After that, it adds the variable to a Varbind object which is then embedded into the response and sent back to the master agent (possibly with further varbinds).

The variable's AbstractVariable::handle_get() method is implemented in the subclasses. It first calls perform_get() to update the internally stored value. The default implementation of perform_get() does nothing, but can be overridden by subclasses.

How SNMP Set requests are served

Each variable provides the functions perform_testset(), perform_commitset(), perform_cleanupset() and perform_undoset(), which are called while processing an SNMP Set request for the variable (see also The anatomy of a Set request). Each of these functions takes the new value as parameter (e.g. an qint32 value for IntegerVariable). The functions should then act as described in The anatomy of a Set request, returning success or failure. It is not required that the functions update the internal member, because on Set request a subagent does not send the new state back to the master agent.

The default implementation of the Set-supporting methods is to fail with AbstractVariable::noAccess, indicating that the variable is read-only. It is required to reimplement the methods in a derived class to enable write support.

How Set requests are handled internally

When the MasterProxy object receives a TestSet, CommitSet, CleanupSet or UndoSet request, it looks up the variable corresponding to the given OID and calls its AbstractVariable::handle_testset(), AbstractVariable::handle_commitset(), AbstractVariable::handle_cleanupset() or AbstractVariable::handle_undoset() method, respectively. These methods are implemented in the subclasses of AbstractVariable. The first one, handle_testset(), is the only one which receives new new value, in form of a pointer to AbstractVariable, and stores it internally for later use. The other three methods then use the stored pointer to obtain access to the new value.

In particular, the handle_testset() method converts the pointer to AbstractVariable into a pointer to the more concrete class (e.g. Gauge32Variable and stores it. Then, it calls the perform_testset() method. The handle_commitset() handle_cleanupset() and handle_undoset() methods only call perform_commitset(), perform_cleanupset() and perform_undoset(), respectively.

The default implementation of perform_testset() returns AbstractVariable::noAccess to indicate that the variable is read-only. The method can be overridden by subclasses to enable write support. The default implementations of perform_commitset(), perform_cleanupset() and perform_undoset() all return false to indicate an error.

Serializing and Parsing Variables

The AbstractVariable interface provides the AbstractVariable::serialize() function to serialize a variable object. Parsing is done using parse constructors. This is the same mechanism as used by the PDU classes. See The PDU Objects for a general explanation.