Example: Building an E-XER Application
The following sample application illustrates the use of the OSS ASN.1 Compiler to compile a simple ASN.1 module, and the use of the OSS runtime APIs to invoke the Extended-XER (here after called E-XER) encoder/decoder.
The C application program in this example is
tebcas.c
and the associated ASN.1 source file is
ebcas.asn .
This ASN.1 file contains a value notation
myCard.
The application program encodes this value (
myCard )
using E-XER, and then decodes the E-XER encoded data into structures.
The following outline shows how you can produce and run a sample executable program that encodes and decodes a message using E-XER (Extended XML Encoding Rules).
Step 1: Invoking the ASN.1 Compiler
1.1 Input ASN.1 Syntax (ebcas.asn)
1.2 Command to compile ebcas.asn
1.3 Output files generated by the ASN.1 Compiler
Step 2: Compiling and Linking the sample application
2.1 Input application program tebcas.c
2.2 Commands to compile and link the sample program
Step 3: Running the sample porgram
3.1 Command to run the executable
3.2 Output of sample program
Step 1: Invoking the ASN.1 Compiler
The following describes how to compile the abstract syntax defined in the ebcas.asn file.
1.1 Input ASN.1 Syntax (ebcas.asn)
BCAS DEFINITIONS XER INSTRUCTIONS ::= BEGIN
BBCard ::= SEQUENCE {
name [ATTRIBUTE] VisibleString (SIZE (1..60)),
team [ATTRIBUTE] VisibleString (SIZE (1..60)),
age INTEGER (1..100),
position VisibleString (SIZE (1..60)),
handedness ENUMERATED
{left-handed(0), right-handed(1), ambidextrous(2)} }
myCard BBCard ::= {
name "Casey",
team "Mudville Nine",
age 32,
position "left field",
handedness right-handed
}
ENCODING-CONTROL XER
GLOBAL-DEFAULTS MODIFIED-ENCODINGS
NAME ALL IN BBCard AS CAPITALIZED
TEXT BBCard.handedness:left-handed AS "left handed"
TEXT BBCard.handedness:right-handed AS "right handed"
NAMESPACE BBCard AS "http://www.example.com" PREFIX "oss"
END
.:. Top
1.2 Command to compile ebcas.asn
The following command compiles ebcas.asn,
and generates ebcas.h and ebcas.c
files. The ebcas.h file contains the structures
corresponding to the components of ASN.1 file. The ebcas.c
file contains information needed by the encoder and the decoder at runtime. The file,
ebcas.c, must be compiled and linked with the
sample application.
asn1 -exer ebcas.asn
or
asn1 -exer ebcas
The
-exer compiler option notifies compiler
that E-XER (Extended XML Encoding Rules) will be used at runtime. A detailed description
of all the compiler options supported by the OSS ASN.1/C Compiler can be found in the
OSS ASN.1 Compiler for C Reference Manual.
.:. Top
1.3 Output files generated by the ASN.1 Compiler
ebcas.h
#ifndef OSS_ebcas
#define OSS_ebcas
#include "asn1hdr.h"
#include "asn1code.h"
#define BBCard_PDU 1
typedef struct BBCard {
char name[61];
char team[61];
unsigned short age;
char position[61];
enum {
left_handed = 0,
right_handed = 1,
ambidextrous = 2
} handedness;
} BBCard;
extern BBCard myCard;
extern void * const ebcas; /* encoder-decoder control table */
#endif /* OSS_ebcas */
.:. Top
ebcas.c
The ebcas.c file contains the information
needed by the runtime APIs to encode and decode PDUs. Since this file contains
internal information, it is not shown here. This file must be compiled and linked with
the sample application.
Step 2: Compiling and Linking the sample application
The following C program, tebcas.c, encodes the PDU described by the ebcas.asn abstract syntax using E-XER (Extended XML Encoding Rules), and then decodes it. Note that ebcas.h (generated by the compiler) has been #included in the application program. This header file contains the generated declarations for the application. (The function calls to the OSS Encoder/Decoder functions are in bold font.)
After the application program is compiled, the OSS Encoder/Decoder runtime library must be linked into the resulting executable file.
2.1 Input application program tebcas.c
/ * Application Program: tebcas.c
* Encodes a sample baseball card
* using BCAS (Baseball Card Abstract Syntax)
*/
#include
#include "ebcas.h" /* compiler-generated header file */
/* Encodes a card. If the card is successfully encoded, decodes it. */
int main()
{
OssBuf encodedData; /* length and address of encoded data */
BBCard *myCardPtr = NULL; /* address of decoded data */
int pdu_num = BBCard_PDU;
struct ossGlobal w, *world = &w;
int retcode; /* return code */
/*
* Call ossinit() first to initialize OSS's global structure
*/
if ((retcode = ossinit(world, ebcas))) {
ossPrint(world, "Ossinit() returned %d\n", retcode);
return retcode;
}
ossSetEncodingFlags(world, DEBUGPDU);
ossSetDecodingFlags(world, DEBUGPDU);
/* Print the input to the encoder */
ossPrint(world, "\nThe input to the encoder ...\n\n");
ossPrintPDU(world, BBCard_PDU, &myCard);
/* Encode a card. Return non-zero for failure. */
encodedData.value = NULL;
encodedData.length = 0;
ossPrint(world, "\nEncoding BBCard ...\n");
if (ossEncode(world, BBCard_PDU, &myCard, &encodedData)) {
/* an error occurred, print errmsg */
ossPrint(world, "%s\n", ossGetErrMsg(world));
return 1;
}
ossPrint(world, "Card encoded.\n");
ossPrint(world, "\nE-XER encoding of BBCard:\n");
/* For XER specifically, print the encoding */
ossPrint(world, "\n%.*s\n", encodedData.length, encodedData.value);
/* Decode a card whose encoding is in encodedData. Return non-zero
* for failure. */
ossPrint(world, "\nDecoding BBCard ...\n");
if (ossDecode(world, &pdu_num, &encodedData, (void **)&myCardPtr)) {
/* an error occurred, print errmsg */
ossPrint(world, "%s\n", ossGetErrMsg(world));
retcode = 1;
} else {
ossPrint(world, "Card decoded.\n"); /* successfully decoded */
/* Print the decoder's output */
ossPrint(world, "\nOutput from the decoder ...\n\n");
ossPrintPDU(world, pdu_num, myCardPtr);
ossFreePDU(world, pdu_num, myCardPtr);
retcode = 0;
}
/* free the encoder's output buffer*/
ossFreeBuf(world, encodedData.value);
/*
* Call ossterm() to free all resources
*/
ossterm(world);
return retcode;
}
.:. Top
2.2 Command to compile and link sample program
The OSS ASN.1/C compiler generated file ebcas.c
and application program tebcas.c should be compiled and linked to generate the sample
executable program.
The easiest way to compile and run the sample program is by using the makefiles
(asn1cpl.mak and tebcas.mak)
under the samples directory of the OSS ASN.1 Tools for C. The asn1cp.mak
file compiles the ASN.1 syntax and generates .h and .c
files. The other makefile, tebcas.mak, compiles application
code with the generated .c file, and links the
object file with the OSS runtime libraries to generate a sample executable. These files are
located under the samples/xml/extended-xer directory.
For example, if you have installed OSS ASN.1 Tools for C
under the /ossasn1/win32/7.0.0 directory, these
makefiles can be found under the /ossasn1/win32/7.0.0/samples/xml/extended-xer
directory. An executable for the sample program can be created by using the following
these commands on Windows or UNIX:
For Windows:
nmake -f asn1cpl.maknmake -f tebcas.mak
For Unix:
make -f asn1cpl.makmake -f tebcas.mak
Step 3: Running the sample program
3.1 Command to run the executable
An executable tebcas (tebcas.exe
for Windows) will be generated after step 2.2. This executable can be run on the command
line by the following command:
tebcas
3.2 Output of the sample program
Running tebcas will generate the
following output:
The input to the encoder ...
value BBCard ::=
{
name "Casey",
team "Mudville Nine",
age 32,
position "left field",
handedness right-handed
}
Encoding BBCard ...
Card encoded.
E-XER encoding of BBCard:
<?xml version="1.0" encoding="UTF-8"?>
<oss:BBCard xmlns:oss="http://www.example.com"
xmlns:asn1="urn:oid:2.1.5.2.0.1" Name="Casey" Team="Mudville Nine">
<Age>32</Age>
<Position>left field</Position>
<Handedness>right handed</Handedness>
</oss:BBCard>
Decoding BBCard ...
Card decoded.
Output from the decoder ...
value BBCard ::=
{
name "Casey",
team "Mudville Nine",
age 32,
position "left field",
handedness right-handed
}
.:. Top
Copyright © 2010 OSS Nokalva, Inc. All Rights Reserved.
