(RCS control information is at the end of this file.)


C++ SNMP Example - Mike Sample Mar 92
---------------------------------

This example illustrates a few more features of the compiler than the
simple example.  It also shows some deficiencies.  No executable
programs are generated by the makefile, it only generates the snmp
code and compiles it without linking.

This directory contains 2 files:
        README
        makefile

Snacc generates source from the following ASN.1 files:
        .../asn1specs/rfc1155-smi.asn1
        .../asn1specs/rfc1157-snmp.asn1
        .../asn1specs/rfc1213-mib2.asn1

multi-module compilation
   The IMPORT/EXPORT mechanisms of ASN.1 '88 are supported so you don't
   have to dump all of the ASN.1 definitions into a single file
   The order of the ASN.1 file arguments is the order that they
   are included in the generated source files.  For example:

   %1 snacc rfc1155-smi.asn1 rfc1157-snmp.asn1 rfc1213-mib2.asn1

   causes the order in which hdr files are included in rfc1213-mib2.C
   to be:

   #include "asn-incl.h"
   #include "rfc1155-smi.h"
   #include "rfc1157-snmp.h"
   #include "rfc1213-mib2.h"


    Currently, snacc assumes that each ASN.1 file given on the command
    line depends on all of the others on the command line.  There is
    no attempt to compute the dependencies via the import lists alone.

SNMP OBJECT-TYPE macro parsing / ANY type hash table
   The SNMP OBJECT-TYPE macro is parsed.   This results in the
   type in the "SYNTAX" part of the macro is put into
   the ANY type hash table using the  OBJECT-TYPE macro's value as the
   hash key.  Also if the type in the SYNTAX field is not defined
   outsided of the macro (could be different tagging etc), a proper
   type definition is generated for it.  If you want to change the way
   the macro is handled, modify the corresponding routine in "do_macros.c".

value definitions
   The OBJECT IDENTIFIER values are turned into statically initialized
   C++ values and included in the generated source and include file.  This
   is also done for INTEGER and BOOLEAN values.  More complex values
   are ignored by the compiler at the moment. (modify parse_vals.c if
   you want to improve this)


-P option of snacc is demonstrated
   The ASN.1 for the parsed modules is generated from the internal data
   structure.  This can be useful for making sure the compiler is
   handling your ASN.1 files correctly.  It is also useful to see how
   the types are modified and sorted to simplify code generation.
   (see the file snacc.output after typeing "make")

Deficiencies
   A deficiency in parsing large integers is shown when parsing the
   following rfc 1155 types:

                  Counter ::=
                      [APPLICATION 1]
                          IMPLICIT INTEGER (0..4294967295)

                  Gauge ::=
                      [APPLICATION 2]
                          IMPLICIT INTEGER (0..4294967295)

                  TimeTicks ::=
                      [APPLICATION 3]
                          IMPLICIT INTEGER (0..4294967295)

Due the size of a C long int the above ASN.1 is represented internally as:

Counter ::= [APPLICATION 1] IMPLICIT INTEGER (0..-1)

Gauge ::= [APPLICATION 2] IMPLICIT INTEGER (0..-1)

TimeTicks ::= [APPLICATION 3] IMPLICIT INTEGER (0..-1)

The ASN.1 library contains routines for encoding/decoding unsigned
long integers but you must hand code the cases where it is used - the
compiler never generates code that calls them.

Note also that the produced code for the SNMP ASN.1 must be modified
to correclty handle the "Opaque" data type.  SNMP does not use the ANY
DEFINED BY type in an effort to simplify things.  Instead an OCTET
STRING is used to hold and encoded value whose type is defined by an
OBJECT IDENTIFIER.  With some simple modifications you can use the
snacc AsnAnyDefinedBy type instead of the OCTET STRING to achieve
the desired results.

This should underline the danger of blindly trusting the compiler to
do the right thing for protocols such as SNMP or X.500 where the type
of an encoded value depends on a mechanism outside of ASN.1 or the ANY
type (ANY DEFINED BY types should work automatically).

There is a problem when generating C++ code with the SNMP ASN.1 files.
Several of the ASN.1 value names conflict with C++ keywords.  The
generated code will not compile properly as a result.  The best way to
fix these is to modify the ASN.1 files directly.  The compiler will
munge field or type names to avoid conflicts with the target language
but currently does not check value names.  The SNMP ASN.1 module shows
this problem the with value "private" in rfc1155-smi.asn1.

#-------------------------------------------------------------------------------
# $Header: /cvs/Darwin/src/live/Security/SecuritySNACCRuntime/c++-examples/snmp/README,v 1.1.1.1 2001/05/18 23:14:05 mb Exp $
# $Log: README,v $
# Revision 1.1.1.1  2001/05/18 23:14:05  mb
# Move from private repository to open source repository
#
# Revision 1.1.1.1  1999/03/16 18:05:58  aram
# Originals from SMIME Free Library.
#
# Revision 1.3  1995/07/27 11:36:13  rj
# rfc1155-smi.asn1, rfc1157-snmp.asn1 and rfc1213-mib2.asn1 renamed from 1155-smi.asn1, 1157-snmp.asn1 and 1213-mib2.asn1 to accomodate to snacc's new file name generation scheme.
#
# Revision 1.2  1995/07/24  15:41:22  rj
# changed `_' to `-' in file names.
#
# Revision 1.1  1994/08/31  08:48:13  rj
# first check-in. for a list of changes to the snacc-1.1 distribution please refer to the ChangeLog.
#
