SecuritySNACCRuntime/c++-examples/snmp/README

   1 (RCS control information is at the end of this file.)
   2
   3
   4 C++ SNMP Example - Mike Sample Mar 92
   5 ---------------------------------
   6
   7 This example illustrates a few more features of the compiler than the
   8 simple example.  It also shows some deficiencies.  No executable
   9 programs are generated by the makefile, it only generates the snmp
  10 code and compiles it without linking.
  11
  12 This directory contains 2 files:
  13         README
  14         makefile
  15
  16 Snacc generates source from the following ASN.1 files:
  17         .../asn1specs/rfc1155-smi.asn1
  18         .../asn1specs/rfc1157-snmp.asn1
  19         .../asn1specs/rfc1213-mib2.asn1
  20
  21 multi-module compilation
  22    The IMPORT/EXPORT mechanisms of ASN.1 '88 are supported so you don't
  23    have to dump all of the ASN.1 definitions into a single file
  24    The order of the ASN.1 file arguments is the order that they
  25    are included in the generated source files.  For example:
  26
  27    %1 snacc rfc1155-smi.asn1 rfc1157-snmp.asn1 rfc1213-mib2.asn1
  28
  29    causes the order in which hdr files are included in rfc1213-mib2.C
  30    to be:
  31
  32    #include "asn-incl.h"
  33    #include "rfc1155-smi.h"
  34    #include "rfc1157-snmp.h"
  35    #include "rfc1213-mib2.h"
  36
  37
  38     Currently, snacc assumes that each ASN.1 file given on the command
  39     line depends on all of the others on the command line.  There is
  40     no attempt to compute the dependencies via the import lists alone.
  41
  42 SNMP OBJECT-TYPE macro parsing / ANY type hash table
  43    The SNMP OBJECT-TYPE macro is parsed.   This results in the
  44    type in the "SYNTAX" part of the macro is put into
  45    the ANY type hash table using the  OBJECT-TYPE macro's value as the
  46    hash key.  Also if the type in the SYNTAX field is not defined
  47    outsided of the macro (could be different tagging etc), a proper
  48    type definition is generated for it.  If you want to change the way
  49    the macro is handled, modify the corresponding routine in "do_macros.c".
  50
  51 value definitions
  52    The OBJECT IDENTIFIER values are turned into statically initialized
  53    C++ values and included in the generated source and include file.  This
  54    is also done for INTEGER and BOOLEAN values.  More complex values
  55    are ignored by the compiler at the moment. (modify parse_vals.c if
  56    you want to improve this)
  57
  58
  59 -P option of snacc is demonstrated
  60    The ASN.1 for the parsed modules is generated from the internal data
  61    structure.  This can be useful for making sure the compiler is
  62    handling your ASN.1 files correctly.  It is also useful to see how
  63    the types are modified and sorted to simplify code generation.
  64    (see the file snacc.output after typeing "make")
  65
  66 Deficiencies
  67    A deficiency in parsing large integers is shown when parsing the
  68    following rfc 1155 types:
  69
  70                   Counter ::=
  71                       [APPLICATION 1]
  72                           IMPLICIT INTEGER (0..4294967295)
  73
  74                   Gauge ::=
  75                       [APPLICATION 2]
  76                           IMPLICIT INTEGER (0..4294967295)
  77
  78                   TimeTicks ::=
  79                       [APPLICATION 3]
  80                           IMPLICIT INTEGER (0..4294967295)
  81
  82 Due the size of a C long int the above ASN.1 is represented internally as:
  83
  84 Counter ::= [APPLICATION 1] IMPLICIT INTEGER (0..-1)
  85
  86 Gauge ::= [APPLICATION 2] IMPLICIT INTEGER (0..-1)
  87
  88 TimeTicks ::= [APPLICATION 3] IMPLICIT INTEGER (0..-1)
  89
  90 The ASN.1 library contains routines for encoding/decoding unsigned
  91 long integers but you must hand code the cases where it is used - the
  92 compiler never generates code that calls them.
  93
  94 Note also that the produced code for the SNMP ASN.1 must be modified
  95 to correclty handle the "Opaque" data type.  SNMP does not use the ANY
  96 DEFINED BY type in an effort to simplify things.  Instead an OCTET
  97 STRING is used to hold and encoded value whose type is defined by an
  98 OBJECT IDENTIFIER.  With some simple modifications you can use the
  99 snacc AsnAnyDefinedBy type instead of the OCTET STRING to achieve
 100 the desired results.
 101
 102 This should underline the danger of blindly trusting the compiler to
 103 do the right thing for protocols such as SNMP or X.500 where the type
 104 of an encoded value depends on a mechanism outside of ASN.1 or the ANY
 105 type (ANY DEFINED BY types should work automatically).
 106
 107 There is a problem when generating C++ code with the SNMP ASN.1 files.
 108 Several of the ASN.1 value names conflict with C++ keywords.  The
 109 generated code will not compile properly as a result.  The best way to
 110 fix these is to modify the ASN.1 files directly.  The compiler will
 111 munge field or type names to avoid conflicts with the target language
 112 but currently does not check value names.  The SNMP ASN.1 module shows
 113 this problem the with value "private" in rfc1155-smi.asn1.
 114
 115 #-------------------------------------------------------------------------------
 116 # $Header: /cvs/root/Security/SecuritySNACCRuntime/c++-examples/snmp/Attic/README,v 1.1.1.1 2001/05/18 23:14:05 mb Exp $
 117 # $Log: README,v $
 118 # Revision 1.1.1.1  2001/05/18 23:14:05  mb
 119 # Move from private repository to open source repository
 120 #
 121 # Revision 1.1.1.1  1999/03/16 18:05:58  aram
 122 # Originals from SMIME Free Library.
 123 #
 124 # Revision 1.3  1995/07/27 11:36:13  rj
 125 # 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.
 126 #
 127 # Revision 1.2  1995/07/24  15:41:22  rj
 128 # changed `_' to `-' in file names.
 129 #
 130 # Revision 1.1  1994/08/31  08:48:13  rj
 131 # first check-in. for a list of changes to the snacc-1.1 distribution please refer to the ChangeLog.
 132 #