Getting Started

Software Distribution

The OSS ASN.1 Tools for C++ is available in three different distributions: compiler-only, target (runtime only), and development (full).

The compiler-only distribution includes only the OSS ASN.1 Compiler; since the runtime libraries are missing, the compiler-only software cannot produce an executable program. It can be used to

• Compile your ASN.1 specification for use on the same type platform as that on which the compiler is running.
• Cross-compile, which is compiling ASN.1 specifications on one computer platform to obtain .cpp and .h files for use on another platform, to any other platform for which you are licensed to use the run-time libraries.

The target distribution includes the OSS Runtime libraries only. The OSS ASN.1 compiler is missing, so the target software cannot compile your ASN.1 specification. It can only be used for runtime support on the target platform where your application using the encoder/decoder is run.

The development distribution is a combination of the compiler-only and target distributions. It includes both the OSS ASN.1 Compiler and the Runtime libraries. The development software can be used to compile your ASN.1 specification for use on the same type of platform as that on which the compiler is running, or to cross-compile to any other platform for which you are licensed to use the runtime libraries. Since the runtime libraries are included, the development software can also be used for runtime support on the target platform where your application using the encoder/decoder is run.

Skill Set

To fully utilize the OSS ASN.1 Tools, learn to do the following:

1. Install the OSS ASN.1 Tools on your platform.
2. Perform a basic sanity test to make sure that the installation was successful. This can easily be done by running the makefiles that are found in the samples directory.
3. Compile your ASN.1 specifications using the OSS ASN.1 Compiler to produce header files and control-table/code files to include in your application.
4. Fill the data structures that the ASN.1 Compiler generates in the header file to represent your ASN.1 specification.
5. Issue calls to instantiated OSS API class methods from within your application source code to encode/decode your application messages and perform auxiliary operations.
6. C++-compile your application code along with ASN.1 Compiler-generated .cpp and .h files, using your C++ compiler.
7. Link your application code with the OSS ASN.1 Runtime libraries, either statically or dynamically, to produce executable code that uses the OSS ASN.1 libraries for encoding/decoding and related tasks.

Compiling an ASN.1 Module

The ASN.1 Compiler translates your ASN.1 specifications into C++ objects that you can use to encode application messages and decode messages. Just pass ASCII text files containing your specifications to the ASN.1 Compiler as command-line arguments. These files typically have a .asn extension.

You can ASN.1-compile using either the command-line ASN.1 Compiler or ASN.1 Studio. Command-line compiling uses this general form:

asn1cpp ASN.1_input_file(s) [commandLineOption(s)] 

where asn1cpp[.exe] is the name of the compiler executable file, ASN.1_input_file(s) specifies one or more .asn files that contain the ASN.1 input modules, and commandLineOption(s) can be one or more dash-prefixed compiler-configuration options.

For example, to compile the bcas.asn file located in the samples/basic/decode and samples/basic/encode directories, issue the following command:

asn1cpp bcas.asn -ber -per -exer

This generates the following files:

• bcas.h is the header file containing the C++ class and method definitions required to represent the ASN.1 specification contained in bcas.asn. To use the produced classes, #include this .h file in your application code.
• bcas.cpp is the file used by the OSS API functions to correctly encode/decode the values you store in the compiler-generated data structures found in bcas.h. This file contains the generated C++ code for the generated classes in bcas.h, as well as the code used by the encoder/decoder.

NOTES:

• To generate C++ representations for all types in all input modules, either specify the -root command-line option when ASN.1-compiling or add the global OSS.ROOT compiler directive to the beginning of your specification. Normally, only representations for the last input ASN.1 module are generated into the produced header file.
• The order of the input files on the command-line can be important. Place files that contain global compiler directives (e.g., asn1dflt files) before all ASN.1 input files. Also, place files that contain definitions referenced by other files first (left to right on the command line). For example, if the myModules.asn file references macro definitions in macro.asn, you would invoke the compiler as:

  asn1cpp macro.asn myModules.asn

Using the ASN.1/C++ Compiler Output

The ASN.1 Compiler output consists of two files:

• <module name>.h contains the class definitions that you will manipulate directly. It is essential that you become familiar with the details of this file.
• <module name>.cpp is used by the OSS API to properly encode and decode your application messages using the standard ASN.1 encoding rules. For the most part, you do not need to know about the contents of the *.cpp files.

The OSS ASN.1 Compiler generates class definitions in the target C++ language based on the input ASN.1 notation. See C++ Representation of ASN.1 Notation for details about the rules used by the ASN.1 Compiler to produce C++ classes. These classes can be later referenced by the application program.

For example, when the following ASN.1 syntax is passed to the ASN.1/C++ Compiler:

-- Baseball Card Abstract Syntax (BCAS) 

BBCard ::= SEQUENCE {
        name IA5String (SIZE (1..60)),
        team IA5String (SIZE (1..60)),
        age INTEGER (1..100),
        position IA5String (SIZE (1..60)),
        handedness ENUMERATED
                {left-handed(0), right-handed(1), ambidextrous(2)},
        batting-average REAL
}

a bcas.h header file is generated that contains the following:

#include "oss.h"
#include "asn1.h"

/* Representation types */

enum _enum1 {
    left_handed = 0,
    right_handed = 1,
    ambidextrous = 2
};

class OSS_PUBLIC BBCard   /* SEQUENCE */
{
public:
    void * operator new(size_t size);
    void operator delete(void *ptr);

    typedef OssString name;
    typedef OssString team;
    typedef OSS_UINT32 age;
    typedef OssString position;
    typedef enum _enum1 handedness;
    typedef double batting_average;

    BBCard();
    BBCard(const BBCard &);
    BBCard(const name &, const team &, age, const position &, handedness, batting_average);

    BBCard & operator = (const BBCard &);
    int operator == (const BBCard &) const;
    int operator != (const BBCard &) const;

    name & get_name();
    const name & get_name() const;
    void set_name(const name &);

    team & get_team();
    const team & get_team() const;
    void set_team(const team &);

    age & get_age();
    age get_age() const;
    void set_age(age);

    position & get_position();
    const position & get_position() const;
    void set_position(const position &);

    handedness & get_handedness();
    handedness get_handedness() const;
    void set_handedness(handedness);

    batting_average & get_batting_average();
    batting_average get_batting_average() const;
    void set_batting_average(batting_average);
private:
    name name_field;
    team team_field;
    age age_field;
    position position_field;
    handedness handedness_field;
    batting_average batting_average_field;
};

/* Universal PDU class */

class OSS_PUBLIC bcas_PDU : public UniversalPDU {
public:
    bcas_PDU();
    void set_BBCard(BBCard &);
    BBCard *get_BBCard() const;
#ifdef OSS_PREALLOCATED_BUFFER_DECODE_SUPPORTED
    void set_const_BBCard(const BBCard &);
    const BBCard *get_const_BBCard() const;
#endif
};

/* Specific PDU classes */

class OSS_PUBLIC BBCard_PDU : public ConcretePDU {
public:
    BBCard_PDU();
    void set_data(BBCard &);
    BBCard *get_data() const;
#ifdef OSS_PREALLOCATED_BUFFER_DECODE_SUPPORTED
    void set_const_data(const BBCard & d);
    const BBCard *get_const_data() const;
#endif
protected:
    OssTypeIndex get_index() const;
};

/* Control object class */

class OSS_PUBLIC bcas_Control : public OssControl {
public:
    bcas_Control();
    bcas_Control(const bcas_Control &);
};

In the first two statements, oss.h and asn1.h are header files needed for a clean compilation of the output code. These files are located in the include subdirectory of the OSS ASN.1 Tools for C++ installation.

Following these statements are class definitions and type declarations you can use to create instantiated objects for encoding, decoding, viewing, or manipulating.

To use the ASN.1 Compiler output in your application, explicitly #include the generated header file in your application code:

