userapps/opensource/net-snmp/man/netsnmp_handler.3

   1 .TH "Net-SNMP Agent handler and extensibility API" 3 "17 Mar 2003" "net-snmp" \" -*- nroff -*-
   2 .ad l
   3 .nh
   4 .SH NAME
   5 Net-SNMP Agent handler and extensibility API \- The basic theory goes something like this: In the past, with the original mib module 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).
   6 More...
   7 .SS "Modules"
   8
   9 .in +1c
  10 .ti -1c
  11 .RI "\fBbulk_to_next: convert GETBULK requests into GETNEXT requests for the handler.\fP"
  12 .br
  13 .RI "\fIThe only purpose of this handler is to convert a GETBULK request to a GETNEXT request.\fP"
  14 .PP
  15 .in +1c
  16
  17 .ti -1c
  18 .RI "\fBdebug: print out debugging information about the handler chain being called.\fP"
  19 .br
  20 .RI "\fIThis is a useful module for run-time debugging of requests as the pass this handler in a calling chain.\fP"
  21 .PP
  22 .in +1c
  23
  24 .ti -1c
  25 .RI "\fBinstance: process scalars and other instances easily.\fP"
  26 .br
  27 .ti -1c
  28 .RI "\fBmode_end_call: at the end of a series of requests, call another handler hook.\fP"
  29 .br
  30 .RI "\fIHandlers that want to loop through a series of requests and then receive a callback at the end of a particular MODE can use this helper to make this possible.\fP"
  31 .PP
  32 .in +1c
  33
  34 .ti -1c
  35 .RI "\fBmultiplexer: splits mode requests into calls to different handlers.\fP"
  36 .br
  37 .RI "\fIThe multiplexer helper lets you split the calling chain depending on the calling mode (get vs getnext vs set).\fP"
  38 .PP
  39 .in +1c
  40
  41 .ti -1c
  42 .RI "\fBold_api: Calls mib module code written in the old style of code.\fP"
  43 .br
  44 .RI "\fIThis is a backwards compatilibity module that allows code written in the old API to be run under the new handler based architecture.\fP"
  45 .PP
  46 .in +1c
  47
  48 .ti -1c
  49 .RI "\fBread_only: make your handler read_only automatically\fP"
  50 .br
  51 .RI "\fIThe only purpose of this handler is to return an appropriate error for any requests passed to it in a SET mode.\fP"
  52 .PP
  53 .in +1c
  54
  55 .ti -1c
  56 .RI "\fBscalar: process scalars easily.\fP"
  57 .br
  58 .ti -1c
  59 .RI "\fBserialize: Calls sub handlers one request at a time.\fP"
  60 .br
  61 .RI "\fIThis functionally passes in one request at a time into lower handlers rather than a whole bunch of requests at once.\fP"
  62 .PP
  63 .in +1c
  64
  65 .ti -1c
  66 .RI "\fBtable: Helps you implement a table.\fP"
  67 .br
  68 .RI "\fIThis handler helps you implement a table by doing some of the processing for you.\fP"
  69 .PP
  70 .in +1c
  71
  72 .ti -1c
  73 .RI "\fBwatcher: watch a specified variable and process\fP"
  74 .br
  75 .RI "\fIit as an instance or scalar object.\fP"
  76 .PP
  77
  78 .in -1c
  79 .SS "Functions"
  80
  81 .in +1c
  82 .ti -1c
  83 .RI "netsnmp_mib_handler * \fBnetsnmp_create_handler\fP (const char *name, Netsnmp_Node_Handler *handler_access_method)"
  84 .br
  85 .RI "\fIcreates a netsnmp_mib_handler structure given a name and a access method.\fP"
  86 .ti -1c
  87 .RI "netsnmp_handler_registration * \fBnetsnmp_create_handler_registration\fP (const char *name, Netsnmp_Node_Handler *handler_access_method, oid *reg_oid, size_t reg_oid_len, int modes)"
  88 .br
  89 .RI "\fIcreates a handler registration structure given a name, a access_method function, a registration location oid and the modes the handler supports.\fP"
  90 .ti -1c
  91 .RI "int \fBnetsnmp_register_handler\fP (netsnmp_handler_registration *reginfo)"
  92 .br
  93 .RI "\fIregister a handler, as defined by the netsnmp_handler_registration pointer.\fP"
  94 .ti -1c
  95 .RI "int \fBnetsnmp_register_handler_nocallback\fP (netsnmp_handler_registration *reginfo)"
  96 .br
  97 .RI "\fIregister a handler, as defined by the netsnmp_handler_registration pointer.\fP"
  98 .ti -1c
  99 .RI "int \fBnetsnmp_inject_handler\fP (netsnmp_handler_registration *reginfo, netsnmp_mib_handler *handler)"
 100 .br
 101 .RI "\fIinject a new handler into the calling chain of the handlers definedy by the netsnmp_handler_registration pointer.\fP"
 102 .ti -1c
 103 .RI "int \fBnetsnmp_call_handlers\fP (netsnmp_handler_registration *reginfo, netsnmp_agent_request_info *reqinfo, netsnmp_request_info *requests)"
 104 .br
 105 .ti -1c
 106 .RI "NETSNMP_INLINE int \fBnetsnmp_call_handler\fP (netsnmp_mib_handler *next_handler, netsnmp_handler_registration *reginfo, netsnmp_agent_request_info *reqinfo, netsnmp_request_info *requests)"
 107 .br
 108 .RI "\fIcalls a handler with with appropriate NULL checking of arguments, etc.\fP"
 109 .ti -1c
 110 .RI "NETSNMP_INLINE int \fBnetsnmp_call_next_handler\fP (netsnmp_mib_handler *current, netsnmp_handler_registration *reginfo, netsnmp_agent_request_info *reqinfo, netsnmp_request_info *requests)"
 111 .br
 112 .RI "\fIcalls the next handler in the chain after the current one with with appropriate NULL checking, etc.\fP"
 113 .ti -1c
 114 .RI "NETSNMP_INLINE int \fBnetsnmp_call_next_handler_one_request\fP (netsnmp_mib_handler *current, netsnmp_handler_registration *reginfo, netsnmp_agent_request_info *reqinfo, netsnmp_request_info *requests)"
 115 .br
 116 .RI "\fIcalls the next handler in the chain after the current one with with appropriate NULL checking, etc.\fP"
 117 .ti -1c
 118 .RI "void \fBnetsnmp_handler_free\fP (netsnmp_mib_handler *handler)"
 119 .br
 120 .RI "\fIfree's the resourceses associated with a given handler.\fP"
 121 .ti -1c
 122 .RI "netsnmp_mib_handler * \fBnetsnmp_handler_dup\fP (netsnmp_mib_handler *handler)"
 123 .br
 124 .RI "\fIdulpicates a handler.\fP"
 125 .ti -1c
 126 .RI "void \fBnetsnmp_handler_registration_free\fP (netsnmp_handler_registration *reginfo)"
 127 .br
 128 .RI "\fIfree the resources associated with a handler registration object.\fP"
 129 .ti -1c
 130 .RI "netsnmp_handler_registration * \fBnetsnmp_handler_registration_dup\fP (netsnmp_handler_registration *reginfo)"
 131 .br
 132 .RI "\fIduplicates the handler registration object.\fP"
 133 .ti -1c
 134 .RI "NETSNMP_INLINE netsnmp_delegated_cache * \fBnetsnmp_create_delegated_cache\fP (netsnmp_mib_handler *handler, netsnmp_handler_registration *reginfo, netsnmp_agent_request_info *reqinfo, netsnmp_request_info *requests, void *localinfo)"
 135 .br
 136 .RI "\fIcreates a cache of information which can be saved for future reference.\fP"
 137 .ti -1c
 138 .RI "NETSNMP_INLINE netsnmp_delegated_cache * \fBnetsnmp_handler_check_cache\fP (netsnmp_delegated_cache *dcache)"
 139 .br
 140 .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"
 141 .ti -1c
 142 .RI "NETSNMP_INLINE void \fBnetsnmp_free_delegated_cache\fP (netsnmp_delegated_cache *dcache)"
 143 .br
 144 .RI "\fIfrees a cache once you're finished using it.\fP"
 145 .ti -1c
 146 .RI "void \fBnetsnmp_handler_mark_requests_as_delegated\fP (netsnmp_request_info *requests, int isdelegated)"
 147 .br
 148 .RI "\fImarks a list of requests as delegated (or not if isdelegaded = 0).\fP"
 149 .ti -1c
 150 .RI "NETSNMP_INLINE void \fBnetsnmp_request_add_list_data\fP (netsnmp_request_info *request, netsnmp_data_list *node)"
 151 .br
 152 .RI "\fIadd data to a request that can be extracted later by submodules.\fP"
 153 .ti -1c
 154 .RI "NETSNMP_INLINE void * \fBnetsnmp_request_get_list_data\fP (netsnmp_request_info *request, const char *name)"
 155 .br
 156 .RI "\fIextract data from a request that was added previously by a parent module.\fP"
 157 .ti -1c
 158 .RI "NETSNMP_INLINE void \fBnetsnmp_free_request_data_set\fP (netsnmp_request_info *request)"
 159 .br
 160 .RI "\fIFree the extra data stored in a request.\fP"
 161 .ti -1c
 162 .RI "NETSNMP_INLINE void \fBnetsnmp_free_request_data_sets\fP (netsnmp_request_info *request)"
 163 .br
 164 .RI "\fIFree the extra data stored in a bunch of requests (all data in the chain).\fP"
 165 .ti -1c
 166 .RI "netsnmp_mib_handler * \fBnetsnmp_find_handler_by_name\fP (netsnmp_handler_registration *reginfo, const char *name)"
 167 .br
 168 .RI "\fIReturns a handler from a chain based on the name.\fP"
 169 .ti -1c
 170 .RI "void * \fBnetsnmp_find_handler_data_by_name\fP (netsnmp_handler_registration *reginfo, const char *name)"
 171 .br
 172 .RI "\fIReturns a handler's void * pointer from a chain based on the name.\fP"
 173 .ti -1c
 174 .RI "netsnmp_mib_handler * \fBclone_handler\fP (netsnmp_mib_handler *it)"
 175 .br
 176 .RI "\fIclones a mib handler (it's name and access methods onlys; not myvoid).\fP"
 177 .ti -1c
 178 .RI "void \fBnetsnmp_register_handler_by_name\fP (const char *name, netsnmp_mib_handler *handler)"
 179 .br
 180 .RI "\fIregisters a given handler by name so that it can be found easily later.\fP"
 181 .ti -1c
 182 .RI "void \fBnetsnmp_inject_handler_into_subtree\fP (netsnmp_subtree *tp, const char *name, netsnmp_mib_handler *handler)"
 183 .br
 184 .ti -1c
 185 .RI "void \fBparse_injectHandler_conf\fP (const char *token, char *cptr)"
 186 .br
 187 .ti -1c
 188 .RI "void \fBnetsnmp_init_handler_conf\fP (void)"
 189 .br
 190 .in -1c
 191 .SH "DETAILED DESCRIPTION"
 192 .PP
 193 The basic theory goes something like this: In the past, with the original mib module 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).
 194 .PP
 195 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.
 196 .PP
 197 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++).
 198 .PP
 199 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 tree 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:
 200 .PP
 201 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 module, 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.
 202 .PP
 203 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
 204 .SH "FUNCTION DOCUMENTATION"
 205 .PP
 206 .SS "netsnmp_mib_handler* clone_handler (netsnmp_mib_handler * it)"
 207 .PP
 208 clones a mib handler (it's name and access methods onlys; not myvoid).
 209 .PP
 210 Definition at line 643 of file agent_handler.c.
 211 .SS "NETSNMP_INLINE int netsnmp_call_handler (netsnmp_mib_handler * next_handler, netsnmp_handler_registration * reginfo, netsnmp_agent_request_info * reqinfo, netsnmp_request_info * requests)"
 212 .PP
 213 calls a handler with with appropriate NULL checking of arguments, etc.
 214 .PP
 215 Definition at line 305 of file agent_handler.c.
 216 .SS "NETSNMP_INLINE int netsnmp_call_next_handler (netsnmp_mib_handler * current, netsnmp_handler_registration * reginfo, netsnmp_agent_request_info * reqinfo, netsnmp_request_info * requests)"
 217 .PP
 218 calls the next handler in the chain after the current one with with appropriate NULL checking, etc.
 219 .PP
 220 Definition at line 340 of file agent_handler.c.
 221 .SS "NETSNMP_INLINE int netsnmp_call_next_handler_one_request (netsnmp_mib_handler * current, netsnmp_handler_registration * reginfo, netsnmp_agent_request_info * reqinfo, netsnmp_request_info * requests)"
 222 .PP
 223 calls the next handler in the chain after the current one with with appropriate NULL checking, etc.
 224 .PP
 225 Definition at line 358 of file agent_handler.c.
 226 .SS "NETSNMP_INLINE netsnmp_delegated_cache* netsnmp_create_delegated_cache (netsnmp_mib_handler * handler, netsnmp_handler_registration * reginfo, netsnmp_agent_request_info * reqinfo, netsnmp_request_info * requests, void * localinfo)"
 227 .PP
 228 creates a cache of information which can be saved for future reference.
 229 .PP
 230 Use \fBnetsnmp_handler_check_cache\fP() later to make sure it's still valid before referencing it in the future.
 231 .PP
 232 \fBExamples: \fP
 233 .in +1c
 234 \fBdelayed_instance.c\fP.
 235 .PP
 236 Definition at line 510 of file agent_handler.c.
 237 .SS "netsnmp_mib_handler* netsnmp_create_handler (const char * name, Netsnmp_Node_Handler * handler_access_method)"
 238 .PP
 239 creates a netsnmp_mib_handler structure given a name and a access method.
 240 .PP
 241 The returned handler should then be \fBregistered.\fP
 242 .PP
 243 \fBSee also: \fP
 244 .in +1c
 245 \fBnetsnmp_create_handler_registration\fP() , \fBnetsnmp_register_handler\fP()
 246 .PP
 247 Definition at line 80 of file agent_handler.c.
 248 .SS "netsnmp_handler_registration* netsnmp_create_handler_registration (const char * name, Netsnmp_Node_Handler * handler_access_method, oid * reg_oid, size_t reg_oid_len, int modes)"
 249 .PP
 250 creates a handler registration structure given a name, a access_method function, a registration location oid and the modes the handler supports.
 251 .PP
 252 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.
 253 .PP
 254 \fBNote: \fP
 255 .in +1c
 256 This ends up calling netsnmp_create_handler(name, handler_access_method)
 257 .PP
 258 \fBSee also: \fP
 259 .in +1c
 260 \fBnetsnmp_create_handler\fP() , \fBnetsnmp_register_handler\fP()
 261 .PP
 262 \fBExamples: \fP
 263 .in +1c
 264 \fBdelayed_instance.c\fP.
 265 .PP
 266 Definition at line 99 of file agent_handler.c.
 267 .SS "netsnmp_mib_handler* netsnmp_find_handler_by_name (netsnmp_handler_registration * reginfo, const char * name)"
 268 .PP
 269 Returns a handler from a chain based on the name.
 270 .PP
 271 Definition at line 614 of file agent_handler.c.
 272 .SS "void* netsnmp_find_handler_data_by_name (netsnmp_handler_registration * reginfo, const char * name)"
 273 .PP
 274 Returns a handler's void * pointer from a chain based on the name.
 275 .PP
 276 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.
 277 .PP
 278 Definition at line 631 of file agent_handler.c.
 279 .SS "NETSNMP_INLINE void netsnmp_free_delegated_cache (netsnmp_delegated_cache * dcache)"
 280 .PP
 281 frees a cache once you're finished using it.
 282 .PP
 283 \fBExamples: \fP
 284 .in +1c
 285 \fBdelayed_instance.c\fP.
 286 .PP
 287 Definition at line 548 of file agent_handler.c.
 288 .SS "NETSNMP_INLINE void netsnmp_free_request_data_set (netsnmp_request_info * request)"
 289 .PP
 290 Free the extra data stored in a request.
 291 .PP
 292 Definition at line 596 of file agent_handler.c.
 293 .SS "NETSNMP_INLINE void netsnmp_free_request_data_sets (netsnmp_request_info * request)"
 294 .PP
 295 Free the extra data stored in a bunch of requests (all data in the chain).
 296 .PP
 297 Definition at line 604 of file agent_handler.c.
 298 .SS "NETSNMP_INLINE netsnmp_delegated_cache* netsnmp_handler_check_cache (netsnmp_delegated_cache * dcache)"
 299 .PP
 300 check's a given cache and returns it if it is still valid (ie, the agent still considers it to be an outstanding request.
 301 .PP
 302 Returns NULL if it's no longer valid.
 303 .PP
 304 \fBExamples: \fP
 305 .in +1c
 306 \fBdelayed_instance.c\fP.
 307 .PP
 308 Definition at line 534 of file agent_handler.c.
 309 .SS "netsnmp_mib_handler* netsnmp_handler_dup (netsnmp_mib_handler * handler)"
 310 .PP
 311 dulpicates a handler.
 312 .PP
 313 Definition at line 394 of file agent_handler.c.
 314 .SS "void netsnmp_handler_free (netsnmp_mib_handler * handler)"
 315 .PP
 316 free's the resourceses associated with a given handler.
 317 .PP
 318 Definition at line 380 of file agent_handler.c.
 319 .SS "void netsnmp_handler_mark_requests_as_delegated (netsnmp_request_info * requests, int isdelegated)"
 320 .PP
 321 marks a list of requests as delegated (or not if isdelegaded = 0).
 322 .PP
 323 Definition at line 562 of file agent_handler.c.
 324 .SS "netsnmp_handler_registration* netsnmp_handler_registration_dup (netsnmp_handler_registration * reginfo)"
 325 .PP
 326 duplicates the handler registration object.
 327 .PP
 328 Definition at line 448 of file agent_handler.c.
 329 .SS "void netsnmp_handler_registration_free (netsnmp_handler_registration * reginfo)"
 330 .PP
 331 free the resources associated with a handler registration object.
 332 .PP
 333 Definition at line 435 of file agent_handler.c.
 334 .SS "int netsnmp_inject_handler (netsnmp_handler_registration * reginfo, netsnmp_mib_handler * handler)"
 335 .PP
 336 inject a new handler into the calling chain of the handlers definedy by the netsnmp_handler_registration pointer.
 337 .PP
 338 The new handler is injected at the top of the list and hence will be the new handler to be called first.
 339 .PP
 340 Definition at line 221 of file agent_handler.c.
 341 .SS "int netsnmp_register_handler (netsnmp_handler_registration * reginfo)"
 342 .PP
 343 register a handler, as defined by the netsnmp_handler_registration pointer.
 344 .PP
 345 Definition at line 125 of file agent_handler.c.
 346 .SS "void netsnmp_register_handler_by_name (const char * name, netsnmp_mib_handler * handler)"
 347 .PP
 348 registers a given handler by name so that it can be found easily later.
 349 .PP
 350 Definition at line 653 of file agent_handler.c.
 351 .SS "int netsnmp_register_handler_nocallback (netsnmp_handler_registration * reginfo)"
 352 .PP
 353 register a handler, as defined by the netsnmp_handler_registration pointer.
 354 .PP
 355 Definition at line 175 of file agent_handler.c.
 356 .SS "NETSNMP_INLINE void netsnmp_request_add_list_data (netsnmp_request_info * request, netsnmp_data_list * node)"
 357 .PP
 358 add data to a request that can be extracted later by submodules.
 359 .PP
 360 \fBExamples: \fP
 361 .in +1c
 362 \fBdelayed_instance.c\fP.
 363 .PP
 364 Definition at line 573 of file agent_handler.c.
 365 .SS "NETSNMP_INLINE void* netsnmp_request_get_list_data (netsnmp_request_info * request, const char * name)"
 366 .PP
 367 extract data from a request that was added previously by a parent module.
 368 .PP
 369 \fBExamples: \fP
 370 .in +1c
 371 \fBdelayed_instance.c\fP.
 372 .PP
 373 Definition at line 586 of file agent_handler.c.