This file contains release notes on the latest release of the ASN1C compiler (version 7.1.x).
Thank you for downloading this release of the ASN1C software. ASN1C is an ASN.1 compiler (code generator) capable of parsing and generating C, C++, C#, or Java source code for the most advanced ASN.1 syntax.This package contains the ASN1C compiler executables and run-time libraries. Documentation is available online at http://www.obj-sys.com/support/asn1c-manuals.php
This release of ASN1C adds the following new capabilities:
- Support added for OER in Java and C#
The capability to generate encoders and decoders for the Octet Encoding Rules (OER) in Java and C# languages has been added. The capability existed previously to generate C/C++ code for these rules. Generated code now supports the ITU-T X.696 standard by default, although it is still possible to code conforming to the original NTCIP standard.
- Support added for Canonical OER
The capability to generate code to support Canonical OER in all languages has been added.
- Generation of C/C++ code to better support 64-bit architectures
Improvements were made in the run-time and code generator for C/C++ to better support 64-bit architectures. This involved adding a new option (-x64) to allow this type of generation to be turned on so as not to affect backward compatibility with existing code bases. The primary change was to use the built-in size type (size_t) for size-related variables rather than a signed or unsigned 32-bit integer.
- Improved support for ISO date/time C/C++ code generation for BER
The generated C/C++ code for BER for ISO date/time types was updated to do full validation of the formats used in these types. Previously, the contents of the fields were not checked and were encoded as simple string values.
- Support for character string types as default values
Previously character string default values were considered to be complex and an optional bit mask flag was used to signal presense or absense. The value itself is now checked to determine if the default value is used. On decode, the structure is populated with value if not present in the encoded data.
- gcc 6.x libraries added to Linux distributions
Libraries built with gcc v6.x are now included in Linux distributions. The default libraries continue to use gcc 4.x and optional libraries built with gcc 5 and 6 are included in the packages.
- The handling of character string and time elements having a DEFAULT value has changed. We now treat these like other types and do, or do not, encode them as appropriate, which should not be an issue for users. However, we also no longer generate a "presence" flag for such elements in the generated C/C++ data structures, since such elements are thought of as always being present. User code that sets the presence flag for such elements will need to be updated.
- The Java and C# class used for certain TIME types has changed from Asn1VisibleString to Asn1Time. This was necessary to correct the BER encoding of TIME types. User code will need to be changed to use the new class name rather than the old one (when used for TIME types).
- The handling of extension groups for Java and C# has changed slightly. In previous versions, depending on the selected encoding rules, we did not always generate extension group presence flags (e.g. mV2ExtPresent). These flags should now always be generated regardless of the encoding rules. When populating data structures for encoding, be sure to set the appropriate extension group presence flag whenever extension elements that are in an extension group are populated; otherwise, the extension element will not be encoded.
- C/C++ type changes for 64-bit support. In general, type changes for 64-bit support are done when the new -x64 option is specified. However, it was found to be impractical in all cases to do this and users may notice some changes to the ABI on 64-bit systems due to theses changes (32-bit should not be affected).
Documentation for this release is available online at the following URL:
The steps to install ASN1C on a Windows system are as follows:
- Download the ASN1C SDK which contains the compiler (code generator) and run-times for C/C++, Java, and C#. The C/C++ run-time contains libraries built with the Microsoft Visual Studio 2010, 2012, 2013 and 2015 compilers, the Cygwin gcc compiler, and the Minimalist GNU for Windows (MinGW) compiler.
- ASN1C for Windows is packaged in a self-extracting executable file format. To install, all that is necessary is to double-click the file after downloading and then following the setup wizard instructions from that point.
- After installation is complete, the license for the product must be installed. This can come in two forms - as a license file or a license key value:
- If a license file was provided either on the user's download page or as an E-mail attachment, this file should be copied to the same directory that the ASN1C compiler executable file is located in. This is in the bin subdirectory located under the top-level install directory.
- Alternately, a license key value may have been provided for product activation. This can be used either through the GUI interface by following the on-screen instructions, or by running ASN1C from the command-line using the -lickey switch.
The compiler should now be operational. The following command can be executed:
<rootdir>\bin\asn1cto verify operation.
The following subdirectories contain the following files (note: <installdir> refers to the installation directory that was specified during the installation process):Base Compiler Package
- <installdir>\bin\asn1c.exe
The command-line compiler executable file. This is invoked on ASN.1 or XSD source files to generate C, C++, C#, or Java encode/decode classes and functions. It is recommended you modify your PATH environment variable to include <installdir>\bin to allow the compiler executable to be run from anywhere.
- <installdir>\bin\acgui.exe
The compiler graphic user interface (GUI) wizard executable file. This GUI guides a user through the process of specifying ASN.1 or XSD source files and options. This is the program invoked from the start menu or desktop icon.
- <installdir>\bin\asn2xsd.exe
ASN.1 to XML Schema (XSD) translation tool.
- <installdir>\bin\berfdump.exe
<installdir>\bin\ber2def.exe
<installdir>\bin\ber2indef.exeUtility programs for operating on BER-encoded files. The first program allows a file to be dumped in a human-readable format. The other two utilities convert files from the use of indefinite to definite length encoding and vice-versa.
- <installdir>\bin\dumpasn1.exe
A public-domain ASN.1 BER/DER encoded data dump tool. Thanks to Peter Gutmann for making this available for public use. The full source code for this program can be found in the utils subdirectory of the installation.
- <installdir>\bin\xsd2asn1.exe
XSD-to-ASN.1 translation program executable file. This program translates an XSD file to its ASN.1 equivalent as per the ITU-T X.694 standard.
- <installdir>\doc
This directory contains documentation files. Note that the bulk of the documentation items are now available online (see the Documentation section above).
- <installdir>\scripts
This directory contains Perl script files for doing source code editing and other transformations. The rtport.pl script is included in this release to port existing C/C++ applications that use ASN1C generated code from version 5.8 or lower to be compatible with the latest release of the product.
- <installdir>\specs
This directory contains ASN.1 specifications from many standards that have been pre-compiled and tested. In some cases, syntax errors that may have existed in the original standards were fixed.
- <installdir>\utils
This directory contains the source code and build makefile for some of the utility programs included in the bin subdirectory.
- <installdir>\xsd\lib\asn1.xsd
This directory contains the common XML schema definitions (XSD) library. This contains type mappings for built-in ASN.1 types that do not have an equivalent types defined in XSD.
- <installdir>\xsd\sample
This directory contains sample programs related to the conversion of ASN.1 to XML Schema. It also contains the XSD.asn ASN.1 specification which contains the XSD ASN.1 module that is sometimes referenced in ASN.1 files that are the result of an XSD-to-ASN.1 translation.
C/C++ run-time libraries and source files
- <installdir>\c\lib\* (Visual C++ 2013 libraries)
- <installdir>\c_vs2010\lib\* (Visual C++ 2010 libraries)
- <installdir>\c_vs2012\lib\* (Visual C++ 2012 libraries
- <installdir>\c_vs2015\lib\* (Visual C++ 2015 libraries
- <installdir>\c_gnu\lib\*.a (Cygwin GNU gcc)
- <installdir>\c_mingw\lib\*.a (MinGW gcc)
The ASN1C C run-time library files. These contain low-level run-time functions for the various encoding rules supported by ASN1C. For each encoding rules type, there is a dynamic link library (.dll) and standard library file (.lib) for linking with the DLL. There is also a static library for direct linkage to the object modules (this is the library file with the '_a.lib' suffix). The licensed version of the product also contains a DLL-ready library (compiled with -MD option) for building your own value-added DLL's. Also note that the evaluation and development libraries are not fully optimized (they contain diagnostic tracing and are not compiled with compiler optimization turned on). The deployment libraries are fully optimized.
- <installdir>\cpp\lib\* (Visual C++ 2013 libraries)
- <installdir>\cpp_vs2010\lib\* (Visual C++ 2010 libraries)
- <installdir>\cpp_vs2012\lib\* (Visual C++ 2012 libraries
- <installdir>\cpp_vs2015\lib\* (Visual C++ 2015 libraries
- <installdir>\cpp_gnu\lib\*.a (Cygwin GNU g++)
- <installdir>\cpp_mingw\lib\*.a (MinGW g++)
The ASN1C C/C++ run-time library files. These are the same as the C run-time libraries above except they contain run-time C++ classes as well as C run-time functions.
- <installdir>\c*\lib_opt\*
- <installdir>\cpp*\lib_opt\*
The optimized version of the ASN1C run-time libraries. This version has all diagnostic messages, error stack trace and text, and non-essential status checks removed. (Note: these libraries are only available in the licensed deployment version of the product. If you wish to do performance testing, please contact us and we will make them available to you).
- <installdir>\c*\lib_debug\*
- <installdir>\cpp*\lib_debug\*
The debug DLL versions of the ASN1C run-time libraries. These are the same as the DLL C/C++ run-time libraries above except they are linked with debug versions of Standard C Run-time DLLs. (Note: these libraries are only available in the licensed development version of the product (SDK)).
- <installdir>\c\sample_*
- <installdir>\cpp\sample_*
The sample directories contain sample programs demonstrating the use of the compiler. There are a set of sample programs that correspond to each encoding rule set supported by ASN1C. Most sample programs are broken down into a writer and a reader. The writer encodes a sample data record and writes it to a disk file. The reader reads the encoded message from the file, decodes it, and then prints the results of the decode operation.
- <installdir>\rtsrc\*
- <installdir>\rtxsrc\*
Run-time source directories containing common type and class definitions used by all encoding rules. The installation run-time source directories contain the header files required to compile the compiler generated code. The C or C++ source files will also be located here if the run-time source code kit option was selected.
- <installdir>\rt*ersrc\*
Run-time source directories for various ASN.1 encoding rules. These contain common code for encoding and decoding using the specific rules. Directories are currently present for BER/DER/CER, PER (aligned and unaligned), MDER, OER, and XER rules.
- <installdir>\rtjsonsrc\*
JSON specific run-time source directory. These contain common code for encoding/decoding JSON messages.
- <installdir>\rtxmlsrc\*
XML specific run-time source directory. These contain common code for encoding/decoding XML messages.
- <installdir>\expatsrc\*
The XML parser run-time source directories contain the source files for the Expat C XML parser.
- <installdir>\libxml2src\*
The LibXML2 parser run-time source directories contain the source files for the GNOME libxml2 C XML parser.
Java run-time libraries
- <installdir>\java\asn1rt.jar
ASN.1 Java run-time libraries. These contain the low-level encode/decode classes for the various encoding rules supported by ASN1C. The asn1rt.jar file contains classes compatible with the Java 5 JRE.
- <installdir>\java\sample_*
Sample programs illustrating the use of the Java version of ASN1C. As was the case for C/C++, most have a writer and a reader. Some contain support code used by other samples (for example, SimpleROSE contains the ROSE headers used by CSTA).
- <installdir>\java\doc\*
The ASN.1 Java run-time libraries documentation files. These are html files generated with the javadoc documentation tool. To view the documentation, open the index.html file with a web browser and follow the hyperlinks.
- <installdir>\java\xmlpull\*
The kXML pull-parser implementation. This parser is used in the generated XER and XML decode classes.
- <installdir>\java\xerces\*
The Apache Xerces Java XML parser implementation. This parser is used to support legacy SAX parsing in the generated XER and XML decode classes. Note that SAX parsing is a deprecated feature at thie time.
C# run-time libraries
- <installdir>\csharp\asn1rt.dll
The ASN.1 C# run-time library DLL, built with Visual Studio 2013. This contains the low-level BER, PER, and/or XER encode/decode classes.
- <installdir>\csharp\vs2010\asn1rt.dll
The ASN.1 C# run-time library DLL, built with Visual Studio 2010. This contains the low-level BER, PER, and/or XER encode/decode classes.
- <installdir>\csharp\sample_*
Sample programs demonstrating the use of the C# version of ASN1C. As was the case for C/C++, most have a writer and a reader. Some contain support code used by other samples (for example, SimpleROSE contains the ROSE headers used by CSTA).
- <installdir>/csharp/doc/*
The ASN.1 C# run-time libraries documentation files. Documentation is contained within the ASN1CLibrary.chm file. This is in Microsoft help format.
The compiler can be run using either the GUI wizard or from the command line. To run the GUI wizard, launch the application and follow these steps. To run a simple test from the command line, do the following:
- Open a Windows Command Prompt (Start -> Accessories -> Command Prompt) or other command shell window. If using Visual Studio, it is best to open a command prompt window for that version under the Visual Studio Tools group of the main menu pulldown item.
- Change directory (cd) to one of the employee sample directories (for example, c/sample_ber/employee).
- Execute the nmake utility program:
nmake
(note: nmake is a make utility program that comes with Microsoft Visual Studio).
This should cause the compiler to be invoked to compile the employee.asn sample file. It will then invoke the Visual C++ compiler to compile the generated C file and the test drivers. The result should be a writer.exe and reader.exe program file which, when invoked, will encode and decode a sample employee record.
It is also possible to compile the sample programs using the Visual Studio IDE. Microsoft Visual Studio 2010 workspace and project files are included in most sample programs. Double-clicking the workspace file should cause it to be opened and updated to be compatible with whatever version of Visual Studio is being used.
- Invoke writer from the command line:
writer
This will generate an encoded record and write it to a disk file. By default, the file generated is message.dat (in the case of XER, it is message.xml). The test program has a number of command line switches that control the encoding. To view the switches, enter writer ? and a usage display will be shown.
- Invoke reader from the command line:
reader
This will read the disk file that was just created by the writer program and decode its contents. The resulting decoded data will be written to standard output. The test program has a number of command line switches that control the encoding. To view the switches, enter reader ? and a usage display will be shown.
The compiler can be run using either the GUI wizard or from the command line. To run the GUI wizard, launch the application and follow the steps. To run a simple test from the command line, do the following:
- Open a command shell window.
- Change directory (cd) to one of the employee sample directories (for example, java/sample_ber/Employee).
- Execute the build batch file:
build
This will cause the ASN1C compiler to be invoked to compile the employee.asn sample file. It will then invoke the Java compiler (javac) to compile all generated java files and the reader and writer programs (Note: JDK 6 was used to build all the run-time library classes). It will also automatically execute the writer and reader programs. These programs will produce a writer.log and reader.log file respectively.
Note: a makefile is also available for use if you have a make utility program available. The makefile is compatible with the GNU make utility and with the Microsoft Visual C++ make utility (nmake).
- View the writer and reader log files. The writer.log file will contain a dump of the encoded message contents. The reader.log file will contain a printout of the decoded data.
The compiler can be run using either the GUI wizard or from the command line. To run the GUI wizard, launch the application and follow the steps. To run a simple test from the command line, do the following:
- Make sure Microsoft .NET 2008 or 2010 is installed on your system.
- Open the appropriate Visual Studio command prompt (VS 2010 or VS 2008).
- Execute the nmake command to run the complete sample program. The makefile will invoke the ASN1C compiler to generate C# code for the ASN.1 definition and then compile the generated C# code.
- Execute writer.exe to encode a binary message and write it to a file.
- Execute reader.exe to read the file containing encoded binary message and decode it.
Report problems you encounter by sending E-mail to support@obj-sys.com. The preferred format of example programs is the same as the sample programs. Please provide a writer and reader and indicate where in the code the problem occurs.
If you have any further questions or comments on what you would like to see in the product or what is difficult to use or understand, please communicate them to us. Your feedback is important to us. Please let us know how it works out for you - either good or bad.