net-snmp 5.7
Data Structures | Defines | Typedefs | Functions | Variables
table_iterator
table

The table iterator helper is designed to simplify the task of writing a table handler for the net-snmp agent when the data being accessed is not in an oid sorted form and must be accessed externally. More...

Data Structures

struct  ti_cache_info_s
struct  netsnmp_iterator_info_s
 Holds iterator information containing functions which should be called by the iterator_handler to loop over your data set and sort it in a SNMP specific manner. More...

Defines

#define TI_REQUEST_CACHE   "ti_cache"
#define TABLE_ITERATOR_NOTAGAIN   255
#define TABLE_ITERATOR_NAME   "table_iterator"
#define netsnmp_register_table_iterator2(reginfo, iinfo)

Typedefs

typedef struct ti_cache_info_s ti_cache_info
typedef netsnmp_variable_list *( Netsnmp_First_Data_Point )(void **loop_context, void **data_context, netsnmp_variable_list *, struct netsnmp_iterator_info_s *)
typedef netsnmp_variable_list *( Netsnmp_Next_Data_Point )(void **loop_context, void **data_context, netsnmp_variable_list *, struct netsnmp_iterator_info_s *)
typedef void *( Netsnmp_Make_Data_Context )(void *loop_context, struct netsnmp_iterator_info_s *)
typedef void( Netsnmp_Free_Loop_Context )(void *, struct netsnmp_iterator_info_s *)
typedef void( Netsnmp_Free_Data_Context )(void *, struct netsnmp_iterator_info_s *)
typedef struct
netsnmp_iterator_info_s 
netsnmp_iterator_info
 Typedefs the netsnmp_iterator_info_s struct into netsnmp_iterator_info.

Functions

 netsnmp_feature_child_of (table_iterator_all, mib_helpers)
void netsnmp_iterator_delete_table (netsnmp_iterator_info *iinfo)
 Free the memory that was allocated for a table iterator.
void netsnmp_handler_owns_iterator_info (netsnmp_mib_handler *h)
netsnmp_mib_handlernetsnmp_get_table_iterator_handler (netsnmp_iterator_info *iinfo)
 Returns a netsnmp_mib_handler object for the table_iterator helper.
int netsnmp_register_table_iterator (netsnmp_handler_registration *reginfo, netsnmp_iterator_info *iinfo)
 Creates and registers a table iterator helper handler calling netsnmp_create_handler with a handler name set to TABLE_ITERATOR_NAME and access method, netsnmp_table_iterator_helper_handler.
NETSNMP_INLINE void * netsnmp_extract_iterator_context (netsnmp_request_info *request)
 extracts the table_iterator specific data from a request.
NETSNMP_INLINE void netsnmp_insert_iterator_context (netsnmp_request_info *request, void *data)
 inserts table_iterator specific data for a newly created row into a request
int netsnmp_table_iterator_helper_handler (netsnmp_mib_handler *handler, netsnmp_handler_registration *reginfo, netsnmp_agent_request_info *reqinfo, netsnmp_request_info *requests)
void * netsnmp_iterator_row_first (netsnmp_iterator_info *iinfo)
void * netsnmp_iterator_row_get (netsnmp_iterator_info *iinfo, void *row)
void * netsnmp_iterator_row_next (netsnmp_iterator_info *iinfo, void *row)
void * netsnmp_iterator_row_get_byidx (netsnmp_iterator_info *iinfo, netsnmp_variable_list *indexes)
void * netsnmp_iterator_row_next_byidx (netsnmp_iterator_info *iinfo, netsnmp_variable_list *indexes)
void * netsnmp_iterator_row_get_byoid (netsnmp_iterator_info *iinfo, oid *instance, size_t len)
void * netsnmp_iterator_row_next_byoid (netsnmp_iterator_info *iinfo, oid *instance, size_t len)
int netsnmp_iterator_row_count (netsnmp_iterator_info *iinfo)

