1
.TH "table_iterator" 3 "5 Sep 2008" "Version 5.4.2" "net-snmp" \" -*- nroff -*-
1
.TH "table_iterator" 3 "23 May 2010" "Version 5.4.3.pre1" "net-snmp" \" -*- nroff -*-
5
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.
7
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.
8
9
.SS "Data Structures"
15
16
.RI "struct \fBnetsnmp_iterator_info_s\fP"
17
18
.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"
19
.RI "struct \fBnetsnmp_iterator_info_s\fP"
21
.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"
40
.RI "typedef \fBti_cache_info_s\fP \fBti_cache_info\fP"
37
.RI "typedef struct \fBti_cache_info_s\fP \fBti_cache_info\fP"
43
40
.RI "typedef \fBnetsnmp_variable_list\fP *( \fBNetsnmp_First_Data_Point\fP )(void **loop_context, void **data_context, \fBnetsnmp_variable_list\fP *, struct \fBnetsnmp_iterator_info_s\fP *)"
55
52
.RI "typedef void( \fBNetsnmp_Free_Data_Context\fP )(void *, struct \fBnetsnmp_iterator_info_s\fP *)"
58
.RI "typedef \fBnetsnmp_iterator_info_s\fP \fBnetsnmp_iterator_info\fP"
55
.RI "typedef struct \fBnetsnmp_iterator_info_s\fP \fBnetsnmp_iterator_info\fP"
60
57
.RI "\fITypedefs the \fBnetsnmp_iterator_info_s\fP struct into netsnmp_iterator_info. \fP"
66
.RI "\fBnetsnmp_iterator_info\fP * \fBnetsnmp_iterator_create_table\fP (\fBNetsnmp_First_Data_Point\fP *firstDP, \fBNetsnmp_Next_Data_Point\fP *nextDP, \fBNetsnmp_First_Data_Point\fP *getidx, \fBnetsnmp_variable_list\fP *indexes)"
63
.RI "\fBnetsnmp_iterator_info\fP * \fBnetsnmp_iterator_create_table\fP (Netsnmp_First_Data_Point *firstDP, Netsnmp_Next_Data_Point *nextDP, Netsnmp_First_Data_Point *getidx, \fBnetsnmp_variable_list\fP *indexes)"
69
66
.RI "void \fBnetsnmp_iterator_delete_table\fP (\fBnetsnmp_iterator_info\fP *iinfo)"
119
.RI "\fBNetsnmp_Node_Handler\fP \fBnetsnmp_table_iterator_helper_handler\fP"
116
.RI "Netsnmp_Node_Handler \fBnetsnmp_table_iterator_helper_handler\fP"
122
119
.SH "Detailed Description"
124
121
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.
126
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.
123
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 \fBmodule\fP that wishes help. The \fBmodule\fP 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.
128
125
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:
131
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.
128
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 \fBnode\fP, 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.
138
135
The table iterator operates in a series of steps that call your code hooks from your netsnmp_iterator_info registration pointer.
141
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.
138
the get_first_data_point hook is called at the beginning of processing. It should set the \fBvariable\fP 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.
150
147
.SS "struct \fBnetsnmp_iterator_info_s\fP \fBnetsnmp_iterator_info\fP"
152
149
Typedefs the \fBnetsnmp_iterator_info_s\fP struct into netsnmp_iterator_info.
154
150
.SH "Function Documentation"
156
152
.SS "void * netsnmp_extract_iterator_context (\fBnetsnmp_request_info\fP * request)"
158
extracts the table_iterator specific data from a request.
160
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.
154
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 \fBmodule\fP and TABLE_ITERATOR_NAME handler name.
162
156
\fBParameters:\fP
174
Definition at line 234 of file table_iterator.c.
176
References netsnmp_request_get_list_data(), and TABLE_ITERATOR_NAME.
177
167
.SS "\fBnetsnmp_mib_handler\fP * netsnmp_get_table_iterator_handler (\fBnetsnmp_iterator_info\fP * iinfo)"
179
169
returns a netsnmp_mib_handler object for the table_iterator helper
181
Definition at line 169 of file table_iterator.c.
183
References netsnmp_mib_handler_s::myvoid, netsnmp_create_handler(), netsnmp_table_iterator_helper_handler, NULL, and TABLE_ITERATOR_NAME.
185
Referenced by netsnmp_register_table_iterator().
186
170
.SS "void netsnmp_insert_iterator_context (\fBnetsnmp_request_info\fP * request, void * data)"
188
172
inserts table_iterator specific data for a newly created row into a request
190
Definition at line 242 of file table_iterator.c.
192
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.
193
173
.SS "int netsnmp_register_table_iterator (\fBnetsnmp_handler_registration\fP * reginfo, \fBnetsnmp_iterator_info\fP * iinfo)"
195
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.
197
If NOT_SERIALIZED is not defined the function injects the serialize handler into the calling chain prior to calling netsnmp_register_table.
175
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.
199
177
\fBParameters:\fP
213
Definition at line 205 of file table_iterator.c.
215
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 netsnmp_iterator_info_s::table_reginfo.
192
Generated automatically by Doxygen for net-snmp from the source code.
added
removed
man/netsnmp_table_iterator.3
