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). More...

Data Structures
struct	netsnmp_mib_handler_s
	the mib handler structure to be registered More...
struct	netsnmp_handler_registration_s
	Root registration info. More...
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_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 MIB handler structure.
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)
	Creates a handler registration structure with a new MIB handler.
int	netsnmp_register_handler (netsnmp_handler_registration *reginfo)
	Registers a MIB handler inside the registration structure.
int	netsnmp_unregister_handler (netsnmp_handler_registration *reginfo)
	Unregisters a MIB handler described inside the registration structure.
int	netsnmp_register_handler_nocallback (netsnmp_handler_registration *reginfo)
	Registers a MIB handler inside the registration structure.
int	netsnmp_inject_handler_before (netsnmp_handler_registration reginfo, netsnmp_mib_handler handler, const char *before_what)
	Injects handler into the calling chain of handlers.
int	netsnmp_inject_handler (netsnmp_handler_registration reginfo, netsnmp_mib_handler handler)
	Injects handler into the calling chain of handlers.
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 MIB handlers chain, starting with specific handler.
void	netsnmp_handler_free (netsnmp_mib_handler *handler)
	Deallocates resources associated with a given handler.
netsnmp_mib_handler *	netsnmp_handler_dup (netsnmp_mib_handler *handler)
	Duplicates a MIB handler and all subsequent handlers.
void	netsnmp_handler_registration_free (netsnmp_handler_registration *reginfo)
	Free resources associated with a handler registration object.
netsnmp_handler_registration *	netsnmp_handler_registration_dup (netsnmp_handler_registration *reginfo)
	Duplicates handler registration object and all subsequent handlers.
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 if a given delegated cache is still valid.
NETSNMP_INLINE void	netsnmp_free_delegated_cache (netsnmp_delegated_cache *dcache)
	Free a cache once it's no longer used.
void	netsnmp_handler_mark_requests_as_delegated (netsnmp_request_info *requests, int isdelegated)
	Sets a list of requests as delegated or not delegated.
NETSNMP_INLINE void	netsnmp_request_add_list_data (netsnmp_request_info request, netsnmp_data_list node)
	Adds data from node list to the request information structure.
NETSNMP_INLINE int	netsnmp_request_remove_list_data (netsnmp_request_info request, const char name)
	Removes all data from a request.
void *	netsnmp_request_get_list_data (netsnmp_request_info request, const char name)
	Extracts data from a request.
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.
netsnmp_mib_handler *	netsnmp_find_handler_by_name (netsnmp_handler_registration reginfo, const char name)
	Returns a MIB 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 *handler)
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 MIB Handlers registration list.
int	netsnmp_call_next_handler_one_request (netsnmp_mib_handler current, netsnmp_handler_registration reginfo, netsnmp_agent_request_info reqinfo, netsnmp_request_info requests)
netsnmp_mib_handler *	netsnmp_create_handler (const char name, Netsnmp_Node_Handler handler_access_method)
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 MIB handlers chain, starting with specific handler.

The given arguments and MIB handler are checked for sanity, then the handlers are called, one by one, until next handler is NULL.

Returns:: Returns SNMPERR_SUCCESS or SNMP_ERR_* error code.

Definition at line 485 of file agent_handler.c.

void netsnmp_clear_handler_list ( void )

Clears the entire MIB Handlers registration list.

MIB Handlers registration list is used to access any MIB Handler by its name. The function frees the list memory and sets pointer to NULL. Instead of calling this function directly, use shutdown_agent().

See also:: shutdown_agent(); netsnmp_register_handler_by_name()

Definition at line 1150 of file agent_handler.c.

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.

The cache is filled with pointers from parameters. Note that the input structures are not duplicated, but put directly into the new cache struct. Use netsnmp_handler_check_cache() later to make sure it's still valid before referencing it in the future.

See also:: netsnmp_handler_check_cache(); netsnmp_free_delegated_cache()

Examples:: delayed_instance.c.

Definition at line 853 of file agent_handler.c.

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
	)

Creates a handler registration structure with a new MIB handler.

This function first creates a MIB handler, then makes registation structure for it.

Parameters:

name	is the handler name for netsnmp_create_handler()
handler_access_method	is a function pointer used as the access method for netsnmp_create_handler()
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, as in netsnmp_handler_registration_create()

