table_iterator(3) net-snmp table_iterator(3)NAME
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 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.
Defines
#define TI_REQUEST_CACHE 'ti_cache'
#define TABLE_ITERATOR_NOTAGAIN 255
#define TABLE_ITERATOR_NAME 'table_iterator'
Typedefs
typedef struct 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 struct netsnmp_iterator_info_s netsnmp_iterator_info
Typedefs the netsnmp_iterator_info_s struct into
netsnmp_iterator_info.
Functions
netsnmp_iterator_info * netsnmp_iterator_create_table
(Netsnmp_First_Data_Point *firstDP, Netsnmp_Next_Data_Point
*nextDP, Netsnmp_First_Data_Point *getidx, netsnmp_variable_list
*indexes)
void netsnmp_iterator_delete_table (netsnmp_iterator_info *iinfo)
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.
NETSNMP_INLINE void netsnmp_insert_iterator_context
(netsnmp_request_info *request, void *data)
inserts table_iterator specific data for a newly created row into a
request
int netsnmp_table_iterator_helper_handler (netsnmp_mib_handler
*handler, netsnmp_handler_registration *reginfo,
netsnmp_agent_request_info *reqinfo, netsnmp_request_info
*requests)
void * netsnmp_iterator_row_first (netsnmp_iterator_info *iinfo)
void * netsnmp_iterator_row_get (netsnmp_iterator_info *iinfo, void
*row)
void * netsnmp_iterator_row_next (netsnmp_iterator_info *iinfo, void
*row)
void * netsnmp_iterator_row_get_byidx (netsnmp_iterator_info *iinfo,
netsnmp_variable_list *indexes)
void * netsnmp_iterator_row_next_byidx (netsnmp_iterator_info *iinfo,
netsnmp_variable_list *indexes)
void * netsnmp_iterator_row_get_byoid (netsnmp_iterator_info *iinfo,
oid *instance, size_t len)
void * netsnmp_iterator_row_next_byoid (netsnmp_iterator_info *iinfo,
oid *instance, size_t len)
int netsnmp_iterator_row_count (netsnmp_iterator_info *iinfo)
Variables
Netsnmp_Node_Handler netsnmp_table_iterator_helper_handler
Detailed Description
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.
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:
· 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.
· 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.
· 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.
· the get_next_data_point 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 free_loop_context function pointer should be set. If
not, then the free_loop_context_at_end pointer should be set, which
is more efficient since a malloc/free will only be performed once for
every iteration.
Typedef Documentation
struct netsnmp_iterator_info_s netsnmp_iterator_info
Typedefs the netsnmp_iterator_info_s struct into netsnmp_iterator_info.
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
netsnmp_mib_handler * netsnmp_get_table_iterator_handler
(netsnmp_iterator_info * iinfo)
returns a netsnmp_mib_handler object for the table_iterator helper
void netsnmp_insert_iterator_context (netsnmp_request_info * request, void
* data)
inserts table_iterator specific data for a newly created row into a
request
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. If
NOT_SERIALIZED is not defined the function injects the serialize
handler into the calling chain prior to calling netsnmp_register_table.
Parameters:
reginfo is a pointer to a netsnmp_handler_registration struct
iinfo is a pointer to a netsnmp_iterator_info struct
Returns:
MIB_REGISTERED_OK is returned if the registration was a success.
Failures are MIB_REGISTRATION_FAILED, MIB_DUPLICATE_REGISTRATION.
If iinfo is NULL, SNMPERR_GENERR is returned.
Author
Generated automatically by Doxygen for net-snmp from the source code.
Version 5.5 23 Sep 2009 table_iterator(3)
