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

   1 .TH "table_dataset: Helps you implement a table with automatted storage." 3 "14 Mar 2003" "net-snmp" \" -*- nroff -*-
   2 .ad l
   3 .nh
   4 .SH NAME
   5 table_dataset: Helps you implement a table with automatted storage. \- This 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.
   6 More...
   7 .SS "Functions"
   8
   9 .in +1c
  10 .ti -1c
  11 .RI "netsnmp_table_data_set * \fBnetsnmp_create_table_data_set\fP (const char *table_name)"
  12 .br
  13 .RI "\fICreate a netsnmp_table_data_set structure given a table_data definition.\fP"
  14 .ti -1c
  15 .RI "netsnmp_mib_handler * \fBnetsnmp_get_table_data_set_handler\fP (netsnmp_table_data_set *data_set)"
  16 .br
  17 .RI "\fIGiven a netsnmp_table_data_set definition, create a handler for it.\fP"
  18 .ti -1c
  19 .RI "int \fBnetsnmp_register_table_data_set\fP (netsnmp_handler_registration *reginfo, netsnmp_table_data_set *data_set, netsnmp_table_registration_info *table_info)"
  20 .br
  21 .RI "\fIregister a given data_set at a given oid (specified in the netsnmp_handler_registration pointer).\fP"
  22 .ti -1c
  23 .RI "netsnmp_table_data_set_storage * \fBnetsnmp_table_data_set_find_column\fP (netsnmp_table_data_set_storage *start, unsigned int column)"
  24 .br
  25 .RI "\fIFinds a column within a given storage set, given the pointer to the start of the storage set list.\fP"
  26 .ti -1c
  27 .RI "netsnmp_table_data_set_storage * \fBnetsnmp_extract_table_data_set_column\fP (netsnmp_request_info *request, unsigned int column)"
  28 .br
  29 .RI "\fIextracts a netsnmp_table_data_set pointer from a given request.\fP"
  30 .ti -1c
  31 .RI "NETSNMP_INLINE netsnmp_table_data_set * \fBnetsnmp_extract_table_data_set\fP (netsnmp_request_info *request)"
  32 .br
  33 .RI "\fIextracts a netsnmp_table_data_set pointer from a given request.\fP"
  34 .ti -1c
  35 .RI "int \fBnetsnmp_mark_row_column_writable\fP (netsnmp_table_row *row, int column, int writable)"
  36 .br
  37 .RI "\fImarks a given column in a row as writable or not.\fP"
  38 .ti -1c
  39 .RI "int \fBnetsnmp_set_row_column\fP (netsnmp_table_row *row, unsigned int column, int type, const char *value, size_t value_len)"
  40 .br
  41 .RI "\fIsets a given column in a row with data given a type, value, and length.\fP"
  42 .ti -1c
  43 .RI "int \fBnetsnmp_table_set_add_default_row\fP (netsnmp_table_data_set *table_set, unsigned int column, int type, int writable, void *default_value, size_t default_value_len)"
  44 .br
  45 .RI "\fIadds a new default row to a table_set.\fP"
  46 .ti -1c
  47 .RI "netsnmp_table_row * \fBnetsnmp_table_data_set_clone_row\fP (netsnmp_table_row *row)"
  48 .br
  49 .RI "\fIclones a dataset row, including all data.\fP"
  50 .ti -1c
  51 .RI "netsnmp_table_row * \fBnetsnmp_table_data_set_create_row_from_defaults\fP (netsnmp_table_data_set_storage *defrow)"
  52 .br
  53 .RI "\fIcreates a new row from an existing defined default set.\fP"
  54 .ti -1c
  55 .RI "newrow_stash * \fBnetsnmp_table_data_set_create_newrowstash\fP (netsnmp_table_data_set *datatable, netsnmp_table_request_info *table_info)"
  56 .br
  57 .ti -1c
  58 .RI "int \fBnetsnmp_table_data_set_helper_handler\fP (netsnmp_mib_handler *handler, netsnmp_handler_registration *reginfo, netsnmp_agent_request_info *reqinfo, netsnmp_request_info *requests)"
  59 .br
  60 .RI "\fIimplements the table data helper.\fP"
  61 .ti -1c
  62 .RI "void \fBnetsnmp_register_auto_data_table\fP (netsnmp_table_data_set *table_set, char *registration_name)"
  63 .br
  64 .RI "\fIregisters a table_dataset so that the 'add_row' snmpd.conf token can be used to add data to this table.\fP"
  65 .ti -1c
  66 .RI "void \fBnetsnmp_config_parse_table_set\fP (const char *token, char *line)"
  67 .br
  68 .ti -1c
  69 .RI "void \fBnetsnmp_config_parse_add_row\fP (const char *token, char *line)"
  70 .br
  71 .ti -1c
  72 .RI "NETSNMP_INLINE void \fBnetsnmp_table_dataset_add_index\fP (netsnmp_table_data_set *table, u_char type)"
  73 .br
  74 .RI "\fIadds an index to the table.\fP"
  75 .ti -1c
  76 .RI "NETSNMP_INLINE void \fBnetsnmp_table_dataset_add_row\fP (netsnmp_table_data_set *table, netsnmp_table_row *row)"
  77 .br
  78 .RI "\fIadds a new row to a dataset table.\fP"
  79 .ti -1c
  80 .RI "NETSNMP_INLINE void \fBnetsnmp_table_dataset_replace_row\fP (netsnmp_table_data_set *table, netsnmp_table_row *origrow, netsnmp_table_row *newrow)"
  81 .br
  82 .RI "\fIadds a new row to a dataset table.\fP"
  83 .ti -1c
  84 .RI "NETSNMP_INLINE netsnmp_table_data_set_storage * \fBnetsnmp_table_dataset_delete_data\fP (netsnmp_table_data_set_storage *data)"
  85 .br
  86 .RI "\fIdeletes a single dataset table data.\fP"
  87 .ti -1c
  88 .RI "NETSNMP_INLINE void \fBnetsnmp_table_dataset_delete_all_data\fP (netsnmp_table_data_set_storage *data)"
  89 .br
  90 .RI "\fIdeletes all the data from this node and beyond in the linked list.\fP"
  91 .ti -1c
  92 .RI "NETSNMP_INLINE void \fBnetsnmp_table_dataset_delete_row\fP (netsnmp_table_row *row)"
  93 .br
  94 .RI "\fIdeletes all the data from this node and beyond in the linked list.\fP"
  95 .ti -1c
  96 .RI "NETSNMP_INLINE void \fBnetsnmp_table_dataset_remove_row\fP (netsnmp_table_data_set *table, netsnmp_table_row *row)"
  97 .br
  98 .RI "\fIremoves a row from the table, but doesn't delete/free anything.\fP"
  99 .ti -1c
 100 .RI "NETSNMP_INLINE void \fBnetsnmp_table_dataset_remove_and_delete_row\fP (netsnmp_table_data_set *table, netsnmp_table_row *row)"
 101 .br
 102 .RI "\fIremoves a row from the table and then deletes it (and all it's data).\fP"
 103 .ti -1c
 104 .RI "void \fBnetsnmp_table_set_multi_add_default_row\fP (va_dcl) va_dcl"
 105 .br
 106 .RI "\fIadds multiple data column definitions to each row.\fP"
 107 .ti -1c
 108 .RI "void \fBnetsnmp_table_set_add_indexes\fP (va_alist) va_dcl"
 109 .br
 110 .RI "\fIadds multiple indexes to a table_dataset helper object.\fP"
 111 .in -1c
 112 .SH "DETAILED DESCRIPTION"
 113 .PP
 114 This 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.
 115 .PP
 116 It handles all MIB requests including GETs, GETNEXTs and SETs. It's possible to simply create a table without actually ever defining a handler to be called when SNMP requests come in. To use the data, you can either attach a sub-handler that merely uses/manipulates the data further when requests come in, or you can loop through it externally when it's actually needed. This handler is most useful in cases where a table is holding configuration data for something which gets triggered via another event.
 117 .PP
 118 NOTE NOTE NOTE: This helper isn't complete and is likely to change somewhat over time. Specifically, the way it stores data internally may change drastically.
 119 .SH "FUNCTION DOCUMENTATION"
 120 .PP
 121 .SS "netsnmp_table_data_set* netsnmp_create_table_data_set (const char * table_name)"
 122 .PP
 123 Create a netsnmp_table_data_set structure given a table_data definition.
 124 .PP
 125 \fBExamples: \fP
 126 .in +1c
 127 \fBdata_set.c\fP.
 128 .PP
 129 Definition at line 63 of file table_dataset.c.
 130 .SS "NETSNMP_INLINE netsnmp_table_data_set* netsnmp_extract_table_data_set (netsnmp_request_info * request)"
 131 .PP
 132 extracts a netsnmp_table_data_set pointer from a given request.
 133 .PP
 134 Definition at line 175 of file table_dataset.c.
 135 .SS "netsnmp_table_data_set_storage* netsnmp_extract_table_data_set_column (netsnmp_request_info * request, unsigned int column)"
 136 .PP
 137 extracts a netsnmp_table_data_set pointer from a given request.
 138 .PP
 139 Definition at line 161 of file table_dataset.c.
 140 .SS "netsnmp_mib_handler* netsnmp_get_table_data_set_handler (netsnmp_table_data_set * data_set)"
 141 .PP
 142 Given a netsnmp_table_data_set definition, create a handler for it.
 143 .PP
 144 Definition at line 75 of file table_dataset.c.
 145 .SS "int netsnmp_mark_row_column_writable (netsnmp_table_row * row, int column, int writable)"
 146 .PP
 147 marks a given column in a row as writable or not.
 148 .PP
 149 \fBExamples: \fP
 150 .in +1c
 151 \fBdata_set.c\fP.
 152 .PP
 153 Definition at line 185 of file table_dataset.c.
 154 .SS "void netsnmp_register_auto_data_table (netsnmp_table_data_set * table_set, char * registration_name)"
 155 .PP
 156 registers a table_dataset so that the 'add_row' snmpd.conf token can be used to add data to this table.
 157 .PP
 158 If registration_name is NULL then the name used when the table was created will be used instead.
 159 .PP
 160 \fB\fBTodo: \fP\fP
 161 .in +1c
 162  create a properly free'ing registeration pointer for the datalist, and get the datalist freed at shutdown.
 163 .PP
 164 \fBExamples: \fP
 165 .in +1c
 166 \fBdata_set.c\fP.
 167 .PP
 168 Definition at line 727 of file table_dataset.c.
 169 .SS "int netsnmp_register_table_data_set (netsnmp_handler_registration * reginfo, netsnmp_table_data_set * data_set, netsnmp_table_registration_info * table_info)"
 170 .PP
 171 register a given data_set at a given oid (specified in the netsnmp_handler_registration pointer).
 172 .PP
 173 The reginfo->handler->access_method *may* be null if the call doesn't ever want to be called for SNMP operations.
 174 .PP
 175 \fBExamples: \fP
 176 .in +1c
 177 \fBdata_set.c\fP.
 178 .PP
 179 Definition at line 101 of file table_dataset.c.
 180 .SS "int netsnmp_set_row_column (netsnmp_table_row * row, unsigned int column, int type, const char * value, size_t value_len)"
 181 .PP
 182 sets a given column in a row with data given a type, value, and length.
 183 .PP
 184 Data is memdup'ed by the function.
 185 .PP
 186 \fBExamples: \fP
 187 .in +1c
 188 \fBdata_set.c\fP.
 189 .PP
 190 Definition at line 221 of file table_dataset.c.
 191 .SS "netsnmp_table_row* netsnmp_table_data_set_clone_row (netsnmp_table_row * row)"
 192 .PP
 193 clones a dataset row, including all data.
 194 .PP
 195 Definition at line 321 of file table_dataset.c.
 196 .SS "netsnmp_table_row* netsnmp_table_data_set_create_row_from_defaults (netsnmp_table_data_set_storage * defrow)"
 197 .PP
 198 creates a new row from an existing defined default set.
 199 .PP
 200 Definition at line 355 of file table_dataset.c.
 201 .SS "netsnmp_table_data_set_storage* netsnmp_table_data_set_find_column (netsnmp_table_data_set_storage * start, unsigned int column)"
 202 .PP
 203 Finds a column within a given storage set, given the pointer to the start of the storage set list.
 204 .PP
 205 Definition at line 149 of file table_dataset.c.
 206 .SS "int netsnmp_table_data_set_helper_handler (netsnmp_mib_handler * handler, netsnmp_handler_registration * reginfo, netsnmp_agent_request_info * reqinfo, netsnmp_request_info * requests)"
 207 .PP
 208 implements the table data helper.
 209 .PP
 210 This is the routine that takes care of all SNMP requests coming into the table.
 211 .PP
 212 Definition at line 393 of file table_dataset.c.
 213 .SS "NETSNMP_INLINE void netsnmp_table_dataset_add_index (netsnmp_table_data_set * table, u_char type)"
 214 .PP
 215 adds an index to the table.
 216 .PP
 217 Call this repeatly for each index.
 218 .PP
 219 \fBExamples: \fP
 220 .in +1c
 221 \fBdata_set.c\fP.
 222 .PP
 223 Definition at line 911 of file table_dataset.c.
 224 .SS "NETSNMP_INLINE void netsnmp_table_dataset_add_row (netsnmp_table_data_set * table, netsnmp_table_row * row)"
 225 .PP
 226 adds a new row to a dataset table.
 227 .PP
 228 \fBExamples: \fP
 229 .in +1c
 230 \fBdata_set.c\fP.
 231 .PP
 232 Definition at line 920 of file table_dataset.c.
 233 .SS "NETSNMP_INLINE void netsnmp_table_dataset_delete_all_data (netsnmp_table_data_set_storage * data)"
 234 .PP
 235 deletes all the data from this node and beyond in the linked list.
 236 .PP
 237 Definition at line 956 of file table_dataset.c.
 238 .SS "NETSNMP_INLINE netsnmp_table_data_set_storage* netsnmp_table_dataset_delete_data (netsnmp_table_data_set_storage * data)"
 239 .PP
 240 deletes a single dataset table data.
 241 .PP
 242 returns the (possibly still good) next pointer of the deleted data object.
 243 .PP
 244 Definition at line 943 of file table_dataset.c.
 245 .SS "NETSNMP_INLINE void netsnmp_table_dataset_delete_row (netsnmp_table_row * row)"
 246 .PP
 247 deletes all the data from this node and beyond in the linked list.
 248 .PP
 249 Definition at line 966 of file table_dataset.c.
 250 .SS "NETSNMP_INLINE void netsnmp_table_dataset_remove_and_delete_row (netsnmp_table_data_set * table, netsnmp_table_row * row)"
 251 .PP
 252 removes a row from the table and then deletes it (and all it's data).
 253 .PP
 254 Definition at line 990 of file table_dataset.c.
 255 .SS "NETSNMP_INLINE void netsnmp_table_dataset_remove_row (netsnmp_table_data_set * table, netsnmp_table_row * row)"
 256 .PP
 257 removes a row from the table, but doesn't delete/free anything.
 258 .PP
 259 Definition at line 979 of file table_dataset.c.
 260 .SS "NETSNMP_INLINE void netsnmp_table_dataset_replace_row (netsnmp_table_data_set * table, netsnmp_table_row * origrow, netsnmp_table_row * newrow)"
 261 .PP
 262 adds a new row to a dataset table.
 263 .PP
 264 Definition at line 930 of file table_dataset.c.
 265 .SS "int netsnmp_table_set_add_default_row (netsnmp_table_data_set * table_set, unsigned int column, int type, int writable, void * default_value, size_t default_value_len)"
 266 .PP
 267 adds a new default row to a table_set.
 268 .PP
 269 Arguments should be the table_set, column number, variable type and finally a 1 if it is allowed to be writable, or a 0 if not. If the default_value field is not NULL, it will be used to populate new valuse in that column fro newly created rows. It is copied into the storage template (free your calling argument).
 270 .PP
 271 returns SNMPERR_SUCCESS or SNMPERR_FAILURE
 272 .PP
 273 Definition at line 277 of file table_dataset.c.
 274 .SS "void netsnmp_table_set_add_indexes (va_alist)"
 275 .PP
 276 adds multiple indexes to a table_dataset helper object.
 277 .PP
 278 To end the list, use a 0 after the list of ASN index types.
 279 .PP
 280 Definition at line 1051 of file table_dataset.c.
 281 .SS "void netsnmp_table_set_multi_add_default_row (va_dcl)"
 282 .PP
 283 adds multiple data column definitions to each row.
 284 .PP
 285 Functionally, this is a wrapper around calling netsnmp_table_set_add_default_row repeatedly for you.
 286 .PP
 287 \fBExamples: \fP
 288 .in +1c
 289 \fBdata_set.c\fP.
 290 .PP
 291 Definition at line 1012 of file table_dataset.c.