Returns:: Returns a pointer to a netsnmp_handler_registration struct. If the structures creation failed, NULL is returned.

See also:: netsnmp_create_handler(); netsnmp_handler_registration_create()

Examples:: data_set.c, delayed_instance.c, and watched.c.

Definition at line 219 of file agent_handler.c.

netsnmp_mib_handler * netsnmp_find_handler_by_name	(	netsnmp_handler_registration *	reginfo,
		const char *	name
	)

Returns a MIB handler from a chain based on the name.

Parameters:

reginfo	Handler registration struct which contains the chain.
name	Target MIB Handler name string. The name is case sensitive.

Returns:: The MIB Handler is returned, or NULL if not found.

See also:: netsnmp_request_add_list_data()

Definition at line 1051 of file agent_handler.c.

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.

Warning:: The void pointer data may change as a handler evolves. Handlers should really advertise some function for you to use instead.

Parameters:

reginfo	Handler registration struct which contains the chain.
name	Target MIB Handler name string. The name is case sensitive.

Returns:: The MIB Handler's void * pointer is returned, or NULL if the handler is not found.

See also:: netsnmp_find_handler_by_name()

Definition at line 1082 of file agent_handler.c.

void netsnmp_free_delegated_cache ( netsnmp_delegated_cache * dcache )

Free a cache once it's no longer used.

Deletes the data allocated by netsnmp_create_delegated_cache(). Structures which were not allocated by netsnmp_create_delegated_cache() are not freed (pointers are dropped).

Parameters:

dcache is the delegated cache to be freed.

See also:: netsnmp_create_delegated_cache(); netsnmp_handler_check_cache()

Examples:: delayed_instance.c.

Definition at line 908 of file agent_handler.c.

void netsnmp_free_request_data_set ( netsnmp_request_info * request )

Free the extra data stored in a request.

Deletes the data in given request only. Other chain items are unaffected.

Parameters:

request Request information structure to be modified.

See also:: netsnmp_request_add_list_data(); netsnmp_free_list_data()

Definition at line 1016 of file agent_handler.c.

void netsnmp_free_request_data_sets ( netsnmp_request_info * request )

Free the extra data stored in a bunch of requests.

Deletes all data in the chain inside request.

Parameters:

request Request information structure to be modified.

See also:: netsnmp_request_add_list_data(); netsnmp_free_request_data_set()

Definition at line 1031 of file agent_handler.c.

netsnmp_delegated_cache * netsnmp_handler_check_cache ( netsnmp_delegated_cache * dcache )

Check if a given delegated cache is still valid.

The cache is valid if it's a part of transaction (ie, the agent still considers it to be an outstanding request).

Parameters:

dcache is the delegated cache to be checked.

Returns:: Returns the cache pointer if it is still valid, NULL otherwise.

See also:: netsnmp_create_delegated_cache(); netsnmp_free_delegated_cache()

Examples:: delayed_instance.c.

Definition at line 885 of file agent_handler.c.

netsnmp_mib_handler * netsnmp_handler_dup ( netsnmp_mib_handler * handler )

Duplicates a MIB handler and all subsequent handlers.

Creates a copy of all data in given handlers chain.

Parameters:

handler is the MIB Handler to be duplicated

Returns:: Returns a pointer to the complete copy, or NULL if any problem occured.

See also:: _clone_handler()

Definition at line 712 of file agent_handler.c.

void netsnmp_handler_free ( netsnmp_mib_handler * handler )

Deallocates resources associated with a given handler.

The handler is removed from chain and then freed. After calling this function, the handler pointer is invalid and should be set to NULL.

Parameters:

handler is the MIB Handler to be freed

make sure we aren't pointing to ourselves.

Definition at line 683 of file agent_handler.c.

void netsnmp_handler_mark_requests_as_delegated	(	netsnmp_request_info *	requests,
		int	isdelegated
	)

Sets a list of requests as delegated or not delegated.

Sweeps through given chain of requests and sets 'delegated' flag accordingly to the isdelegaded parameter.

Parameters:

isdelegaded New value of the 'delegated' flag.

Definition at line 928 of file agent_handler.c.

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 MIB handler structure.

The new structure is allocated and filled using the given name, access function, registration location OID and list of modes that 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()

