documentation update
git-svn-id: file:///home/hardaker/lib/sf-bkups/net-snmp-convert-svnrepo/trunk@13342 06827809-a52a-0410-b366-d66718629ded
diff --git a/man/netsnmp_table_data.3 b/man/netsnmp_table_data.3
index 30c331d..5b1aa06 100644
--- a/man/netsnmp_table_data.3
+++ b/man/netsnmp_table_data.3
@@ -1,8 +1,8 @@
-.TH "table_data: Helps you implement a table with datamatted storage." 3 "24 Nov 2004" "net-snmp" \" -*- nroff -*-
+.TH "table_data: Helps you implement a table with datamatted storage." 3 "31 Oct 2005" "net-snmp" \" -*- nroff -*-
.ad l
.nh
.SH NAME
-table_data: Helps you implement a table with datamatted storage. \- This 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.
+table_data: Helps you implement a table with datamatted storage. \- This helper is obsolete.
.PP
.SS "Modules"
@@ -11,7 +11,7 @@
.ti -1c
.RI "group\fBtable_dataset: Helps you implement a table with automatted storage.\fP"
.br
-.RI "\fIThis handler helps you implement a table where all the data is expected to be stored within the agent itself and not in some external storage location. \fP"
+.RI "\fIThis helper is obsolete. \fP"
.PP
.in -1c
@@ -21,35 +21,53 @@
.ti -1c
.RI "void \fBnetsnmp_table_data_generate_index_oid\fP (netsnmp_table_row *row)"
.br
-.RI "\fIgenerates the index portion of an table oid from a varlist. \fP"
.ti -1c
-.RI "int \fBnetsnmp_table_data_add_row\fP (netsnmp_table_data *table, netsnmp_table_row *row)"
+.RI "netsnmp_table_data * \fBnetsnmp_create_table_data\fP (const char *name)"
.br
-.RI "\fIAdds a row of data to a given table (stored in proper lexographical order). \fP"
+.RI "\fIcreates and returns a pointer to table data set \fP"
.ti -1c
-.RI "netsnmp_table_row * \fBnetsnmp_table_data_remove_row\fP (netsnmp_table_data *table, netsnmp_table_row *row)"
+.RI "netsnmp_table_row * \fBnetsnmp_create_table_data_row\fP (void)"
.br
-.RI "\fIremoves a row of data to a given table and returns it (no free's called) \fP"
+.RI "\fIcreates and returns a pointer to table data set \fP"
+.ti -1c
+.RI "netsnmp_table_row * \fBnetsnmp_table_data_clone_row\fP (netsnmp_table_row *row)"
+.br
+.RI "\fIclones a data row. \fP"
.ti -1c
.RI "void * \fBnetsnmp_table_data_delete_row\fP (netsnmp_table_row *row)"
.br
.RI "\fIdeletes a row's memory. \fP"
.ti -1c
-.RI "void * \fBnetsnmp_table_data_remove_and_delete_row\fP (netsnmp_table_data *table, netsnmp_table_row *row)"
+.RI "int \fBnetsnmp_table_data_add_row\fP (netsnmp_table_data *table, netsnmp_table_row *row)"
.br
-.RI "\fIremoves and frees a row of data to a given table and returns the void * \fP"
+.RI "\fIAdds a row of data to a given table (stored in proper lexographical order). \fP"
.ti -1c
.RI "NETSNMP_INLINE void \fBnetsnmp_table_data_replace_row\fP (netsnmp_table_data *table, netsnmp_table_row *origrow, netsnmp_table_row *newrow)"
.br
.RI "\fIswaps out origrow with newrow. \fP"
.ti -1c
-.RI "netsnmp_table_row * \fBnetsnmp_table_data_get\fP (netsnmp_table_data *table, \fBnetsnmp_variable_list\fP *indexes)"
+.RI "netsnmp_table_row * \fBnetsnmp_table_data_remove_row\fP (netsnmp_table_data *table, netsnmp_table_row *row)"
.br
-.RI "\fIfinds the data in 'datalist' stored at 'indexes' \fP"
+.RI "\fIremoves a row of data to a given table and returns it (no free's called) \fP"
.ti -1c
-.RI "netsnmp_table_row * \fBnetsnmp_table_data_get_from_oid\fP (netsnmp_table_data *table, oid *searchfor, size_t searchfor_len)"
+.RI "void * \fBnetsnmp_table_data_remove_and_delete_row\fP (netsnmp_table_data *table, netsnmp_table_row *row)"
.br
-.RI "\fIfinds the data in 'datalist' stored at the searchfor oid \fP"
+.RI "\fIremoves and frees a row of data to a given table and returns the void * \fP"
+.ti -1c
+.RI "netsnmp_table_data * \fBnetsnmp_table_data_create_table\fP (const char *name, long flags)"
+.br
+.ti -1c
+.RI "void \fBnetsnmp_table_data_delete_table\fP (netsnmp_table_data *table)"
+.br
+.ti -1c
+.RI "netsnmp_table_row * \fBnetsnmp_table_data_create_row\fP (void *entry)"
+.br
+.ti -1c
+.RI "int \fBnetsnmp_table_data_copy_row\fP (netsnmp_table_row *old_row, netsnmp_table_row *new_row)"
+.br
+.ti -1c
+.RI "void * \fBnetsnmp_table_data_remove_delete_row\fP (netsnmp_table_data *table, netsnmp_table_row *row)"
+.br
.ti -1c
.RI "\fBnetsnmp_mib_handler\fP * \fBnetsnmp_get_table_data_handler\fP (netsnmp_table_data *table)"
.br
@@ -65,51 +83,100 @@
.ti -1c
.RI "int \fBnetsnmp_table_data_helper_handler\fP (\fBnetsnmp_mib_handler\fP *handler, \fBnetsnmp_handler_registration\fP *reginfo, \fBnetsnmp_agent_request_info\fP *reqinfo, \fBnetsnmp_request_info\fP *requests)"
.br
-.RI "\fIThe helper handler that takes care of passing a specific row of data down to the lower handler(s). \fP"
-.ti -1c
-.RI "netsnmp_table_data * \fBnetsnmp_create_table_data\fP (const char *name)"
-.br
-.RI "\fIcreates and returns a pointer to table data set \fP"
-.ti -1c
-.RI "netsnmp_table_row * \fBnetsnmp_create_table_data_row\fP (void)"
-.br
-.RI "\fIcreates and returns a pointer to table data set \fP"
-.ti -1c
-.RI "NETSNMP_INLINE void \fBnetsnmp_insert_table_row\fP (\fBnetsnmp_request_info\fP *request, netsnmp_table_row *row)"
-.br
-.RI "\fIinserts a newly created table_data row into a request \fP"
-.ti -1c
-.RI "netsnmp_table_row * \fBnetsnmp_extract_table_row\fP (\fBnetsnmp_request_info\fP *request)"
-.br
-.RI "\fIextracts the row being accessed passed from the table_data helper \fP"
.ti -1c
.RI "netsnmp_table_data * \fBnetsnmp_extract_table\fP (\fBnetsnmp_request_info\fP *request)"
.br
.RI "\fIextracts the table being accessed passed from the table_data helper \fP"
.ti -1c
+.RI "netsnmp_table_row * \fBnetsnmp_extract_table_row\fP (\fBnetsnmp_request_info\fP *request)"
+.br
+.RI "\fIextracts the row being accessed passed from the table_data helper \fP"
+.ti -1c
.RI "void * \fBnetsnmp_extract_table_row_data\fP (\fBnetsnmp_request_info\fP *request)"
.br
.RI "\fIextracts the data from the row being accessed passed from the table_data helper \fP"
.ti -1c
+.RI "NETSNMP_INLINE void \fBnetsnmp_insert_table_row\fP (\fBnetsnmp_request_info\fP *request, netsnmp_table_row *row)"
+.br
+.RI "\fIinserts a newly created table_data row into a request \fP"
+.ti -1c
.RI "int \fBnetsnmp_table_data_build_result\fP (\fBnetsnmp_handler_registration\fP *reginfo, \fBnetsnmp_agent_request_info\fP *reqinfo, \fBnetsnmp_request_info\fP *request, netsnmp_table_row *row, int column, u_char type, u_char *result_data, size_t result_data_len)"
.br
-.RI "\fIbuilds a result given a row, a varbind to set and the data \fP"
.ti -1c
-.RI "netsnmp_table_row * \fBnetsnmp_table_data_clone_row\fP (netsnmp_table_row *row)"
+.RI "netsnmp_table_row * \fBnetsnmp_table_data_get_first_row\fP (netsnmp_table_data *table)"
.br
-.RI "\fIclones a data row. \fP"
+.RI "\fIreturns the first row in the table \fP"
+.ti -1c
+.RI "netsnmp_table_row * \fBnetsnmp_table_data_get_next_row\fP (netsnmp_table_data *table, netsnmp_table_row *row)"
+.br
+.RI "\fIreturns the next row in the table \fP"
+.ti -1c
+.RI "netsnmp_table_row * \fBnetsnmp_table_data_get\fP (netsnmp_table_data *table, \fBnetsnmp_variable_list\fP *indexes)"
+.br
+.RI "\fIfinds the data in 'datalist' stored at 'indexes' \fP"
+.ti -1c
+.RI "netsnmp_table_row * \fBnetsnmp_table_data_get_from_oid\fP (netsnmp_table_data *table, oid *searchfor, size_t searchfor_len)"
+.br
+.RI "\fIfinds the data in 'datalist' stored at the searchfor oid \fP"
.ti -1c
.RI "int \fBnetsnmp_table_data_num_rows\fP (netsnmp_table_data *table)"
.br
+.ti -1c
+.RI "netsnmp_table_row * \fBnetsnmp_table_data_row_first\fP (netsnmp_table_data *table)"
+.br
+.ti -1c
+.RI "netsnmp_table_row * \fBnetsnmp_table_data_row_get\fP (netsnmp_table_data *table, netsnmp_table_row *row)"
+.br
+.ti -1c
+.RI "netsnmp_table_row * \fBnetsnmp_table_data_row_next\fP (netsnmp_table_data *table, netsnmp_table_row *row)"
+.br
+.ti -1c
+.RI "netsnmp_table_row * \fBnetsnmp_table_data_row_get_byoid\fP (netsnmp_table_data *table, oid *instance, size_t len)"
+.br
+.ti -1c
+.RI "netsnmp_table_row * \fBnetsnmp_table_data_row_next_byoid\fP (netsnmp_table_data *table, oid *instance, size_t len)"
+.br
+.ti -1c
+.RI "netsnmp_table_row * \fBnetsnmp_table_data_row_get_byidx\fP (netsnmp_table_data *table, \fBnetsnmp_variable_list\fP *indexes)"
+.br
+.ti -1c
+.RI "netsnmp_table_row * \fBnetsnmp_table_data_row_next_byidx\fP (netsnmp_table_data *table, \fBnetsnmp_variable_list\fP *indexes)"
+.br
+.ti -1c
+.RI "int \fBnetsnmp_table_data_row_count\fP (netsnmp_table_data *table)"
+.br
+.ti -1c
+.RI "void * \fBnetsnmp_table_data_entry_first\fP (netsnmp_table_data *table)"
+.br
+.ti -1c
+.RI "void * \fBnetsnmp_table_data_entry_get\fP (netsnmp_table_data *table, netsnmp_table_row *row)"
+.br
+.ti -1c
+.RI "void * \fBnetsnmp_table_data_entry_next\fP (netsnmp_table_data *table, netsnmp_table_row *row)"
+.br
+.ti -1c
+.RI "void * \fBnetsnmp_table_data_entry_get_byidx\fP (netsnmp_table_data *table, \fBnetsnmp_variable_list\fP *indexes)"
+.br
+.ti -1c
+.RI "void * \fBnetsnmp_table_data_entry_next_byidx\fP (netsnmp_table_data *table, \fBnetsnmp_variable_list\fP *indexes)"
+.br
+.ti -1c
+.RI "void * \fBnetsnmp_table_data_entry_get_byoid\fP (netsnmp_table_data *table, oid *instance, size_t len)"
+.br
+.ti -1c
+.RI "void * \fBnetsnmp_table_data_entry_next_byoid\fP (netsnmp_table_data *table, oid *instance, size_t len)"
+.br
.in -1c
.SH "Detailed Description"
.PP
+This helper is obsolete. If you are writing a new module, please consider using the table_tdata helper instead.
+.PP
This 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. It can be used to store a list of rows, where a row consists of the indexes to the table and a generic data pointer. You can then implement a subhandler which is passed the exact row definition and data it must return data for or accept data for. Complex GETNEXT handling is greatly simplified in this case.
.SH "Function Documentation"
.PP
.SS "netsnmp_table_data* netsnmp_create_table_data (const char * name)"
.PP
-creates and returns a pointer to table data set Definition at line 544 of file table_data.c.
+creates and returns a pointer to table data set Definition at line 51 of file table_data.c.
.PP
References SNMP_MALLOC_TYPEDEF.
.PP
@@ -122,121 +189,112 @@
.in +1c
\fBdata_set.c\fP.
.PP
-Definition at line 554 of file table_data.c.
+Definition at line 61 of file table_data.c.
.PP
References SNMP_MALLOC_TYPEDEF.
.PP
Referenced by netsnmp_table_data_set_create_row_from_defaults().
.SS "netsnmp_table_data* netsnmp_extract_table (\fBnetsnmp_request_info\fP * request)"
.PP
-extracts the table being accessed passed from the table_data helper Definition at line 635 of file table_data.c.
+extracts the table being accessed passed from the table_data helper Definition at line 648 of file table_data.c.
.PP
References netsnmp_request_get_list_data().
.SS "netsnmp_table_row* netsnmp_extract_table_row (\fBnetsnmp_request_info\fP * request)"
.PP
-extracts the row being accessed passed from the table_data helper Definition at line 627 of file table_data.c.
+extracts the row being accessed passed from the table_data helper Definition at line 656 of file table_data.c.
.PP
References netsnmp_request_get_list_data().
.PP
-Referenced by netsnmp_extract_table_row_data(), and netsnmp_table_data_set_helper_handler().
+Referenced by netsnmp_extract_table_row_data().
.SS "void* netsnmp_extract_table_row_data (\fBnetsnmp_request_info\fP * request)"
.PP
-extracts the data from the row being accessed passed from the table_data helper Definition at line 644 of file table_data.c.
+extracts the data from the row being accessed passed from the table_data helper Definition at line 665 of file table_data.c.
.PP
References netsnmp_extract_table_row().
.PP
Referenced by netsnmp_extract_table_data_set_column().
.SS "\fBnetsnmp_mib_handler\fP* netsnmp_get_table_data_handler (netsnmp_table_data * table)"
.PP
-Creates a table_data handler and returns it. Definition at line 263 of file table_data.c.
+Creates a table_data handler and returns it. Definition at line 370 of file table_data.c.
.PP
References netsnmp_mib_handler_s::flags, netsnmp_mib_handler_s::myvoid, netsnmp_create_handler(), netsnmp_mib_handler, and snmp_log().
.PP
Referenced by netsnmp_register_table_data().
.SS "NETSNMP_INLINE void netsnmp_insert_table_row (\fBnetsnmp_request_info\fP * request, netsnmp_table_row * row)"
.PP
-inserts a newly created table_data row into a request Definition at line 562 of file table_data.c.
+inserts a newly created table_data row into a request Definition at line 677 of file table_data.c.
.PP
References netsnmp_table_request_info_s::indexes, netsnmp_create_data_list(), netsnmp_extract_table_info(), netsnmp_request_add_list_data(), netsnmp_request_info_s::next, netsnmp_request_info_s::prev, and snmp_oid_compare().
.SS "int netsnmp_register_read_only_table_data (\fBnetsnmp_handler_registration\fP * reginfo, netsnmp_table_data * table, \fBnetsnmp_table_registration_info\fP * table_info)"
.PP
-registers a handler as a read-only data table If table_info != NULL, it registers it as a normal table too. Definition at line 297 of file table_data.c.
+registers a handler as a read-only data table If table_info != NULL, it registers it as a normal table too. Definition at line 404 of file table_data.c.
.PP
References netsnmp_get_read_only_handler(), netsnmp_handler_registration, netsnmp_inject_handler(), and netsnmp_register_table_data().
.SS "int netsnmp_register_table_data (\fBnetsnmp_handler_registration\fP * reginfo, netsnmp_table_data * table, \fBnetsnmp_table_registration_info\fP * table_info)"
.PP
-registers a handler as a data table. If table_info != NULL, it registers it as a normal table too. Definition at line 286 of file table_data.c.
+registers a handler as a data table. If table_info != NULL, it registers it as a normal table too. Definition at line 393 of file table_data.c.
.PP
References netsnmp_get_table_data_handler(), netsnmp_handler_registration, netsnmp_inject_handler(), and netsnmp_register_table().
.PP
Referenced by netsnmp_register_read_only_table_data(), and netsnmp_register_table_data_set().
.SS "int netsnmp_table_data_add_row (netsnmp_table_data * table, netsnmp_table_row * row)"
.PP
-Adds a row of data to a given table (stored in proper lexographical order). returns SNMPERR_SUCCESS on successful addition. or SNMPERR_GENERR on failure (E.G., indexes already existed) xxx-rks: remove invalid row? Definition at line 51 of file table_data.c.
+Adds a row of data to a given table (stored in proper lexographical order). returns SNMPERR_SUCCESS on successful addition. or SNMPERR_GENERR on failure (E.G., indexes already existed) xxx-rks: remove invalid row? Definition at line 129 of file table_data.c.
.PP
-References netsnmp_table_data_generate_index_oid(), snmp_log(), and snmp_oid_compare().
+References snmp_log(), and snmp_oid_compare().
.PP
Referenced by netsnmp_table_data_replace_row(), and netsnmp_table_dataset_add_row().
-.SS "int netsnmp_table_data_build_result (\fBnetsnmp_handler_registration\fP * reginfo, \fBnetsnmp_agent_request_info\fP * reqinfo, \fBnetsnmp_request_info\fP * request, netsnmp_table_row * row, int column, u_char type, u_char * result_data, size_t result_data_len)"
-.PP
-builds a result given a row, a varbind to set and the data Definition at line 656 of file table_data.c.
-.PP
-References netsnmp_agent_request_info_s::mode, netsnmp_handler_registration, netsnmp_request_info_s::requestvb, netsnmp_handler_registration_s::rootoid, netsnmp_handler_registration_s::rootoid_len, and snmp_set_var_typed_value().
-.PP
-Referenced by netsnmp_table_data_helper_handler(), and netsnmp_table_data_set_helper_handler().
.SS "netsnmp_table_row* netsnmp_table_data_clone_row (netsnmp_table_row * row)"
.PP
-clones a data row. DOES NOT CLONE THE CONTAINED DATA. Definition at line 690 of file table_data.c.
+clones a data row. DOES NOT CLONE THE CONTAINED DATA. Definition at line 69 of file table_data.c.
.PP
References memdup().
.PP
Referenced by netsnmp_table_data_set_clone_row().
.SS "void* netsnmp_table_data_delete_row (netsnmp_table_row * row)"
.PP
-deletes a row's memory. returns the void data that it doesn't know how to delete. Definition at line 177 of file table_data.c.
+deletes a row's memory. returns the void data that it doesn't know how to delete. Definition at line 100 of file table_data.c.
.PP
References SNMP_FREE.
.PP
Referenced by netsnmp_table_data_remove_and_delete_row(), and netsnmp_table_dataset_delete_row().
-.SS "void netsnmp_table_data_generate_index_oid (netsnmp_table_row * row)"
-.PP
-generates the index portion of an table oid from a varlist. Definition at line 39 of file table_data.c.
-.PP
-References build_oid().
-.PP
-Referenced by netsnmp_table_data_add_row().
.SS "netsnmp_table_row* netsnmp_table_data_get (netsnmp_table_data * table, \fBnetsnmp_variable_list\fP * indexes)"
.PP
-finds the data in 'datalist' stored at 'indexes' Definition at line 231 of file table_data.c.
+finds the data in 'datalist' stored at 'indexes' Definition at line 803 of file table_data.c.
.PP
References netsnmp_table_data_get_from_oid().
+.SS "netsnmp_table_row* netsnmp_table_data_get_first_row (netsnmp_table_data * table)"
+.PP
+returns the first row in the table Definition at line 784 of file table_data.c.
+.PP
+Referenced by netsnmp_table_data_set_get_first_row().
.SS "netsnmp_table_row* netsnmp_table_data_get_from_oid (netsnmp_table_data * table, oid * searchfor, size_t searchfor_len)"
.PP
-finds the data in 'datalist' stored at the searchfor oid Definition at line 245 of file table_data.c.
+finds the data in 'datalist' stored at the searchfor oid Definition at line 817 of file table_data.c.
.PP
References snmp_oid_compare().
.PP
-Referenced by netsnmp_table_data_get(), and netsnmp_table_data_helper_handler().
-.SS "int netsnmp_table_data_helper_handler (\fBnetsnmp_mib_handler\fP * handler, \fBnetsnmp_handler_registration\fP * reginfo, \fBnetsnmp_agent_request_info\fP * reqinfo, \fBnetsnmp_request_info\fP * requests)"
+Referenced by netsnmp_table_data_get().
+.SS "netsnmp_table_row* netsnmp_table_data_get_next_row (netsnmp_table_data * table, netsnmp_table_row * row)"
.PP
-The helper handler that takes care of passing a specific row of data down to the lower handler(s). It sets request->processed if the request should not be handled. Definition at line 313 of file table_data.c.
+returns the next row in the table Definition at line 793 of file table_data.c.
.PP
-References netsnmp_table_request_info_s::colnum, netsnmp_mib_handler_s::flags, netsnmp_table_registration_info_s::max_column, netsnmp_table_registration_info_s::min_column, netsnmp_agent_request_info_s::mode, netsnmp_mib_handler_s::myvoid, variable_list::name, variable_list::name_length, netsnmp_call_next_handler(), netsnmp_create_data_list(), netsnmp_extract_table_info(), netsnmp_find_table_registration_info(), netsnmp_handler_registration, netsnmp_mib_handler, netsnmp_request_add_list_data(), netsnmp_set_request_error(), netsnmp_table_data_build_result(), netsnmp_table_data_get_from_oid(), netsnmp_request_info_s::next, netsnmp_request_info_s::processed, netsnmp_request_info_s::requestvb, netsnmp_handler_registration_s::rootoid, netsnmp_handler_registration_s::rootoid_len, SNMP_MIN, snmp_oid_compare(), and variable_list::type.
+Referenced by netsnmp_table_data_set_get_next_row().
.SS "void* netsnmp_table_data_remove_and_delete_row (netsnmp_table_data * table, netsnmp_table_row * row)"
.PP
-removes and frees a row of data to a given table and returns the void * returns the void * data on successful deletion. or NULL on failure (bad arguments) Definition at line 206 of file table_data.c.
+removes and frees a row of data to a given table and returns the void * returns the void * data on successful deletion. or NULL on failure (bad arguments) Definition at line 269 of file table_data.c.
.PP
References netsnmp_table_data_delete_row(), and netsnmp_table_data_remove_row().
.PP
Referenced by netsnmp_table_dataset_remove_and_delete_row(), and netsnmp_table_dataset_remove_row().
.SS "netsnmp_table_row* netsnmp_table_data_remove_row (netsnmp_table_data * table, netsnmp_table_row * row)"
.PP
-removes a row of data to a given table and returns it (no free's called) returns the row pointer itself on successful removing. or NULL on failure (bad arguments) Definition at line 155 of file table_data.c.
+removes a row of data to a given table and returns it (no free's called) returns the row pointer itself on successful removing. or NULL on failure (bad arguments) Definition at line 243 of file table_data.c.
.PP
Referenced by netsnmp_table_data_remove_and_delete_row(), and netsnmp_table_data_replace_row().
.SS "NETSNMP_INLINE void netsnmp_table_data_replace_row (netsnmp_table_data * table, netsnmp_table_row * origrow, netsnmp_table_row * newrow)"
.PP
-swaps out origrow with newrow. This does *not* delete/free anything! Definition at line 221 of file table_data.c.
+swaps out origrow with newrow. This does *not* delete/free anything! Definition at line 228 of file table_data.c.
.PP
References netsnmp_table_data_add_row(), and netsnmp_table_data_remove_row().
.PP
