TOP

ASN.1/C Runtime API Overview

Applies to: ASN.1/C 10.5

The OSS Encoder/Decoder API, also known as the OSS Runtime API, is a collection of functions that you can call to encode, decode, and perform auxiliary operations on application messages or Protocol Data Units (PDUs).

This section describes the characteristics of runtime functions, how to use the OSS Runtime API, and how to use multiple threads.

Introduction

Runtime functions enable you to:

  • Encode and decode using the following encoding rules: Basic Encoding Rules (BER), Packed Encoding Rules (Aligned: PER, Unaligned: UPER), Distinguished Encoding Rules (DER), Canonical Encoding Rules (CER), XML Encoding Rules (Basic: XER, Canonical: CXER, Extended: E-XER), Octet Encoding Rules (Basic: OER, Canonical: C-OER), JavaScript Object Notation Encoding Rules (JSON).
  • Check an unencoded PDU to see if the schema constraints are satisfied.
  • Print PDUs in encoded and unencoded/decoded forms.
  • Copy PDUs to different destinations.
  • Compare unencoded or decoded PDUs.
  • Free encoder/decoder output memory.

Encoder/Decoder Types

The encoder transforms data stored in C structures into encoded data.

The decoder, on the other hand, transforms encodings into C data structures. The encoder/decoder relies on the C code generated by the OSS ASN.1 compiler.

NOTE: Starting with version 9.0, by default, the OSS ASN.1 compiler generates TOED files instead of SOED files.

OSS Nokalva provides three types of encoders/decoders:

Time-Optimized Encoder/Decoder (TOED)
Optimized to minimize CPU utilization. This is the default encoder/decoder for the OSS ASN.1/C Tools.
Space-Optimized Encoder/Decoder (SOED)
Optimized to minimize the use of memory. The API for the first two types of encoders/decoders is identical.
Lean Encoder/Decoder (LED)
Optimized for embedded systems with limited available memory running applications which require fast processing time. The speed is comparable to that of TOED and the memory usage is smaller than that of SOED. LED is provided separately.

You can switch between the first two encoders/decoders without modifying your application program. To switch, specify the -soed or -toed option and re-compile your ASN.1 schema. Then rebuild your application by linking to the corresponding encoder/decoder runtime library.

In case the size of your schema is small or medium, the code generated by TOED is smaller, thus is executed faster than the code generated by SOED. Unless you need the externalized memory manager that the SOED uses, we recommend that you use TOED.

If the size of your schema is large or complex, note that SOED requires less memory than TOED.

Linking Options

To use the API functions, link your application with the OSS API libraries.

There are two types of libraries provided:

  • Static
  • Dynamic

Additionally, each type has three basic variants according to the type of encoder/decoder used:

  • Space-Optimized library
  • Time-Optimized library
  • Lean library

Until you become more familiar with the OSS API, we recommend that you use the Space-Optimized library.

The following table contains filenames associated with the libraries mentioned above, available for the Microsoft Windows platform:

Encoder/Decoder type Dynamic library (DLL) Static library Notes
Space-Optimized
ossapi.lib
soeddefa.lib
soeddemd.lib
*md.lib is a static encoder/decoder library linked with the dynamic C-runtime (built using /MD C compiler option).
Time-Optimized
ossapit.lib
toedcode.lib
toedcomd.lib
Lean
ossapil.lib
asn1lean.lib
asn1lemd.lib
asn1dlean.lib
asn1dlemd.lib
asn1d*.lib include tracing capabilities useful during debugging.

To avoid having multiple incompatible copies of runtime code in memory, make sure you are consistent in the way you are using your C/C++ compiler options. For example, if you compile your DLLs or executables to link statically with the C runtime libraries (/MT for Microsoft VC++), use the static OSS library soeddefa.lib (also compiled with /MT).

Similarly, if you compile your code to link dynamically with the C runtime libraries (/MD for Microsoft VC++), either use ossapi.lib or soeddemd.lib (the latter is built using /MD option for C runtime libraries).

OSS encoder/decoder DLLs are located in the bin/ directory of the OSS ASN.1/C Tools. Make sure these libraries are available at run time. For example, include the bin/ directory in the environment path of the operating system or move these DLLs to another location in your environment path.

Using the API

This is a typical OSS API function prototype:

returnType ossFunctionName(OssGlobal *world, ...);

All OSS API functions begin with the oss prefix. Most functions take a pointer to an instance of the structure OssGlobal as their first argument. This structure contains information about the OSS runtime environment that must be retained from an OSS API function to the next. For example:

OssGlobal world;
ossinit(&world, controlHeader);
ossPrint(&world, "Hello world.\n");
ossterm(&worldn);

controlHeader is the extern void* pointer declared at the end of the ASN.1 compiler-generated header file. This pointer is set to reference the SOED control table or the TOED code file entry points.

Your application must call the terminating function ossterm() to end the session.

NOTE: If you need multiple schemas for your application, a separate instance of the OssGlobal structure must be allocated and initialized for each control table (SOED) or each code file (TOED) generated for each schema by the ASN.1 compiler.

Using Multiple Threads

OSS API functions are re-entrant and thread-safe. However, you must ensure that, when using the OSS API functions in multiple simultaneous threads, you either serialize access to the OssGlobal structure or keep a separate copy of OssGlobal in each thread. If you choose to keep a separate copy of the OssGlobal structure in each thread, call ossinit() and ossterm() from within each thread.

NOTE: Unless you are using the Windows platform, you must not specify the OSS_TRAPPING flag to achieve thread-safety. For more information, see ossSetFlags().

To create a duplicate copy of the OssGlobal structure in each thread, instead of using ossinit(), you can call ossDupWorld(). Compared to ossinit(), the latter has a lower overhead. To free OssGlobal in each thread, call ossterm().

NOTE: If you are using the static OSS libraries (soeddefa.lib) on Windows, to achieve thread-safety, call ossInitSync() or ossTermSync(), before and after you use the OSS API.


This documentation applies to the OSS® ASN.1 Tools for C release 10.5 and later.

Copyright © 2017 OSS Nokalva, Inc. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means electronic, mechanical, photocopying, recording or otherwise, without the prior permission of OSS Nokalva, Inc.
Every distributed copy of the OSS® ASN.1 Tools for C is associated with a specific license and related unique license number. That license determines, among other things, what functions of the OSS ASN.1 Tools for C are available to you.