ASNSDK TCE-C
Application Example

The following application example describes how to use the ASNSDK TCE-C tools to encode and decode ASN.1 data. It presents the main concepts and features of the runtime.

Based on a very simple ASN.1 description, this application example encodes a ASN.1 value in PER encoding rules, then decodes it. Tracing facilities are activated during the encoding and the decoding.

Compiling the ASN.1 abstract syntax

Let's consider the following abstract syntax, written in a syntax.asn file:

The first step, to build a user application, which can encode or decode ASN.1 values of the MyType ASN.1 type, is to compile the above abstract syntax. To do so, the TCE-C ASN.1 compiler is called with the command line:
asnc -c -per -trace syntax.asn

This command line tells the TCE-C ASN.1 compiler to generate a C API corresponding to the abstract syntax contained in the syntax.asn file, using the Aligned PER encoding rules.

The generated C API is composed of one C source file asntable.c and of two C include files asn and asntype.

Writing the user application

The second step is to write the application example in C source code. The application example is fully detailed in the remaining of this section.

Declarations

To use the specific C API, the user application must first include the asn.h file generated by the TCE-C ASN.1 Compiler that contains all the #include directives necessary to use the C API.

Some variables are necessary to perform the encoding and the decoding processes:

The variable context is necessary in all functions of the C API. The variable traceStream can be used to get some traces about the encoding and decoding processes.

Context initialization

Each encoding and decoding function needs a context as a parameter. A context is a variable of type casnContext. In a multi-threaded environment, each thread must use a different context. Furthermore, a context contains settings, which control the way encoding and decoding are performed. The context is initialized with these instructions:

A field in the context has to be set with a descriptor of the abstract syntax in which the types to encode or decode are defined. This descriptor is defined in the asntype file, usually with the name AbstractSyntax (the name of this descriptor can be changed with the -idpfx compiler option). For debugging purposes, it can be useful to trace the results of the encoding and decoding processes in some file. This requires the definition of a stream. Streams are the abstractions used by the TCE-C runtime as target for traces, as output for the encoding process and as input for the decoding process. The following instructions create an output text file stream to the file named traces.txt and check the return code:

The newly created stream has to be defined as the trace stream in the context:

Then, the trace mechanism is activated at the encoding and at the decoding:

Encoding process

The encoding process converts a value defined on the ASNSDK TCE-C API into a message encoded in ASN.1 PER.

For the encoded message, it is necessary to define a stream:

For the value, it is necessary to define a variable of the appropriate C type. The file asntype generated by the ASN.1 compiler contains a C type definition for each ASN.1 type. The name of the C type is derived from the name of the ASN.1 type. The C type corresponding to the MyType ASN.1 type is simply MyType:

It is necessary to define the kind of stream used to contain the result of the encoding process. In this example, an automatic output memory stream is used. Such a stream hides a memory buffer, automatically allocated during the encoding process with the exact size of the encoded message. The following instructions initialize the stream:

It is necessary to initialize myValue before encoding. The first step is always to initialize the value globally. This requires calling the casnInitvalue function giving the context, the address and the size of the value to initialize:

To encode this value using the ASN.1 aligned packed encoding rules, the user application must just call the casnPERencode function with the appropriate parameters:

The second parameter is the identifier of the type to encode. It is a constant defined in the asntype file. The name of this identifier is the name of the C type prefixed by casnT, here casnTMyType. The fourth parameter is the stream where the PER encoding engine will write the ASN.1 encoded message corresponding to the value. The last parameter returns the length in bytes of the encoded message.

Depending on the settings in the context, this function can do automatically some additional work. Here it writes a trace of the encoded message in the trace stream (the traces.txt file).

If the encoding is successful, the output stream contains the encoded message. Here the output stream is an automatic memory stream. For such a stream, it is possible to detach the automatically allocated buffer from the stream:

The user application accesses the encoded message using the buffer and length variables. The buffer will be released later using the asnCtxFree function.

The output stream and the value to encode are no longer necessary. For proper operation, it is required to release the memory used by these variables:

It is a good practice to always do this cleaning, even if, as in this very simple example, the cleaning of myValue does nothing.

Decoding process

The decoding process converts a message encoded in ASN.1 into a value defined on the ASNSDK TCE-C API. To decode the message, it is necessary to define a stream that will contain the encoded message:

For storing the decoded value, it is necessary to define a variable of the appropriate C type. The file asntype generated by the ASN.1 compiler contains a C type definition for each ASN.1 type. The name of the C type is derived from the name of the ASN.1 type. The C type corresponding to the MyType ASN.1 type is simply MyType:

The message to decode is contained in a memory buffer but the ASN.1 runtime requires an input stream to decode from. It is necessary to build an input memory stream over the memory buffer:

To decode the message using the ASN.1 aligned PER, the user application must just call the casnPERdecode function with the appropriate parameters:

These parameters are almost identical to the parameters of the casnPERencode function. The second parameter is the identifier of the type to decode. It is a constant defined in the asntype file. The name of this identifier is the name of the C type prefixed by casnT, here casnTMyType. The third parameter is the address of the value where to decode into, here myValue of type MyType.

Depending on the settings in the context, this function can do automatically some additional work. Here it writes a trace of the decoded value in the trace stream (the traces.txt file).

If the decoding is successful, the myValue variable contains the ASN.1 message in the format of the C API. The user application can access the fields of this variable in a way depending on the ASN.1 type of each field. Here, the user application simply displays the value of the two fields on the standard output:

The input stream and the decoded value are no longer necessary. For proper operation, it is necessary to release the memory used by these variables:

Overall cleaning

The buffer obtained from the encoding process, and used as input for the decoding process, is no longer necessary. It is released with the asnCtxFree function:

For proper operation, it is also necessary to release the memory used by the trace stream and the context:

Running the user application

Running the application example generates the traces.txt file, which contains in sequence the XML trace of the encoding, then the XML trace of the decoded value: