SNMP编程

开发平台：
Unix_Linux

netsnmp_read_config.3：源码内容
							.TH "parsing various configuration files at run time" 3 "28 Nov 2005" "Version 5.2.1.rc3" "net-snmp" " -*- nroff -*-
.ad l
.nh
.SH NAME
parsing various configuration files at run time - The read_config related functions are a fairly extensible system of parsing various configuration files at the run time.  
.PP
.SS "Defines"
.in +1c
.ti -1c
.RI "#define fBSNMP_CONFIG_DELIMETERSfP   ' \t='"
.br
.in -1c
.SS "Functions"
.in +1c
.ti -1c
.RI "fBconfig_linefP * fBregister_prenetsnmp_mib_handlerfP (const char *type, const char *token, void(*parser)(const char *, char *), void(*releaser)(void), const char *help)"
.br
.ti -1c
.RI "fBconfig_linefP * fBregister_app_prenetsnmp_mib_handlerfP (const char *token, void(*parser)(const char *, char *), void(*releaser)(void), const char *help)"
.br
.ti -1c
.RI "fBconfig_linefP * fBregister_config_handlerfP (const char *type_param, const char *token, void(*parser)(const char *, char *), void(*releaser)(void), const char *help)"
.br
.RI "fIregister_config_handler registers handlers for certain tokens specified in certain types of files. fP"
.ti -1c
.RI "fBconfig_linefP * fBregister_app_config_handlerfP (const char *token, void(*parser)(const char *, char *), void(*releaser)(void), const char *help)"
.br
.ti -1c
.RI "void fBunregister_config_handlerfP (const char *type_param, const char *token)"
.br
.RI "fIuregister_config_handler un-registers handlers given a specific type_param and token. fP"
.ti -1c
.RI "void fBunregister_app_config_handlerfP (const char *token)"
.br
.ti -1c
.RI "void fBunregister_all_config_handlersfP ()"
.br
.ti -1c
.RI "fBconfig_linefP * fBread_config_get_handlersfP (const char *type)"
.br
.ti -1c
.RI "void fBread_config_with_type_whenfP (const char *filename, const char *type, int when)"
.br
.ti -1c
.RI "void fBread_config_with_typefP (const char *filename, const char *type)"
.br
.ti -1c
.RI "fBconfig_linefP * fBread_config_find_handlerfP (struct fBconfig_linefP *line_handlers, const char *token)"
.br
.ti -1c
.RI "int fBrun_config_handlerfP (struct fBconfig_linefP *lptr, const char *token, char *cptr, int when)"
.br
.ti -1c
.RI "int fBsnmp_config_whenfP (char *line, int when)"
.br
.ti -1c
.RI "int fBnetsnmp_configfP (char *line)"
.br
.ti -1c
.RI "void fBnetsnmp_config_remember_in_listfP (char *line, struct fBread_config_memoryfP **mem)"
.br
.ti -1c
.RI "void fBnetsnmp_config_remember_free_listfP (struct fBread_config_memoryfP **mem)"
.br
.ti -1c
.RI "void fBnetsnmp_config_process_memory_listfP (struct fBread_config_memoryfP **memp, int when, int clear)"
.br
.ti -1c
.RI "void fBnetsnmp_config_rememberfP (char *line)"
.br
.ti -1c
.RI "void fBnetsnmp_config_process_memoriesfP (void)"
.br
.ti -1c
.RI "void fBnetsnmp_config_process_memories_whenfP (int when, int clear)"
.br
.ti -1c
.RI "void fBread_configfP (const char *filename, struct fBconfig_linefP *line_handler, int when)"
.br
.ti -1c
.RI "void fBfree_configfP (void)"
.br
.ti -1c
.RI "void fBread_configs_optionalfP (const char *optional_config, int when)"
.br
.ti -1c
.RI "void fBread_configsfP (void)"
.br
.ti -1c
.RI "void fBread_premib_configsfP (void)"
.br
.ti -1c
.RI "void fBset_configuration_directoryfP (const char *dir)"
.br
.ti -1c
.RI "const char * fBget_configuration_directoryfP ()"
.br
.ti -1c
.RI "void fBset_persistent_directoryfP (const char *dir)"
.br
.ti -1c
.RI "const char * fBget_persistent_directoryfP ()"
.br
.ti -1c
.RI "void fBset_temp_file_patternfP (const char *pattern)"
.br
.ti -1c
.RI "const char * fBget_temp_file_patternfP ()"
.br
.ti -1c
.RI "void fBread_config_filesfP (int when)"
.br
.ti -1c
.RI "void fBread_config_print_usagefP (const char *lead)"
.br
.ti -1c
.RI "void fBread_config_storefP (const char *type, const char *line)"
.br
.RI "fIread_config_store intended for use by applications to store permenant configuration information generated by sets or persistent counters. fP"
.ti -1c
.RI "void fBread_app_config_storefP (const char *line)"
.br
.ti -1c
.RI "void fBsnmp_save_persistentfP (const char *type)"
.br
.ti -1c
.RI "void fBsnmp_clean_persistentfP (const char *type)"
.br
.ti -1c
.RI "void fBconfig_perrorfP (const char *str)"
.br
.ti -1c
.RI "void fBconfig_pwarnfP (const char *str)"
.br
.ti -1c
.RI "char * fBskip_whitefP (char *ptr)"
.br
.ti -1c
.RI "char * fBskip_not_whitefP (char *ptr)"
.br
.ti -1c
.RI "char * fBskip_tokenfP (char *ptr)"
.br
.ti -1c
.RI "char * fBcopy_nwordfP (char *from, char *to, int len)"
.br
.ti -1c
.RI "char * fBcopy_wordfP (char *from, char *to)"
.br
.ti -1c
.RI "char * fBread_config_save_octet_stringfP (char *saveto, u_char *str, size_t len)"
.br
.ti -1c
.RI "char * fBread_config_read_octet_stringfP (char *readfrom, u_char **str, size_t *len)"
.br
.ti -1c
.RI "char * fBread_config_save_objidfP (char *saveto, oid *objid, size_t len)"
.br
.ti -1c
.RI "char * fBread_config_read_objidfP (char *readfrom, oid **objid, size_t *len)"
.br
.ti -1c
.RI "char * fBread_config_read_datafP (int type, char *readfrom, void *dataptr, size_t *len)"
.br
.RI "fIread_config_read_data reads data of a given type from a token(s) on a configuration line. fP"
.ti -1c
.RI "char * fBread_config_read_memoryfP (int type, char *readfrom, char *dataptr, size_t *len)"
.br
.ti -1c
.RI "char * fBread_config_store_datafP (int type, char *storeto, void *dataptr, size_t *len)"
.br
.RI "fIread_config_store_data stores data of a given type to a configuration line into the storeto buffer. fP"
.ti -1c
.RI "char * fBread_config_store_data_prefixfP (char prefix, int type, char *storeto, void *dataptr, size_t len)"
.br
.in -1c
.SS "Variables"
.in +1c
.ti -1c
.RI "fBconfig_filesfP * fBconfig_filesfP = NULL"
.br
.ti -1c
.RI "int fBlinecountfP"
.br
.ti -1c
.RI "const char * fBcurfilenamefP"
.br
.in -1c
.SH "Detailed Description"
.PP 
The read_config related functions are a fairly extensible system of parsing various configuration files at the run time. 
.PP
The idea is that the calling application is able to register handlers for certain tokens specified in certain types of files. The read_configs function can then be called to look for all the files that it has registrations for, find the first word on each line, and pass the remainder to the appropriately registered handler.
.PP
For persistent configuration storage you will need to use the read_config_read_data, read_config_store, and read_config_store_data APIs in conjunction with first registering a callback so when the agent shutsdown for whatever reason data is written to your configuration files. The following explains in more detail the sequence to make this happen.
.PP
This is the callback registration API, you need to call this API with the appropriate parameters in order to configure persistent storage needs.
.PP
int snmp_register_callback(int major, int minor, SNMPCallback *new_callback, void *arg);
.PP
You will need to set major to SNMP_CALLBACK_LIBRARY, minor to SNMP_CALLBACK_STORE_DATA. arg is whatever you want.
.PP
Your callback function's prototype is: int (SNMPCallback) (int majorID, int minorID, void *serverarg, void *clientarg);
.PP
The majorID, minorID and clientarg are what you passed in the callback registration above. When the callback is called you have to essentially transfer all your state from memory to disk. You do this by generating configuration lines into a buffer. The lines are of the form token followed by token parameters.
.PP
Finally storing is done using read_config_store(type, buffer); type is the application name this can be obtained from:
.PP
netsnmp_ds_get_string(NETSNMP_DS_LIBRARY_ID, NETSNMP_DS_LIB_APPTYPE);
.PP
Now, reading back the data: This is done by registering a config handler for your token using the register_config_handler function. Your handler will be invoked and you can parse in the data using the read_config_read APIs.
.SH "Function Documentation"
.PP 
.SS "char* read_config_read_data (int type, char * readfrom, void * dataptr, size_t * len)"
.PP
read_config_read_data reads data of a given type from a token(s) on a configuration line. 
.PP
The supported types are:
.PP
.IP "(bu" 2
ASN_INTEGER
.IP "(bu" 2
ASN_TIMETICKS
.IP "(bu" 2
ASN_UNSIGNED
.IP "(bu" 2
ASN_OCTET_STR
.IP "(bu" 2
ASN_BIT_STR
.IP "(bu" 2
ASN_OBJECT_ID
.PP
.PP
fBParameters:fP
.RS 4
fItypefP the asn data type to be read in.
.br
fIreadformfP the configuration line data to be read.
.br
fIdataptrfP an allocated pointer expected to match the type being read (int *, u_int *, char **, oid **)
.br
fIlenfP is the length of an asn oid or octet/bit string, not required for the asn integer, unsigned integer, and timeticks types
.RE
.PP
fBReturns:fP
.RS 4
the next token in the configuration line. NULL if none left or if an unknown type.
.RE
.PP
.PP
Definition at line 1745 of file read_config.c.
.PP
References NULL, read_config_read_objid(), read_config_read_octet_string(), and skip_token().
.PP
Referenced by netsnmp_read_data_callback().
.SS "void read_config_store (const char * type, const char * line)"
.PP
read_config_store intended for use by applications to store permenant configuration information generated by sets or persistent counters. 
.PP
Appends line to a file named either ENV(SNMP_PERSISTENT_FILE) or '<PERSISTENT_DIRECTORY>/<type>.conf'. Adds a trailing newline to the stored file if necessary.
.PP
fBParameters:fP
.RS 4
fItypefP is the application name 
.br
fIlinefP is the configuration line written to the application name's configuration file
.RE
.PP
fBReturns:fP
.RS 4
void
.RE
.PP
.PP
Definition at line 1203 of file read_config.c.
.PP
References get_persistent_directory(), netsnmp_ds_get_boolean(), netsnmp_getenv(), NULL, and snmp_log().
.PP
Referenced by netsnmp_oid_stash_store(), netsnmp_save_all_data(), read_app_config_store(), and snmp_save_persistent().
.SS "char* read_config_store_data (int type, char * storeto, void * dataptr, size_t * len)"
.PP
read_config_store_data stores data of a given type to a configuration line into the storeto buffer. 
.PP
Calls read_config_store_data_prefix with the prefix parameter set to a char space. The supported types are:
.PP
.IP "(bu" 2
ASN_INTEGER
.IP "(bu" 2
ASN_TIMETICKS
.IP "(bu" 2
ASN_UNSIGNED
.IP "(bu" 2
ASN_OCTET_STR
.IP "(bu" 2
ASN_BIT_STR
.IP "(bu" 2
ASN_OBJECT_ID
.PP
.PP
fBParameters:fP
.RS 4
fItypefP the asn data type to be stored
.br
fIstoretofP a pre-allocated char buffer which will contain the data to be stored
.br
fIdataptrfP contains the value to be stored, the supported pointers: (int *, u_int *, char **, oid **)
.br
fIlenfP is the length of the pre-allocated storeto buffer, not required for the asn integer, unsigned integer, and timeticks types.
.RE
.PP
fBReturns:fP
.RS 4
character pointer to the end of the line. NULL if an unknown type.
.RE
.PP
.PP
Definition at line 1873 of file read_config.c.
.PP
References read_config_store_data_prefix().
.SS "struct fBconfig_linefP* register_config_handler (const char * type_param, const char * token, void(*)(const char *, char *) parser, void(*)(void) releaser, const char * help)"
.PP
register_config_handler registers handlers for certain tokens specified in certain types of files. 
.PP
Allows a module writer use/register multiple configuration files based off of the type parameter. A module writer may want to set up multiple configuration files to separate out related tasks/variables or just for management of where to put tokens as the module or modules get more complex in regard to handling token registrations.
.PP
fBParameters:fP
.RS 4
fItypefP the configuration file used, e.g., if snmp.conf is the file where the token is located use 'snmp' here. If NULL the configuration file used will be snmpd.conf.
.br
fItokenfP the token being parsed from the file. Must be non-NULL.
.br
fIparserfP the handler function pointer that use the specified token and the rest of the line to do whatever is required Should be non-NULL in order to make use of this API.
.br
fIreleaserfP if non-NULL, the function specified is called if and when the configuration files are re-read. This function should free any resources allocated by the token handler function.
.br
fIhelpfP if non-NULL, used to display help information on the expected arguments after the token.
.RE
.PP
fBReturns:fP
.RS 4
Pointer to a new config line entry or NULL on error.
.RE
.PP
.PP
Definition at line 196 of file read_config.c.
.PP
References netsnmp_ds_get_string(), NULL, and register_config_handler().
.PP
Referenced by netsnmp_ds_register_config(), netsnmp_register_save_list(), register_app_config_handler(), register_config_handler(), register_mib_handlers(), and register_prenetsnmp_mib_handler().
.SS "void unregister_config_handler (const char * type_param, const char * token)"
.PP
uregister_config_handler un-registers handlers given a specific type_param and token. 
.PP
fBParameters:fP
.RS 4
fItype_paramfP the configuration file used where the token is located. Used to lookup the config file entry
.br
fItokenfP the token that is being unregistered
.RE
.PP
fBReturns:fP
.RS 4
void
.RE
.PP
.PP
Definition at line 301 of file read_config.c.
.PP
References netsnmp_ds_get_string(), config_line::next, NULL, SNMP_FREE, and unregister_config_handler().
.PP
Referenced by netsnmp_ds_shutdown(), unregister_all_config_handlers(), unregister_app_config_handler(), and unregister_config_handler().

						