mfd-readme.m2c

开发snmp的开发包有两个开放的SNMP开发库

########################################################################
## generic include for XXX. Don't use directly.
##
## $Id: mfd-readme.m2c 12091 2005-04-18 22:05:47Z rstory $
########################################################################
@if $m2c_mark_boundary == 1@
/** START code generated by $RCSfile$ $Revision: 12091 $ */
@end@
########################################################################
##
@open ${name}-README-FIRST.txt@
************************************************************************
${name} README
------------------------------------------------------------------------
This document describes the results of the mib2c code generation
system using the mfd code generation template.  The resulting files
are documented both in this README file as well as per-table specific
README files.  All of the files generated by this run of mib2c will
begin with the ${name} prefix.

Quick Start
-----------
For those interested in a quick start, to get a pseudo-todo list, try
this command in directory with the generated code:

 grep -n "TODO:" *.[ch] | sed 's/\([^ ]*\) \(.*\)TODO\(.*\)/\3 (\1)/' | sort -n

Key:
  :o: Optional
  :r: Recommended
  :M: Mandatory
  :A: Advanced users

This will give you and ordered list of places in the code that you
may (or must) take a closer look at).

You may also want to take a look at the on-line tutorial, found here:

    http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mfd/index.html


MIBs For Dummies Overview
-------------------------
The MIBs For Dummies (MFD) configuration files have been written to help
SNMP novices implement SNMP MIBs. This section will be a brief
introduction to some of the general concepts you should be familar with.

  Managed Information Base (MIB)
  ------------------------------
  A SNMP MIB (Managed information base) is a text file that describes the
  syntax for some set of data objects. The MIB creates a correlation
  between an ASCII name for an object and a number OID (Object Identifier).
  The SNMP protocol communicates information using the OIDs, and the MIB
  allows tools to display a name, which we humans find easier to deal with.

  To use an analogy, a MIB is much like a menu at a restaurant. If you've
  ever been to a reataurant and ordered a meal, and later received a bill
  that simply had '#6' on it, you get the idea. The name is easier for
  the customers to remember, and the waiters and chefs use the number for
  efficency.


    Scalars
    -------
    A scalar variable is a unique object in a MIB which can represent
    a single value. For example, the SNMP standard MIB-II defines a
    variable, sysContact.0, which is a string containing the contact
    information for the person in charge of a particular agent. Note
    that scalar variable always end with '.0'.
    

    Rows and Tables
    ---------------
    When a group of related attributes occur more than once, they can be
    grouped together in a table. A table has an index, which uniquely
    identifies a particular row, and data columns, which contain the
    attributes for that row.

    For example, the SNMP standard MIB-II defines a table, ifTable, which
    contains information on the ethernet interfaces on a system.
    

  Data Structures
  ---------------
  The code generated by the MFD configuration files has a few important
  structures.


    The Data Context
    ----------------
    The data context structure should contain the necessary information
    to provide the data for the columns in a given row. As long as you
    can extract the data for a column for the data context, the data context
    can be anything you want: a pointer to an existing structure, the
    parameters needed for a function call or an actual copy of the data.

    By default, a data context structure is generated with storage for
    all the data in a row. Information on changing the default is presented
    later on in this help.


    The MIB Context
    ---------------
    The MIB context structure is generated with storage for all the
    indexes of a table. This data will be used when searching for the
    correct row to process for a request.


    The Row Request Context
    -----------------------
    Each table will have a unique data structure for holding data during
    the processing of a particular row. The row request context contains
    the registration context (that you supply during initilization),
    the data context, the MIB context, the undo context (for settable
    tables) and other data. There is also a netsnmp_data_list, which can
    be used to temporary storage during processing.


    The Table Registration Pointer
    ------------------------------
    During initilization, you may provide a pointer to arbitrary data for
    you own use. This pointer will be saved in the row request context,
    and is passed as a parameter to several functions. It is not required,
    and is provided as a way for you to access table specific data in
    the generated code.



These files are top-level files potentially useful for all the tables: 
------------------------------------------------------------------------

  File    : ${name}_Makefile
  ----------------------------------------------------------------------
  Purpose : Make file for compiling a (sub)agent.  This file is only
            useful if you don't want to compile your code directly
            into the Net-SNMP master agent.
  Editable: Optional
  Usage   : make -f ${name}_Makefile


  File    : ${name}_subagent.c
  ----------------------------------------------------------------------
  Purpose : This file contains a main() function for an agent or
            sub-agent and is compiled using the Makefile above.




