userapps/opensource/net-snmp/man/netsnmp_table.3

   1 .TH "table: Helps you implement a table." 3 "17 Mar 2003" "net-snmp" \" -*- nroff -*-
   2 .ad l
   3 .nh
   4 .SH NAME
   5 table: Helps you implement a table. \- This handler helps you implement a table by doing some of the processing for you.
   6 More...
   7 .SS "Modules"
   8
   9 .in +1c
  10 .ti -1c
  11 .RI "\fBtable_array: Helps you implement a table when data can be stored locally. The data is stored in a sorted array, using a binary search for lookups.\fP"
  12 .br
  13 .RI "\fIThe table_array handler is used (automatically) in conjuntion with the \fBtable\fP handler.\fP"
  14 .PP
  15 .in +1c
  16
  17 .ti -1c
  18 .RI "\fBtable_data: Helps you implement a table with datamatted storage.\fP"
  19 .br
  20 .RI "\fIThis helper helps you implement a table where all the indexes are expected to be stored within the agent itself and not in some external storage location.\fP"
  21 .PP
  22 .in +1c
  23
  24 .ti -1c
  25 .RI "\fBtable_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.\fP"
  26 .br
  27 .RI "\fIFunctionally, 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.\fP"
  28 .PP
  29
  30 .in -1c
  31 .SS "Functions"
  32
  33 .in +1c
  34 .ti -1c
  35 .RI "netsnmp_mib_handler * \fBnetsnmp_get_table_handler\fP (netsnmp_table_registration_info *tabreq)"
  36 .br
  37 .RI "\fIGiven a netsnmp_table_registration_info object, creates a table handler.\fP"
  38 .ti -1c
  39 .RI "int \fBnetsnmp_register_table\fP (netsnmp_handler_registration *reginfo, netsnmp_table_registration_info *tabreq)"
  40 .br
  41 .RI "\fIcreates a table handler given the netsnmp_table_registration_info object, inserts it into the request chain and then calls \fBnetsnmp_register_handler\fP() to register the table into the agent.\fP"
  42 .ti -1c
  43 .RI "NETSNMP_INLINE netsnmp_table_request_info * \fBnetsnmp_extract_table_info\fP (netsnmp_request_info *request)"
  44 .br
  45 .RI "\fIextracts the processed table information from a given request.\fP"
  46 .ti -1c
  47 .RI "netsnmp_table_registration_info * \fBnetsnmp_find_table_registration_info\fP (netsnmp_handler_registration *reginfo)"
  48 .br
  49 .RI "\fIextracts the registered netsnmp_table_registration_info object from a netsnmp_handler_registration object.\fP"
  50 .ti -1c
  51 .RI "int \fBtable_helper_handler\fP (netsnmp_mib_handler *handler, netsnmp_handler_registration *reginfo, netsnmp_agent_request_info *reqinfo, netsnmp_request_info *requests)"
  52 .br
  53 .RI "\fIimplements the table helper handler.\fP"
  54 .ti -1c
  55 .RI "int \fBnetsnmp_table_build_result\fP (netsnmp_handler_registration *reginfo, netsnmp_request_info *reqinfo, netsnmp_table_request_info *table_info, u_char type, u_char *result, size_t result_len)"
  56 .br
  57 .RI "\fIBuilds the result to be returned to the agent given the table information.\fP"
  58 .ti -1c
  59 .RI "int \fBnetsnmp_table_build_oid\fP (netsnmp_handler_registration *reginfo, netsnmp_request_info *reqinfo, netsnmp_table_request_info *table_info)"
  60 .br
  61 .RI "\fIgiven a registration info object, a request object and the table info object it builds the request->requestvb->name oid from the index values and column information found in the table_info object.\fP"
  62 .ti -1c
  63 .RI "int \fBnetsnmp_table_build_oid_from_index\fP (netsnmp_handler_registration *reginfo, netsnmp_request_info *reqinfo, netsnmp_table_request_info *table_info)"
  64 .br
  65 .RI "\fIBuilds an oid from index information.\fP"
  66 .ti -1c
  67 .RI "int \fBnetsnmp_update_variable_list_from_index\fP (netsnmp_table_request_info *tri)"
  68 .br
  69 .RI "\fIparses an OID into table indexses.\fP"
  70 .ti -1c
  71 .RI "int \fBnetsnmp_update_indexes_from_variable_list\fP (netsnmp_table_request_info *tri)"
  72 .br
  73 .RI "\fIbuilds an oid given a set of indexes.\fP"
  74 .ti -1c
  75 .RI "int \fBnetsnmp_check_getnext_reply\fP (netsnmp_request_info *request, oid *prefix, size_t prefix_len, netsnmp_variable_list *newvar, netsnmp_variable_list **outvar)"
  76 .br
  77 .RI "\fIchecks the original request against the current data being passed in if its greater than the request oid but less than the current valid return, set the current valid return to the new value.\fP"
  78 .in -1c
  79 .SH "DETAILED DESCRIPTION"
  80 .PP
  81 This handler helps you implement a table by doing some of the processing for you.
  82 .PP
  83 This handler truly shows the power of the new handler mechanism. By creating a table handler and injecting it into your calling chain, or by using the \fBnetsnmp_register_table\fP() function to register your table, you get access to some pre-parsed information. Specifically, the table handler pulls out the column number and indexes from the request oid so that you don't have to do the complex work to do that parsing within your own code.
  84 .PP
  85 To do this, the table handler needs to know up front how your table is structured. To inform it about this, you fill in a table_registeration_info structure that is passed to the table handler. It contains the asn index types for the table as well as the minimum and maximum column that should be used.
  86 .SH "FUNCTION DOCUMENTATION"
  87 .PP
  88 .SS "int netsnmp_check_getnext_reply (netsnmp_request_info * request, oid * prefix, size_t prefix_len, netsnmp_variable_list * newvar, netsnmp_variable_list ** outvar)"
  89 .PP
  90 checks the original request against the current data being passed in if its greater than the request oid but less than the current valid return, set the current valid return to the new value.
  91 .PP
  92 returns 1 if outvar was replaced with the oid from newvar (success). returns 0 if not.
  93 .PP
  94 Definition at line 654 of file table.c.
  95 .SS "NETSNMP_INLINE netsnmp_table_request_info* netsnmp_extract_table_info (netsnmp_request_info * request)"
  96 .PP
  97 extracts the processed table information from a given request.
  98 .PP
  99 call this from subhandlers on a request to extract the processed netsnmp_request_info information. The resulting information includes the index values and the column number.
 100 .PP
 101 Definition at line 94 of file table.c.
 102 .SS "netsnmp_table_registration_info* netsnmp_find_table_registration_info (netsnmp_handler_registration * reginfo)"
 103 .PP
 104 extracts the registered netsnmp_table_registration_info object from a netsnmp_handler_registration object.
 105 .PP
 106 Definition at line 103 of file table.c.
 107 .SS "netsnmp_mib_handler* netsnmp_get_table_handler (netsnmp_table_registration_info * tabreq)"
 108 .PP
 109 Given a netsnmp_table_registration_info object, creates a table handler.
 110 .PP
 111 You can use this table handler by injecting it into a calling chain. When the handler gets called, it'll do processing and store it's information into the request->parent_data structure.
 112 .PP
 113 Definition at line 58 of file table.c.
 114 .SS "int netsnmp_register_table (netsnmp_handler_registration * reginfo, netsnmp_table_registration_info * tabreq)"
 115 .PP
 116 creates a table handler given the netsnmp_table_registration_info object, inserts it into the request chain and then calls \fBnetsnmp_register_handler\fP() to register the table into the agent.
 117 .PP
 118 Definition at line 81 of file table.c.
 119 .SS "int netsnmp_table_build_oid (netsnmp_handler_registration * reginfo, netsnmp_request_info * reqinfo, netsnmp_table_request_info * table_info)"
 120 .PP
 121 given a registration info object, a request object and the table info object it builds the request->requestvb->name oid from the index values and column information found in the table_info object.
 122 .PP
 123 Definition at line 572 of file table.c.
 124 .SS "int netsnmp_table_build_oid_from_index (netsnmp_handler_registration * reginfo, netsnmp_request_info * reqinfo, netsnmp_table_request_info * table_info)"
 125 .PP
 126 Builds an oid from index information.
 127 .PP
 128 Definition at line 598 of file table.c.
 129 .SS "int netsnmp_table_build_result (netsnmp_handler_registration * reginfo, netsnmp_request_info * reqinfo, netsnmp_table_request_info * table_info, u_char type, u_char * result, size_t result_len)"
 130 .PP
 131 Builds the result to be returned to the agent given the table information.
 132 .PP
 133 Use this function to return results from lowel level handlers to the agent. It takes care of building the proper resulting oid (containing proper indexing) and inserts the result value into the returning varbind.
 134 .PP
 135 Definition at line 539 of file table.c.
 136 .SS "int netsnmp_update_indexes_from_variable_list (netsnmp_table_request_info * tri)"
 137 .PP
 138 builds an oid given a set of indexes.
 139 .PP
 140 Definition at line 636 of file table.c.
 141 .SS "int netsnmp_update_variable_list_from_index (netsnmp_table_request_info * tri)"
 142 .PP
 143 parses an OID into table indexses.
 144 .PP
 145 Definition at line 625 of file table.c.
 146 .SS "int table_helper_handler (netsnmp_mib_handler * handler, netsnmp_handler_registration * reginfo, netsnmp_agent_request_info * reqinfo, netsnmp_request_info * requests)"
 147 .PP
 148 implements the table helper handler.
 149 .PP
 150 Definition at line 111 of file table.c.