tableiterator: The table iterator helper is designed to simplify the task of writing a table handler for the net-snmp agent when the data beingeaccessedr:isTnottinlanioidasortedlformiandemustebetaccessedfexternally.(3)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.(3)



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.



   Data Structures
       struct ticacheinfos
       struct netsnmpiteratorinfos
           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 netsnmpiteratorinfos
           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.

   Defines
       #define TIREQUESTCACHE   'ticache'
       #define TABLEITERATORNOTAGAIN   255
       #define TABLEITERATORNAME   'tableiterator'

   Typedefs
       typedef ticacheinfos ticacheinfo
       typedef netsnmpvariablelist *( NetsnmpFirstDataPoint )(void
           **loopcontext, void **datacontext, netsnmpvariablelist *,
           struct netsnmpiteratorinfos *)
       typedef netsnmpvariablelist *( NetsnmpNextDataPoint )(void
           **loopcontext, void **datacontext, netsnmpvariablelist *,
           struct netsnmpiteratorinfos *)
       typedef void *( NetsnmpakeDataContext )(void *loopcontext, struct
           netsnmpiteratorinfos *)
       typedef void( NetsnmpFreeLoopContext )(void *, struct
           netsnmpiteratorinfos *)
       typedef void( NetsnmpFreeDataContext )(void *, struct
           netsnmpiteratorinfos *)
       typedef netsnmpiteratorinfos netsnmpiteratorinfo
           Typedefs the netsnmpiteratorinfos struct into
           netsnmpiteratorinfo.

   Functions
       netsnmpmibhandler * netsnmpgettableiteratorhandler
           (netsnmpiteratorinfo *iinfo)
           returns a netsnmpmibhandler object for the tableiterator helper
       int netsnmpregistertableiterator (netsnmphandlerregistration
           *reginfo, netsnmpiteratorinfo *iinfo)
           Creates and registers a table iterator helper handler calling
           netsnmpcreatehandler with a handler name set to
           TABLEITERATORNAME and access method,
           netsnmptableiteratorhelperhandler.
       NETSNMPINLINE void * netsnmpextractiteratorcontext
           (netsnmprequestinfo *request)
           extracts the tableiterator specific data from a request.
       NETSNMPINLINE void netsnmpinsertiteratorcontext
           (netsnmprequestinfo *request, void *data)
           inserts tableiterator specific data for a newly created row into a
           request
       int netsnmptableiteratorhelperhandler (netsnmpmibhandler
           *handler, netsnmphandlerregistration *reginfo,
           netsnmpagentrequestinfo *reqinfo, netsnmprequestinfo
           *requests)
           implements the tableiterator helper

   Variables
       NetsnmpNodeHandler netsnmptableiteratorhelperhandler

Detailed Description
       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 storage
       mechanism, 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 NUL 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.



Typedef Documentation
   struct netsnmpiteratorinfos netsnmpiteratorinfo
       Typedefs the netsnmpiteratorinfos struct into netsnmpiteratorinfo.
       Referenced by netsnmpgettableiteratorhandler(),
       netsnmpregistertableiterator(), and
       netsnmptableiteratorhelperhandler().

Function Documentation
   void ** netsnmpextractiteratorcontext (netsnmprequestinfo ** request)
       extracts the tableiterator specific data from a request. This function
       extracts the table iterator specific data from a netsnmprequestinfo
       object. Calls netsnmprequestgetlistdata with request->parentdata
       set with data from a request that was added previously by a module and
       TABLEITERATORNAME handler name.

       Parameters::
           request the netsnmp request info structure

       Returns::
           a void pointer(request->parentdata->data), otherwise NUL is
           returned if request is NUL or request->parentdata is NUL or
           request->parentdata object is not found.the net

       Definition at line 163 of file tableiterator.c.

       References netsnmprequestgetlistdata().

   netsnmpmibhandler ** netsnmpgettableiteratorhandler
       (netsnmpiteratorinfo ** iinfo)
       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().

   void netsnmpinsertiteratorcontext (netsnmprequestinfo ** request,, void
       ** data)
       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().

   int netsnmpregistertableiterator (netsnmphandlerregistration **
       reginfo,, netsnmpiteratorinfo ** iinfo)
       Creates and registers a table iterator helper handler calling
       netsnmpcreatehandler 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.

       Parameters::
           reginfo is a pointer to a netsnmphandlerregistration struct
           iinfo is a pointer to a netsnmpiteratorinfo struct

       Returns::
           MIBREGISTEREDOK is returned if the registration was a success.
           Failures are MIBREGISTRATIONFAILED, MIBDUPLICATEREGISTRATION.
           If iinfo is NUL, SNMPERGENER is returned.

       Definition at line 138 of file tableiterator.c.

       References netsnmpgettableiteratorhandler(),
       netsnmphandlerregistration, netsnmpinjecthandler(),
       netsnmpiteratorinfo, netsnmpregistertable(), and
       netsnmpiteratorinfos::tablereginfo.

   int netsnmptableiteratorhelperhandler (netsnmpmibhandler ** handler,,
       netsnmphandlerregistration ** reginfo,, netsnmpagentrequestinfo **
       reqinfo,, netsnmprequestinfo ** requests)
       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, SNMPFRE, snmplog(),
       SNMPMALOCTYPEDEF, 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 beingsaccessed is not in an oid sortedJform00and must be accessed externally.(3)