Table specific README files
------------------------------------------------------------------------
Each table for which code was generated has its own README file
describing the files specifically associated with each table.  You
should probably read these next:

@foreach $table table@
@    include m2c_setup_table.m2i@
   ${name}-README-${table}.txt
@end@



These are miscellaneous auto-generated code files you generally
shouldn't edit.  They contain code that ties your code together with
the Net-SNMP agent.
------------------------------------------------------------------------
@if $m2c_create_fewer_files == 1@
  File    : ${name}.c
  Purpose : Initilization for the entire module set, including the
            SNMP tables.

@end@
  File    : ${name}.h
  Purpose : Header file for the module set.  Includes config_require
            macros to auto-load the other code pieces when compiled
            into the agent.

@if $m2c_create_fewer_files != 1@
  File    : ${name}_oids.h
  Purpose : C #define definitions of the tables, columns, and OIDs

  File    : ${name}_enums.h
  Purpose : C #define definitions of the enumerated type values for
            each column of each table that requires them.
@else@
  File    : ${name}_constants.h
  Purpose : C #define definitions of the tables, columns, OIDs, enumerated
            type values for each column of each table that requires them.
@end@

  File    : ${name}_interface.c
  Purpose : MFD interface to Net-SNMP.  This auto-generated code ties the
            functions you will fill out to the code that the agent needs.

########################################################################
@foreach $table table@
@    include m2c_setup_table.m2i@
@    open ${name}-README-${table}.txt@
************************************************************************
${context} README
------------------------------------------------------------------------
  This readme file describes the code generated by mib2c (using the MIBs
  for Dummies (MFD) configuration file). The code generated was
  generated specifically for the following SNMP table:

     ${context}

  Your code will be called when the snmp agent receives requests for
  the ${context} table.  The agent will start by looking for the right
  row in your existing data to operate on, if one exists.


  Configuration Variables
  ------------------------------------------------------------
  Some variables used for code generation may be set to affect the code
  generation. You may override these variables by setting them in the
  file ${m2c_defaults_dir}table-${context}.m2d, and then re-running mib2c.

    m2c_table_settable (currently '$m2c_table_settable')
    --------------------------------------------------------
    This variable determines whether or not code is generated to support
    MIB object which have an access of read-write or read-create. The
    default is set based on whether or not the table contains writable
    objects, but can be over-ridden.

    Syntax: @eval $@m2c_table_settable = 0@


    m2c_table_dependencies (currently '$m2c_table_dependencies')
    --------------------------------------------------------
    This variable determines whether or not code is generated to support
    checking dependencies between columns, rows or tables. The default
    is set based on whether or not the table contains writable objects,
    but can be over-ridden.

    Syntax: @eval $@m2c_table_dependencies = 0@


    m2c_table_row_creation (currently '$m2c_table_row_creation')
    --------------------------------------------------------
    This variable determines whether or not code is generated to support
    checking creation of new rows via SNMP. The default is set based on
    whether or not the table contains read-create objects, but can be
    over-ridden.

    Syntax: @eval $@m2c_table_row_creation = 0@


    m2c_context_reg (currently '$m2c_context_reg')
    --------------------------------------------------------
    This variable contains the structure name to typedef for the
    ${context}_registration.

    During initilization, you will provide a pointer to a structure of
    this type. This pointer is used as a parameter to many functions so
    that you have access to your registration data. The default is a
    netsnmp_data_list pointer, which will allow you to keep multiple
    pointers tagged by a text name. If you have a new or existing structure
    you would rather use, you can redefine this variable.
    

    To avoid regenerating code, you may also change this typedef directly
    in the ${table}.h header.

    Syntax: @eval $@m2c_context_reg = "struct my_registration_context@


    m2c_data_context (currently '$m2c_data_context')
    --------------------------------------------------------
    This variable contains the structure name to typedef for the
    ${context}_data.

    This typedef is used in the row request context structure for the table,
    ${context}_rowreq_ctx.

    The typedef in the primary table context will be used for the data and
    undo structure types. This structure should contain all the data
    needed for all the columns in the table. The default is 'generated',
    which will cuase a new data strcuture to be generated with data members
    for each column.

    To avoid regenerating code, you may also change this typedef directly
    in the ${table}.h header.

    Syntax: @eval $@m2c_data_context = "struct my_data_context"@


    m2c_data_allocate (currently '$m2c_data_allocate')
    --------------------------------------------------------
    This variable determines whether or not the data context (see above)
    requires memory to be allocated. The default generated data structure
    does not. If you are using a custom data context which needs to
    allocate memory, override this value and two additional functions
    will be generated:

      ${context}_allocate_data
      ${context}_release_data

    Syntax: @eval $@m2c_data_allocate = 1@


    m2c_data_init (currently '$m2c_data_init')
    --------------------------------------------------------
    This variable determines whether or not the data context (see above)
    or any other items you have added to the table context requires
    initialization. The default generated data structure does not. If you
    are using a custom data context or have added items needing initialization
    to the table context, override this value and two additional functions
    will be generated:

      ${context}_rowreq_ctx_init
      ${context}_rowreq_ctx_cleanup

    Syntax: @eval $m2c_data_init = 1@


    m2c_table_access (currently '$m2c_table_access')
    ------------------------------------------------------------------
    This variable determines which data interface will be use to generate
    code for looking up data for a given index. The default is the
    'container-cached' access code, which caches the data in a netsnmp-
    container (usually a sorted array).

    Available options can be determined by checking for mib2c configuration
    files that begin with 'mfd-access-*'.

    Syntax: @eval $@m2c_table_access = '$m2c_table_access'@

 
    m2c_include_examples (currently '$m2c_include_examples')
    ------------------------------------------------------------------
    This variable determines whether or not to generate example code. The
    default is to generate example code.

    Syntax: @eval $@m2c_include_examples = 0@


    m2c_data_transient (currently '$m2c_data_transient')
    ------------------------------------------------------------------
    This variable determines how the generated example code deals with the
    data during data lookup. See the table readme file for details on how
    the current table access method interprets this value. In general,
    a value of 0 indicates persistent data, 1 indicates semi-transient and
    2 indicates transient data.

    Syntax: @eval $@m2c_data_transient = 0@


 Index(es) for the ${context} table
  ------------------------------------------------------------
  The index(es) for the ${context} table are:

