~ubuntu-branches/ubuntu/wily/net-snmp/wily-proposed

« back to all changes in this revision

Viewing changes to .pc/56_manpage.patch/man/netsnmp_handler.3

  • Committer: Bazaar Package Importer
  • Author(s): Chuck Short
  • Date: 2010-06-28 14:59:36 UTC
  • mfrom: (1.2.3 upstream) (1.1.12 sid)
  • Revision ID: james.westby@ubuntu.com-20100628145936-cbiallic69pn044g
Tags: 5.4.3~dfsg-1ubuntu1
* Merge from debian unstable.  Remaining changes:
  - Set Ubuntu maintainer address.
  - net-snmp-config: Use bash. (LP: #104738)
  - Removed multiuser option when calling update-rc.d. (LP: #254261)
  - debian/snmpd.init: LSBify the init script.
  - debian/patches/52_fix_snmpcmd_1_typo.patch: Adjust a typo in snmpcmd.1
    (LP: #250459)
  - debian/snmpd.postinst: source debconf before doing work, LP: #589056
  - debian/snmp.preinst, debian/snmp.prerm: kill any/all processes owned by
    snmp user before install/uninstall, LP: #573391
  - Add apport hook (LP: #533603):
  - debian/{snmp,snmpd}.apport: Added.
  - debian/control: Build-depends on dh-apport.
  - debian/rules: 
    + Add --with apport.
    + override_dh_apport to install hook on snmpd package only.
 * Dropped patches:
   - debian/patches/99-fix-ubuntu-div0.patch: Fix dvision by zero.. 

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
.TH "Net-SNMP Agent handler and extensibility API" 3 "23 May 2010" "Version 5.4.3.pre1" "net-snmp" \" -*- nroff -*-
 
2
.ad l
 
3
.nh
 
4
.SH NAME
 
5
Net-SNMP Agent handler and extensibility API \- 
 
6
.PP
 
7
The basic theory goes something like this: In the past, with the original mib \fBmodule\fP api (which derived from the original CMU SNMP code) the underlying mib modules were passed very little information (only the truly most basic information about a request).  
 
8
 
 
9
.SS "Data Structures"
 
10
 
 
11
.in +1c
 
12
.ti -1c
 
13
.RI "struct \fBnetsnmp_mib_handler_s\fP"
 
14
.br
 
15
.RI "\fIthe mib handler structure to be registered \fP"
 
16
.ti -1c
 
17
.RI "struct \fBnetsnmp_handler_registration_s\fP"
 
18
.br
 
19
.RI "\fIRoot registration info. \fP"
 
20
.ti -1c
 
21
.RI "struct \fBnetsnmp_handler_args_s\fP"
 
22
.br
 
23
.ti -1c
 
24
.RI "struct \fBnetsnmp_delegated_cache_s\fP"
 
25
.br
 
26
.in -1c
 
27
.SS "Modules"
 
28
 
 
29
.in +1c
 
30
.ti -1c
 
31
.RI "\fButility_handlers\fP"
 
32
.br
 
33
.PP
 
34
 
 
35
.RI "\fISimplify request processing A group of handlers intended to simplify certain aspects of processing a request for a MIB object. \fP"
 
36
.ti -1c
 
37
.RI "\fBleaf_handlers\fP"
 
38
.br
 
39
.PP
 
40
 
 
41
.RI "\fIProcess individual leaf objects A group of handlers to implement individual leaf objects and instances (both scalar objects, and individual objects and instances within a table). \fP"
 
42
.ti -1c
 
43
.RI "\fBbaby_steps\fP"
 
44
.br
 
45
.PP
 
46
 
 
47
.RI "\fICalls your handler in baby_steps for set processing. \fP"
 
48
.ti -1c
 
49
.RI "\fBold_api\fP"
 
50
.br
 
51
.PP
 
52
 
 
53
.RI "\fICalls mib \fBmodule\fP code written in the old style of code. \fP"
 
54
.ti -1c
 
55
.RI "\fBstash_cache\fP"
 
56
.br
 
57
.PP
 
58
 
 
59
.RI "\fIAutomatically caches data for certain handlers. \fP"
 
60
.ti -1c
 
61
.RI "\fBtable\fP"
 
62
.br
 
63
.PP
 
64
 
 
65
.RI "\fIHelps you implement a table. \fP"
 
66
.in -1c
 
67
.SS "Defines"
 
68
 
 
69
.in +1c
 
70
.ti -1c
 
71
.RI "#define \fBMIB_HANDLER_AUTO_NEXT\fP   0x00000001"
 
72
.br
 
73
.ti -1c
 
74
.RI "#define \fBMIB_HANDLER_AUTO_NEXT_OVERRIDE_ONCE\fP   0x00000002"
 
75
.br
 
76
.ti -1c
 
77
.RI "#define \fBMIB_HANDLER_INSTANCE\fP   0x00000004"
 
78
.br
 
79
.ti -1c
 
80
.RI "#define \fBMIB_HANDLER_CUSTOM4\fP   0x10000000"
 
81
.br
 
82
.ti -1c
 
83
.RI "#define \fBMIB_HANDLER_CUSTOM3\fP   0x20000000"
 
84
.br
 
85
.ti -1c
 
86
.RI "#define \fBMIB_HANDLER_CUSTOM2\fP   0x40000000"
 
87
.br
 
88
.ti -1c
 
89
.RI "#define \fBMIB_HANDLER_CUSTOM1\fP   0x80000000"
 
90
.br
 
91
.ti -1c
 
92
.RI "#define \fBHANDLER_CAN_GETANDGETNEXT\fP   0x01"
 
93
.br
 
94
.ti -1c
 
95
.RI "#define \fBHANDLER_CAN_SET\fP   0x02"
 
96
.br
 
97
.ti -1c
 
98
.RI "#define \fBHANDLER_CAN_GETBULK\fP   0x04"
 
99
.br
 
100
.ti -1c
 
101
.RI "#define \fBHANDLER_CAN_NOT_CREATE\fP   0x08"
 
102
.br
 
103
.ti -1c
 
104
.RI "#define \fBHANDLER_CAN_BABY_STEP\fP   0x10"
 
105
.br
 
106
.ti -1c
 
107
.RI "#define \fBHANDLER_CAN_STASH\fP   0x20"
 
108
.br
 
109
.ti -1c
 
110
.RI "#define \fBHANDLER_CAN_RONLY\fP   (HANDLER_CAN_GETANDGETNEXT)"
 
111
.br
 
112
.ti -1c
 
113
.RI "#define \fBHANDLER_CAN_RWRITE\fP   (HANDLER_CAN_GETANDGETNEXT | HANDLER_CAN_SET)"
 
114
.br
 
115
.ti -1c
 
116
.RI "#define \fBHANDLER_CAN_SET_ONLY\fP   (HANDLER_CAN_SET | HANDLER_CAN_NOT_CREATE)"
 
117
.br
 
118
.ti -1c
 
119
.RI "#define \fBHANDLER_CAN_DEFAULT\fP   (HANDLER_CAN_RONLY | HANDLER_CAN_NOT_CREATE)"
 
120
.br
 
121
.ti -1c
 
122
.RI "#define \fBREQUEST_IS_DELEGATED\fP   1"
 
123
.br
 
124
.ti -1c
 
125
.RI "#define \fBREQUEST_IS_NOT_DELEGATED\fP   0"
 
126
.br
 
127
.in -1c
 
128
.SS "Typedefs"
 
129
 
 
130
.in +1c
 
131
.ti -1c
 
132
.RI "typedef struct \fBnetsnmp_mib_handler_s\fP \fBnetsnmp_mib_handler\fP"
 
133
.br
 
134
.RI "\fITypedefs the \fBnetsnmp_mib_handler_s\fP struct into netsnmp_mib_handler. \fP"
 
135
.ti -1c
 
136
.RI "typedef struct \fBnetsnmp_handler_registration_s\fP \fBnetsnmp_handler_registration\fP"
 
137
.br
 
138
.RI "\fITypedefs the \fBnetsnmp_handler_registration_s\fP struct into netsnmp_handler_registration. \fP"
 
139
.ti -1c
 
140
.RI "typedef int( \fBNetsnmp_Node_Handler\fP )(\fBnetsnmp_mib_handler\fP *handler, \fBnetsnmp_handler_registration\fP *reginfo, \fBnetsnmp_agent_request_info\fP *reqinfo, \fBnetsnmp_request_info\fP *requests)"
 
141
.br
 
142
.ti -1c
 
143
.RI "typedef struct \fBnetsnmp_handler_args_s\fP \fBnetsnmp_handler_args\fP"
 
144
.br
 
145
.ti -1c
 
146
.RI "typedef struct \fBnetsnmp_delegated_cache_s\fP \fBnetsnmp_delegated_cache\fP"
 
147
.br
 
148
.in -1c
 
149
.SS "Functions"
 
150
 
 
151
.in +1c
 
152
.ti -1c
 
153
.RI "\fBnetsnmp_mib_handler\fP * \fBnetsnmp_create_handler\fP (const char *name, Netsnmp_Node_Handler *handler_access_method)"
 
154
.br
 
155
.RI "\fIcreates a netsnmp_mib_handler structure given a name and a access method. \fP"
 
156
.ti -1c
 
157
.RI "\fBnetsnmp_handler_registration\fP * \fBnetsnmp_handler_registration_create\fP (const char *name, \fBnetsnmp_mib_handler\fP *handler, oid *reg_oid, size_t reg_oid_len, int modes)"
 
158
.br
 
159
.RI "\fIcreates a handler registration structure given a name, a access_method function, a registration location oid and the modes the handler supports. \fP"
 
160
.ti -1c
 
161
.RI "\fBnetsnmp_handler_registration\fP * \fBnetsnmp_create_handler_registration\fP (const char *name, Netsnmp_Node_Handler *handler_access_method, oid *reg_oid, size_t reg_oid_len, int modes)"
 
162
.br
 
163
.ti -1c
 
164
.RI "int \fBnetsnmp_register_handler\fP (\fBnetsnmp_handler_registration\fP *reginfo)"
 
165
.br
 
166
.RI "\fIregister a handler, as defined by the netsnmp_handler_registration pointer. \fP"
 
167
.ti -1c
 
168
.RI "int \fBnetsnmp_unregister_handler\fP (\fBnetsnmp_handler_registration\fP *reginfo)"
 
169
.br
 
170
.RI "\fIunregister a handler, as defined by the netsnmp_handler_registration pointer. \fP"
 
171
.ti -1c
 
172
.RI "int \fBnetsnmp_register_handler_nocallback\fP (\fBnetsnmp_handler_registration\fP *reginfo)"
 
173
.br
 
174
.RI "\fIregister a handler, as defined by the netsnmp_handler_registration pointer. \fP"
 
175
.ti -1c
 
176
.RI "int \fBnetsnmp_inject_handler_before\fP (\fBnetsnmp_handler_registration\fP *reginfo, \fBnetsnmp_mib_handler\fP *handler, const char *before_what)"
 
177
.br
 
178
.RI "\fIinject a new handler into the calling chain of the handlers definedy by the netsnmp_handler_registration pointer. \fP"
 
179
.ti -1c
 
180
.RI "int \fBnetsnmp_inject_handler\fP (\fBnetsnmp_handler_registration\fP *reginfo, \fBnetsnmp_mib_handler\fP *handler)"
 
181
.br
 
182
.RI "\fIinject a new handler into the calling chain of the handlers definedy by the netsnmp_handler_registration pointer. \fP"
 
183
.ti -1c
 
184
.RI "NETSNMP_INLINE int \fBnetsnmp_call_handler\fP (\fBnetsnmp_mib_handler\fP *next_handler, \fBnetsnmp_handler_registration\fP *reginfo, \fBnetsnmp_agent_request_info\fP *reqinfo, \fBnetsnmp_request_info\fP *requests)"
 
185
.br
 
186
.RI "\fIcalls a handler with with appropriate NULL checking of arguments, etc. \fP"
 
187
.ti -1c
 
188
.RI "int \fBnetsnmp_call_handlers\fP (\fBnetsnmp_handler_registration\fP *reginfo, \fBnetsnmp_agent_request_info\fP *reqinfo, \fBnetsnmp_request_info\fP *requests)"
 
189
.br
 
190
.ti -1c
 
191
.RI "NETSNMP_INLINE int \fBnetsnmp_call_next_handler\fP (\fBnetsnmp_mib_handler\fP *current, \fBnetsnmp_handler_registration\fP *reginfo, \fBnetsnmp_agent_request_info\fP *reqinfo, \fBnetsnmp_request_info\fP *requests)"
 
192
.br
 
193
.RI "\fIcalls the next handler in the chain after the current one with with appropriate NULL checking, etc. \fP"
 
194
.ti -1c
 
195
.RI "NETSNMP_INLINE int \fBnetsnmp_call_next_handler_one_request\fP (\fBnetsnmp_mib_handler\fP *current, \fBnetsnmp_handler_registration\fP *reginfo, \fBnetsnmp_agent_request_info\fP *reqinfo, \fBnetsnmp_request_info\fP *requests)"
 
196
.br
 
197
.RI "\fIcalls the next handler in the chain after the current one with with appropriate NULL checking, etc. \fP"
 
198
.ti -1c
 
199
.RI "void \fBnetsnmp_handler_free\fP (\fBnetsnmp_mib_handler\fP *handler)"
 
200
.br
 
201
.RI "\fIfree's the resourceses associated with a given handler \fP"
 
202
.ti -1c
 
203
.RI "\fBnetsnmp_mib_handler\fP * \fBnetsnmp_handler_dup\fP (\fBnetsnmp_mib_handler\fP *handler)"
 
204
.br
 
205
.RI "\fIdulpicates a handler and all subsequent handlers see also _clone_handler \fP"
 
206
.ti -1c
 
207
.RI "void \fBnetsnmp_handler_registration_free\fP (\fBnetsnmp_handler_registration\fP *reginfo)"
 
208
.br
 
209
.RI "\fIfree the resources associated with a handler registration object \fP"
 
210
.ti -1c
 
211
.RI "\fBnetsnmp_handler_registration\fP * \fBnetsnmp_handler_registration_dup\fP (\fBnetsnmp_handler_registration\fP *reginfo)"
 
212
.br
 
213
.RI "\fIduplicates the handler registration object \fP"
 
214
.ti -1c
 
215
.RI "NETSNMP_INLINE \fBnetsnmp_delegated_cache\fP * \fBnetsnmp_create_delegated_cache\fP (\fBnetsnmp_mib_handler\fP *handler, \fBnetsnmp_handler_registration\fP *reginfo, \fBnetsnmp_agent_request_info\fP *reqinfo, \fBnetsnmp_request_info\fP *requests, void *localinfo)"
 
216
.br
 
217
.RI "\fIcreates a cache of information which can be saved for future reference. \fP"
 
218
.ti -1c
 
219
.RI "NETSNMP_INLINE \fBnetsnmp_delegated_cache\fP * \fBnetsnmp_handler_check_cache\fP (\fBnetsnmp_delegated_cache\fP *dcache)"
 
220
.br
 
221
.RI "\fIcheck's a given cache and returns it if it is still valid (ie, the agent still considers it to be an outstanding request. \fP"
 
222
.ti -1c
 
223
.RI "NETSNMP_INLINE void \fBnetsnmp_free_delegated_cache\fP (\fBnetsnmp_delegated_cache\fP *dcache)"
 
224
.br
 
225
.RI "\fIfrees a cache once you're finished using it \fP"
 
226
.ti -1c
 
227
.RI "void \fBnetsnmp_handler_mark_requests_as_delegated\fP (\fBnetsnmp_request_info\fP *requests, int isdelegated)"
 
228
.br
 
229
.RI "\fImarks a list of requests as delegated (or not if isdelegaded = 0) \fP"
 
230
.ti -1c
 
231
.RI "NETSNMP_INLINE void \fBnetsnmp_request_add_list_data\fP (\fBnetsnmp_request_info\fP *request, \fBnetsnmp_data_list\fP *\fBnode\fP)"
 
232
.br
 
233
.RI "\fIadd data to a request that can be extracted later by submodules \fP"
 
234
.ti -1c
 
235
.RI "NETSNMP_INLINE int \fBnetsnmp_request_remove_list_data\fP (\fBnetsnmp_request_info\fP *request, const char *name)"
 
236
.br
 
237
.RI "\fIremove data from a request \fP"
 
238
.ti -1c
 
239
.RI "void * \fBnetsnmp_request_get_list_data\fP (\fBnetsnmp_request_info\fP *request, const char *name)"
 
240
.br
 
241
.RI "\fIextract data from a request that was added previously by a parent \fBmodule\fP \fP"
 
242
.ti -1c
 
243
.RI "NETSNMP_INLINE void \fBnetsnmp_free_request_data_set\fP (\fBnetsnmp_request_info\fP *request)"
 
244
.br
 
245
.RI "\fIFree the extra data stored in a request. \fP"
 
246
.ti -1c
 
247
.RI "NETSNMP_INLINE void \fBnetsnmp_free_request_data_sets\fP (\fBnetsnmp_request_info\fP *request)"
 
248
.br
 
249
.RI "\fIFree the extra data stored in a bunch of requests (all data in the chain). \fP"
 
250
.ti -1c
 
251
.RI "\fBnetsnmp_mib_handler\fP * \fBnetsnmp_find_handler_by_name\fP (\fBnetsnmp_handler_registration\fP *reginfo, const char *name)"
 
252
.br
 
253
.RI "\fIReturns a handler from a chain based on the name. \fP"
 
254
.ti -1c
 
255
.RI "void * \fBnetsnmp_find_handler_data_by_name\fP (\fBnetsnmp_handler_registration\fP *reginfo, const char *name)"
 
256
.br
 
257
.RI "\fIReturns a handler's void * pointer from a chain based on the name. \fP"
 
258
.ti -1c
 
259
.RI "void \fBhandler_free_callback\fP (void *free)"
 
260
.br
 
261
.ti -1c
 
262
.RI "void \fBnetsnmp_register_handler_by_name\fP (const char *name, \fBnetsnmp_mib_handler\fP *handler)"
 
263
.br
 
264
.RI "\fIregisters a given handler by name so that it can be found easily later. \fP"
 
265
.ti -1c
 
266
.RI "void \fBnetsnmp_clear_handler_list\fP (void)"
 
267
.br
 
268
.RI "\fIclears the entire handler-registration list \fP"
 
269
.ti -1c
 
270
.RI "void \fBnetsnmp_inject_handler_into_subtree\fP (\fBnetsnmp_subtree\fP *tp, const char *name, \fBnetsnmp_mib_handler\fP *handler, const char *before_what)"
 
271
.br
 
272
.ti -1c
 
273
.RI "void \fBparse_injectHandler_conf\fP (const char *token, char *cptr)"
 
274
.br
 
275
.ti -1c
 
276
.RI "void \fBnetsnmp_init_handler_conf\fP (void)"
 
277
.br
 
278
.ti -1c
 
279
.RI "void * \fBnetsnmp_handler_get_parent_data\fP (\fBnetsnmp_request_info\fP *, const char *)"
 
280
.br
 
281
.in -1c
 
282
.SH "Detailed Description"
 
283
.PP 
 
284
The basic theory goes something like this: In the past, with the original mib \fBmodule\fP api (which derived from the original CMU SNMP code) the underlying mib modules were passed very little information (only the truly most basic information about a request). 
 
285
 
 
286
This worked well at the time but in todays world of subagents, device instrumentation, low resource consumption, etc, it just isn't flexible enough. 'handlers' are here to fix all that.
 
287
.PP
 
288
With the rewrite of the agent internals for the net-snmp 5.0 release, we introduce a modular calling scheme that allows agent modules to be written in a very flexible manner, and more importantly allows reuse of code in a decent way (and without the memory and speed overheads of OO languages like C++).
 
289
.PP
 
290
Functionally, the notion of what a handler does is the same as the older api: A handler is \fBcreated\fP and then \fBregistered\fP with the main agent at a given OID in the OID \fBtree\fP and gets called any time a request is made that it should respond to. You probably should use one of the convenience helpers instead of doing anything else yourself though:
 
291
.PP
 
292
Most importantly, though, is that the handlers are built on the notion of modularity and reuse. Specifically, rather than do all the really hard work (like parsing table indexes out of an incoming oid request) in each \fBmodule\fP, the API is designed to make it easy to write 'helper' handlers that merely process some aspect of the request before passing it along to the final handler that returns the real answer. Most people will want to make use of the \fBinstance\fP, \fBtable\fP, \fBtable_iterator\fP, \fBtable_data\fP, or \fBtable_dataset\fP helpers to make their life easier. These 'helpers' interpert important aspects of the request and pass them on to you.
 
293
.PP
 
294
For instance, the \fBtable\fP helper is designed to hand you a list of extracted index values from an incoming request. THe \fBtable_iterator\fP helper is built on top of the table helper, and is designed to help you iterate through data stored elsewhere (like in a kernel) that is not in OID lexographical order (ie, don't write your own index/oid sorting routine, use this helper instead). The beauty of the \fBtable_iterator helper\fP, as well as the \fBinstance\fP helper is that they take care of the complex GETNEXT processing entirely for you and hand you everything you need to merely return the data as if it was a GET request. Much less code and hair pulling. I've pulled all my hair out to help you so that only one of us has to be bald. 
 
295
.SH "Typedef Documentation"
 
296
.PP 
 
297
.SS "struct \fBnetsnmp_handler_registration_s\fP \fBnetsnmp_handler_registration\fP"
 
298
.PP
 
299
Typedefs the \fBnetsnmp_handler_registration_s\fP struct into netsnmp_handler_registration. 
 
300
.SS "struct \fBnetsnmp_mib_handler_s\fP \fBnetsnmp_mib_handler\fP"
 
301
.PP
 
302
Typedefs the \fBnetsnmp_mib_handler_s\fP struct into netsnmp_mib_handler. 
 
303
.SH "Function Documentation"
 
304
.PP 
 
305
.SS "int netsnmp_call_handler (\fBnetsnmp_mib_handler\fP * next_handler, \fBnetsnmp_handler_registration\fP * reginfo, \fBnetsnmp_agent_request_info\fP * reqinfo, \fBnetsnmp_request_info\fP * requests)"
 
306
.PP
 
307
calls a handler with with appropriate NULL checking of arguments, etc. 
 
308
.SS "int netsnmp_call_next_handler (\fBnetsnmp_mib_handler\fP * current, \fBnetsnmp_handler_registration\fP * reginfo, \fBnetsnmp_agent_request_info\fP * reqinfo, \fBnetsnmp_request_info\fP * requests)"
 
309
.PP
 
310
calls the next handler in the chain after the current one with with appropriate NULL checking, etc. 
 
311
.SS "int netsnmp_call_next_handler_one_request (\fBnetsnmp_mib_handler\fP * current, \fBnetsnmp_handler_registration\fP * reginfo, \fBnetsnmp_agent_request_info\fP * reqinfo, \fBnetsnmp_request_info\fP * requests)"
 
312
.PP
 
313
calls the next handler in the chain after the current one with with appropriate NULL checking, etc. 
 
314
.SS "void netsnmp_clear_handler_list (void)"
 
315
.PP
 
316
clears the entire handler-registration list 
 
317
.SS "\fBnetsnmp_delegated_cache\fP * netsnmp_create_delegated_cache (\fBnetsnmp_mib_handler\fP * handler, \fBnetsnmp_handler_registration\fP * reginfo, \fBnetsnmp_agent_request_info\fP * reqinfo, \fBnetsnmp_request_info\fP * requests, void * localinfo)"
 
318
.PP
 
319
creates a cache of information which can be saved for future reference. Use \fBnetsnmp_handler_check_cache()\fP later to make sure it's still valid before referencing it in the future. 
 
320
.PP
 
321
\fBExamples: \fP
 
322
.in +1c
 
323
\fBdelayed_instance.c\fP.
 
324
.SS "\fBnetsnmp_mib_handler\fP * netsnmp_create_handler (const char * name, Netsnmp_Node_Handler * handler_access_method)"
 
325
.PP
 
326
creates a netsnmp_mib_handler structure given a name and a access method. The returned handler should then be \fBregistered.\fP
 
327
.PP
 
328
\fBParameters:\fP
 
329
.RS 4
 
330
\fIname\fP is the handler name and is copied then assigned to netsnmp_mib_handler->handler_name
 
331
.br
 
332
\fIhandler_access_method\fP is a function pointer used as the access method for this handler registration instance for whatever required needs.
 
333
.RE
 
334
.PP
 
335
\fBReturns:\fP
 
336
.RS 4
 
337
a pointer to a populated netsnmp_mib_handler struct to be registered
 
338
.RE
 
339
.PP
 
340
\fBSee also:\fP
 
341
.RS 4
 
342
netsnmp_create_handler_registration() 
 
343
.PP
 
344
\fBnetsnmp_register_handler()\fP 
 
345
.RE
 
346
.PP
 
347
 
 
348
.SS "\fBnetsnmp_mib_handler\fP * netsnmp_find_handler_by_name (\fBnetsnmp_handler_registration\fP * reginfo, const char * name)"
 
349
.PP
 
350
Returns a handler from a chain based on the name. 
 
351
.SS "void * netsnmp_find_handler_data_by_name (\fBnetsnmp_handler_registration\fP * reginfo, const char * name)"
 
352
.PP
 
353
Returns a handler's void * pointer from a chain based on the name. This probably shouldn't be used by the general public as the void * data may change as a handler evolves. Handlers should really advertise some function for you to use instead. 
 
354
.SS "void netsnmp_free_delegated_cache (\fBnetsnmp_delegated_cache\fP * dcache)"
 
355
.PP
 
356
frees a cache once you're finished using it 
 
357
.PP
 
358
\fBExamples: \fP
 
359
.in +1c
 
360
\fBdelayed_instance.c\fP.
 
361
.SS "void netsnmp_free_request_data_set (\fBnetsnmp_request_info\fP * request)"
 
362
.PP
 
363
Free the extra data stored in a request. 
 
364
.SS "void netsnmp_free_request_data_sets (\fBnetsnmp_request_info\fP * request)"
 
365
.PP
 
366
Free the extra data stored in a bunch of requests (all data in the chain). 
 
367
.SS "\fBnetsnmp_delegated_cache\fP * netsnmp_handler_check_cache (\fBnetsnmp_delegated_cache\fP * dcache)"
 
368
.PP
 
369
check's a given cache and returns it if it is still valid (ie, the agent still considers it to be an outstanding request. Returns NULL if it's no longer valid. 
 
370
.PP
 
371
\fBExamples: \fP
 
372
.in +1c
 
373
\fBdelayed_instance.c\fP.
 
374
.SS "\fBnetsnmp_mib_handler\fP * netsnmp_handler_dup (\fBnetsnmp_mib_handler\fP * handler)"
 
375
.PP
 
376
dulpicates a handler and all subsequent handlers see also _clone_handler 
 
377
.SS "void netsnmp_handler_free (\fBnetsnmp_mib_handler\fP * handler)"
 
378
.PP
 
379
free's the resourceses associated with a given handler 
 
380
.PP
 
381
make sure we aren't pointing to ourselves.
 
382
.PP
 
383
XXX : segv here at shutdown if SHUTDOWN_AGENT_CLEANLY defined. About 30 functions down the stack, starting in clear_context() -> clear_subtree()
 
384
.SS "void netsnmp_handler_mark_requests_as_delegated (\fBnetsnmp_request_info\fP * requests, int isdelegated)"
 
385
.PP
 
386
marks a list of requests as delegated (or not if isdelegaded = 0) 
 
387
.SS "\fBnetsnmp_handler_registration\fP * netsnmp_handler_registration_create (const char * name, \fBnetsnmp_mib_handler\fP * handler, oid * reg_oid, size_t reg_oid_len, int modes)"
 
388
.PP
 
389
creates a handler registration structure given a name, a access_method function, a registration location oid and the modes the handler supports. If modes == 0, then modes will automatically be set to the default value of only HANDLER_CAN_DEFAULT, which is by default read-only GET and GETNEXT requests. A hander which supports sets but not row creation should set us a mode of HANDLER_CAN_SET_ONLY. 
 
390
.PP
 
391
\fBNote:\fP
 
392
.RS 4
 
393
This ends up calling netsnmp_create_handler(name, handler_access_method) 
 
394
.RE
 
395
.PP
 
396
\fBParameters:\fP
 
397
.RS 4
 
398
\fIname\fP is the handler name and is copied then assigned to netsnmp_handler_registration->handlerName.
 
399
.br
 
400
\fIhandler\fP is a function pointer used as the access method for this handler registration instance for whatever required needs.
 
401
.br
 
402
\fIreg_oid\fP is the registration location oid.
 
403
.br
 
404
\fIreg_oid_len\fP is the length of reg_oid, can use the macro, OID_LENGTH
 
405
.br
 
406
\fImodes\fP is used to configure read/write access. If modes == 0, then modes will automatically be set to the default value of only HANDLER_CAN_DEFAULT, which is by default read-only GET and GETNEXT requests. The other two mode options are read only, HANDLER_CAN_RONLY, and read/write, HANDLER_CAN_RWRITE.
 
407
.RE
 
408
.PP
 
409
.IP "\(bu" 2
 
410
HANDLER_CAN_GETANDGETNEXT
 
411
.IP "\(bu" 2
 
412
HANDLER_CAN_SET
 
413
.IP "\(bu" 2
 
414
HANDLER_CAN_GETBULK
 
415
.PP
 
416
.PP
 
417
.IP "\(bu" 2
 
418
HANDLER_CAN_RONLY (HANDLER_CAN_GETANDGETNEXT)
 
419
.IP "\(bu" 2
 
420
HANDLER_CAN_RWRITE (HANDLER_CAN_GETANDGETNEXT | HANDLER_CAN_SET)
 
421
.IP "\(bu" 2
 
422
HANDLER_CAN_DEFAULT HANDLER_CAN_RONLY
 
423
.PP
 
424
.PP
 
425
\fBReturns:\fP
 
426
.RS 4
 
427
Returns a pointer to a netsnmp_handler_registration struct. NULL is returned only when memory could not be allocated for the netsnmp_handler_registration struct.
 
428
.RE
 
429
.PP
 
430
\fBSee also:\fP
 
431
.RS 4
 
432
\fBnetsnmp_create_handler()\fP 
 
433
.PP
 
434
\fBnetsnmp_register_handler()\fP 
 
435
.RE
 
436
.PP
 
437
 
 
438
.SS "\fBnetsnmp_handler_registration\fP * netsnmp_handler_registration_dup (\fBnetsnmp_handler_registration\fP * reginfo)"
 
439
.PP
 
440
duplicates the handler registration object 
 
441
.SS "void netsnmp_handler_registration_free (\fBnetsnmp_handler_registration\fP * reginfo)"
 
442
.PP
 
443
free the resources associated with a handler registration object 
 
444
.SS "int netsnmp_inject_handler (\fBnetsnmp_handler_registration\fP * reginfo, \fBnetsnmp_mib_handler\fP * handler)"
 
445
.PP
 
446
inject a new handler into the calling chain of the handlers definedy by the netsnmp_handler_registration pointer. The new handler is injected at the top of the list and hence will be the new handler to be called first. 
 
447
.SS "int netsnmp_inject_handler_before (\fBnetsnmp_handler_registration\fP * reginfo, \fBnetsnmp_mib_handler\fP * handler, const char * before_what)"
 
448
.PP
 
449
inject a new handler into the calling chain of the handlers definedy by the netsnmp_handler_registration pointer. The new handler is injected after the before_what handler, or if NULL at the top of the list and hence will be the new handler to be called first. 
 
450
.SS "int netsnmp_register_handler (\fBnetsnmp_handler_registration\fP * reginfo)"
 
451
.PP
 
452
register a handler, as defined by the netsnmp_handler_registration pointer. 
 
453
.SS "void netsnmp_register_handler_by_name (const char * name, \fBnetsnmp_mib_handler\fP * handler)"
 
454
.PP
 
455
registers a given handler by name so that it can be found easily later. 
 
456
.SS "int netsnmp_register_handler_nocallback (\fBnetsnmp_handler_registration\fP * reginfo)"
 
457
.PP
 
458
register a handler, as defined by the netsnmp_handler_registration pointer. 
 
459
.SS "void netsnmp_request_add_list_data (\fBnetsnmp_request_info\fP * request, \fBnetsnmp_data_list\fP * node)"
 
460
.PP
 
461
add data to a request that can be extracted later by submodules \fBParameters:\fP
 
462
.RS 4
 
463
\fIrequest\fP the netsnmp request info structure
 
464
.br
 
465
\fI\fBnode\fP\fP this is the data to be added to the linked list request->parent_data
 
466
.RE
 
467
.PP
 
468
\fBReturns:\fP
 
469
.RS 4
 
470
void 
 
471
.RE
 
472
.PP
 
473
 
 
474
.PP
 
475
\fBExamples: \fP
 
476
.in +1c
 
477
\fBdelayed_instance.c\fP.
 
478
.SS "void * netsnmp_request_get_list_data (\fBnetsnmp_request_info\fP * request, const char * name)"
 
479
.PP
 
480
extract data from a request that was added previously by a parent \fBmodule\fP \fBParameters:\fP
 
481
.RS 4
 
482
\fIrequest\fP the netsnmp request info function
 
483
.br
 
484
\fIname\fP used to compare against the request->parent_data->name value, if a match is found request->parent_data->data is returned
 
485
.RE
 
486
.PP
 
487
\fBReturns:\fP
 
488
.RS 4
 
489
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. 
 
490
.RE
 
491
.PP
 
492
 
 
493
.PP
 
494
\fBExamples: \fP
 
495
.in +1c
 
496
\fBdelayed_instance.c\fP.
 
497
.SS "int netsnmp_request_remove_list_data (\fBnetsnmp_request_info\fP * request, const char * name)"
 
498
.PP
 
499
remove data from a request \fBParameters:\fP
 
500
.RS 4
 
501
\fIrequest\fP the netsnmp request info structure
 
502
.br
 
503
\fIname\fP this is the name of the previously added data
 
504
.RE
 
505
.PP
 
506
\fBReturns:\fP
 
507
.RS 4
 
508
0 on successful find-and-delete, 1 otherwise. 
 
509
.RE
 
510
.PP
 
511
 
 
512
.SS "int netsnmp_unregister_handler (\fBnetsnmp_handler_registration\fP * reginfo)"
 
513
.PP
 
514
unregister a handler, as defined by the netsnmp_handler_registration pointer. 
 
515
.SH "Author"
 
516
.PP 
 
517
Generated automatically by Doxygen for net-snmp from the source code.