NAME
netsnmptableiterator - The table iterator helper is designed to
simplify the task of writing a table handler for the net-snmp agent
when the data being accessed is not in an oid sorted form and must be accessed externally. DDaattaa SSttrruuccttuurreess struct ttiiccaacchheeiinnffooss struct nneettssnnmmppiitteerraattoorriinnffooss Holds iterator information containing functions which should be called by the iteratorhandler to loop over your data set and sort it in a SNMP specific manner. struct nneettssnnmmppiitteerraattoorriinnffooss Holds iterator information containing functions which should be called by the iteratorhandler to loop over your data set and sort it in a SNMP specific manner. DDeeffiinneess#define TTIIRREEQQUUEESSTTCCAACCHHEE 'ticache'
#define TTAABBLLEEIITTEERRAATTOORRNNOOTTAAGGAAIINN 255
dfn TABLEITERATORNAME 'alieao'
TTyyppeeddeeffss typedef ticacheinfos ttiiccaacchheeiinnffoo typedef nneettssnnmmppvvaarriiaabblleelliisstt *( NNeettssnnmmppFFiirrssttDDaattaaPPooiinntt )(void **loopcontext, void **datacontext, nneettssnnmmppvvaarriiaabblleelliisstt *, struct nneettssnnmmppiitteerraattoorriinnffooss *) typedef nneettssnnmmppvvaarriiaabblleelliisstt *( NNeettssnnmmppNNeexxttDDaattaaPPooiinntt )(void **loopcontext, void **datacontext, nneettssnnmmppvvaarriiaabblleelliisstt *, struct nneettssnnmmppiitteerraattoorriinnffooss *) typedef void *( NNeettssnnmmppMMaakkeeDDaattaaCCoonntteexxtt )(void *loopcontext, struct nneettssnnmmppiitteerraattoorriinnffooss *) typedef void( NNeettssnnmmppFFrreeeeLLooooppCCoonntteexxtt )(void *, struct nneettssnnmmppiitteerraattoorriinnffooss *) typedef void( NNeettssnnmmppFFrreeeeDDaattaaCCoonntteexxtt )(void *, struct nneettssnnmmppiitteerraattoorriinnffooss *) typedef nneettssnnmmppiitteerraattoorriinnffooss nneettssnnmmppiitteerraattoorriinnffoo Typedefs the nneettssnnmmppiitteerraattoorriinnffooss struct into netsnmpiteratorinfo. FFuunnccttiioonnss nneettssnnmmppmmiibbhhaannddlleerr * nneettssnnmmppggeettttaabblleeiitteerraattoorrhhaannddlleerr (nneettssnnmmppiitteerraattoorriinnffoo *iinfo) returns a netsnmpmibhandler object for the tableiterator helper int nneettssnnmmpprreeggiisstteerrttaabblleeiitteerraattoorr (nneettssnnmmpphhaannddlleerrrreeggiissttrraattiioonn *reginfo, nneettssnnmmppiitteerraattoorriinnffoo *iinfo) Creates and registers a table iterator helper handler calling netsnmpcreatehandler with a handler name set toTABLEITERATORNAME and access method,
netsnmptableiteratorhelperhandler. NETSNMPINLINE void * nneettssnnmmppeexxttrraaccttiitteerraattoorrccoonntteexxtt (nneettssnnmmpprreeqquueessttiinnffoo *request) extracts the tableiterator specific data from a request. NETSNMPINLINE void nneettssnnmmppiinnsseerrttiitteerraattoorrccoonntteexxtt (nneettssnnmmpprreeqquueessttiinnffoo *request, void *data) inserts tableiterator specific data for a newly created row into a request int nneettssnnmmppttaabblleeiitteerraattoorrhheellppeerrhhaannddlleerr (nneettssnnmmppmmiibbhhaannddlleerr *handler, nneettssnnmmpphhaannddlleerrrreeggiissttrraattiioonn *reginfo, nneettssnnmmppaaggeennttrreeqquueessttiinnffoo *reqinfo, nneettssnnmmpprreeqquueessttiinnffoo *requests) implements the tableiterator helper VVaarriiaabblleess NetsnmpNodeHandler nneettssnnmmppttaabblleeiitteerraattoorrhheellppeerrhhaannddlleerr DDeettaaiilleedd DDeessccrriippttiioonn Functionally, it is a specialized version of the more generic table helper but easies the burden of GETNEXT processing by manually looping through all the data indexes retrieved through function calls which should be supplied by the module that wishes help. The module the tableiterator helps should, afterwards, never be called for the case of 'MODEGETNEXT' and only for the GET and SET related modes instead. The fundamental notion between the table iterator is that it allows your code to iterate over each 'row' within your data storagemechanism, without requiring that it be sorted in a SNMP-index-
compliant manner. Through the getfirstdatapoint and getnextdatapoint hooks, the tableiterator helper will repeatedly call your hooks to find the 'proper' row of data that needs processing. The following concepts are important: +o A loop context is a pointer which indicates where in the current processing of a set of rows you currently are. Allows the get*datapoint routines to move from one row to the next, once the iterator handler has identified the appropriate row for this request, the job of the loop context is done. The most simple example would be a pointer to an integer which simply counts rows from 1 to X. More commonly, it might be a pointer to a linked list node, or someother internal or external reference to a data set (file seek value, array pointer, ...). If allocated during iteration, either the freeloopcontextatend (preferably) or the freeloopcontext pointers should be set. +o A data context is something that your handler code can use in order to retrieve the rest of the data for the needed row. This data can be accessed in your handler via netsnmpextractiteratorcontext api with the netsnmprequestinfo structure that's passed in. The important difference between a loop context and a data context is that multiple data contexts can be kept by the tableiterator helper, where as only one loop context will ever be held by the tableiterator helper. If allocated during iteration the freedatacontext pointer should be set to an appropriate function. The table iterator operates in a series of steps that call your code hooks from your netsnmpiteratorinfo registration pointer. +o the getfirstdatapoint hook is called at the beginning of processing. It should set the variable list to a list of indexes for the given table. It should also set the loopcontext and maybe a datacontext which you will get a pointer back to when it needs to call your code to retrieve actual data later. The list of indexes should be returned after being update. +o the getnextdatapoint hook is then called repeatedly and is passed the loop context and the data context for it to update. The indexes, loop context and data context should all be updated if more data is available, otherwise they should be left alone and a NULL should be returned. Ideally, it should update the loop context without the need to reallocate it. If reallocation is necessary for every iterative step, then the freeloopcontext function pointer should be set. If not, then the freeloopcontextatend pointer should be set, which is more efficient since a malloc/free will only be performed once for every iteration. TTyyppeeddeeff DDooccuummeennttaattiioonn ssttrruucctt nneettssnnmmppiitteerraattoorriinnffooss nneettssnnmmppiitteerraattoorriinnffoo Typedefs the nneettssnnmmppiitteerraattoorriinnffooss struct into netsnmpiteratorinfo. Referenced by netsnmpgettableiteratorhandler(), netsnmpregistertableiterator(), and netsnmptableiteratorhelperhandler(). FFuunnccttiioonn DDooccuummeennttaattiioonn vvooiidd ** nneettssnnmmppeexxttrraaccttiitteerraattoorrccoonntteexxtt ((nneettssnnmmpprreeqquueessttiinnffoo ** rreeqquueesstt)) extracts the tableiterator specific data from a request. This function extracts the table iterator specific data from a netsnmprequestinfoobject. Calls netsnmprequestgetlistdata with request->parentdata
set with data from a request that was added previously by a module andTABLEITERATORNAME handler name.
PPaarraammeetteerrss:: request the netsnmp request info structure RReettuurrnnss::a void pointer(request->parentdata->data), otherwise NULL is
returned if request is NULL or request->parentdata is NULL or
request->parentdata object is not found.the net
Definition at line 163 of file tableiterator.c. References netsnmprequestgetlistdata(). nneettssnnmmppmmiibbhhaannddlleerr ** nneettssnnmmppggeettttaabblleeiitteerraattoorrhhaannddlleerr ((nneettssnnmmppiitteerraattoorriinnffoo ** iiiinnffoo)) returns a netsnmpmibhandler object for the tableiterator helper Definition at line 106 of file tableiterator.c. References netsnmpmibhandlers::myvoid, netsnmpcreatehandler(), netsnmpiteratorinfo, and netsnmpmibhandler. Referenced by netsnmpregistertableiterator(). vvooiidd nneettssnnmmppiinnsseerrttiitteerraattoorrccoonntteexxtt ((nneettssnnmmpprreeqquueessttiinnffoo ** rreeqquueesstt,, vvooiidd ** ddaattaa)) inserts tableiterator specific data for a newly created row into a request Definition at line 171 of file tableiterator.c. References netsnmptablerequestinfos::indexes, netsnmpcreatedatalist(), netsnmpextracttableinfo(), netsnmprequestaddlistdata(), netsnmprequestinfos::next, netsnmprequestinfos::prev, and snmpoidcompare(). iinntt nneettssnnmmpprreeggiisstteerrttaabblleeiitteerraattoorr ((nneettssnnmmpphhaannddlleerrrreeggiissttrraattiioonn ** rreeggiinnffoo,, nneettssnnmmppiitteerraattoorriinnffoo ** iiiinnffoo)) Creates and registers a table iterator helper handler callingnetsnmpcreatehandler with a handler name set to TABLEITERATORNAME
and access method, netsnmptableiteratorhelperhandler. If NOTSERIALIZED is not defined the function injects the serialize handler into the calling chain prior to calling netsnmpregistertable. PPaarraammeetteerrss:: reginfo is a pointer to a netsnmphandlerregistration struct iinfo is a pointer to a netsnmpiteratorinfo struct RReettuurrnnss:: MIBREGISTEREDOK is returned if the registration was a success. Failures are MIBREGISTRATIONFAILED, MIBDUPLICATEREGISTRATION. If iinfo is NULL, SNMPERRGENERR is returned. Definition at line 138 of file tableiterator.c. References netsnmpgettableiteratorhandler(), netsnmphandlerregistration, netsnmpinjecthandler(), netsnmpiteratorinfo, netsnmpregistertable(), and netsnmpiteratorinfos::tablereginfo. iinntt nneettssnnmmppttaabblleeiitteerraattoorrhheellppeerrhhaannddlleerr ((nneettssnnmmppmmiibbhhaannddlleerr ** hhaannddlleerr,, nneettssnnmmpphhaannddlleerrrreeggiissttrraattiioonn ** rreeggiinnffoo,, nneettssnnmmppaaggeennttrreeqquueessttiinnffoo ** rreeqqiinnffoo,, nneettssnnmmpprreeqquueessttiinnffoo ** rreeqquueessttss)) implements the tableiterator helper Definition at line 309 of file tableiterator.c. References netsnmptablerequestinfos::colnum, netsnmpdatalists::data, netsnmpiteratorinfos::flags, netsnmpiteratorinfos::freedatacontext, netsnmpiteratorinfos::freeloopcontext, netsnmpiteratorinfos::freeloopcontextatend, netsnmpiteratorinfos::getfirstdatapoint, netsnmpiteratorinfos::getnextdatapoint, netsnmphandlerregistrations::handlerName, netsnmptablerequestinfos::indexes, netsnmptableregistrationinfos::maxcolumn, netsnmptableregistrationinfos::mincolumn, netsnmpagentrequestinfos::mode, netsnmpmibhandlers::myvoid, variablelist::name, variablelist::namelength, netsnmpcallnexthandler(), netsnmpcheckgetnextreply(), netsnmpcreatedatalist(), netsnmpextractstashcache(), netsnmpextracttableinfo(), netsnmpfindtableregistrationinfo(), netsnmpfreerequestdatasets(), netsnmpgetlistnode(), netsnmphandlerregistration, netsnmpiteratorinfo, netsnmpmibhandler, netsnmpoidstashadddata(), netsnmprequestaddlistdata(), netsnmprequestgetlistdata(), netsnmprequestinfos::next, netsnmprequestinfos::parentdata, netsnmprequestinfos::processed, netsnmprequestinfos::requestvb, netsnmphandlerregistrations::rootoid, netsnmphandlerregistrations::rootoidlen, SNMPFREE, snmplog(), SNMPMALLOCTYPEDEF, snmpoidcompare(), netsnmprequestinfos::subtree, netsnmpiteratorinfos::tablereginfo, and variablelist::type.tableiterator: The table iterator helper is designed to simplify the task of writing a table handler for the net-snmp agent when the data bneeitn-gsnamcpcessed is not in an oid sor2t4edJafnor2m00a5nd must be accessed externally.(3)