#include "bcas.h"

where bcas.h is the file location of the generated header file.

Using the OSS ASN.1/C++ API Routines

Once you have successfully compiled your ASN.1 specification, you can begin to initialize your environment and instantiate the objects to be used by your application. Then, you can fill the created objects and data-structures with your application data for encoding, decoding, viewing, or manipulating via the provided routines. To learn how this is done, see this comprehensive example.

Switching Between the Encoders/Decoders

OSS provides three types of encoders/decoders:

• Space-Optimized
• Time-Optimized
• Lean (available separately)

The application program interface for the three types of encoders/decoders is identical. You can use any of the available encoders/decoders without having to modify your application.

To use a particular encoder, explicitly link your application with one of the runtime library files in the lib subdirectory of the Tools. By default, the ASN.1 Compiler produces output suitable for use with the Time-Optimized Encoder/Decoder, which is the fastest encoder/decoder.

Specify the -lean compiler option to generate output suitable for use with the Space-Optimized or Lean Encoder/Decoder. You can switch between them just by linking with the corresponding encoder/decoder library (SOED or LED). You do not need to recompile your application. However, if you want to use SOED-specific features that are not present in LED, recompile your input specification with the -soed option specified.

Compiler-generated TOED code is usually much bigger than the SOED/LED control table. To help exclude unneeded code from the resulting application, the ASN.1 Compiler puts some generated TOED code sections under #ifdef preprocessor directives, so they are compiled only when the user specifies the corresponding preprocessor symbol in the C++ compiler command line. For example, to print decoded PDU values using the ASN1Handle::print function and TOED is in use, specify -DOSSPRINT when compiling the generated TOED code; otherwise any call to ASN1Handle::print will fail. When no preprocessor symbols are defined, only encoding and decoding routines without debugging capabilities are compiled.

In practice, you will find that the Time-Optimized Encoder/Decoder is the best choice for applications that require fast processing times and the Lean Encoder/Decoder best for running under constrained environments, such as embedded systems with limited space. The Space-Optimized Encoder/Decoder is more appropriate for applications that require advanced API support from their runtime libraries.

NOTE: The Lean Encoder/Decoder (LED) is only available on common platforms like Windows, Linux, and Solaris, and may not be available for your embedded system port. If you are interested in LED for your platform, contact OSS Nokalva Sales.

See Also

• Linking Options
• Cross-compiling to a Different Target Platform

C++-compiling your Application

cl -c -MT -EHsc -I. -I "C:\Program Files\OSS Nokalva\asn1cpp\<platform name>\<version>\include"
                                                                      -DOSSPRINT bcas.cpp encode.cpp

CC -I. -I/usr/local/asn1cpp/include -DOSSPRINT -c  bcas.cpp

CC -I. -I/usr/local/asn1cpp/include -c  encode.cpp

Linking your Application with the OSS Libraries

link  \
    -out:encode.exe bcas.obj encode.obj \
    "C:\Program Files\OSS Nokalva\asn1cpp\<platform name>\<version>\lib\osscppmt.lib"  \
    "C:\Program Files\OSS Nokalva\asn1cpp\<platform name>\<version>\lib\cpptoedmt.lib"  \
    user32.lib

link 
    -out:encode.exe encode.obj bcas.obj \
    "C:\Program Files\OSS Nokalva\asn1cpp\<platform name>\<version>\lib\cpptoed.lib"

CC  -o encode encode.o bcas.o /usr/local/asn1cpp/lib/libosscpp.a  \
      /usr/local/asn1cpp/lib/libcpptoed.a -lm -lsocket -lnsl

CC  -o encode encode.o bcas.o /usr/local/asn1cpp/lib/libosscpp.so  \
      /usr/local/asn1cpp/lib/libcpptoed.so -lm -lsocket -lnsl

Running your application

encode

-DUSE_MD_LIB

./encode

For information about the OSS Nokalva makefiles, see the README.TXT files located in the samples directory.