Definition at line 170 of file agent_handler.c.

netsnmp_handler_registration * netsnmp_handler_registration_dup ( netsnmp_handler_registration * reginfo )

Duplicates handler registration object and all subsequent handlers.

Creates a copy of the handler registration object and all its data.

Parameters:

handler is the handler registration object to be duplicated

Returns:: Returns a pointer to the complete copy, or NULL if any problem occured.

See also:: netsnmp_handler_dup()

Definition at line 785 of file agent_handler.c.

void netsnmp_handler_registration_free ( netsnmp_handler_registration * reginfo )

Free resources associated with a handler registration object.

The registration object and all MIB Handlers in the chain are freed. When the function ends, given pointer is no longer valid and should be set to NULL.

Parameters:

reginfo is the handler registration object to be freed

Definition at line 762 of file agent_handler.c.

int netsnmp_inject_handler	(	netsnmp_handler_registration *	reginfo,
		netsnmp_mib_handler *	handler
	)

Injects handler into the calling chain of handlers.

The given MIB handler is put at the top of the list, and hence will be the handler to be called first.

Returns:: Returns SNMPERR_SUCCESS or SNMP_ERR_* error code.

See also:: netsnmp_create_handler_registration(); netsnmp_inject_handler_before()

Definition at line 471 of file agent_handler.c.

int netsnmp_inject_handler_before	(	netsnmp_handler_registration *	reginfo,
		netsnmp_mib_handler *	handler,
		const char *	before_what
	)

Injects handler into the calling chain of handlers.

The given MIB handler is inserted after the handler named before_what. If before_what is NULL, the handler is put at the top of the list, and hence will be the handler to be called first.

Returns:: Returns SNMPERR_SUCCESS or SNMP_ERR_* error code.

See also:: netsnmp_create_handler_registration(); netsnmp_inject_handler()

Definition at line 409 of file agent_handler.c.

int netsnmp_register_handler ( netsnmp_handler_registration * reginfo )

Registers a MIB handler inside the registration structure.

Checks given registation handler for sanity, then performs registration in the MIB tree, as defined by the netsnmp_handler_registration pointer. On success, SNMP_CALLBACK_APPLICATION is called. The registration struct may be created by call of netsnmp_create_handler_registration().

Parameters:

reginfo Pointer to a netsnmp_handler_registration struct.

Returns:: Returns SNMPERR_SUCCESS or SNMP_ERR_* error code.

See also:: netsnmp_create_handler_registration(); netsnmp_register_mib()

Definition at line 252 of file agent_handler.c.

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.

Pointer to the handler is put into a list where it can be easily located at any time.

Parameters:

name	Name string to be associated with the handler.
handler	Pointer the MIB Handler.

See also:: netsnmp_clear_handler_list()

Definition at line 1132 of file agent_handler.c.

int netsnmp_register_handler_nocallback ( netsnmp_handler_registration * reginfo )

Registers a MIB handler inside the registration structure.

Checks given registation handler for sanity, then performs registration in the MIB tree, as defined by the netsnmp_handler_registration pointer. Never calls SNMP_CALLBACK_APPLICATION. The registration struct may be created by call of netsnmp_create_handler_registration().

Parameters:

reginfo Pointer to a netsnmp_handler_registration struct.

Returns:: Returns SNMPERR_SUCCESS or SNMP_ERR_* error code.

See also:: netsnmp_create_handler_registration(); netsnmp_register_mib()

Definition at line 352 of file agent_handler.c.

void netsnmp_request_add_list_data	(	netsnmp_request_info *	request,
		netsnmp_data_list *	node
	)

Adds data from node list to the request information structure.

Data in the request can be later extracted and used by submodules.

Parameters:

request	Destination request information structure.
node	The data to be added to the linked list request->parent_data.

See also:: netsnmp_request_remove_list_data(); netsnmp_request_get_list_data()

Examples:: delayed_instance.c.

Definition at line 950 of file agent_handler.c.

void * netsnmp_request_get_list_data	(	netsnmp_request_info *	request,
		const char *	name
	)

Extracts data from a request.

Retrieves data that was previously added to the request, usually by a parent module.

Parameters:

request	Source request information structure.
name	Used to compare against the request->parent_data->name value; if a match is found, request->parent_data->data is returned.