Net-SNMP Agent handler 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). More...

  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.
This is a backwards compatilibity module that allows code written in the old API to be run under the new handler based architecture.

stash_cache: automatically caches data for certain handlers.
This handler caches data in an optimized way which may aleviate the need for the lower level handlers to perform as much optimization.

table: Helps you implement a table.
This handler helps you implement a table by doing some of the processing for you.

  Data Structures
struct netsnmp_delegated_cache_s
struct netsnmp_handler_registration_s
Root registration info.
struct netsnmp_handler_registration_s
Root registration info.
struct netsnmp_mib_handler_s
the mib handler structure to be registered
struct netsnmp_mib_handler_s
the mib handler structure to be registered

  Typedefs
typedef netsnmp_mib_handler_s netsnmp_mib_handler
Typedefs the netsnmp_mib_handler_s struct into netsnmp_mib_handler.
typedef netsnmp_handler_registration_s netsnmp_handler_registration
Typedefs the netsnmp_handler_registration_s struct into netsnmp_handler_registration.

  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_create_handler_registration (const char *name, Netsnmp_Node_Handler *handler_access_method, 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.
int netsnmp_register_handler (netsnmp_handler_registration *reginfo)
register 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.
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
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 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.
netsnmp_mib_handler * clone_handler (netsnmp_mib_handler *it)
clones a mib handler (it's name and access methods onlys; not myvoid)
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

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

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

  netsnmp_mib_handler* clone_handler (netsnmp_mib_handler * it)

clones a mib handler (it's name and access methods onlys; not myvoid)

Definition at line 764 of file agent_handler.c.

References netsnmp_mib_handler_s::access_method, netsnmp_mib_handler_s::handler_name, and netsnmp_create_handler().

  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.

Definition at line 339 of file agent_handler.c.

References netsnmp_mib_handler_s::access_method, netsnmp_mib_handler_s::handler_name, netsnmp_agent_request_info_s::mode, and snmp_log().

Referenced by netsnmp_call_next_handler(), netsnmp_call_next_handler_one_request(), and netsnmp_multiplexer_helper_handler().

  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.

Definition at line 438 of file agent_handler.c.

References netsnmp_call_handler(), netsnmp_mib_handler_s::next, and snmp_log().

Referenced by netsnmp_cache_helper_handler(), netsnmp_row_merge_helper_handler(), netsnmp_serialize_helper_handler(), netsnmp_stash_cache_update(), netsnmp_table_data_helper_handler(), netsnmp_table_data_set_helper_handler(), netsnmp_table_iterator_helper_handler(), and table_helper_handler().

  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.

Definition at line 456 of file agent_handler.c.

References netsnmp_call_handler(), netsnmp_mib_handler_s::next, netsnmp_request_info_s::next, and snmp_log().

  void netsnmp_clear_handler_list (void)

clears the entire handler-registration list

Definition at line 792 of file agent_handler.c.

References netsnmp_free_all_list_data().

  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.

Use netsnmp_handler_check_cache() later to make sure it's still valid before referencing it in the future.

Examples:
delayed_instance.c.

Definition at line 612 of file agent_handler.c.

References netsnmp_agent_request_info_s::asp, and SNMP_MALLOC_TYPEDEF.

  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()

Definition at line 101 of file agent_handler.c.

References netsnmp_mib_handler_s::access_method, netsnmp_mib_handler_s::handler_name, and SNMP_MALLOC_TYPEDEF.

Referenced by clone_handler(), get_old_api_handler(), netsnmp_create_handler_registration(), netsnmp_get_baby_steps_handler(), netsnmp_get_bulk_to_next_handler(), netsnmp_get_cache_handler(), netsnmp_get_debug_handler(), netsnmp_get_instance_handler(), netsnmp_get_mode_end_call_handler(), netsnmp_get_multiplexer_handler(), netsnmp_get_read_only_handler(), netsnmp_get_row_merge_handler(), netsnmp_get_scalar_handler(), netsnmp_get_serialize_handler(), netsnmp_get_stash_cache_handler(), netsnmp_get_table_data_handler(), netsnmp_get_table_data_set_handler(), netsnmp_get_table_handler(), and netsnmp_get_table_iterator_handler().

  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)

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.

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_access_method
    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()

Examples:
delayed_instance.c.

Definition at line 154 of file agent_handler.c.

References netsnmp_handler_registration_s::handler, netsnmp_handler_registration_s::handlerName, memdup(), netsnmp_handler_registration_s::modes, netsnmp_create_handler(), netsnmp_handler_registration_s::rootoid, netsnmp_handler_registration_s::rootoid_len, and SNMP_MALLOC_TYPEDEF.

  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.

Definition at line 735 of file agent_handler.c.

References netsnmp_handler_registration_s::handler, netsnmp_mib_handler_s::handler_name, and netsnmp_mib_handler_s::next.

Referenced by netsnmp_find_handler_data_by_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.

Definition at line 752 of file agent_handler.c.

References netsnmp_mib_handler_s::myvoid, and netsnmp_find_handler_by_name().

Referenced by netsnmp_find_table_registration_info().

  NETSNMP_INLINE void netsnmp_free_delegated_cache (netsnmp_delegated_cache * dcache)

frees a cache once you're finished using it

Examples:
delayed_instance.c.

Definition at line 650 of file agent_handler.c.

References SNMP_FREE.

  NETSNMP_INLINE void netsnmp_free_request_data_set (netsnmp_request_info * request)

Free the extra data stored in a request.

Definition at line 717 of file agent_handler.c.

References netsnmp_free_list_data(), and netsnmp_request_info_s::parent_data.

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

Definition at line 725 of file agent_handler.c.

References netsnmp_free_all_list_data(), and netsnmp_request_info_s::parent_data.

Referenced by netsnmp_table_iterator_helper_handler().

  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.

Returns NULL if it's no longer valid.

Examples:
delayed_instance.c.

Definition at line 636 of file agent_handler.c.

References netsnmp_check_transaction_id().

  netsnmp_mib_handler* netsnmp_handler_dup (netsnmp_mib_handler * handler)

dulpicates a handler

Definition at line 496 of file agent_handler.c.

References netsnmp_mib_handler_s::access_method, netsnmp_mib_handler_s::handler_name, netsnmp_mib_handler_s::myvoid, netsnmp_mib_handler_s::next, netsnmp_mib_handler_s::prev, and SNMP_FREE.

Referenced by netsnmp_handler_registration_dup().

  void netsnmp_handler_free (netsnmp_mib_handler * handler)

free's the resourceses associated with a given handler

Definition at line 478 of file agent_handler.c.

References netsnmp_mib_handler_s::handler_name, netsnmp_mib_handler_s::next, and SNMP_FREE.

Referenced by netsnmp_handler_registration_free().

  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)

Definition at line 664 of file agent_handler.c.

References netsnmp_request_info_s::delegated, and netsnmp_request_info_s::next.

  netsnmp_handler_registration* netsnmp_handler_registration_dup (netsnmp_handler_registration * reginfo)

duplicates the handler registration object

Definition at line 550 of file agent_handler.c.

References netsnmp_handler_registration_s::contextName, netsnmp_handler_registration_s::handler, netsnmp_handler_registration_s::handlerName, memdup(), netsnmp_handler_registration_s::modes, netsnmp_handler_dup(), netsnmp_handler_registration_free(), netsnmp_handler_registration_s::priority, netsnmp_handler_registration_s::range_subid, netsnmp_handler_registration_s::range_ubound, netsnmp_handler_registration_s::rootoid, netsnmp_handler_registration_s::rootoid_len, and netsnmp_handler_registration_s::timeout.

  void netsnmp_handler_registration_free (netsnmp_handler_registration * reginfo)

free the resources associated with a handler registration object

Definition at line 537 of file agent_handler.c.

References netsnmp_handler_registration_s::contextName, netsnmp_handler_registration_s::handler, netsnmp_handler_registration_s::handlerName, netsnmp_handler_free(), netsnmp_handler_registration_s::rootoid, and SNMP_FREE.

Referenced by netsnmp_handler_registration_dup(), netsnmp_register_mib_table_row(), and netsnmp_register_old_api().

  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.

Definition at line 331 of file agent_handler.c.

References netsnmp_inject_handler_before().

Referenced by netsnmp_register_cache_handler(), netsnmp_register_handler(), netsnmp_register_instance(), netsnmp_register_read_only_instance(), netsnmp_register_read_only_scalar(), netsnmp_register_read_only_table_data(), netsnmp_register_row_merge(), netsnmp_register_scalar(), netsnmp_register_serialize(), netsnmp_register_table(), netsnmp_register_table_data(), netsnmp_register_table_data_set(), and netsnmp_register_table_iterator().

  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.

Definition at line 286 of file agent_handler.c.

References netsnmp_handler_registration_s::handler, netsnmp_mib_handler_s::handler_name, netsnmp_mib_handler_s::next, netsnmp_mib_handler_s::prev, and snmp_log().

Referenced by netsnmp_inject_handler().

  int netsnmp_register_handler (netsnmp_handler_registration * reginfo)

register a handler, as defined by the netsnmp_handler_registration pointer.

Definition at line 180 of file agent_handler.c.

References netsnmp_handler_registration_s::contextName, netsnmp_handler_registration_s::handler, netsnmp_mib_handler_s::handler_name, netsnmp_handler_registration_s::handlerName, netsnmp_handler_registration_s::modes, netsnmp_get_bulk_to_next_handler(), netsnmp_inject_handler(), netsnmp_mib_handler_s::next, netsnmp_handler_registration_s::priority, netsnmp_handler_registration_s::range_subid, netsnmp_handler_registration_s::range_ubound, netsnmp_handler_registration_s::rootoid, netsnmp_handler_registration_s::rootoid_len, snmp_log(), and netsnmp_handler_registration_s::timeout.

Referenced by netsnmp_register_cache_handler(), netsnmp_register_old_api(), netsnmp_register_row_merge(), netsnmp_register_serialize(), and netsnmp_register_table().

  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.

Definition at line 780 of file agent_handler.c.

References netsnmp_add_list_data(), and netsnmp_create_data_list().

Referenced by netsnmp_init_baby_steps_helper(), netsnmp_init_bulk_to_next_helper(), netsnmp_init_debug_helper(), netsnmp_init_read_only_helper(), netsnmp_init_row_merge(), netsnmp_init_serialize(), and netsnmp_init_stash_cache_helper().

  int netsnmp_register_handler_nocallback (netsnmp_handler_registration * reginfo)

register a handler, as defined by the netsnmp_handler_registration pointer.

Definition at line 235 of file agent_handler.c.

References netsnmp_handler_registration_s::contextName, netsnmp_handler_registration_s::handler, netsnmp_mib_handler_s::handler_name, netsnmp_handler_registration_s::modes, netsnmp_mib_handler_s::next, netsnmp_handler_registration_s::priority, netsnmp_handler_registration_s::range_subid, netsnmp_handler_registration_s::range_ubound, netsnmp_handler_registration_s::rootoid, netsnmp_handler_registration_s::rootoid_len, snmp_log(), and netsnmp_handler_registration_s::timeout.

Referenced by netsnmp_register_mib_table_row().

  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

Parameters:

requset
    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.

Definition at line 684 of file agent_handler.c.

References netsnmp_add_list_data(), and netsnmp_request_info_s::parent_data.

Referenced by netsnmp_insert_iterator_context(), netsnmp_old_api_helper(), netsnmp_table_data_helper_handler(), netsnmp_table_data_set_helper_handler(), netsnmp_table_iterator_helper_handler(), and table_helper_handler().

  NETSNMP_INLINE 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.

Definition at line 707 of file agent_handler.c.

References netsnmp_get_list_data(), and netsnmp_request_info_s::parent_data.

Referenced by netsnmp_extract_array_context(), netsnmp_extract_iterator_context(), netsnmp_extract_table_data_set(), netsnmp_extract_table_info(), netsnmp_extract_table_row(), netsnmp_old_api_helper(), and netsnmp_table_iterator_helper_handler().