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.
Runtime functions enable you to:
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:
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.
To use the API functions, link your application with the OSS API libraries.
There are two types of libraries provided:
Additionally, each type has three basic variants according to the type of encoder/decoder used:
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|
|*md.lib is a static encoder/decoder library linked with the dynamic C-runtime (built using /MD C compiler option).|
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.
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.
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().
This documentation applies to the OSS® ASN.1 Tools for C release 10.7 and later.
Copyright © 2020 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.