when the data being accessed is not in an oid sorted form and must be
       accessed externally.



   Data Structures
       struct ti_cache_info_s
       struct netsnmp_iterator_info_s
           Holds iterator information containing functions which should be
           called by the iterator_handler to loop over your data set and sort
           it in a SNMP specific manner.
       struct netsnmp_iterator_info_s
           Holds iterator information containing functions which should be
           called by the iterator_handler to loop over your data set and sort
           it in a SNMP specific manner.

   Defines
       #define TI_REQUEST_CACHE   'ti_cache'
       #define TABLE_ITERATOR_NOTAGAIN   255
       #define TABLE_ITERATOR_NAME   'table_iterator'

   Typedefs
       typedef ti_cache_info_s ti_cache_info
       typedef netsnmp_variable_list *( Netsnmp_First_Data_Point )(void
           **loop_context, void **data_context, netsnmp_variable_list *,
           struct netsnmp_iterator_info_s *)
       typedef netsnmp_variable_list *( Netsnmp_Next_Data_Point )(void
           **loop_context, void **data_context, netsnmp_variable_list *,
           struct netsnmp_iterator_info_s *)
       typedef void *( Netsnmp_Make_Data_Context )(void *loop_context, struct
           netsnmp_iterator_info_s *)
       typedef void( Netsnmp_Free_Loop_Context )(void *, struct
           netsnmp_iterator_info_s *)
       typedef void( Netsnmp_Free_Data_Context )(void *, struct
           netsnmp_iterator_info_s *)
       typedef netsnmp_iterator_info_s netsnmp_iterator_info
           Typedefs the netsnmp_iterator_info_s struct into
           netsnmp_iterator_info.

   Functions
       netsnmp_mib_handler * netsnmp_get_table_iterator_handler
           (netsnmp_iterator_info *iinfo)
           returns a netsnmp_mib_handler object for the table_iterator helper
       int netsnmp_register_table_iterator (netsnmp_handler_registration
           *reginfo, netsnmp_iterator_info *iinfo)
           Creates and registers a table iterator helper handler calling
           netsnmp_create_handler with a handler name set to
           TABLE_ITERATOR_NAME and access method,
           netsnmp_table_iterator_helper_handler.
       NETSNMP_INLINE void * netsnmp_extract_iterator_context
           (netsnmp_request_info *request)
           extracts the table_iterator specific data from a request.

       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
       table_iterator helps should, afterwards, never be called for the case
       of 'MODE_GETNEXT' 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 get_first_data_point and
       get_next_data_point hooks, the table_iterator 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_*_data_point 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
         free_loop_context_at_end (preferably) or the free_loop_context
         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 netsnmp_extract_iterator_context api
         with the netsnmp_request_info 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 table_iterator helper,
         where as only one loop context will ever be held by the
         table_iterator helper. If allocated during iteration the
         free_data_context pointer should be set to an appropriate function.


       The table iterator operates in a series of steps that call your code
       hooks from your netsnmp_iterator_info registration pointer.


       o the get_first_data_point 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 loop_context and maybe a
         data_context 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.

Typedef Documentation

   struct netsnmp_iterator_info_s netsnmp_iterator_info
       Typedefs the netsnmp_iterator_info_s struct into netsnmp_iterator_info.
       Referenced by netsnmp_get_table_iterator_handler(),
       netsnmp_register_table_iterator(), and
       netsnmp_table_iterator_helper_handler().

Function Documentation

   void * netsnmp_extract_iterator_context (netsnmp_request_info * request)
       extracts the table_iterator specific data from a request. This function
       extracts the table iterator specific data from a netsnmp_request_info
       object. Calls netsnmp_request_get_list_data with request->parent_data
       set with data from a request that was added previously by a module and
       TABLE_ITERATOR_NAME handler name.

       Parameters:
           request the netsnmp request info structure

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

       Definition at line 163 of file table_iterator.c.

       References netsnmp_request_get_list_data().

   netsnmp_mib_handler * netsnmp_get_table_iterator_handler
       (netsnmp_iterator_info * iinfo)
       returns a netsnmp_mib_handler object for the table_iterator helper
       Definition at line 106 of file table_iterator.c.

       References netsnmp_mib_handler_s::myvoid, netsnmp_create_handler(),
       netsnmp_iterator_info, and netsnmp_mib_handler.

       Referenced by netsnmp_register_table_iterator().

   void netsnmp_insert_iterator_context (netsnmp_request_info * request, void
       * data)
       inserts table_iterator specific data for a newly created row into a
       request Definition at line 171 of file table_iterator.c.

       References netsnmp_table_request_info_s::indexes,
       netsnmp_create_data_list(), netsnmp_extract_table_info(),
       netsnmp_request_add_list_data(), netsnmp_request_info_s::next,
       netsnmp_request_info_s::prev, and snmp_oid_compare().

   int netsnmp_register_table_iterator (netsnmp_handler_registration *
       reginfo, netsnmp_iterator_info * iinfo)
       Creates and registers a table iterator helper handler calling
       netsnmp_create_handler with a handler name set to TABLE_ITERATOR_NAME

       References netsnmp_get_table_iterator_handler(),
       netsnmp_handler_registration, netsnmp_inject_handler(),
       netsnmp_iterator_info, netsnmp_register_table(), and
       netsnmp_iterator_info_s::table_reginfo.

   int netsnmp_table_iterator_helper_handler (netsnmp_mib_handler * handler,
       netsnmp_handler_registration * reginfo, netsnmp_agent_request_info *
       reqinfo, netsnmp_request_info * requests)
       implements the table_iterator helper Definition at line 309 of file
       table_iterator.c.

       References netsnmp_table_request_info_s::colnum,
       netsnmp_data_list_s::data, netsnmp_iterator_info_s::flags,
       netsnmp_iterator_info_s::free_data_context,
       netsnmp_iterator_info_s::free_loop_context,
       netsnmp_iterator_info_s::free_loop_context_at_end,
       netsnmp_iterator_info_s::get_first_data_point,
       netsnmp_iterator_info_s::get_next_data_point,
       netsnmp_handler_registration_s::handlerName,
       netsnmp_table_request_info_s::indexes,
       netsnmp_table_registration_info_s::max_column,
       netsnmp_table_registration_info_s::min_column,
       netsnmp_agent_request_info_s::mode, netsnmp_mib_handler_s::myvoid,
       variable_list::name, variable_list::name_length,
       netsnmp_call_next_handler(), netsnmp_check_getnext_reply(),
       netsnmp_create_data_list(), netsnmp_extract_stash_cache(),
       netsnmp_extract_table_info(), netsnmp_find_table_registration_info(),
       netsnmp_free_request_data_sets(), netsnmp_get_list_node(),
       netsnmp_handler_registration, netsnmp_iterator_info,
       netsnmp_mib_handler, netsnmp_oid_stash_add_data(),
       netsnmp_request_add_list_data(), netsnmp_request_get_list_data(),
       netsnmp_request_info_s::next, netsnmp_request_info_s::parent_data,
       netsnmp_request_info_s::processed, netsnmp_request_info_s::requestvb,
       netsnmp_handler_registration_s::rootoid,
       netsnmp_handler_registration_s::rootoid_len, SNMP_FREE, snmp_log(),
       SNMP_MALLOC_TYPEDEF, snmp_oid_compare(),
       netsnmp_request_info_s::subtree,
       netsnmp_iterator_info_s::table_reginfo, and variable_list::type.

table_iterator: 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 sortedJform0and must be accessed externally.(3)