1table_iterator(3) net-snmp table_iterator(3)
2
6 table_iterator - The table iterator helper is designed to simplify the
7 task of writing a table handler for the net-snmp agent when the data
8 being accessed is not in an oid sorted form and must be accessed
9 externally.
10 Data Structures
13 struct ti_cache_info_s
14 struct netsnmp_iterator_info_s
15 Holds iterator information containing functions which should be
16 called by the iterator_handler to loop over your data set and sort
17 it in a SNMP specific manner.
18 struct netsnmp_iterator_info_s
19 Holds iterator information containing functions which should be
20 called by the iterator_handler to loop over your data set and sort
21 it in a SNMP specific manner.
22 Defines
24 #define TI_REQUEST_CACHE 'ti_cache'
25 #define TABLE_ITERATOR_NOTAGAIN 255
26 #define TABLE_ITERATOR_NAME 'table_iterator'
27 Typedefs
29 typedef ti_cache_info_s ti_cache_info
30 typedef netsnmp_variable_list *() Netsnmp_First_Data_Point (void
31 **loop_context, void **data_context, netsnmp_variable_list *,
32 struct netsnmp_iterator_info_s *)
33 typedef netsnmp_variable_list *() Netsnmp_Next_Data_Point (void
34 **loop_context, void **data_context, netsnmp_variable_list *,
35 struct netsnmp_iterator_info_s *)
36 typedef void *() Netsnmp_Make_Data_Context (void *loop_context, struct
37 netsnmp_iterator_info_s *)
38 typedef void() Netsnmp_Free_Loop_Context (void *, struct
39 netsnmp_iterator_info_s *)
40 typedef void() Netsnmp_Free_Data_Context (void *, struct
41 netsnmp_iterator_info_s *)
42 typedef netsnmp_iterator_info_s netsnmp_iterator_info
43 Typedefs the netsnmp_iterator_info_s struct into
44 netsnmp_iterator_info.
45 Functions
47 netsnmp_iterator_info * netsnmp_iterator_create_table
48 (Netsnmp_First_Data_Point *firstDP, Netsnmp_Next_Data_Point
49 *nextDP, Netsnmp_First_Data_Point *getidx, netsnmp_variable_list
50 *indexes)
51 void netsnmp_iterator_delete_table (netsnmp_iterator_info *iinfo)
52 netsnmp_mib_handler * netsnmp_get_table_iterator_handler
53 (netsnmp_iterator_info *iinfo)
54 returns a netsnmp_mib_handler object for the table_iterator helper
55 int netsnmp_register_table_iterator (netsnmp_handler_registration
56 *reginfo, netsnmp_iterator_info *iinfo)
57 Creates and registers a table iterator helper handler calling
58 netsnmp_create_handler with a handler name set to
59 TABLE_ITERATOR_NAME and access method,
60 netsnmp_table_iterator_helper_handler.
61 NETSNMP_INLINE void * netsnmp_extract_iterator_context
62 (netsnmp_request_info *request)
63 extracts the table_iterator specific data from a request.
64 NETSNMP_INLINE void netsnmp_insert_iterator_context
65 (netsnmp_request_info *request, void *data)
66 inserts table_iterator specific data for a newly created row into a
67 request
68 int netsnmp_table_iterator_helper_handler (netsnmp_mib_handler
69 *handler, netsnmp_handler_registration *reginfo,
70 netsnmp_agent_request_info *reqinfo, netsnmp_request_info
71 *requests)
72 void * netsnmp_iterator_row_first (netsnmp_iterator_info *iinfo)
73 void * netsnmp_iterator_row_get (netsnmp_iterator_info *iinfo, void
74 *row)
75 void * netsnmp_iterator_row_next (netsnmp_iterator_info *iinfo, void
76 *row)
77 void * netsnmp_iterator_row_get_byidx (netsnmp_iterator_info *iinfo,
78 netsnmp_variable_list *indexes)
79 void * netsnmp_iterator_row_next_byidx (netsnmp_iterator_info *iinfo,
80 netsnmp_variable_list *indexes)
81 void * netsnmp_iterator_row_get_byoid (netsnmp_iterator_info *iinfo,
82 oid *instance, size_t len)
83 void * netsnmp_iterator_row_next_byoid (netsnmp_iterator_info *iinfo,
84 oid *instance, size_t len)
85 int netsnmp_iterator_row_count (netsnmp_iterator_info *iinfo)
86 Variables
88 Netsnmp_Node_Handler netsnmp_table_iterator_helper_handler
89
91 The table iterator helper is designed to simplify the task of writing a
92 table handler for the net-snmp agent when the data being accessed is
93 not in an oid sorted form and must be accessed externally.
94 Functionally, it is a specialized version of the more generic table
96 helper but easies the burden of GETNEXT processing by manually looping
97 through all the data indexes retrieved through function calls which
98 should be supplied by the module that wishes help. The module the
99 table_iterator helps should, afterwards, never be called for the case
100 of 'MODE_GETNEXT' and only for the GET and SET related modes instead.
101 The fundamental notion between the table iterator is that it allows
103 your code to iterate over each 'row' within your data storage
104 mechanism, without requiring that it be sorted in a SNMP-index-
105 compliant manner. Through the get_first_data_point and
106 get_next_data_point hooks, the table_iterator helper will repeatedly
107 call your hooks to find the 'proper' row of data that needs processing.
108 The following concepts are important:
109 · A loop context is a pointer which indicates where in the current
111 processing of a set of rows you currently are. Allows the
112 get_*_data_point routines to move from one row to the next, once the
113 iterator handler has identified the appropriate row for this request,
114 the job of the loop context is done. The most simple example would be
115 a pointer to an integer which simply counts rows from 1 to X. More
116 commonly, it might be a pointer to a linked list node, or someother
117 internal or external reference to a data set (file seek value, array
118 pointer, ...). If allocated during iteration, either the
119 free_loop_context_at_end (preferably) or the free_loop_context
120 pointers should be set.
121 · A data context is something that your handler code can use in order
123 to retrieve the rest of the data for the needed row. This data can be
124 accessed in your handler via netsnmp_extract_iterator_context api
125 with the netsnmp_request_info structure that's passed in. The
126 important difference between a loop context and a data context is
127 that multiple data contexts can be kept by the table_iterator helper,
128 where as only one loop context will ever be held by the
129 table_iterator helper. If allocated during iteration the
130 free_data_context pointer should be set to an appropriate function.
131 The table iterator operates in a series of steps that call your code
133 hooks from your netsnmp_iterator_info registration pointer.
134 · the get_first_data_point hook is called at the beginning of
136 processing. It should set the variable list to a list of indexes for
137 the given table. It should also set the loop_context and maybe a
138 data_context which you will get a pointer back to when it needs to
139 call your code to retrieve actual data later. The list of indexes
140 should be returned after being update.
141 · the get_next_data_point hook is then called repeatedly and is passed
143 the loop context and the data context for it to update. The indexes,
144 loop context and data context should all be updated if more data is
145 available, otherwise they should be left alone and a NULL should be
146 returned. Ideally, it should update the loop context without the need
147 to reallocate it. If reallocation is necessary for every iterative
148 step, then the free_loop_context function pointer should be set. If
149 not, then the free_loop_context_at_end pointer should be set, which
150 is more efficient since a malloc/free will only be performed once for
151 every iteration.
152
154 struct netsnmp_iterator_info_s netsnmp_iterator_info
155 Typedefs the netsnmp_iterator_info_s struct into netsnmp_iterator_info.
156
158 void * netsnmp_extract_iterator_context (netsnmp_request_info * request)
159 extracts the table_iterator specific data from a request.
160 This function extracts the table iterator specific data from a
162 netsnmp_request_info object. Calls netsnmp_request_get_list_data with
163 request->parent_data set with data from a request that was added
164 previously by a module and TABLE_ITERATOR_NAME handler name.
165 Parameters:
167 request the netsnmp request info structure
168 Returns:
170 a void pointer(request->parent_data->data), otherwise NULL is
171 returned if request is NULL or request->parent_data is NULL or
172 request->parent_data object is not found.the net
173 Definition at line 234 of file table_iterator.c.
175 References netsnmp_request_get_list_data(), and TABLE_ITERATOR_NAME.
177 netsnmp_mib_handler * netsnmp_get_table_iterator_handler
179 (netsnmp_iterator_info * iinfo)
180 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(),
185 netsnmp_table_iterator_helper_handler, NULL, and TABLE_ITERATOR_NAME.
186 Referenced by netsnmp_register_table_iterator().
188 void netsnmp_insert_iterator_context (netsnmp_request_info * request, void
190 * data)
191 inserts table_iterator specific data for a newly created row into a
192 request
193 Definition at line 242 of file table_iterator.c.
195 References build_oid_noalloc(), netsnmp_table_request_info_s::indexes,
197 netsnmp_create_data_list(), netsnmp_extract_table_info(),
198 netsnmp_request_add_list_data(), netsnmp_request_info_s::next, NULL,
199 netsnmp_request_info_s::prev, snmp_oid_compare(), and
200 TABLE_ITERATOR_NAME.
201 int netsnmp_register_table_iterator (netsnmp_handler_registration *
203 reginfo, netsnmp_iterator_info * iinfo)
204 Creates and registers a table iterator helper handler calling
205 netsnmp_create_handler with a handler name set to TABLE_ITERATOR_NAME
206 and access method, netsnmp_table_iterator_helper_handler.
207 If NOT_SERIALIZED is not defined the function injects the serialize
209 handler into the calling chain prior to calling netsnmp_register_table.
210 Parameters:
212 reginfo is a pointer to a netsnmp_handler_registration struct
213 iinfo is a pointer to a netsnmp_iterator_info struct
214 Returns:
216 MIB_REGISTERED_OK is returned if the registration was a success.
217 Failures are MIB_REGISTRATION_FAILED, MIB_DUPLICATE_REGISTRATION.
218 If iinfo is NULL, SNMPERR_GENERR is returned.
219 Definition at line 205 of file table_iterator.c.
221 References HANDLER_CAN_STASH,
223 netsnmp_table_registration_info_s::indexes,
224 netsnmp_iterator_info_s::indexes,
225 netsnmp_handler_registration_s::modes,
226 netsnmp_get_table_iterator_handler(), netsnmp_inject_handler(),
227 netsnmp_register_table(), snmp_clone_varbind(), and
228 netsnmp_iterator_info_s::table_reginfo.
229Version 5.4 24 Nov 2006 table_iterator(3)