Variables

Netsnmp_Node_Handler netsnmp_table_iterator_helper_handler

Detailed Description

The table iterator helper is designed to simplify the task of writing a table handler for the net-snmp agent when the data being accessed is not in an oid sorted form and must be accessed externally.

Functionally, it is a specialized version of the more generic table helper but easies the burden of GETNEXT processing by manually looping through all the data indexes retrieved through function calls which should be supplied by the module that wishes help. The module the table_iterator helps should, afterwards, never be called for the case of "MODE_GETNEXT" and only for the GET and SET related modes instead.

The fundamental notion between the table iterator is that it allows your code to iterate over each "row" within your data storage mechanism, without requiring that it be sorted in a SNMP-index-compliant manner. Through the get_first_data_point and get_next_data_point hooks, the table_iterator helper will repeatedly call your hooks to find the "proper" row of data that needs processing. The following concepts are important:

The table iterator operates in a series of steps that call your code hooks from your netsnmp_iterator_info registration pointer.


Define Documentation

#define netsnmp_register_table_iterator2 (   reginfo,
  iinfo 
)
Value:
(((iinfo)->flags |= NETSNMP_HANDLER_OWNS_IINFO),           \
        netsnmp_register_table_iterator((reginfo), (iinfo)))

Definition at line 135 of file table_iterator.h.


Typedef Documentation

Typedefs the netsnmp_iterator_info_s struct into netsnmp_iterator_info.


Function Documentation

void * netsnmp_extract_iterator_context ( netsnmp_request_info request)

extracts the table_iterator specific data from a request.

This function extracts the table iterator specific data from a netsnmp_request_info object. Calls netsnmp_request_get_list_data with request->parent_data set with data from a request that was added previously by a module and TABLE_ITERATOR_NAME handler name.

Parameters:
requestthe netsnmp request info structure
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.the net

Definition at line 290 of file table_iterator.c.

netsnmp_mib_handler * netsnmp_get_table_iterator_handler ( netsnmp_iterator_info iinfo)

Returns a netsnmp_mib_handler object for the table_iterator helper.

The caller remains the owner of the iterator information object if the flag NETSNMP_HANDLER_OWNS_IINFO has not been set, and the created handler becomes the owner of the iterator information if the flag NETSNMP_HANDLER_OWNS_IINFO has been set.

Definition at line 217 of file table_iterator.c.

void netsnmp_insert_iterator_context ( netsnmp_request_info request,
void *  data 
)

inserts table_iterator specific data for a newly created row into a request

Definition at line 299 of file table_iterator.c.

void netsnmp_iterator_delete_table ( netsnmp_iterator_info iinfo)

Free the memory that was allocated for a table iterator.

Definition at line 158 of file table_iterator.c.

int netsnmp_register_table_iterator ( netsnmp_handler_registration reginfo,
netsnmp_iterator_info iinfo 
)

Creates and registers a table iterator helper handler calling netsnmp_create_handler with a handler name set to TABLE_ITERATOR_NAME and access method, netsnmp_table_iterator_helper_handler.

If NOT_SERIALIZED is not defined the function injects the serialize handler into the calling chain prior to calling netsnmp_register_table.

Parameters:
reginfois a pointer to a netsnmp_handler_registration struct
iinfoA pointer to a netsnmp_iterator_info struct. If the flag NETSNMP_HANDLER_OWNS_IINFO is not set in iinfo->flags, the caller remains the owner of this structure. And if the flag NETSNMP_HANDLER_OWNS_IINFO is set in iinfo->flags, ownership of this data structure is passed to the handler.
Returns:
MIB_REGISTERED_OK is returned if the registration was a success. Failures are MIB_REGISTRATION_FAILED, MIB_DUPLICATE_REGISTRATION. If iinfo is NULL, SNMPERR_GENERR is returned.

Definition at line 259 of file table_iterator.c.