#ifndef fsubagent_H #define fsubagent_H #include "fsubagentArray2.h" #include #ifdef __cplusplus extern "C" { #endif /* end of an OID string passed to fsubagent. * Can't be zero, since some OID's have embedded zeroes. * Pick -2 arbitrarily, as it'll be a bit easier to see in hex dumps * than -1. * NOTE: this library assumes that any one oid component never exceeds * 65534! */ #define fsubagent_END 0xfffe /**------------------------------------------------------------------------- C module to handle I/O between a daemon being monitored and the SNMP daemon doing the monitoring. Communication is unidirectional; the daemon being monitored sets the values and calls fsubagent_save(); the SNMP daemon calls fsubagent_load() and reads the values. At startup, the programmer must initialize the fsubagent by calling fsubagent_createScalarRow(), fsubagent_createArray(), and/or fsubagent_createArray2() with the OID and type signature of each scalar row, single-index table, or two-index table from the MIB, using defines from the .h file produced from the MIB by mib2h.pl. This must be done before the first call to fsubagent_load() or fsubagent_save(). This sets the number and type of variables in the rows, and allows typechecking of SNMP variable accesses. This module is centered around the idea of a 'row' of snmp variables. The programmer accesses variables via a row pointer (see below) and the last part of the SNMP object identifier before the indices. Individual variable values can be modified with fsubagentRow_setInt(row, index, val), fsubagentRow_addInt(row, index, val), or fsubagentRow_setString(row, index, val, len). Individual variable values can be retrieved with fsubagentRow_getInt(row, index) or fsubagentRow_getString(row, index, &p). See fsubagentArray.h and fsubagentRow.h. SNMP daemons trying to look up the values of SNMP variables use these methods as follows. Given arbitrary SNMP variables simpleVariable.0 fooTable.fooEntry.fooMember.index barTable.barEntry.barMember.index1.index2 the daemon should pass the numerical value of the last named OID component before the indices (e.g. simpleVariable, fooMember, or barMember) to fsubagentRow_{get,set}{Int,String}(), the last index to fsubagentArray_getRow(), and the next-to-last index to fsubagentArray2_getArray(). Examples: To set podunk.fleet.uptime.0 to 15: row = fsubagent_createScalarRow(...); ... fsubagentRow_getInt(row, PODUNK_RR_uptime, 15); To set podunk.fleet.trainTable.trainEntry.trainLastDeparture.2 to 37: array = fsubagent_createArray(...); or array = fsubagent_getArray(...); ... row = fsubagentArray_createRow(array, ...); or row = fsubagentArray_getRow(array, 2); ... fsubagentRow_setInt(row, PODUNK_RR_trainLastDeparture, 37); Notes: fsubagent_getArray() is provided for convenience, in case you don't want to save the pointer returned via fsubagent_createArray(). fsubagentArray_getRow() is required on the SNMP daemon side because you don't have to call fsubagentArray_createRow() before calling fsubagent_load(), so there's no other way to get the row pointer associated with a given SNMP table index. The routines that take full OID's (fsubagent_createScalarRow, fsubagent_createArray, fsubagent_getArray) take arrays of integers terminated by fsubagent_END to represent the OID of the row in question. The module is implemented in C using an object-oriented idiom which provides good encapsualation. Since all data members of fsubagent are private, the structure is only named here; the full definition is private to fsubagent.c. C++ programmers using this module may wish to use the object-oriented wrappers generated by mib2h.pl rather than calling fsubagentRow_setInt() etc. --------------------------------------------------------------------------*/ typedef struct fsubagent_s fsubagent; /* class fsubagent { */ /**---------------------------------------------------------------------- Create a fsubagent. @return initialized fsubagent * on success, NULL on failure -----------------------------------------------------------------------*/ fsubagent *fsubagent_new(void); /**---------------------------------------------------------------------- Delete a fsubagent and release any resources it has allocated. -----------------------------------------------------------------------*/ void fsubagent_delete(fsubagent *); /**---------------------------------------------------------------------- Specify the filename used for all I/O. @param filename - transient pointer to filename @return 0 on success, Unix error code on failure -----------------------------------------------------------------------*/ int fsubagent_setFilename(fsubagent *, const char *filename); /**---------------------------------------------------------------------- Load new current MIB contents (or changes to MIB contents) from disk. Must have already created all arrays and scalar rows. For use by snmp daemon. @return 0 on success, Unix error code on failure -----------------------------------------------------------------------*/ int fsubagent_load(fsubagent *); /**---------------------------------------------------------------------- Save the current MIB contents to a temporary file on disk, then when file is complete, quickly rename it to the real filename. (That way fsubagent_load() never sees a partial file.) After the first call, might only write out changes. For use by monitored app. @return 0 on success, Unix error code on failure -----------------------------------------------------------------------*/ int fsubagent_save(fsubagent *); /**---------------------------------------------------------------------- Create a 1d array of SNMP scalar variables (columns whose only element has an OID suffix of .0). For instance, the integer scalar variables podunk.fleet.fleetStatus.fsTrainUsed.0 podunk.fleet.fleetStatus.fsTrainFree.0 podunk.fleet.fleetStatus.fsTrainCount.0, where fsTrainUsed, fsTrainFree, and fsTrainCount are consecutively numbered starting from 1, are created by the call fsubagent_createScalarRow(subagent, oid, PODUNK_RR_fleetStatus_FORMAT) where oid = { PODUNK_RR_fleetStatus, fsubagent_END } and PODUNK_RR_fleetStatus_FORMAT = "iii" @param format = stable pointer to row constraints (from output of mib2h.pl) @param oid = transient pointer to fsubagent_END-terminated OID suffix (built up from symbols defined in output of mib2h.pl) @return persistant row pointer on success, NULL on failure -----------------------------------------------------------------------*/ fsubagentRow *fsubagent_createScalarRow(fsubagent *, const int *oid, const char *format); /**---------------------------------------------------------------------- Create a 1-d array of SNMP columns. For instance, the variables podunk.fleet.trainTable.trainEntry.trainIndex.1 podunk.fleet.trainTable.trainEntry.trainIndex.2 podunk.fleet.trainTable.trainEntry.trainName.1 podunk.fleet.trainTable.trainEntry.trainName.2 podunk.fleet.trainTable.trainEntry.trainLastDeparture.1 podunk.fleet.trainTable.trainEntry.trainLastDeparture.2 ..., where trainIndex, trainName, and trainLastDeparture are consecutively numbered starting from 1, are part of the fsubagentArray at podunk.fleet.trainTable.trainEntry and are created by the calls array = fsubagent_createArray(subagent, oid, PODUNK_RR_trainEntry_FORMAT) row1 = fsubagentArray_createRow(array); row2 = fsubagentArray_createRow(array); where oid = { PODUNK_RR_trainTable, PODUNK_RR_trainEntry, fsubagent_END } and PODUNK_RR_trainEntry_FORMAT = "isi..." @param format = stable pointer to row constraints (from output of mib2h.pl) @param oid = transient pointer to fsubagent_END-terminated OID suffix (from output of mib2h.pl) @return array pointer on success, NULL on failure -----------------------------------------------------------------------*/ fsubagentArray *fsubagent_createArray(fsubagent *, const int *oid, const char *format); /**---------------------------------------------------------------------- Retrieve a pointer to an already created fsubagentArray. @param oid = transient pointer to fsubagent_END-terminated OID suffix (from output of mib2h.pl) @return array pointer on success, NULL on failure -----------------------------------------------------------------------*/ fsubagentArray *fsubagent_getArray(fsubagent *, const int *oid); /**---------------------------------------------------------------------- Create a 2-d array of SNMP columns. For instance, the variables podunk.fleet.trainTable.trainEntry.trainIndex.1.1 podunk.fleet.trainTable.trainEntry.trainIndex.1.2 podunk.fleet.trainTable.trainEntry.trainIndex.2.1 ... are part of the fsubagentArray2 at podunk.fleet.trainTable.trainEntry and are created by the calls root = fsubagent_createArray2(subagent, oid, PODUNK_RR_trainEntry_FORMAT) array1 = fsubagentArray2_createArray(root); row11 = fsubagentArray_createRow(array); row12 = fsubagentArray_createRow(array); array2 = fsubagentArray2_createArray(root); row21 = fsubagentArray_createRow(array); where oid = { PODUNK_RR_trainTable, PODUNK_RR_trainEntry, fsubagent_END }, PODUNK_RR_trainEntry_FORMAT = "i...", PODUNK_RR_trainIndex = 1, etc. @param format = stable pointer to row constraints (from output of mib2h.pl) @param oid = transient pointer to fsubagent_END-terminated OID suffix (built from symbols defined in output of mib2h.pl) @return array pointer on success, NULL on failure -----------------------------------------------------------------------*/ fsubagentArray2 *fsubagent_createArray2(fsubagent *, const int *oid, const char *format); /**---------------------------------------------------------------------- Retrieve a pointer to an already created fsubagentArray2. @param oid = transient pointer to fsubagent_END-terminated OID suffix (built from symbols defined in output of mib2h.pl) @return array pointer on success, NULL on failure -----------------------------------------------------------------------*/ fsubagentArray2 *fsubagent_getArray2(fsubagent *, const int *oid); /* } */ #ifdef __cplusplus } #endif #endif