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 Structuresstruct ti_cache_info_s
struct netsnmp_iterator_info_s
Holds iterator information containing functions whichshould 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 whichshould 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'
Typedefstypedef 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.
Functionsnetsnmp_iterator_info * netsnmp_iterator_create_table
(Netsnmp_First_Data_Point *firstDP,
Netsnmp_Next_Data_Point *nextDP,
Netsnmp_First_Data_Point *getidx, ne
void netsnmp_iterator_delete_table (netsnmp_iterator_info
*iinfo)netsnmp_mib_handler * netsnmp_get_table_iterator_handler
(netsnmp_iterator_info *iinfo)
Version 5.4.1 Last change: 27 Jul 2007 1net-snmp table_iterator(3)
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 handlercalling 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 requestint netsnmp_table_iterator_helper_handler
(netsnmp_mib_handler *handler,
netsnmp_handler_registration *reginfo,
netsnmp_agent_request_info *reqinfo, netsnmp_request_
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) VariablesNetsnmp_Node_Handler netsnmp_table_iterator_helper_handler
Detailed Description The table iterator helper is designed to simplify the taskof 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 Version 5.4.1 Last change: 27 Jul 2007 2net-snmp table_iterator(3)
retrieved through function calls which should be supplied bythe 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 aSNMP-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 thefree_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 vianetsnmp_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 thetable_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 callyour 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 theloop_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. Version 5.4.1 Last change: 27 Jul 2007 3net-snmp table_iterator(3)
+o 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 forevery iterative step, then the free_loop_context function
pointer should be set. If not, then thefree_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 Documentationstruct netsnmp_iterator_info_s netsnmp_iterator_info
Typedefs the netsnmp_iterator_info_s struct into
netsnmp_iterator_info.
Function Documentationvoid * 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 froma 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 amodule 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 netDefinition at line 234 of file table_iterator.c.
References netsnmp_request_get_list_data(), and
TABLE_ITERATOR_NAME.
netsnmp_mib_handler * netsnmp_get_table_iterator_handler
(netsnmp_iterator_info * iinfo)
returns a netsnmp_mib_handler object for the table_iterator
helperDefinition at line 169 of file table_iterator.c.
References netsnmp_mib_handler_s::myvoid,
netsnmp_create_handler(),
Version 5.4.1 Last change: 27 Jul 2007 4net-snmp table_iterator(3)
netsnmp_table_iterator_helper_handler, NULL, and
TABLE_ITERATOR_NAME.
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 requestDefinition at line 242 of file table_iterator.c.
References build_oid_noalloc(),
netsnmp_table_request_info_s::indexes,
netsnmp_create_data_list(), netsnmp_extract_table_info(),
netsnmp_request_add_list_data(),
netsnmp_request_info_s::next, NULL,
netsnmp_request_info_s::prev, snmp_oid_compare(), and
TABLE_ITERATOR_NAME.
int netsnmp_register_table_iterator
(netsnmp_handler_registration * reginfo,
netsnmp_iterator_info * iinfo)
Creates and registers a table iterator helper handlercalling 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 callingnetsnmp_register_table.
Parameters:reginfo is a pointer to a netsnmp_handler_registration
structiinfo 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.
Definition at line 205 of file table_iterator.c.
References HANDLER_CAN_STASH,
netsnmp_table_registration_info_s::indexes,
netsnmp_iterator_info_s::indexes,
netsnmp_handler_registration_s::modes,
netsnmp_get_table_iterator_handler(),
netsnmp_inject_handler(), netsnmp_register_table(),
snmp_clone_varbind(), and
Version 5.4.1 Last change: 27 Jul 2007 5net-snmp table_iterator(3)
netsnmp_iterator_info_s::table_reginfo.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:_______________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|____________________|__________________________________|_
| Availability | system/management/snmp/net-snmp|
|____________________|__________________________________|_
| Interface Stability| Volatile ||____________________|_________________________________|
NOTESSource for net-snmp is available on http://opensolaris.org.
Version 5.4.1 Last change: 27 Jul 2007 6