SNMP编程

开发平台：
Unix_Linux

netsnmp_table_iterator.3：源码内容
							.TH "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." 3 "28 Nov 2005" "Version 5.2.1.rc3" "net-snmp" " -*- nroff -*-
.ad l
.nh
.SH 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. - 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.  
.PP
.SS "Data Structures"
.in +1c
.ti -1c
.RI "struct fBti_cache_info_sfP"
.br
.ti -1c
.RI "struct fBnetsnmp_iterator_info_sfP"
.br
.RI "fIHolds 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. fP"
.ti -1c
.RI "struct fBnetsnmp_iterator_info_sfP"
.br
.RI "fIHolds 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. fP"
.in -1c
.SS "Defines"
.in +1c
.ti -1c
.RI "#define fBTI_REQUEST_CACHEfP   'ti_cache'"
.br
.ti -1c
.RI "#define fBTABLE_ITERATOR_NOTAGAINfP   255"
.br
.ti -1c
.RI "#define fBTABLE_ITERATOR_NAMEfP   'table_iterator'"
.br
.in -1c
.SS "Typedefs"
.in +1c
.ti -1c
.RI "typedef fBti_cache_info_sfP fBti_cache_infofP"
.br
.ti -1c
.RI "typedef fBnetsnmp_variable_listfP *( fBNetsnmp_First_Data_PointfP )(void **loop_context, void **data_context, fBnetsnmp_variable_listfP *, struct fBnetsnmp_iterator_info_sfP *)"
.br
.ti -1c
.RI "typedef fBnetsnmp_variable_listfP *( fBNetsnmp_Next_Data_PointfP )(void **loop_context, void **data_context, fBnetsnmp_variable_listfP *, struct fBnetsnmp_iterator_info_sfP *)"
.br
.ti -1c
.RI "typedef void *( fBNetsnmp_Make_Data_ContextfP )(void *loop_context, struct fBnetsnmp_iterator_info_sfP *)"
.br
.ti -1c
.RI "typedef void( fBNetsnmp_Free_Loop_ContextfP )(void *, struct fBnetsnmp_iterator_info_sfP *)"
.br
.ti -1c
.RI "typedef void( fBNetsnmp_Free_Data_ContextfP )(void *, struct fBnetsnmp_iterator_info_sfP *)"
.br
.ti -1c
.RI "typedef fBnetsnmp_iterator_info_sfP fBnetsnmp_iterator_infofP"
.br
.RI "fITypedefs the fBnetsnmp_iterator_info_sfP struct into netsnmp_iterator_info. fP"
.in -1c
.SS "Functions"
.in +1c
.ti -1c
.RI "fBnetsnmp_mib_handlerfP * fBnetsnmp_get_table_iterator_handlerfP (fBnetsnmp_iterator_infofP *iinfo)"
.br
.RI "fIreturns a netsnmp_mib_handler object for the table_iterator helper fP"
.ti -1c
.RI "int fBnetsnmp_register_table_iteratorfP (fBnetsnmp_handler_registrationfP *reginfo, fBnetsnmp_iterator_infofP *iinfo)"
.br
.RI "fICreates 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. fP"
.ti -1c
.RI "NETSNMP_INLINE void * fBnetsnmp_extract_iterator_contextfP (fBnetsnmp_request_infofP *request)"
.br
.RI "fIextracts the table_iterator specific data from a request. fP"
.ti -1c
.RI "NETSNMP_INLINE void fBnetsnmp_insert_iterator_contextfP (fBnetsnmp_request_infofP *request, void *data)"
.br
.RI "fIinserts table_iterator specific data for a newly created row into a request fP"
.ti -1c
.RI "int fBnetsnmp_table_iterator_helper_handlerfP (fBnetsnmp_mib_handlerfP *handler, fBnetsnmp_handler_registrationfP *reginfo, fBnetsnmp_agent_request_infofP *reqinfo, fBnetsnmp_request_infofP *requests)"
.br
.RI "fIimplements the table_iterator helper fP"
.in -1c
.SS "Variables"
.in +1c
.ti -1c
.RI "fBNetsnmp_Node_HandlerfP fBnetsnmp_table_iterator_helper_handlerfP"
.br
.in -1c
.SH "Detailed Description"
.PP 
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. 
.PP
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.
.PP
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:
.PP
.IP "(bu" 2
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.
.PP
.PP
.IP "(bu" 2
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.
.PP
.PP
The table iterator operates in a series of steps that call your code hooks from your netsnmp_iterator_info registration pointer.
.PP
.IP "(bu" 2
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.
.PP
.PP
.IP "(bu" 2
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.
.PP
.SH "Typedef Documentation"
.PP 
.SS "struct fBnetsnmp_iterator_info_sfP fBnetsnmp_iterator_infofP"
.PP
Typedefs the fBnetsnmp_iterator_info_sfP struct into netsnmp_iterator_info. 
.PP
.SH "Function Documentation"
.PP 
.SS "void * netsnmp_extract_iterator_context (fBnetsnmp_request_infofP * request)"
.PP
extracts the table_iterator specific data from a request. 
.PP
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.
.PP
fBParameters:fP
.RS 4
fIrequestfP the netsnmp request info structure
.RE
.PP
fBReturns:fP
.RS 4
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
.RE
.PP
.PP
Definition at line 163 of file table_iterator.c.
.PP
References netsnmp_request_get_list_data(), and TABLE_ITERATOR_NAME.
.SS "fBnetsnmp_mib_handlerfP * netsnmp_get_table_iterator_handler (fBnetsnmp_iterator_infofP * iinfo)"
.PP
returns a netsnmp_mib_handler object for the table_iterator helper 
.PP
Definition at line 106 of file table_iterator.c.
.PP
References netsnmp_mib_handler_s::myvoid, netsnmp_create_handler(), netsnmp_table_iterator_helper_handler, NULL, and TABLE_ITERATOR_NAME.
.PP
Referenced by netsnmp_register_table_iterator().
.SS "void netsnmp_insert_iterator_context (fBnetsnmp_request_infofP * request, void * data)"
.PP
inserts table_iterator specific data for a newly created row into a request 
.PP
Definition at line 171 of file table_iterator.c.
.PP
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.
.SS "int netsnmp_register_table_iterator (fBnetsnmp_handler_registrationfP * reginfo, fBnetsnmp_iterator_infofP * iinfo)"
.PP
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. 
.PP
If NOT_SERIALIZED is not defined the function injects the serialize handler into the calling chain prior to calling netsnmp_register_table.
.PP
fBParameters:fP
.RS 4
fIreginfofP is a pointer to a netsnmp_handler_registration struct
.br
fIiinfofP is a pointer to a netsnmp_iterator_info struct
.RE
.PP
fBReturns:fP
.RS 4
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.
.RE
.PP
.PP
Definition at line 138 of file table_iterator.c.
.PP
References netsnmp_get_table_iterator_handler(), netsnmp_inject_handler(), netsnmp_register_table(), and netsnmp_iterator_info_s::table_reginfo.
.SS "int netsnmp_table_iterator_helper_handler (fBnetsnmp_mib_handlerfP * handler, fBnetsnmp_handler_registrationfP * reginfo, fBnetsnmp_agent_request_infofP * reqinfo, fBnetsnmp_request_infofP * requests)"
.PP
implements the table_iterator helper 
.PP
Definition at line 309 of file table_iterator.c.
.PP
References ti_cache_info_s::best_match, ti_cache_info_s::best_match_len, build_oid_noalloc(), netsnmp_table_request_info_s::colnum, netsnmp_data_list_s::data, ti_cache_info_s::data_context, 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_ITERATOR_FLAG_SORTED, netsnmp_oid_stash_add_data(), netsnmp_request_add_list_data(), netsnmp_request_get_list_data(), netsnmp_request_info_s::next, NULL, netsnmp_request_info_s::parent_data, netsnmp_request_info_s::processed, netsnmp_request_info_s::requestvb, ti_cache_info_s::results, netsnmp_handler_registration_s::rootoid, netsnmp_handler_registration_s::rootoid_len, snmp_clone_varbind(), SNMP_FREE, snmp_free_var(), snmp_free_varbind(), snmp_log(), SNMP_MALLOC_TYPEDEF, snmp_oid_compare(), snmp_set_var_objid(), netsnmp_request_info_s::subtree, TABLE_ITERATOR_NAME, TABLE_ITERATOR_NOTAGAIN, netsnmp_iterator_info_s::table_reginfo, and TI_REQUEST_CACHE.

						