Tutorial for Visual xAgentBuilder for C++
Lesson 9: Read-write Scalar Object in the Agent
In this tutorial we are going to add one more scalar object to the agent. This time it will be read-write object garageAddress as we are going to see handling of the SET request. Here is the definition of the garageAddress
garageAddress OBJECT-TYPE
SYNTAX DisplayString (SIZE(0..32))
MAX-ACCESS read-write
STATUS current
DESCRIPTION “Garage address. E.g. 10
St, SomePlace.”
::= { garageObjects 1 }
MAX-ACCESS for this object is read-write, and that means that we have to provide both OnGet and OnSet methods. Handling of this object is implemented in the same Garage class. As we mentioned in the previous lesson, we can group all scalar objects that are direct children of the same branch node into the class derived from BMibScalarGroupImpl. Both garageAddress and garageAddress are direct children of the garage.
New data member
BString m_strAddress;
keeps the address of the garage.
GET request is handled in OnGet_GarageAddress:
SNMP_ERRSTAT OnGet_GarageAddress(tUint32
transactionId, BString& strVal)
{
strVal = m_strAddress;
return eSNMP_ERRSTAT_NO_ERROR;
}
It is very similar to the example we’ve seen in the previous lesson. Difference is that this time argument type is BString as our object is DisplayString.
Handling of the SET request is the interesting part. Here is the listing
SNMP_ERRSTAT OnSet_GarageAddress(ESnmpSetOpCode
eOpCode,
tUINT transactionId,
const string&
strVal,
void** ppContextInfo)
{
switch (eOpCode)
{
case eSNMP_SET_TEST:
{
*ppContextInfo = new BString (m_strAddress);
return eSNMP_ERRSTAT_NO_ERROR;
}
case eSNMP_SET_COMMIT:
{
m_strAddress = strVal;
return eSNMP_ERRSTAT_NO_ERROR;
}
case eSNMP_SET_UNDO:
{
m_strAddress = *(( BString *)*ppContextInfo);
return eSNMP_ERRSTAT_NO_ERROR;
}
case eSNMP_SET_CLEANUP:
{
if (*ppContextInfo)
delete (BString*)*ppContextInfo;
return eSNMP_ERRSTAT_NO_ERROR;
}
}
return eSNMP_ERRSTAT_GENERAL_ERR;
}
SET is multiphase operation and as standard requires it is atomic operation: either all sets in the pdu succeed or neither does.
The first phase, test, is performed on all varbinds in the pdu before actual objects are changed in the commit phase. If internal test fails (for example manager tries to set read-only object) appropriate error code is returned without calling SET handling routine. If internal test succeed, set handling routine is called with opcode = eSNMP_SET_TEST. This is the chance for the agent implementers to perform additional checking.
This object is defined as having the syntax DisplayString of length 0 to 32. What happens when SET request contains string of 40 octets? This is the place where constraint map comes into the picture.
BEGIN_CONSTRAINT_MAP(GarageObjects)
CRANGE_TCX(1, cszDisplayString, 0, 32) //garageAddress
END_CONSTRAINT_MAP()
Constraint map keeps the list of constraints. In this example it contains single row, which should be interpreted like this: CRANGE (“this is Constraint of type RANGE”) TCX (“this object has syntax defined in Textual Convention and has further limitation”), 1 is the id of the object, cszDisplayString is pointer to “DisplayString” string, 0 is the minimum length and 32 is the maximum length.
For the list of other macros that could be used in constraint maps please consult reference.
The constraint map is used during processing of test phase of set request. If request contains string longer then 32, as specified in this map, then appropriate error code is returned.
Before returning from the test phase in OnSet_GarageAddress, a copy of the m_strAddress is created and assigned to the *ppContextInfo
pointer. The agent can use this parameter to store context information used during multiphase SET operations. The same parameter will be passed to the OnSet method in each phase. The agent must release resources associated with this parameter during the cleanup
phase.
As we mentioned, SET is multiphase operation and as standard requires it is atomic operation: either all sets in the pdu succeed or neither does. If all tests succeed, processing continue with commit phase: set handling routine is called with opcode = eSNMP_SET_COMMIT. In this phase the actual alteration of the object value takes place. Note that it is possible for commit to fail. In this example simple assigning of new value is performed and eSNMP_ERRSTAT_NO_ERROR is returned.
It is possible that, in multivarbind scenario, test phase succeed and then commit phase fails but after a few objects are already altered. If this happens undo phase will be performed in order to restore altered objects to theirs previous values. This is the place where saved value from the test phase becomes handy.
At the end cleanup phase is performed. It is always executed no matter of the outcome of the previous phases. As a reminder, the agent must release resources associated with *ppContextInfo parameter during this phase or memory leak will occur.
In the next lesson Lesson 10: Implementing Table in the Agent, handling of the MIB table will be shown.