@foreach $node index@
@    include m2c_setup_node.m2i@
     $node:
        Syntax:      $node.syntax
        DataType:    $node.perltype
        ASN type:    $node.type
        C-code type: $m2c_decl
@end@ # foreach

  You should know how to set all these values from your data context,
  ${context}_data.


************************************************************************
${context} File Overview
------------------------------------------------------------------------
  Several files have been generated to implement the ${context}
  table. We'll go through these files, one by one, explaining each and
  letting you know which you need to edit.


File: ${name}_data_access.[c|h]
------------------------------------------------------------------------
  The ${name}_data_access file contains the interface to your data in
  its raw format.  These functions are used to build the row cache or 
  locate the row (depending on the table access method).

  Set MIB context
  -----------------
  TODO : Set MIB index values
  FUNC : ${context}_indexes_set
  WHERE: ${context}_data_access.c

  This is a convenience function for setting the index context from
  the native C data. Where necessary, value mapping should be done.

@if $mfd_readme_verbose == 1@
  This function should update the table index values (found in
  tbl_idx) for the given raw data.

@end@
  
@    eval $m2c_processing_type = 'r'@
@    include mfd-access-${m2c_table_access}-defines.m2i@


@if $m2c_create_fewer_files != 1@
File: ${name}_enums.h
@else@
File: ${name}_constants.h
@end@
------------------------------------------------------------------------
  This file contains macros for mapping enumeration values when the
  enumerated values defined by the MIB do not match the values used
  internally.

  Review this file to see if any values need to be updated.


@if $m2c_create_fewer_files != 1@
File: ${name}_data_get.c
@else@
File: ${name}.c; GET support
@end@
------------------------------------------------------------------------
@    if ("$m2c_data_allocate" eq "yes") && ("$m2c_data_context" ne "generated")@
  Allocate data context
  ---------------------
  TODO : allocate memory for a data context
  FUNC : ${context}_allocate_data

  This function will be called to allocate memory for a data context
  when a new row request context is being created, or to create an