Net-SNMP Agent handler and exteNet-SNMPsAgent3handler and extensibility API(3)NAME
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).
Data Structures
struct netsnmp_mib_handler_s
the mib handler structure to be registered
struct netsnmp_handler_registration_s
Root registration info.
struct netsnmp_handler_args_s
struct netsnmp_delegated_cache_s
Modules
utility_handlers
Simplify request processing A group of handlers intended to simplify
certain aspects of processing a request for a MIB object.
leaf_handlers
Process 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).
baby_steps
Calls your handler in baby_steps for set processing.
old_api
Calls mib module code written in the old style of code.
stash_cache
Automatically caches data for certain handlers.
table
Helps you implement a table.
Defines
#define MIB_HANDLER_AUTO_NEXT 0x00000001
#define MIB_HANDLER_AUTO_NEXT_OVERRIDE_ONCE 0x00000002
#define MIB_HANDLER_INSTANCE 0x00000004
#define MIB_HANDLER_CUSTOM4 0x10000000
#define MIB_HANDLER_CUSTOM3 0x20000000
#define MIB_HANDLER_CUSTOM2 0x40000000
#define MIB_HANDLER_CUSTOM1 0x80000000
#define HANDLER_CAN_GETANDGETNEXT 0x01
#define HANDLER_CAN_SET 0x02
#define HANDLER_CAN_GETBULK 0x04
#define HANDLER_CAN_NOT_CREATE 0x08
#define HANDLER_CAN_BABY_STEP 0x10
#define HANDLER_CAN_STASH 0x20
#define HANDLER_CAN_RONLY (HANDLER_CAN_GETANDGETNEXT)
#define HANDLER_CAN_RWRITE (HANDLER_CAN_GETANDGETNEXT |
HANDLER_CAN_SET)
#define HANDLER_CAN_SET_ONLY (HANDLER_CAN_SET |
HANDLER_CAN_NOT_CREATE)
#define HANDLER_CAN_DEFAULT (HANDLER_CAN_RONLY |
HANDLER_CAN_NOT_CREATE)
#define REQUEST_IS_DELEGATED 1
#define REQUEST_IS_NOT_DELEGATED 0
Typedefs
typedef struct netsnmp_mib_handler_s netsnmp_mib_handler
Typedefs the netsnmp_mib_handler_s struct into netsnmp_mib_handler.
typedef struct netsnmp_handler_registration_s
netsnmp_handler_registration
Typedefs the netsnmp_handler_registration_s struct into
netsnmp_handler_registration.
typedef int( Netsnmp_Node_Handler )(netsnmp_mib_handler *handler,
netsnmp_handler_registration *reginfo, netsnmp_agent_request_info
*reqinfo, netsnmp_request_info *requests)
typedef struct netsnmp_handler_args_s netsnmp_handler_args
typedef struct netsnmp_delegated_cache_s netsnmp_delegated_cache
Functions
netsnmp_mib_handler * netsnmp_create_handler (const char *name,
Netsnmp_Node_Handler *handler_access_method)
creates a netsnmp_mib_handler structure given a name and a access
method.
netsnmp_handler_registration * netsnmp_handler_registration_create
(const char *name, netsnmp_mib_handler *handler, const oid
*reg_oid, size_t reg_oid_len, int modes)
creates a handler registration structure given a name, a
access_method function, a registration location oid and the modes
the handler supports.
netsnmp_handler_registration * netsnmp_create_handler_registration
(const char *name, Netsnmp_Node_Handler *handler_access_method,
const oid *reg_oid, size_t reg_oid_len, int modes)
int netsnmp_register_handler (netsnmp_handler_registration *reginfo)
register a handler, as defined by the netsnmp_handler_registration
pointer.
int netsnmp_unregister_handler (netsnmp_handler_registration *reginfo)
unregister a handler, as defined by the
netsnmp_handler_registration pointer.
int netsnmp_register_handler_nocallback (netsnmp_handler_registration
*reginfo)
register a handler, as defined by the netsnmp_handler_registration
pointer.
int netsnmp_inject_handler_before (netsnmp_handler_registration
*reginfo, netsnmp_mib_handler *handler, const char *before_what)
inject a new handler into the calling chain of the handlers
definedy by the netsnmp_handler_registration pointer.
int netsnmp_inject_handler (netsnmp_handler_registration *reginfo,
netsnmp_mib_handler *handler)
inject a new handler into the calling chain of the handlers
definedy by the netsnmp_handler_registration pointer.
NETSNMP_INLINE int netsnmp_call_handler (netsnmp_mib_handler
*next_handler, netsnmp_handler_registration *reginfo,
netsnmp_agent_request_info *reqinfo, netsnmp_request_info
*requests)
calls a handler with with appropriate NULL checking of arguments,
etc.
int netsnmp_call_handlers (netsnmp_handler_registration *reginfo,
netsnmp_agent_request_info *reqinfo, netsnmp_request_info
*requests)
NETSNMP_INLINE int netsnmp_call_next_handler (netsnmp_mib_handler
*current, netsnmp_handler_registration *reginfo,
netsnmp_agent_request_info *reqinfo, netsnmp_request_info
*requests)
calls the next handler in the chain after the current one with with
appropriate NULL checking, etc.
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)
calls the next handler in the chain after the current one with with
appropriate NULL checking, etc.
void netsnmp_handler_free (netsnmp_mib_handler *handler)
free's the resourceses associated with a given handler
netsnmp_mib_handler * netsnmp_handler_dup (netsnmp_mib_handler
*handler)
dulpicates a handler and all subsequent handlers see also
_clone_handler
void netsnmp_handler_registration_free (netsnmp_handler_registration
*reginfo)
free the resources associated with a handler registration object
netsnmp_handler_registration * netsnmp_handler_registration_dup
(netsnmp_handler_registration *reginfo)
duplicates the handler registration object
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)
creates a cache of information which can be saved for future
reference.
NETSNMP_INLINE netsnmp_delegated_cache * netsnmp_handler_check_cache
(netsnmp_delegated_cache *dcache)
check's a given cache and returns it if it is still valid (ie, the
agent still considers it to be an outstanding request.
NETSNMP_INLINE void netsnmp_free_delegated_cache
(netsnmp_delegated_cache *dcache)
frees a cache once you're finished using it
void netsnmp_handler_mark_requests_as_delegated (netsnmp_request_info
*requests, int isdelegated)
marks a list of requests as delegated (or not if isdelegaded = 0)
NETSNMP_INLINE void netsnmp_request_add_list_data (netsnmp_request_info
*request, netsnmp_data_list *node)
add data to a request that can be extracted later by submodules
NETSNMP_INLINE int netsnmp_request_remove_list_data
(netsnmp_request_info *request, const char *name)
remove data from a request
void * netsnmp_request_get_list_data (netsnmp_request_info *request,
const char *name)
extract data from a request that was added previously by a parent
module
NETSNMP_INLINE void netsnmp_free_request_data_set (netsnmp_request_info
*request)
Free the extra data stored in a request.
NETSNMP_INLINE void netsnmp_free_request_data_sets
(netsnmp_request_info *request)
Free the extra data stored in a bunch of requests (all data in the
chain).
netsnmp_mib_handler * netsnmp_find_handler_by_name
(netsnmp_handler_registration *reginfo, const char *name)
Returns a handler from a chain based on the name.
void * netsnmp_find_handler_data_by_name (netsnmp_handler_registration
*reginfo, const char *name)
Returns a handler's void * pointer from a chain based on the name.
void handler_free_callback (void *free)
void netsnmp_register_handler_by_name (const char *name,
netsnmp_mib_handler *handler)
registers a given handler by name so that it can be found easily
later.
void netsnmp_clear_handler_list (void)
clears the entire handler-registration list
void netsnmp_inject_handler_into_subtree (netsnmp_subtree *tp, const
char *name, netsnmp_mib_handler *handler, const char *before_what)
void parse_injectHandler_conf (const char *token, char *cptr)
void netsnmp_init_handler_conf (void)
void * netsnmp_handler_get_parent_data (netsnmp_request_info *, const
char *)
Detailed Description
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).
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.
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++).
Functionally, the notion of what a handler does is the same as the
older api: A handler is created and then registered 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:
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 instance, table, table_iterator,
table_data, or table_dataset helpers to make their life easier. These
'helpers' interpert important aspects of the request and pass them on
to you.
For instance, the table helper is designed to hand you a list of
extracted index values from an incoming request. THe table_iterator
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 table_iterator
helper, as well as the instance 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.
Typedef Documentation
struct netsnmp_handler_registration_s netsnmp_handler_registration
Typedefs the netsnmp_handler_registration_s struct into
netsnmp_handler_registration.
struct netsnmp_mib_handler_s netsnmp_mib_handler
Typedefs the netsnmp_mib_handler_s struct into netsnmp_mib_handler.
Function Documentation
int netsnmp_call_handler (netsnmp_mib_handler * next_handler,
netsnmp_handler_registration * reginfo, netsnmp_agent_request_info *
reqinfo, netsnmp_request_info * requests)
calls a handler with with appropriate NULL checking of arguments, etc.
int netsnmp_call_next_handler (netsnmp_mib_handler * current,
netsnmp_handler_registration * reginfo, netsnmp_agent_request_info *
reqinfo, netsnmp_request_info * requests)
calls the next handler in the chain after the current one with with
appropriate NULL checking, etc.
int netsnmp_call_next_handler_one_request (netsnmp_mib_handler * current,
netsnmp_handler_registration * reginfo, netsnmp_agent_request_info *
reqinfo, netsnmp_request_info * requests)
calls the next handler in the chain after the current one with with
appropriate NULL checking, etc.
void netsnmp_clear_handler_list (void)
clears the entire handler-registration list
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)
creates a cache of information which can be saved for future reference.
Use netsnmp_handler_check_cache() later to make sure it's still valid
before referencing it in the future.
Examples:
delayed_instance.c.
netsnmp_mib_handler * netsnmp_create_handler (const char * name,
Netsnmp_Node_Handler * handler_access_method)
creates a netsnmp_mib_handler structure given a name and a access
method. The returned handler should then be registered.
Parameters:
name is the handler name and is copied then assigned to
netsnmp_mib_handler->handler_name
handler_access_method is a function pointer used as the access
method for this handler registration instance for whatever required
needs.
Returns:
a pointer to a populated netsnmp_mib_handler struct to be
registered
See also:
netsnmp_create_handler_registration()netsnmp_register_handler()
netsnmp_mib_handler * netsnmp_find_handler_by_name
(netsnmp_handler_registration * reginfo, const char * name)
Returns a handler from a chain based on the name.
void * netsnmp_find_handler_data_by_name (netsnmp_handler_registration *
reginfo, const char * name)
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.
void netsnmp_free_delegated_cache (netsnmp_delegated_cache * dcache)
frees a cache once you're finished using it
Examples:
delayed_instance.c.
void netsnmp_free_request_data_set (netsnmp_request_info * request)
Free the extra data stored in a request.
void netsnmp_free_request_data_sets (netsnmp_request_info * request)
Free the extra data stored in a bunch of requests (all data in the
chain).
netsnmp_delegated_cache * netsnmp_handler_check_cache
(netsnmp_delegated_cache * dcache)
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.
Examples:
delayed_instance.c.
netsnmp_mib_handler * netsnmp_handler_dup (netsnmp_mib_handler * handler)
dulpicates a handler and all subsequent handlers see also
_clone_handler
void netsnmp_handler_free (netsnmp_mib_handler * handler)
free's the resourceses associated with a given handler
make sure we aren't pointing to ourselves.
XXX : segv here at shutdown if SHUTDOWN_AGENT_CLEANLY defined. About 30
functions down the stack, starting in clear_context() ->
clear_subtree()
void netsnmp_handler_mark_requests_as_delegated (netsnmp_request_info *
requests, int isdelegated)
marks a list of requests as delegated (or not if isdelegaded = 0)
netsnmp_handler_registration * netsnmp_handler_registration_create (const
char * name, netsnmp_mib_handler * handler, const oid * reg_oid, size_t
reg_oid_len, int modes)
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.
Note:
This ends up calling netsnmp_create_handler(name,
handler_access_method)
Parameters:
name is the handler name and is copied then assigned to
netsnmp_handler_registration->handlerName.
handler is a function pointer used as the access method for this
handler registration instance for whatever required needs.
reg_oid is the registration location oid.
reg_oid_len is the length of reg_oid, can use the macro, OID_LENGTH
modes 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.
· HANDLER_CAN_GETANDGETNEXT
· HANDLER_CAN_SET
· HANDLER_CAN_GETBULK
· HANDLER_CAN_RONLY (HANDLER_CAN_GETANDGETNEXT)
· HANDLER_CAN_RWRITE (HANDLER_CAN_GETANDGETNEXT | HANDLER_CAN_SET)
· HANDLER_CAN_DEFAULT HANDLER_CAN_RONLY
Returns:
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.
See also:
netsnmp_create_handler()netsnmp_register_handler()
netsnmp_handler_registration * netsnmp_handler_registration_dup
(netsnmp_handler_registration * reginfo)
duplicates the handler registration object
void netsnmp_handler_registration_free (netsnmp_handler_registration *
reginfo)
free the resources associated with a handler registration object
int netsnmp_inject_handler (netsnmp_handler_registration * reginfo,
netsnmp_mib_handler * handler)
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.
int netsnmp_inject_handler_before (netsnmp_handler_registration * reginfo,
netsnmp_mib_handler * handler, const char * before_what)
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.
int netsnmp_register_handler (netsnmp_handler_registration * reginfo)
register a handler, as defined by the netsnmp_handler_registration
pointer.
void netsnmp_register_handler_by_name (const char * name,
netsnmp_mib_handler * handler)
registers a given handler by name so that it can be found easily later.
int netsnmp_register_handler_nocallback (netsnmp_handler_registration *
reginfo)
register a handler, as defined by the netsnmp_handler_registration
pointer.
void netsnmp_request_add_list_data (netsnmp_request_info * request,
netsnmp_data_list * node)
add data to a request that can be extracted later by submodules
Parameters:
request the netsnmp request info structure
node this is the data to be added to the linked list
request->parent_data
Returns:
void
Examples:
delayed_instance.c.
void * netsnmp_request_get_list_data (netsnmp_request_info * request, const
char * name)
extract data from a request that was added previously by a parent
module Parameters:
request the netsnmp request info function
name used to compare against the request->parent_data->name value,
if a match is found request->parent_data->data is returned
Returns:
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.
Examples:
delayed_instance.c.
int netsnmp_request_remove_list_data (netsnmp_request_info * request, const
char * name)
remove data from a request Parameters:
request the netsnmp request info structure
name this is the name of the previously added data
Returns:
0 on successful find-and-delete, 1 otherwise.
int netsnmp_unregister_handler (netsnmp_handler_registration * reginfo)
unregister a handler, as defined by the netsnmp_handler_registration
pointer.
Author
Generated automatically by Doxygen for net-snmp from the source code.
Version 5.5 Net-SNMPpAgent handler and extensibility API(3)
