---
name: "netsnmp_table_iterator"
section: "3snmp"
platform: "linux"
package: "libsnmp-dev"
version: "5.4.3~dfsg-2.8+deb7u1"
release: "Debian 7 (Wheezy)"
platforms: ["linux"]
url: "https://new.carta.tech/netsnmp_table_iterator"
---

# netsnmp\_table\_iterator(3snmp)

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.

## NAME

table\_iterator -

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.

### 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.*

### Defines

\#define **TI\_REQUEST\_CACHE**   'ti\_cache'\
 \#define **TABLE\_ITERATOR\_NOTAGAIN**   255\
 \#define **TABLE\_ITERATOR\_NAME**   'table\_iterator'\

### 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\_iterator\_info** \* **netsnmp\_iterator\_create\_table** (Netsnmp\_First\_Data\_Point \*firstDP, Netsnmp\_Next\_Data\_Point \*nextDP, Netsnmp\_First\_Data\_Point \*getidx, **netsnmp\_variable\_list** \*indexes)\
 void **netsnmp\_iterator\_delete\_table** (**netsnmp\_iterator\_info** \*iinfo)\
 **netsnmp\_mib\_handler** \* **netsnmp\_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:

- •

  A loop context is a pointer which indicates where in the current processing of a set of rows you currently are. Allows the get\_\*\_data\_point routines to move from one row to the next, once the iterator handler has identified the appropriate row for this request, the job of the loop context is done. The most simple example would be a pointer to an integer which simply counts rows from 1 to X. More commonly, it might be a pointer to a linked list **node**, or someother internal or external reference to a data set (file seek value, array pointer, ...). If allocated during iteration, either the free\_loop\_context\_at\_end (preferably) or the free\_loop\_context pointers should be set.

- •

  A data context is something that your handler code can use in order to retrieve the rest of the data for the needed row. This data can be accessed in your handler via netsnmp\_extract\_iterator\_context api with the netsnmp\_request\_info structure that's passed in. The important difference between a loop context and a data context is that multiple data contexts can be kept by the table\_iterator helper, where as only one loop context will ever be held by the table\_iterator helper. If allocated during iteration the free\_data\_context pointer should be set to an appropriate function.

The table iterator operates in a series of steps that call your code hooks from your netsnmp\_iterator\_info registration pointer.

- •

  the get\_first\_data\_point hook is called at the beginning of processing. It should set the **variable** list to a list of indexes for the given table. It should also set the loop\_context and maybe a data\_context which you will get a pointer back to when it needs to call your code to retrieve actual data later. The list of indexes should be returned after being update.

- •

  the get\_next\_data\_point hook is then called repeatedly and is passed the loop context and the data context for it to update. The indexes, loop context and data context should all be updated if more data is available, otherwise they should be left alone and a NULL should be returned. Ideally, it should update the loop context without the need to reallocate it. If reallocation is necessary for every iterative step, then the free\_loop\_context function pointer should be set. If not, then the free\_loop\_context\_at\_end pointer should be set, which is more efficient since a malloc/free will only be performed once for every iteration.

## Typedef Documentation

### struct netsnmp\_iterator\_info\_s netsnmp\_iterator\_info

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:**

*request* the 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

### netsnmp\_mib\_handler \* netsnmp\_get\_table\_iterator\_handler (netsnmp\_iterator\_info \* iinfo)

returns a netsnmp\_mib\_handler object for the table\_iterator helper

### 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\_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:**

*reginfo* is a pointer to a netsnmp\_handler\_registration struct\
 *iinfo* is a pointer to a netsnmp\_iterator\_info struct

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

## Author

Generated automatically by Doxygen for net-snmp from the source code.