Home

ASN.1 Compiler Version 5.8 C/C++ Compiler User`s Manual

1. const OSOCTET msgptr OSOCTET msgbuf 1024 int msglen ASNIBEREncodeBuffer encodeBuffer msgbuf sizeof msgbuf ASNIT PersonnelRecord msgData ASN1C PersonnelRecord employ encodeBuffer msgData Encode loop starts here this will repeatedly use the objects declared above to encode the messages for A ASNIC V5 8 117 ASNIC V5 8 logic here to read record from some source database flat file socket etc populate structure with data to be encoded msgData name SMITH invoke Encode method if msglen employee Encode gt 0 encoding successful get pointer to start of message msgptr encodeBuffer getMsgPtr do something with th ncoded messag else error processing Call the init method on th ncodeBuffer object to prepare the buffer for encoding another message encodeBuffer init 118 Generated BER Decode Functions NOTE This section assumes standard memory buffer based decoding is to be done If stream based decoding is to be done specified by adding stream to the ASNIC command line see the Generated BER Stream Oriented Decode Functions section for correct procedures on using the stream based functions For each ASN 1 production defined in an ASN 1 source file a C decode function is generated This function will decode an ASN 1 message into a C variable o
2. EmbeddedPDV UNIVERSAL 11 IMPLICIT SEQUENCE identification CHOICE syntaxes SEQUENCE abstract OBJECT IDENTIFIER transfer OBJECT IDENTIFIER syntax OBJECT IDENTIFIER presentation context id INTEGER context negotiation SEQUENCE presentation context id INTEGER transfer syntax OBJECT IDENTIFIER transfer syntax OBJECT IDENTIFIER fixed NULL data value descriptor ObjectDescriptor OPTIONAL data value OCTET STRING WITH COMPONENTS data value descriptor ABSENT The ASNIC compiler is used to create a meta definition for this structure This code will be always generated in the Asnl EmbeddedPDV h and Asn1 EmbeddedPDV c cpp files The code will only be generated if the given ASN 1 source specification requires this definition The resulting C structure is populated just like any other compiler generated structure for working with ASN 1 data NOTE It is recommended that if a specification contains multiple ASN 1 source files that reference EMBEDDED PDV all of these source files be compiled with a single ASNIC call in order to ensure that only a singled copy of the Asn EmbeddedPDV source files are generated Parameterized Types The ASNIC compiler can parse parameterized type definitions and references as specified in the X 683 standard These types all
3. In this case EsSetParam refers to an information object set specification that constrains the values that are allowed to be passed for any given instance of a type referencing a ProtocolIE Field The compiler does not add any extra code to check for these values so the parameter can be discarded note that this is not true if the tables compiler option is specified After processing the Information Object Class references within the construct refer to the section on Information Objects for information on how this is done the reduced definition for ProtocolIE Field becomes the following ProtocollIE Field SEQUENCE id ProtocolIE ID criticality Criticality value ASN 1 OPEN TYPE References to the field are simply replaced with a reference to the ProtocolID Field typedef If tables 1s specified the parameters are used and a new type instance 1s created in accordance with the rules above ASNIC V5 8 67 Value Specifications The compiler can parse any type of ASN 1 value specification but the standard version of the ASNIC compiler will only generate code for following value specifications e BOOLEAN INTEGER e REAL e ENUMERATED e Binary String e Hexadecimal String e Character String e OBJECT IDENTIFER All value types except INTEGER and REAL cause an extern statement to be generated in the header file and a global value assignment to be added to the C or C source fil
4. c or cpp None Generate C source code c or csharp None Generate C source code See the ASNIC C User s Guide for more information and options for generating C code cer None This option instructs the compiler to generate functions that implement the Canonical Encoding Rules CER as specified in the X 690 ASN 1 standard cfile filename This option allows the specification of a C or C source c or cpp file to which all of the generated encode decode functions will be written If not specified the default is to write to a series of c or cpp files based on the ASN 1 module name s of the documents being compiled compact None This option instructs the compiler to generate more compact code at the expense of some constraint and error checking This is an optimization option that should be used after an application is thoroughly tested compat lt versionNumber gt Generate code compatible with an older version of the compiler The compiler will attempt to generate code more closely aligned with the given previous release of the compiler lt versionNumber gt is specified as x x for example compat 5 2 config lt filename gt This option is used to specify the name of a file containing configuration information for the source file being parsed A full discussion of the contents of a configuration file is provided in the Compiler Conf
5. return 1 xe setp amp ctxt msgbuf sizeof msgbuf Step 2 Populate the structure to b ncoded mployee name numocts 5 mployee name data SMITH Step 3 Call the generated encode function msglen asnlE Employee amp ctxt amp employee ASNIEXPL Step 4 Check the return status note the test is gt 0 because the returned value is the length of the ASNIC V5 8 112 encoded message component if msglen gt 0 Step 5 If encoding is successful call xe getp to fetch a pointer to the start of th ncoded messag msgptr xe getp amp ctxt else error processing In general static buffers should be used for encoding messages where possible as they offer a substantial performance benefit over dynamic buffer allocation The problem with static buffers however is that you are required to estimate in advance the approximate size of the messages you will be encoding There is no built in formula to do this the size of an ASN 1 message can vary widely based on data types and the number of tags required If performance is not a significant an issue then dynamic buffer allocation is a good alternative Setting the buffer pointer argument to NULL in the call to xe setp specifies dynamic allocation This tells the encoding functions to allocate a buffer dynamically The address of the start of the message is obtained as before by calling xe_
6. out printErrorInfo return 1 step 2 construct ASN1C C generated class ASNIT PersonnelRecord msgData ASN1C PersonnelRecord employ msgData for step 3 populate msgData structure with data to be encoded note this uses the generated assignment operator to assign a string msgData name SMITH step 4 invoke operator or EncodeTo method out employee or employee EncodeTo out can be used here step 5 fetch and check status if out getStatus ASN OK printf Encoding failed Status i n out getStatus out printErrorInfo return 1 if trace printf Encoding was successful n ASNIC V5 8 138 ASNIC V5 8 139 Generated BER Stream Oriented Decode Functions BER messages can be directly read and decoded from an input stream such as a file network or memory stream using BER stream oriented decode functions The ASNIC compiler stream option is used to generate decoders of this type For each ASN 1 production defined in an ASN 1 source file a C stream oriented decode function is generated This function will decode an ASN 1 message into a C variable of the given type If C code generation is specified a control class is generated that contains a DecodeFrom method that wraps this function This function is invoked through the class interface to decode an ASN 1 message into the variable referenced in the msgDa
7. Here ClassName 1s replaced with name of the Class Assignment and FieldName is replaced with name of this field Type Is the type definition in CLASS s TypeField This type is used as a defined type in the information object definition for an absent value of the TypeField It 1s also useful for generation of a value for a related Open Type definition in a table constraint 2 A new Type Assignment is created for a Value Field or Value Set Field type definition as follows if the type definition is one of the following ConstraintedType ENUMERATED NamedList BIT STRING SEQUENCE SET CHOICE SEQUENCE OF SET OF _ lt ClassName gt lt FieldName gt lt Type gt Here ClassName is replaced with the name of the CLASS assignment and FieldName is replaced with name of the ValueField or ValueSetField Type is the type definition in the CLASS s ValueField or ValueSetField This type will appear as a defined type in the CLASS s ValueField or ValueSetField This new type assignment is used for compiler internal code generation purpose It is not required for a user to understand this logic 3 A new Value Assignment is created for a ValueField s default value definition as follows _ lt ClassName gt FieldName default lt Type gt lt Value gt Here ClassName is replaced with name of the Class Assignment and FieldName is replaced with name of this ValueField Value is the default value in Class s ValueField and Type is
8. SEQUENCE lt elementl name gt lt elementl type gt lt element2 name gt lt element2 type gt Generated C code typedef struct lt typel gt elementl name lt type2 gt lt element2 name gt lt name gt Or typedef struct lt tempNamel gt typedef struct lt tempName2 gt typedef struct tempNamel lt elementl name gt lt tempName2 gt lt element2 name gt lt name gt The lt typel gt and lt type2 gt placeholders represent the equivalent C types for the ASN 1 types lt elementl type gt and lt element2 type gt respectively This form of the structure will be generated if the internal types are primitive tempNamel and lt tempName2 gt are formed using the algorithm described above for pulling structured types out of the definition This form is used for constructed elements and elements that map to structured C types The example above would result in the following generated C typedefs ASNIC V5 8 49 typedef struct A x OSINT32 al OSBOOL a2 A x typedef struct A y OSUINT32 numocts OSOCTET data 10 A y typedef struct A Ax X Ay y A In this case elements x and y map to structured C types so temporary typedefs are generated In the case of nesting levels greater than two all of the intermediate element names are used to form the final name For example consider the following type definition that conta
9. SMITH stat rtInitContext amp ctxt if stat ASN OK printf rtInitContext failed check license n rtErrPrint amp ctxt return stat pu_setBuffer amp ctxt 0 0 aligned if stat asnlPE Employee amp ctxt amp employee ASN OK pe GetMsgPtr amp ctxt amp msglen msgptr else error processing Procedure for Using the C Control Class Encode Method The procedure to encode a message using the C class interface is as follows 1 Instantiate an ASN 1 PER encode buffer object ASN PEREncodeBuffer to describe the buffer into which the message will be encoded Two overloaded constructors are available The first form takes as arguments a static encode buffer and size and a Boolean value indicating whether aligned encoding is to be done The second form only takes the Boolean aligned argument This form is used to specify dynamic encoding 2 Instantiate an ASNIT ProdName object and populate it with data to be encoded 3 Instantiate an ASNIC_ lt ProdName gt object to associate the message buffer with the data to be encoded 4 Invoke the ASNIC_ lt ProdName gt object Encode method 5 Check the return status The return value is a status value indicating whether encoding was successful or not Zero ASN OK indicates success If encoding failed the status value will be a negative number The encode buffer method printErrorInfo can be invoked to get a textual e
10. lt name gt pvalue ASN1TagType tagging In this definition lt name gt denotes the prefixed production name defined above The pctxt argument is used to hold a context pointer to keep track of encode parameters This 1s a basic handle variable that is used to make the function reentrant so it can be used in an asynchronous or threaded application The user is required to supply a pointer to a variable of this type declared somewhere in his or her program The variable should be initialized using the rt nitContext run time library function see the C C Common Run Time Library Reference Manual for a complete description of this function The pvalue argument holds a pointer to the data to be encoded and is of the type generated from the ASN 1 production The tagging argument is for internal use when calls to encode functions are nested to accomplish encoding of complex variables It indicates whether the tag associated with the production should be applied or not implicit versus explicit tagging At the top level the tag should always be applied so this parameter should always be set to the constant ASNI EXPL for EXPLICIT ASNIC V5 8 109 The function result variable 1en returns the length of the data actually encoded or an error status code if encoding fails Error status codes are negative to tell them apart from length values Return status values are defined in the asn type h include file ASNIC V5 8 110 Generated C E
11. ASN OK printf Encoding was successful n printf Hex dump of encoded record n ncodeBuffer hexDump printf Binary dump Nn encodeBuffer binDump employee step 6 get start of message pointer and message length start of message pointer is start of msgbuf call getMsgLen to get message 1 msgptr encodeBuffer getMsgPtr len encodeBuffer getMsgLen else printf Encoding failed n encodeBuffer printErrorInfo ASNIC V5 8 ngth will return msgbuf 155 In general static buffers should be used for encoding messages where possible as they offer a substantial performance benefit over dynamic buffer allocation The problem with static buffers however is that you are required to estimate in advance the approximate size of the messages you will be encoding There is no built in formula to do this the size of exit 0 msgptr and len now describe fully encoded messag an ASN 1 message can vary widely based on data types and other factors If performance is not a significant issue then dynamic buffer allocation is a good alternative Using the form of the ASNIPEREncodeBuffer constructor that does not include buffer address and size arguments specifies dynamic buffer allocation This constructor only requires a Boolean value to specify whether aligned or unaligned encoding should be performed aligned is true The following code frag
12. In XER the non parameterized type name is used For example in the employee sample program the following element exists in the PersonnelRecord construct children 3 IMPLICIT SEQUENCE OF ChildInformation In XER this is encoded as follows Xchildren ChildInformation ChildInformation In XML it is as follows lt children gt lt element gt lt element gt It is done this way in order to match the XML schema generated for the ASN 1 specification ASNIC V5 8 176 The calling conventions for generated XML encode and decode functions are identical to those of XER that were presented in the previous section The only difference is the prefix of the generated functions For XER encode functions contain the asn XE_ prefix and decode functions have asn1XD For XML the prefixes are asn1XMLE and asnIXMLD respectively It is also important to note that the xsd switch is complementary to the xml switch when generating XML encoders and decoders This is because the XML schema produced from the ASN 1 specification using the xsd switch can be used to validate the XML messages generated using the XML encode functions Similarly an XML instance can be validated using the generated XML schema prior to decoding When C code generation is specified using the xml switch the generated EncodeTo and DecodeFrom methods in the PDU control class are set up to encode complete XML documents including the start doc
13. Step 1 Generate code MySeq SEQUENCE a INTEGER b BOOLEAN c UTFSString Step 2 Build Application XML document MySeq gt lt a gt 22 lt a gt lt b gt lt true gt lt b gt lt c gt Hello lt c gt MySeq gt ASNIC V5 8 XML Parser ASN1C generated SAX handlers C header file struct MySeq int a bool b char c C source file startElement characters endElement Populated data var 22 true Hello 170 ASNIC generates code to implement the following methods defined in the SAX content handler interface startElement characters endElement The interface defines other methods that can be implemented as well but these are sufficient to decode XER encoded data Procedure for Using the C Interface The ASNIC compiler generates XER decode functions for C for constructed types in a specification These can be invoked in the same manner as other decode functions In this case they install the generated SAX content handler functions and invoke the XML parser s parse function to parse a document The procedure to call these generated functions is described below Generated C Function Format and Calling Parameters The format of the name of each generated C XER decode function is as follows asnlXD prefix prodName where lt prodName gt is the name of the ASN 1 production for which the function i
14. The value argument contains the value to be encoded or holds a pointer to the value to be encoded This variable 1s of the type generated from the ASN 1 production The object is passed by value if it is a primitive ASN 1 data type such as BOOLEAN INTEGER ENUMERATED etc It is passed using a pointer reference if it is a structured ASN 1 type value in this case the name will be pvalue instead of value Check the generated function prototype in the header file to determine how this argument is to be passed for a given function The elemName and attributes arguments are used to pass the XML element name and attributes respectively The elemName argument is the name that will be included in the lt name gt lt name gt brackets used to delimit an XML item There are three distinct ways this argument can be specified 1 Ifit contains standard text this text will be used as the element name 2 Ifit is null a default element name will be applied Default names for all of the built in ASN 1 types are defined in the 2002 X 680 standard For example lt BOOLEAN gt is the default element name for the BOOLEAN built in type ee 3 Ifthe name is empty i e equal to a zero length string not to be confused with null then no element name is applied to the encoded data ASNIC V5 8 164 The function result variable stat returns the status of the encode operation Status code 0 ASN_OK indicates the function was successful A negat
15. 0r typedef struct lt tempNamel gt typedef struct lt tempName2 gt typedef struct int t union lt tempNamel gt elementi name lt tempName2 gt element2 name ASNIC V5 8 59 Fou name If the static command line option or storage static lt storage gt configuration variable is set for the given production then pointers will not be used for the variable declarations This is true for the C case only for C pointers must be used due to the fact that the generated code will not compile if constructors are used in a non pointer variable within a union construct The C mapping is the same with the exception that the 4SN T prefix is added to the generated type name lt typel gt and lt type2 gt are the equivalent C types representing the ASN 1 types lt element1 type gt and lt element2 type gt respectively lt tempNamel gt and lt tempName2 gt represent the names of temporary types that may have been generated as the result of using nested constructed types within the definition Choice alternatives may be unnamed in which case lt element name gt is derived from lt element type gt by making the first letter lowercase One needs to be careful when nesting CHOICE structures at different levels within other nested ASN 1 structures SEQUENCEs SETs or other CHOICEs A problem arises when CHOICE element names at different levels are not unique this is likely when elemen
16. ASN XEREncodeBuffer to describe the buffer into which the message will be encoded Constructors are available that allow a static message buffer to be specified and or canonical encoding to be turned on canonical encoding removes all encoding options from the final message to produce a single encoded representation of the data The default constructor specifies use of a dynamic encode buffer and canonical encoding set to off 2 Instantiate an ASNIT type object and populate it with data to be encoded 3 Instantiate an ASN1C_ lt type gt object to associate the message buffer with the data to be encoded 4 Invoke the ASNIC type object Encode method 5 Check the return status The return value is a status value indicating whether encoding was successful or not Zero ASN OK indicates success If encoding failed the status value will be a negative number The encode buffer method printErrorInfo can be invoked to get a textual explanation and stack trace of where the error occurred 6 Ifencoding was successful get the start of message pointer and message length The start of message pointer is obtained by calling the getMsgPtr method of the encode buffer object If static encoding was specified i e a message buffer address and size were specified to the PER Encode Buffer class constructor the start of message pointer is the buffer start address The message length is obtained by calling the getMsgLen method of the encode buffer obje
17. My ops opcode The My ops constraint on the opcode element specifies an information object set not shown that constrains the element value to one of the values in the object set The My ops opcode constraint on the argument element goes a step further it ties the type of the field to the type specified in the row that matches the given opcode value ASNIC generates an in memory table either an array or a list of structures for each of the items in the information object sets defined in a specification In the example above a table would be generated for the My ops information object set The code generated for the type would then use this table to verify that the given items in a structure that reference this table match the constraints ASNIC V5 8 88 The C or C type generated for the SEQUENCE above when tables is specified would be as follows typedef struct Invoke OSINT32 invokeID OPERATION operationCode opcode ASN10bject argument Invoke This is almost identical to the type generated in the simple case The difference is the ASN Object type or ASNITObject for C that is used instead of ASN OpenType This type is defined in the asn type h run time header file as follows typedef struct ASN1Object ASNl1OpenTyp ncoded void decoded OSINT32 index This holds the value to be encoded or decoded in both encoded or decoded form The way a user uses this to encode a value
18. The X 680 Open Type replaces the X 208 ANY or ANY DEFINED BY constructs An ANY or ANY DEFINED BY encountered within an ASN 1 module will result in the generation of code corresponding to the Open Type described below An Open Type as defined in the X 680 standard is specified as a reference to a Type Field in an Information Object Class The most common form of this is when the Type field in the built in TYPE IDENTIFIER class is referenced as follows TYPE IDENTIFIER amp Type See the section in this document on Information Objects for a more detailed explanation The Open Type is converted into a C or C structure used to model a dynamic OCTET STRING type This structure contains a pointer and length field The pointer is assumed to point at a string of previously encoded ASN 1 data When a message containing an open type is decoded the address of the open type contents field is stored in the pointer field and the length of the component is stored in the length field The general mapping of an Open Type to C C is as follows ASN 1 production lt name gt ANY Generated C code typedef ASN1OpenType lt name gt Generated C code typedef ASN1TOpenType lt name gt The difference between the two types is the C version contains constructors to initialize the value to zero or to a given open type value If the tables command line option is selected and the ASN 1 type definition references a table constraint the co
19. Thus all memory allocated by rtMemAlloc will be overwritten and data will be lost Procedure for Using the C Control Class Encode Method The procedure to encode a message using the C class interface is as follows 1 Create a variable of the ASNIT lt name gt type and populate it with the data to be encoded Create an ASNI BEREncodeBuffer object 3 Create a variable of the generated ASN C_ lt name gt class specifying the items created in 1 and 2 as arguments to the constructor 4 Invoke the Encode method The constructor of the ASNIC type class takes a message buffer object argument This makes it possible to specify a static encode message buffer when the class variable 1s declared A static buffer can improve encoding performance greatly as it relieves the internal software from having to repeatedly resize the buffer to hold the encoded message If you know the general size of the messages you will be sending or have a fixed size maximum message length then a static buffer should be used The message buffer argument can also be used to specify the start address and length of a received message to be decoded After the data to be encoded is set the Encode method is called This method returns the length of the encoded message or a negative value indicating that an error occurred The error codes can be found in the asnltype h run time header file or in Appendix A of the C C Common Functions Reference Manual If encoding is
20. and or ext ex appinfo tags enum ext default all if items not given attrs lt items gt generate non native attributes for items items is same as for appinfo targetns namespace Specify target namespace namespace is namespace URI if not given no target namespace declaration is added Note that this usage summary shows all options for the pro version of ASNIC Some of these options are not available in the basic version To use the compiler at a minimum an ASN 1 source file must be provided The source file specification can be a full pathname or only what is necessary to qualify the file If directory information is not provided the user s current default directory is assumed If a file extension is not provided the default extension asn is appended to the name Multiple source filenames may be specified on the command line to compile a set of files The wildcard characters and are also allowed in source filenames for example the command asnlc asn will compile all ASN 1 files in the current working directory The source file s must contain ASN 1 productions that define ASN 1 types and or value specifications This file must strictly adhere to the syntax specified in ASN 1 standard ITU X 680 The asnstd x208 command line option should be used to parse files based on the 1990 ASN 1 standard x 208 or that contain references to ROSE macro specifications The following table l
21. and these functions are being linked into the application even if they are not actually used But still the size of the final application created with maxcfiles option should be less than the size of the application created without this option Generated C C files and the compat Option ASNIC 5 6 and below did not generate separate files for common definitions encode and decode functions lt module Name gt c cpp lt moduleName gt Enc c cpp lt moduleName gt Dec c cpp All code was generated in a single file with ASNIC V5 8 100 the name lt moduleName gt c cpp If it is necessary to maintain this behavior then use the compat 5 6 option Also the behavior of the cfile option is slightly changed in ASNIC 5 7 In 5 6 and below the cfile option did not have any effect for files containing copy print compare etc functions For ASNIC 5 7 and above cfile causes everything to be output to one file the exception is if specific filename parameters are specified with genPrint genCopy etc Once again to maintain the previous behavior the compat 5 6 option can be used ASNIC V5 8 101 General Procedures for Encoding and Decoding Encoding functions and methods generated by the ASN1C compiler are designed to be similar in use across the different encoding rule types In other words if you have written an application to use the Basic Encoding Rules BER and then later decide to use the Packed Encoding Rules PER
22. decode functions Generate event handlers J Generate event handlers with no type definitions SAX parser Generate code to handle table constraints lt Back Cancel Help This allows options to be set that are only present in the professional version of the compiler Click on Help to get a summary of what each of these options do All of these items are optional Some items will be grayed out if they are not applicable to the encoding rules language combination selected on the previous page The Other Options tab is as follows ASNIC V5 8 17 ASN1IC compiler 5 80 Objective Systems Inc 3 objective SYSTEMS INC Code Reduction Options Code Addition Alter Options PRO Version Options Other Options Choose additional compiler options NOTE All of these items are optional m Other Options Generate listing Output compiler warning messages Output Directory Name c asnic dey c sample_beremployee E lt Back Cancel Help The Output Directory Name control at the bottom of the page allows you to specify where your generated code will be stored By default this is the same directory as the ASN 1 source files A different output can be selected by either typing the name directly into the box or clicking the button to open a file navigation window Once specification of these items is complete click Next to move to the next window T
23. freed The final step of the procedure is to close the stream and free the context block The function to free the context is rtFreeContext A program fragment that could be used to decode an employee record is as follows finclude employee h include file generated by ASNIC main int stat ASNICTXT ctxt PersonnelRecord employee ASN1ConstCharPtr filename message xml Step 1 Init context structure if rtInitContext amp ctxt ASN OK return 1 rtStreamInit amp ctxt Step 2 Open a stream stat rtStreamFileOpen amp ctxt filename OSRTSTRMF INPUT if stat ASN OK rtErrPrint amp ctxt errInfo return 1 Step 3 decode the record stat asnlXD PersonnelRecord amp ctxt amp employee if stat ASN OK if trace printf Decode of PersonnelRecord was successful Mn printf Decoded record Mn asnlPrint PersonnelRecord Employee amp employee else printf decode of PersonnelRecord failed n rtErrPrint amp ctxt errInfo rtStreamClose amp ctxt return 1 Step 4 Close the stream and free the context rtStreamClose amp ctxt ASNIC V5 8 173 rtFreeContext amp ctxt return 0 Procedure for Using the C Interface SAX handler methods are added to the C control class generated for each ASN 1 production The procedure to invoke the generated decode method is similar to that for
24. it should only be a simple matter of changing a few function calls to accomplish the change Procedures for such things as populating data for encoding accessing decoded data and dynamic memory management are the same for all of the different encoding rules This section describes common procedures for encoding or decoding data that are applicable to any of the different encoding rules Subsequent sections will then describe what will change for the different rules Dynamic Memory Management The ASNIC run time uses specialized dynamic memory functions to improve the performance of the encoder decoder It is imperative that the user understands how this methodology works in order to avoid memory problems in their applications ASNIC also provides the capability to plug in a different memory management scheme at two different levels the high level API called by the generated code and the low level API that provides the core memory managment functionality The ASNIC Default Memory Manager The default ASNIC run time memory manager uses an algorithm called the nibble allocation algorithm What this means is that large blocks of memory are allocated up front and then split up to provide memory for smaller allocation requests This reduces the number of calls required to the C malloc and free functions These functions are very expensive in terms of performance The large blocks of memory are tracked through the ASN 1 context block ASNICTXT struct
25. lt name gt ASNIC V5 8 45 The struct type provides a namespace for the enumerated elements This allows the same enumerated constant names to be used in different productions within the ASN 1 specification An enumerated item is specified in the code using the lt name gt lt id gt form Every generated definition contains a Root enumerated specification and optionally an Ext specification The Root specification contains the root elements of the type or all of the elements if it is not an extended type and the Ext specification contains the extension enumerated items The form of the typedef following the struct specification depends on whether or not the enumerated type contains an extension marker or not If a marker is present it means the type can contain values outside the root enumeration An OSUINT32 is always used in the final typedef to ensure a consistent size of an enumerated variable and to handle the case of unknown extension values NULL The ASN 1 NULL type does not generate an associated C or C type definition ASNIC V5 8 46 OBJECT IDENTIFIER The ASN 1 OBJECT IDENTIFIER type is converted into a C or C structured type to hold the subidentifier values that make up the object identifier ASN 1 production lt name gt OBJECT IDENTIFIER Generated C code typedef ASNIOBJID lt name gt Generated C code typedef ASN1TObjId ASN1T lt name gt In this case different base types are used
26. rtMemHeapFreePtr and rtMemHeapRealloc Note that there is no analog in standard memory management for ASNIC s rtMemFree macro i e the rtrMemHeapFreeAIl function A user would be responsible for freeing all items in a generated ASNIC structure individually if standard memory management is used The rtMemHeapCreate and rtMemHeapRelease functions are specialized functions used when a special heap is to be used for allocation for example a static block within an embedded system In this case rrMemHeapCreate must set the ppvMemHeap argument to point at the block of memory to be used This will then be passed in to all of the other memory management functions for their use through the ASNICTXT structure The rtMemHeapRelease function can then be used to dispose of this memory when it is no longer needed To add these definitions to an application program compile the C source file it can have any name and link the resulting object file OBJ or O in with the application Low Level Memory Management API It is possible to replace the core memory management functions used by the ASNIC run time memory manager This has the advantage of preserving the existing management scheme but with the use of different core functions One reason for doing this might be an embedded system that does not have the standard C run time functions malloc free and realloc To replace the core functions the following global variables must be defined in a standard C fil
27. setp amp ctxt msgbuf 0 amp msgtag amp msglen Step 2 Test message tag for type of message received note this is optional the decode function can be 7 called directly if the type of message is known xj msgtag TV PersonnelRecord Step 3 Call decode function note last two args should always be ASNIEXPL and 0 status asnlD PersonnelRecord amp ctxt amp employee ASNIEXPL 0 Step 4 Check return status if status ASN OK process received data in employee variable Remember to release dynamic memory when done rtMemFree amp ctxt else 121 error processing else check for other known message types Decoding a Series of Messages Using the C Decode Functions The above example is fine as a sample for decoding a single message but what happens in the more typical scenario of having a long running loop that continuously decodes messages It will be necessary to put the decoding logic into a loop A code fragment showing a way to do this is as follows main OSOCTET msgbuf 1024 ASNITAG msgtag int msglen ASNICTXT ctxt PersonnelRecord employee Step 1 Initialize a context variable for decoding if rtInitContext amp ctxt ASN OK initialization failed could be a license problem printf context initialization failed check license n return 1 for zy d logic to read message in
28. the C mapping is very similar to the C mapping However there are some important differences 1 As with all C types the prefix ASNIT is added before the typename to distinguish the data class from the control class the control class contains an ASN C_ prefix 2 A default constructor is generated to initialize the structure elements This constructor will initialize all elements and set any simple default values that may have been specified in the ASN 1 definition 3 If the genCopy command line switch was specified a copy constructor will be generated to allow an instance of the data contained within a PDU control class object to be copied 4 Also if genCopy was specified a destructor is generated if the type contains dynamic fields This destructor will free all memory held by the type when the object is deleted or goes out of scope SET The ASN 1 SET type is converted into a C or C structured type that is identical to that for SEQUENCE as described in the previous section The only difference between SEQUENCE and SET is that elements may be transmitted in any order in a SET whereas they must be in the defined order in a SEQUENCE The only impact this has on ASNIC is in the generated decoder for a SET type The decoder must take into account the possibility of out of order elements This is handled by using a loop to parse each element in the message Each time an item is parsed an internal mask bit within the decoder is set
29. 1 type is extensible or not The C mapping adds a struct wrapper around this type to provide a namespace to aid in making the enumerated values unique across all modules C Mapping ASN 1 production name ENUMERATED idi vall lt id2 gt lt val2 gt Generated code typedef enum idl vall id2 val2 lt name gt The compiler will automatically generate a new identifier value if it detects a duplicate within the source specification The format of this generated identifier is id_n where id is the original identifier and n is a sequential number The compiler will output an informational message when this is done This message is only displayed if the warnings qualifier is specified on the command line A configuration setting is also available to further disambiguate duplicate enumerated item names This is the enum prefix setting that is available at both the module and production levels For example the following would cause the prefix h225 to be added to all enumerated identifiers within the H225 module lt module gt lt name gt H225 lt name gt lt enumPrefix gt h225 lt enumPrefix gt lt module gt C Mapping ASN 1 production lt name gt ENUMERATED idl vall lt id2 gt lt val2 gt Generated code struct lt name gt enum Root idl vall id2 val2 enum Ext extidl extvall typedef OSUINT32 ASNIT
30. 183 shortnames 10 50 Simple API for XML 36 169 SNMP OBJECT TYPE macro 204 source code ANSI standard 24 source file for encode decode functions 6 for generated compare functions 7 for generated print functions 8 for generated print to stream functions 8 for generated print to string functions 8 special characters invalid 31 specification attribute in more thanone section 25 module 25 production 25 standard ITU X 680 5 startElement event 193 static 10 static sized SEQUENCE OF type definition 56 static array 55 static encode buffer for BER encoding 111 113 116 for PER encoding 156 storage ASNIC V5 7 array 27 dynamicArray 27 list 27 maxSize attribute 27 static 27 stream 10 108 111 119 132 140 stream open functions 172 stream oriented decode method C control class 146 syntax errors 31 T Table Constraint Code Generation 88 tables 62 67 TCAP 201 temporary types generating for SEQUENCE OF type def inition 57 test functions generated 189 toStream method 183 toString method 182 tree directory 24 TYPE IDENTIFIER 62 C C mapping 78 types import and export 200 U UniversalString type C C mapping 63 unnamed elements in SEQUENCE 51 uppercase letters when to use 31 UTCTime 64 UTCTime type C C mapping 64 UTF 8 64 UTF8String type C C mapping 62 V value specification binary string 69 character string 69 CHOICE 72 hexadecimal string 69 INTEGER 68 object identifier 70 SEQUENC
31. 35 EncodeFrom and DecodeTo methods are declared that wrap the respective compiler generated C encode and decode stream functions Standard Encode and Decode methods exist in the ASN CType base class for direct encoding and decoding to a memory buffer Command line options may cause additional methods to be generated For example if the print command line argument was specified a Print method is generated to wrap the corresponding C print function Specification of the XML encoding rules option xer or xm causes a number of additional methods to be generated for constructed types These additional methods are implementations of the standard Simple API for XML SAX content handling interface used to parse content from XML messages The startElement characters and endElement methods are implemented as well as additional support methods The control class is also defined to inherit from the ASNIXERSAXHandler base class as well as ASN1CType or one of its descendents The equivalent C and C type definitions for each of the various ASN 1 types follow ASNIC V5 8 36 BOOLEAN The ASN 1 BOOLEAN type is converted into a C type named OSBOOL In the global include file osSysTypes h OSBOOL is defined to be an unsigned character ASN 1 production lt name gt BOOLEAN Generated C code typedef OSBOOL lt name gt Generated C code typedef OSBOOL ASNIT lt name gt For example if B PRIVATE 10 BOOLEAN was define
32. BER messages encoded back to back then it is necessary to modify the buffer pointer in each iteration The getByteIndex method should be used at the end of loop to get the current offset in the buffer This offset should be used with the decode buffer object s setBuffer method call at the beginning of the loop to determine the correct buffer pointer and length OSUINT32 offset 0 for offset msglen set buffer pointer and its length to decode decodeBuffer setBuffer amp msgbuf offset msglen offset int curlen int msglen offset status decodeBuffer ParseTagLen msgtag curlen if status ASN OK handle error Now switch on initial tag value to determine what type of message was received switch msgtag case TV PersonnelRecord compiler generated constant if status employee Decode ASN OK decoding successful data in employeeData process received data else error processing ASNIC V5 8 127 break default handle unknown message type her switch get new offset offset decodeBuffer getByteIndex Need to reinitialize objects for next iteration if it is not last iteration if offset lt msglen employee memFreeAll end of loop BER Decode Performance Enhancement Techniques There are a number of different things that can be done in application code to improve BER dec
33. The configuration setting used to set the prefix is the lt typePrefix gt element This element specifies a prefix that will be applied to all generated typedef names and function names for the production The calling sequence for each generated copy function is as follows void asniCopy name ASNICTXT pctxt name pSrcValue name pDstValue In this definition lt name gt denotes the prefixed production name defined above The pointer to the context structure pctxt provides a storage area for the function to store all variables that have been copied The pSrcValue argument 1s used to pass a pointer to a variable to be copied The pDstValue argument is used to pass the pointer to the destination value The source value is then copied to the destination value field by field Memory will be allocated for dynamic fields via calls to the rtMemAlloc function If C is used cpp option is specified and PDU generation is not disabled noPDU config option is not used then the control class ASNIC name additionally will contain e A copy constructor that can be used to create an exact copy of the class instance The calling sequence is as follows ASNIC lt name gt ASN1C name amp orginal For example ASNIC PersonnelRecord ASN1C PersonnelRecord amp original e A getCopy method that creates a copy of the ASNIT lt name gt variable ASNIT name amp getCopy ASNIT name pDstData 0 ASNIC V5 8 1
34. The constructor arguments are a reference to an ASN MessageBufferIF message buffer interface type and a reference to an ASNIT lt name gt type The message buffer interface argument is a reference to an abstract message buffer or ASNIC V5 8 84 stream class Implementations of the interface class are available for BER DER PER or XER encode or decode message buffers or for a BER or XER encode or decode stream The ASNIT lt name gt argument is used to specify the data variable containing data to be encoded or to receive data on a decode call The procedure for encoding is to declare a variable of this type populate it with data and then instantiate the ASNIC_ lt name gt object to associate a message buffer object with the data to be encoded The Encode or Encode To method can then be called to encode the data On the decode side a variable must be declared and passed to the constructor to receive the decoded data Note that the ASN C class declarations are only required in the application code as an entry point for encoding or decoding a top level message or Protocol Data Unit PDU As of ASNIC version 5 6 control classes are only generated for ASN 1 types that are determined to be PDU s A type is determined to be a PDU if it is referenced by no other types This differs from previous versions of ASNIC where control classes were generated for all types This default behavior can be overridden by using a configuration file entry or the p
35. The format of the new type name is as follows where lt ObjectName gt is replaced with the information object name and lt FieldName gt is replaced with the name of the _ lt ObjectName gt lt FieldName gt field from within the object ASNIC V5 8 80 Information Object Set NOTE Information Object Set code generation is available for tables option only This additional code is generated to support the processing required to verify table constraints This code is intended for use only in compiler generated code Therefore it is not necessary for the average user to understand the mappings in order to use the product The information presented here is informative only to provide a better understanding of how the compiler handles table constraints Table constraint processing code to support Information Object Sets is generated in a header and source file with a C struct C class to hold the values The name of the header and source file are of the following format lt ModuleName gt Table h lt ModuleName gt Table c cpp In this definition lt ModuleName gt would be replaced with the name of the ASN 1 module in which the information object is defined C Code Generation A C global variable is generated containing an array of values for the ASN 1 CLASS definition Each structure in the array is the equivalent C structure representing the corresponding ASN 1 information object As of this writing a static a
36. a an INTEGER and b an OCTET STRING Simple SEQUENCE a INTEGER b OCTET STRING Assume an encoded value of this type contains a value of a 123 hex 7B and b contains the hex octets 0x01 0x02 0x03 The generated variable for the OCTET STRING will contain a data pointer So rather than allocate memory for this string and copy the data to it fast copy will simply store a pointer directly to the data in the buffer ASNIC V5 8 129 Simple a 123 Simple b numocts 3 Simple b data ptr Message buffer EXNGN The pointer stored in the data structure points directly at data in the message buffer No memory allocation or copy is done The user must keep in mind that if this technique is used the message buffer containing the decoded message must be available as long as the type variable containing the decoded data is in use This will not work in a producer consumer threading model where one thread is decoding messages and the next thread is processing the contents The producer thread will overwrite the buffer contents and therefore data referenced in the decoded message type variable that the consumer is processing This will also not work if the message buffer is an automatic variable in a function and the decoded result type is being passed out The result type variable will point at data in the buffer variable that has gone out of scope To set fast copy the rtSetFastCopy function must be i
37. a variable of the structure to be encoded a decode function can be called to decode a message from the stream If the return status indicates success the C variable that was passed as an argument will contain the decoded message contents Note that the decoder may have allocated dynamic memory and stored pointers to objects in the C structure After processing on the C structure is complete the run time library function rtMemFree should be called to free the allocated memory ASNIC V5 8 141 After stream processing is complete the stream is closed by invoking the rtStreamBufClose function A program fragment that could be used to decode an employee record is as follows include employee h include file generated by ASNIC main ASNITAG msgtag int msglen ASNICTXT ctxt PersonnelRecord employee const char filename message dat Step 1 Initialize a context variable for decoding if rtInitContext amp ctxt ASN OK initialization failed could be a license problem printf context initialization failed check license Nn return 1 rtStreamBufInit amp ctxt Step 2 Open the input stream to read data stat rtStreamFileOpen amp ctxt filename OSRTSTRMF INPUT if stat ASN OK rtErrPrint amp ctxt return stat Step 3 Test message tag for type of message received note this is optional the decode function can be x calle
38. an element to be an open type by using the lt isOpenType gt configuration setting This setting causes the ASNIC compiler to insert an Asn OpenType placeholder in place of the type that would have normally been used for the ASNIC V5 8 130 element The data in its original encoded form will be stored in the open type container when the message is decoded If fast copy is used only a pointer to the data in the message buffer is stored so large copies of data are avoided The data within the deferred decoding open type container can be fully decoded later by using a special decode function generated by the ASNIC compiler for this purpose The format of this function is as follows asnlD ProdName lt ElementName gt OpenType ASNICTXT pctxt lt ElementType gt pvalue Here lt ProdName gt is replaced with name of the type assignment and ElementName gt is replaced with name of the element In this function the argument pctxt is used to pass the a pointer to a context variable initialized with the open type data and the pvalue argument will hold the final decoded data value In following example decoding of the element id 1s deferred Identifier SEQUENCE id INTEGER oid OBJECT IDENTIFIER The following configuration file is required to indicate the element id is to be processed as an open type i e that it will be decoded later lt asnlconfig gt lt module gt lt name gt mod
39. be accomplished by using the rt nitContext function Also the context must be initialized for streaming operations by calling the rtStreamInit function ASNICTXT ctxt context variable if rtInitContext amp ctxt ASN OK initialization failed could be a license problem printf context initialization failed check license Nn return 1 rtStreamInit amp ctxt Initialize stream The next step is to create a stream object within the context This object is an abstraction of the output device to which the data is to be encoded and is initialized by calling one of the following functions rtStreamFileOpen rtStreamFileAttach e rtStreamSocketAttach r tStreamMemoryCreate e rtStreamMemoryAttach The flags parameter of these functions should be set to the OSRTSTRMF INPUT constant value to indicate an input stream is being created see the C C Common Run Time Library Reference Manual for a full description of these functions A decode function can then be called to decode the message If the return status indicates success ASN OK then the message will have been decoded into the given ASN 1 type variable The decode function may automatically allocate dynamic memory to hold variable length items during the course of decoding This memory will be tracked in the ASNIC V5 8 172 context structure so the programmer does not need to worry about freeing it It will be released when the context is
40. be maintained to allow for a properly indented printout A header file must first be created to hold our print handler class definition or the definition could be added to an existing header file This file will contain a class derived from the Asn NamedEventHandler base class as follows class PrintHandler public AsnlNamedEventHandler protected const char mVarName int mIndentSpaces public PrintHandler const char varName PrintHandler void indent virtual void startElement const char name int index 1 virtual void endElement const char name int index 1 virtual void boolValue OSBOOL value other virtual contents method declarations In this definition we chose to add the mVarName and mIndentSpaces member variables to keep track of these items The user is free to add any type of member variables he or she wants The only firm requirement in defining this derived class is the implementation of the virtual methods We implement these virtual methods as follows In startElement we print the name equal sign and opening brace void PrintHandler startElement const char name int index indent printf s n name mindentLevelt t In this simplified implementation we simply indent this is another private method within the class and print out the name equal sign and opening brace We then increment the indent level Note that this is a highly si
41. class for the type An instance of this class can be created using the list element within a generated structure as a parameter The helper methods can then be used to allocate and initialize an element and then append it to the list after it is populated See the cpp sample ber employee writer cpp file for an example of how this is done In this program the following logic is used to populate one of the elements in the children list for encoding ASNIT ChildInformation pChildInfo ASNIC SeqOfChildInformation listHelper encodeBuffer msgData children pChildInfo listHelper NewElement fill Name amp pChildInfo name Ralph T Smith pChildInfo dateOfBirth 19571111 listHelper Append pChildInfo In this example msgData is an instance of the main PDU class being encoded PersonnelRecord This object contains an element called children which is a linked list of ChildInformation records The code snippet illustrates how to use the generated control class for the list to allocate a record populate it and append it to the list Generation of Temporary Types for SEQUENCE OF Elements As with other constructed types the type variable can reference any ASN 1 type including other ASN 1 constructed types Therefore it is possible to have a SEQUENCE OF SEQUENCE SEQUENCE OF CHOICE etc When a constructed type or type that maps to a C structured type is referenced a temporary type is generated for use in the final p
42. classes EXTERNAL Type The ASN 1 EXTERNAL type is a useful type used to include non ASN 1 or other data within an ASN 1 encoded message This type is described using the following ASN 1 SEQUENCE EXTERNAL Hio UNIVERSAL 8 IMPLICIT SEQUENCE direct referenc OBJECT IDENTIFIER OPTIONAL indirect referenc INTEGER OPTIONAL data value descriptor ObjectDescriptor OPTIONAL encoding CHOICE single ASN1 type 0 ABSTRACT SYNTAX amp Type octet aligned 1 IMPLICIT OCTET STRING arbitrary 2 IMPLICIT BIT STRING The ASNIC compiler is used to create a meta definition for this structure This code will be always generated in the Asn1External h and Asn1External c cpp files The code will only be generated if the given ASN 1 source specification ASNIC V5 8 64 requires this definition The resulting C structure is populated just like any other compiler generated structure for working with ASN 1 data NOTE It is recommended that if a specification contains multiple ASN 1 source files that reference EXTERNAL all of these source files be compiled with a single ASNIC call in order to ensure that only a single copy of the AsnIExternal source files are generated EMBEDDED PDV Type The ASN 1 EMBEDDED PDV type is a useful type used to include non ASN 1 or other data within an ASN 1 encoded message This type is described using the following ASN 1 SEQUENCE
43. decodeTagAndLen failed n in printErrorInfo return 1 if in reset ASN OK printf reset failed n in printErrorInfo return 1 Now switch on initial tag value to determin type of message was received include file generated by ASNIC what 148 switch msgtag case TV PersonnelRecord compiler generated constant in employee if in getStatus ASN OK printf decode of PersonnelRecord failed n in printErrorInfo return 1 or employee DecodeFrom in case TV handle other known messages Need to reinitialize objects for next iteration mployee memFreeAll end of loop return 0 This is quite similar to the first example Note that we have pulled the ASNIT Employee and ASNIC Employee object creation logic out of the switch statement and moved it above the loop These objects can now be reused to process each received message The only other change was the call to employee memFreeAll that was added at the bottom of the loop Since the objects are not deleted to automatically release allocated memory we need to do it manually This call will free all memory held within the decoding context This will allow the loop to start again with no outstanding memory allocations for the next pass ASNIC V5 8 149 Generated PER Encode Functions PER encode decode functions are generated when the per switch is spec
44. document If C code generation is specified a control class is generated that contains an Encode method that wraps this function This function is invoked through the class interface to encode an ASN 1 message into the variable referenced in the msgData component of the class Generated C Function Format and Calling Parameters The format of the name of each generated XER encode function is as follows asnlXE lt prefix gt lt prodName gt where lt prodName gt is the name of the ASN 1 production for which the function is being generated and prefix is an optional prefix that can be set via a configuration file setting The configuration setting used to set the prefix is the lt typePrefix gt element This element specifies a prefix that will be applied to all generated typedef names and function names for the production The calling sequence for each encode function is as follows status asnlXE name ASNICTXT pctxt lt name gt value ASN1ConstCharPtr elemName ASN1ConstCharPtr attributes In this definition lt name gt denotes the prefixed production name defined above The pctxt argument is used to hold a context pointer to keep track of encode parameters This is a basic handle variable that is used to make the function reentrant so it can be used in an asynchronous or threaded application The user is required to supply a pointer to a variable of this type declared somewhere in his or her or her program
45. element references a simple defined type as above with no additional tagging or constraint information an optimization is done to reduce the size of the generated code This optimization is to generate a common name for the new temporary type that can be used for other similar references The form of this common name is as follows _SeqOf lt elementProdName gt So instead of this SomePDU addresses SEQUENCE OF AliasAddress The following equivalent type would be generated _SeqOfAliasAddress SEQUENCE OF AliasAddress The advantage is that the new type can now be easily reused if SEQUENCE OF AliasAddress is used in any other element declarations Note the illegal use of an underscore in the first position This is to ensure that no name collisions occur with other ASN 1 productions defined within the specification SET OF The ASN 1 SET OF type is converted into a C or C structured type that is identical to that for SEQUENCE OF as described in the previous section CHOICE The ASN 1 CHOICE type is converted into a C or C structured type containing an integer for the choice tag value t followed by a union u of all of the equivalent types that make up the CHOICE elements ASNIC V5 8 58 The tag value is simply a sequential number starting at one for each alternative in the CHOICE A define constant is generated for each of these values The format of this constant is T lt name gt _ lt elemen
46. file was chosen over embedding directives within the ASN 1 source itself due to the fact that ASN 1 source versions tend to change frequently An external configuration file can be reused with a new version of an ASN 1 module but internal directives would have to be reapplied to the new version of the ASN 1 code At the outer level of the markup is the asnlconfig asnlconfig tag pair Within this tag pair the specification of global items and modules can be made Global items are applied to all items in all modules An example would be the storage qualifier A storage class such as dynamic can be specified and applied to all productions in all modules This will cause dynamic storage pointers to be used for any embedded structures within all of the generated code to reduce memory consumption demands The specification of a module is done using the lt module gt lt module gt tag pair This tag pair can only be nested within the top level lt asnlconfig gt section The module is identified by using the required lt name gt lt name gt tag pair or by specifying the name as an attribute for example module name MyModule Other attributes specified within the module section apply only to that module and not to other modules specified within the specification A complete list of all module attributes is provided in the table at the end of this section The specification of an individual production is done using the lt production
47. get online help on specific options The Windows installation program should have installed an ASNIC Compiler option on your computer desktop and an ASNIC option on the start menu The wizard can be launched using either of these items The following shows the initial Window that is displayed ASN1C compiler 5 80 Objective Systems Inc 3 objective SYSTEMS INC Welcome to the ASN1C compiler wizard This Wizard helps you generate C C C Java amp XML Schema for an ASN 1 definition If you have any questions or concerns please email us at support obj sys com Objective Systems Inc http www obj sys com Next gt Cancel Help Caneel Hep This is a greeting window and no action is required Click Next to proceed to the next window ASNIC V5 8 12 ASN1IC compiler 5 80 Objective Systems Inc SYSTEMS INC 3 objective Select Source Files and Directories ASN 1 Files Include Directories Configuration Files In this window the ASN 1 file or files to be compiled are selected This is done by clicking the Add button on the right hand side of the top windows pane A file selection box will appear allowing you to select the ASN 1 files to be compiled Files can be removed from the pane by highlighting the entry and clicking the Remove button Include directories are selected in a similar manner in the middle pane These are directories the compil
48. gt For TypeField definitions an encode and decode function pointer and type size field is generated to hold the information of the type for the OpenType If the print option is selected a print function pointer is also added int lt FieldName gt Size int encode lt FieldName gt int decode lt FieldName gt void print lt FieldName gt For an Object Field lt ClassName gt lt FieldName gt For an ObjectSetField definition an array of class definitions is generated to hold the list of information objects lt ClassName gt lt FieldName gt In each of these definitions lt FieldName gt would be replaced with the name of the field without the leading amp lt TypeName gt would be replaced with the C type name for the ASN 1 Type lt ClassName gt would be replaced with the C type name of the class for the Information Object ASNIC V5 8 73 As an example consider the following ASN 1 class definition ATTRIBUTE is CLASS amp Type amp id OBJECT IDENTIFIER UNIQUE WITH SYNTAX WITH SYNTAX amp Type ID amp id This would result in the following definition in the C source file typedef struct ATTRIBUTE int TypeSize int encodeType ASNICTXT void ASNlTagType int decodeType ASNICTXT void ASN1TagType int ASNIOBJID id C Code generation The C abstract class generated to model an ASN 1 CLASS contains me
49. gt lt production gt tag pair This tag pair can only be nested within a module section The production is identified by using the required lt name gt lt name gt tag pair or by specifying the name as an attribute for example production name MyProd Other attributes within the production section apply only to the referenced production and nothing else A complete list of attributes that can be applied to individual productions is provided in the table at the end of this section When an attribute is specified in more than one section the most specific application 1s always used For example assume a lt typePrefix gt qualifier is used within a module specification to specify a prefix for all generated types in the module and another one is used to a specify a prefix for a single production The production with the type prefix will be generated with the type prefix assigned to it and all other generated types will contain the type prefix assigned at the module level Values in the different sections can be specified in one of the following ways 1 Using the lt name gt value lt name gt form This assigns the given value to the given name For example the following would be used to specify the name of the H323 MESSAGES module in a module section lt name gt H323 MESSAGES lt name gt 2 Flag variables that turn some attribute on or off would be specified using a single lt name gt entry For example to specify a given prod
50. include file generated by ASNIC main OSOCTET msgbuf 1024 ASNITAG msgtag int msglen stat ASNICTXT ctxt OSBOOL aligned TRUE PersonnelRecord employee logic to read message into msgbuf This example uses a static context block step 1 prepare the context block stat rtInitContext amp ctxt if stat ASN OK printf rtInitContext failed check license n rtErrPrint amp ctxt return stat pu_setBuffer amp ctxt msgbuf msglen aligned step 2 decode the record stat asnlPD PersonnelRecord amp ctxt amp employee if stat ASN OK process received data ASNIC V5 8 159 else error processing rtErrPrint amp ctxt step 3 free the context rtFreeContext amp ctxt Procedure for Using the C Control Class Encode Method The following are the steps are involved in decoding a PER message using the generated C class 1 Instantiate an ASN 1 PER decode buffer object ASN PERDecodeBuffer to describe the message to be decoded The constructor takes as arguments a pointer to the message to be decoded the length of the message and a flag indicating whether aligned encoding was used or not Instantiate an ASNIT_ lt ProdName gt object to hold the decoded message data Instantiate an ASNIC ProdName object to decode the message This class associates the message buffer object with the object that is to
51. int msglen stat ASNICTXT ctxt PersonnelRecord employee const char filename message dat Step 1 Initialize a context variable for decoding if rtInitContext amp ctxt ASN OK initialization failed could be a license problem printf context initialization failed check license n return 1 rtStreamBufInit amp ctxt Step 2 Open the input stream to read data stat rtStreamFileOpen amp ctxt filename OSRTSTRMF INPUT if stat ASN OK rtErrPrint amp ctxt return stat for Step 3 Test message tag for type of message received note this is optional the decode function can be called directly if the type of message is known stat rtStreamBufMark amp ctxt 32 if stat ASN OK rtErrPrint amp ctxt return stat stat berDecStrmTagAndLen amp ctxt amp msgtag amp msglen if stat ASN OK rtErrPrint amp ctxt return stat if msgtag TV PersonnelRecord stat rtStreamBufReset amp ctxt ASNIC V5 8 144 if stat ASN OK rtErrPrint amp ctxt return stat Step 4 Call decode function note last two args should always be ASNIEXPL and 0 stat asnlBSD PersonnelRecord amp ctxt amp employee ASNIEXPL 0 Step 5 Check return status if stat ASN OK process received data in employee variable else
52. interface example error handler class 196 198 example formatted print handler 194 how it works 193 how to use it 194 events 7 9 193 EXPAT interface library 175 Expat XML Parser 169 export of types 200 extEleml 53 extension elements in SEQUENCE 53 EXTERNAL type C C mapping 64 65 F fast copy 129 field fixed type 87 variable type 88 file platform mk 24 fixed type field 87 freeing allocated memory 121 125 127 145 147 149 function encode decode prototypes 83 G genBitMacros 41 genCompare 185 genCopy 54 186 GeneralizedTime 64 GeneralizedTime type C C mapping 64 generated BER decode function decoding a series of messages using C control class interface 125 generated C function format and calling parameters 119 generated C decode method format and calling pa ASNIC V5 7 rameters 120 performance consideration of dynamic memory man agement 128 procedure for calling C decode functions 120 procedure for using C control class decode method 124 generated BER encode function encoding a series of messages using C control class interface 114 117 generated C function format and calling parameters 109 generated C encode method format and calling pa rameters 111 procedure for calling C encode functions 111 procedure for using C control class encode method 115 generated BER stream oriented decode function decoding a series of messages using C control class interface 148 decoding a series o
53. is an object of the class generated for the given production The function result variable stat returns the status value from the PER encode function This status value will be ASN OK 0 if encoding was successful or a negative error status value if encoding fails Return status values are defined in the asnltype h include file The user must call the encode buffer class methods getMsgPtr and getMsgLen to obtain the starting address and length of the encoded message component Populating Generated Structure Variables for Encoding See the section Populating Generated Structure Variables for Encoding for a discussion on how to populate variables for encoding There is no difference in how it is done for BER versus how it is done for PER Procedure for Calling C Encode Functions This section describes the step by step procedure for calling a C PER encode function This method must be used if C code generation was done This method can also be used as an alternative to using the control class interface 1f C code generation was done Before a PER encode function can be called the user must first initialize an encoding context block structure The context block is initialized by either calling the rtNewContext function to allocate a dynamic context block or by calling rt nitContext to initialize a static block The user then must call pu setBuffer to specify a message buffer to receive the encoded message Specification of a dynamic message b
54. is much more difficult to find these boundaries in PER Our example can be found in the cpp sample_ber errorHandler subdirectory In this example we have purposely added a bogus element to one of the constructs within an encoded employee record The error handler will be invoked when this element is encountered Our recovery action will simply be to print out a warning message skip the element and continue As before the first step is to create a class derived from the Asn ErrorHandler base class This class is as follows class MyErrorHandler public AsnlErrorHandler public The error handler callback method This is the method that the user must override to provide customized error handling virtual int error ASNICTXT pCtxt ASNICCB pCCB int stat Simple enough All we are doing is providing an implementation of the error method Implementing the error method requires some knowledge of the run time internals In most cases it will be necessary to somehow alter the decoding buffer pointer so that the same field isn t looked at again If this isn t done an infinite loop can occur as the parser encounters the same error condition over and over again The run time functions xd NextElement or xd OpenType might be useful in the endeavor as they provide a way to skip the current element and move on to the next item Our sample handler corrects the error in which an unknown element is encountered within a SET constru
55. isPDU gt n a This is a flag variable that specifies that this production represents a Protocol Data Unit PDU This is defined as a production that will be encoded or decoded from within the application code This attribute only makes a difference in the generation of C classes Control classes that are only used in the application code are only generated for types with this attribute set Element Level These attributes can be applied at the element level by including them within an element section Name Values Description name element name This attribute identifies the element within a SEQUENCE SET or lt name gt CHOICE construct to which this section applies It is required lt isOpenType gt n a This is a flag variable an empty element in XML terminology that specifies that this element will be decoded as an open type i e skipped Refer to the section on deferred decoding for further information ASNIC V5 8 30 Compiler Error Reporting Errors that can occur when generating source code from an ASN 1 source specification take two forms syntax errors and semantics errors Syntax errors are errors in the ASN 1 source specification itself These occur when the rules specified in the ASN 1 grammar are not followed ASNIC will flag these types of errors with the error message Syntax Error and abort compilation on the source file The offending line number will b
56. message header Invoke SEQUENCE invokeID INTEGER opcode OPERATION amp 0perationCode argument OPERATION amp ArgumentType This is a very simple case that purposely omits a lot of additional information such as Information Object Set constraints that are typically a part of definitions such as this The reason this information is not present is because we are just interested in showing the items that the compiler is concerned with We will use this type to demonstrate the simple form of code generation We will then add table constraints and discuss what changes when the tables command line options 1s used The opcode field within this definition is an example of a fixed type field reference It is known as this because if you go back to the original class specification you will see that operationCode is defined to be of a specific type namely a ASNIC V5 8 87 choice between a local and global value The generated typedef for this field will contain a reference to the type from the class definition The argument field is an example of a variable type field In this case if you refer back to the class definition you will see that no type is provided This means that this field can contain an instance of any encoded type note in practice table constraints can be used with Information Object Sets to limit the message types that can be placed in this field The generated typedef for this field contai
57. not used in ASNIC C therefore the user must fetch the status value following a call such as this in order to determine if it was successful The getStatus method in the ASN OutputStream class is used for this purpose Also the method Encode without parameters is supported for backward compatibility In this case it is necessary to create control class i e ASN1C_ lt prodName gt using an output stream reference as the first parameter and msgdata reference as the second parameter of the constructor Procedure for Using the Stream Oriented C Control Class Encode Method The procedure to encode a message directly to an output stream using the C class interface is as follows 1 Create an ASNIBEROutputStream inherited object Create a variable of the ASNIT lt name gt type and populate it with the data to be encoded 3 Create a variable of the generated ASN C_ lt name gt class specifying the item created in 2 as an argument to the constructor 4 Invoke the EncodeTo method or operator ASNIC V5 8 136 A program fragment that could be used to encode an employee record is as follows This example uses a file output stream include employee h include file generated by ASNIC main int msglen const char filename message dat step 1 construct output stream object ASNIBERFileOutputStream out filename if out getStatus ASN OK out printErrorInfo return 1 ste
58. of the ASN 1 information object C objects As of this writing a static array is used to hold the objects but this could be changed to something like a linked list or hash without affecting the public interface to the class The class also contains an object lookup method for each of the key fields Key fields are identified in the class as either a fields that are marked unique or b fields that are referenced in table constraints with the notation The generated constructor initializes all required values and information objects An example of an information object set that uses the information object class defined above is as follows SupportedAttributes ATTRIBUTE name commonName E This results in the generation of the following C class class EXTERN SupportedAttributes protected ATTRIBUTE mObjectSet 2 const size_t mNumObjects static SupportedAttributes mpInstance SupportedAttributes ASNICTXT pctxt public ATTRIBUTE lookupObject ASNITObjId id static SupportedAttributes instance ASNICTXT pctxt The mObjectSet array is the container for the information object classes These objects are created and this array populated in the class constructor Note that this is a singleton class as evidenced by the protected constructor and instance methods Therefore the object set array 1s only initialized once the first time the instance method 1s invoked The other method of inter
59. of the element is passed to the event handling callback function 2 endElement This event occurs when the parser leaves a given element space Using the example above these would occur after the parsing of a b and c are complete The name of the element is once again passed to the event handling callback function 3 contents methods A series of virtual methods are defined to pass all of the different types of primitive values that might be encountered when parsing a message see the event handler class definition below for a complete list 4 error This event will be fired when a parsing error occurs It will provide fault tolerance to the parsing process as it will give the user the opportunity to fix or ignore errors on the fly to allow the parsing process to continue ASNIC V5 8 193 These events are defined as unimplemented virtual methods in two base classes Asn NamedEventHandler the first 3 events and Asn ErrorHandler the error event These classes are defined in the asn CppEvtHndir h header file The start and end element methods are invoked when an element is parsed within a constructed type The start method is invoked as soon as the tag length is parsed in a BER message or the preamble length is parsed in a PER message The end method is invoked after the contents of the field are processed The signature of these methods is as follows virtual void startElement const char name int index 0 virtual
60. of this type is as follows Populate a variable of the type to be used as the argument to the invoke type Plug the address of this variable into the decoded void pointer in the structure above Populate the remaining Invoke type fields Encode the Invoke type to produce the final message Bee Note that in this case the intermediate type does not need to be manually encoded by the user The generated encoder has logic built in to encode the complete message using the information in the generated tables Additional Code Generated with the tables option When the tables command line option is used additional code is generated to support the additional processing required to verify table constraints This code varies depending on whether C or C code generation is selected The C code is designed to take advantage of the object oriented capabilities of C These capabilities are well suited for modeling the behavior of information objects in practice The following subsections describe the code generated for each of these languages The code generated to support these constraints is intended for use only in compiler generated code Therefore it is not necessary for the average user to understand the mappings in order to use the product The information presented here is informative only to provide a better understanding of how the compiler handles table constraints C Code Generation For C code is generated for the Information Obje
61. productions to form a name of the form lt module gt _ lt name gt Note that name collisions can also be manually resolved by using the typePrefix enumPrefix and valuePrefix configuration items see the Compiler Configuration File section for more details warnings None Output information on compiler generated warnings xer None This option instructs the compiler to generate functions that implement the XML Encoding Rules XER as specified in the X 693 ASN 1 standard xml None This option instructs the compiler to generate functions that encode decode data in an XML format that is more closely aligned with World Wide Web Consortium W3C XML schema The xsd option can be used in conjunction with this option to generate a schema describing the XML format xsd lt filename gt This option instructs the compiler to generate an equivalent XML Schema Definition XSD for each of the ASN 1 productions in the ASN 1 source file The definitions are written to the given filename or to lt modulename gt xsd if the filename argument is not provided ASNIC V5 8 11 Using the GUI Wizard to Run ASNIC The Windows version of ASNIC includes a graphical user interface GUI wizard that can be used as an alternative to the command line version This makes it possible to specify ASN 1 files and configuration files via file navigation windows to set command line options by checking boxes and to
62. receive the decoded data The results of the decode operation will be placed in the variable declared in step 2 Invoke the ASNIC ProdName object Decode method Check the return status The return value is a status value indicating whether decoding was successful or not Zero ASN OK indicates success If decoding failed the status value will be a negative number The decode buffer method PrintErrorInfo can be invoked to get a textual explanation and stack trace of where the error occurred Release dynamic memory that was allocated by the decoder All memory associated with the decode context 1s released when both the ASN PERDecodeBuffer and ASNIC ProdName objects go out of scope A program fragment that could be used to decode an employee record is as follows finclude employee h include file generated by ASNIC main OSOCTET msgbuf 1024 int msglen stat OSBOOL aligned TRUE logic to read message into msgbuf step 1 instantiate a PER decode buffer object ASNIPERDecodeBuffer decodeBuffer msgbuf msglen aligned step 2 instantiate an ASNIT lt ProdName gt object ASNIC V5 8 160 ASNIT PersonnelRecord msgData step 3 instantiate an ASNI1C ProdName object ASN1C PersonnelRecord employ decodeBuffer msgData step 4 decode the record stat employee Decode step 5 check the return status if stat ASN OK process received data els
63. respectively These programs are generated using the genwriter and genreader command line switches ASNIC V5 8 189 ASNIC V5 8 190 Generated Makefile The genmake option causes a portable makefile to be generated to assist in the C or C compilation of all of the generated C or C source files This makefile contains a rule to invoke ASNIC to regenerate the c and h files if any of the dependent ASN 1 source files are modified It also contains rules to compile all of the C or C source files Header file dependencies are generated for all the C or C source files Two basic types of makefiles are generated 1 A GNU compatible makefile This makefile is compatible with the GNU make utility which is suitable for compiling code on Linux and many UNIX operating systems and 2 A Microsoft Visual Studio compatible makefile This makefile is compatible with the Microsoft Visual Studio nmake utility A GNU compatible makefile is produced by default the Microsoft compatible file is produced when the w32 command line option is specified in addition to genmake Both of these makefile types rely on definitions in the platform mk make include file This file contains parameters specific to different compiler and linker utilities available on different platforms Typically all the needs to be done to port to a different platform is to adjust the parameters in this file When a makefile is generated it is assumed that the ASNIC proj
64. rt nitContext run time function before use The pvalue argument is a pointer to a variable of the generated type that will receive the decoded data The tagging and length arguments are for internal use when calls to decode functions are nested to accomplish decoding of complex variables At the top level these parameters should always be set to the constants ASNIEXPL and zero respectively The function result variable status returns the status of the decode operation The return status will be zero ASN OK if decoding is successful or negative if an error occurs Return status values are defined in the asn1type h include file ASNIC V5 8 119 Generated C Decode Method Format and Calling Parameters Generated decode functions are invoked through the class interface by calling the base class Decode method The calling sequence for this method is as follows status lt object gt Decode In this definition lt object gt is an instance of the control class i e ASNIC prodName generated for the given production An ASNIBERDecodeBuffer object reference is a required argument to the lt object gt constructor This is where the message start address and length are specified The message length argument is used to specify the size of the message if it is known In ASN 1 BER or DER encoded messages the overall length of the message is embedded in the first few bytes of the message so this variable is not required It is
65. s decode method A program fragment that could be used to decode an employee record is as follows include employee h include file generated by ASNIC main ASNITAG tag int i len const char filename message dat OSBOOL trace TRUE Decode ASNIBERFileInputStream in filename if in getStatus ASN OK in printErrorInfo return 1 ASNIC V5 8 146 if in mark 32 ASN OK printf mark failed n in printErrorInfo return 1 if in decodeTagAndLen tag len ASN OK printf decodeTagAndLen failed n in printErroriInfo return 1 if in reset ASN OK printf reset failed n in printErrorInfo return 1 Now switch on initial tag value to determine what type of message was received switch msgtag case TV PersonnelRecord compiler generated constant ASNIT PersonnelRecord msgData ASN1C PersonnelRecord employ msgData in employee if in getStatus ASN OK printf decode of PersonnelRecord failed n in printErrorInfo return 1 or employee DecodeFrom in break case TV handle other known messages return 0 Note that the call to free memory and the stream close method are not required to release dynamic memory when using the C interface This is because the control class hides all of the details of managing the context and releasing d
66. that allow direct assignment of values in this from to the target variable The professional version of the ASNIC compiler will generate code for following remaining value definitions SEQUENCE e SET e SEQUENCE OF e SET OF CHOICE NOTE SEQUENCE SET SEQUENCE Of SET Of and CHOICE values are available only when the tables option is selected The values are initialized in a module value initialization function The format of this function name is as follows init_ lt ModuleName gt Value ASN1CTXT pctxt Where lt ModuleName gt would be replaced with the name of the module containing the value specifications The only required argument is an initialized context block structure used to hold dynamic memory allocated in the creation of the value structures If the value definitions are used in table constraint definitions then the generated table constraint processing code will handle the initialization of these definitions otherwise the initialization function must be called explicitly ASNIC V5 8 70 SEQUENCE Value Specification The mapping of an ASN 1 declaration to a global C or C value declaration is as follows ASN 1 production lt name gt lt SeqType gt lt value gt Generated code lt SeqType gt lt name gt The sequence value will be initialized in the value initialization function For example consider the following declaration SeqType SEQUENCE id INTEGER na
67. the installation to the build lib subdirectory on the target platform note if going from DOS to UNIX or vice versa FTP the files in ASCII mode to ensure lines are terminated properly 5 Edit the platform mk file in the root subdirectory and modify the compilation parameters to fit those of the compiler of the target system In general the following parameters will need to be adjusted CC C compiler executable name CCCC compiler executable name CFLAGS Flags that should be specified on the C or C command line The platform w32 and platform gnu files in the root directory of the installation are sample files for Windows 32 Visual C and GNU compilers respectively Either of these can be renamed to platform mk for building in either of these environments 6 Invoke the makefile in the build lib subdirectory If all parameters were set up correctly the result should be binary library files created in the lib subdirectory ASNIC V5 8 24 Compiler Configuration File In addition to command line options a configuration file can be used to specify compiler options These options can be applied not only globally but also to specific modules and productions A simple form of the XML is used to format items in the file This language was chosen because it is fairly well known and provides a natural interface for representing hierarchical data such as the structure of ASN 1 modules and productions The use of an external configuration
68. the other encoding rules It is as follows 1 Instantiate an ASN 1 XER decode buffer object 4SNIXERDecodeBuffer to describe the message to be decoded Constructors exist that allow an XML file or memory buffer to be specified as an input source Instantiate an ASNIT_ TypeName object to hold the decoded message data Instantiate an ASNIC TypeName object to decode the message This class associates the message buffer object with the object that is to receive the decoded data The results of the decode operation will be placed in the variable declared in step 2 Invoke the ASNIC 7ypeName object Decode method This method initiates and invokes the XML parser s parse method to parse the document This in turn invokes the generated SAX handler methods Error handling is accomplished using a try catch block to catch SAX exceptions In general ASNIC does not use exceptions because they are not portable in all situations and are inefficient in terms of performance However exceptions are part of the standard SAX interface so they are used in this case Release dynamic memory that was allocated by the decoder All memory associated with the decode context 1s released when both the ASNIXERDecodeBuffer and ASNIC T7ypeName objects go out of scope A program fragment that could be used to decode an employee record is as follows int main int argc char argv const char filename employee xml int stat note that a try c
69. tions DER encode function procedure for calling in C 111 DER encode function See also BER DER C encode func tions diagnostic messages adding to generated code 11 directory generated files 10 searching for IMPORT items 9 directory tree for porting run time code 24 Distinguished Encoding Rules 1 7 dynamic encode buffer 111 113 for BER encoding 116 for PER encoding 153 156 dynamic memory management 102 performance considerations in generated BER decode functions 128 performance considerations in generated PER decode functions 163 Dynamic SEQUENCE OF type 55 dynamicArray 55 E encode buffer dynamic for BER encoding 116 for PER encoding 153 156 encode buffer static for BER encoding 111 113 116 for PER encoding 156 encode function BER 109 prototype 83 Encode method 84 165 encode method C control class using in generated BER encode functions 115 using in generated BER stream oriented encode func tions 136 using in generated PER encode functions 153 160 using in generated XER encode functions 167 encode method using in generated C C source code 86 encode decode functions 207 suppressing 9 encoded message accessing 107 EncodeFrom method 36 86 EncodeTo method 84 136 encoding data 102 endElement event 193 ENUMERATED type C C mapping 45 error semantic 31 syntax 31 error event 193 error macro ROSE 203 error reporting compiler 31 event endElement 193 error 193 startElement 193 event handler
70. to stream functions are similar to print functions except that the output is written to a user provided stream instead of stdout The stream is in the form of an output callback function that can be set within the run time context making it possible to redirect output to any type of device The lt filename gt argument to this option is optional If not specified the functions will be written to lt modulename gt Print c where lt modulename gt is the name of the module from the ASN 1 source file genTables tables lt filename gt This option is used to generate additional code for the handling of table constraints as defined in the X 682 standard See the Generated Information Object Table Structures section for additional details on the type of code generated to support table constraints genTest lt filename gt This option allows the specification of a C or C source c or cpp file to which generated test functions will be written Test functions are used to populate an instance of a generated PDU type variable with random test data This instance can then be used in an encode function call to test the encoder Another advantage of these functions is that they can act as templates for writing your own population functions The lt filename gt argument to this option is optional If not specified the functions will be written to lt modulename gt Test c where lt modulename gt is the name of the mod
71. with a simplified calling interface for encoding and decoding a message They are not used in any of the ASNIC internally generated logic the exception to this rule is the XER XML encoding rules where they are used internally and still must be generated for all types A type is determined to be a PDU in two different ways 1 If it is explicitly declared to be PDU via the lt isPDU gt configuration setting or pdu command line option 2 Ifno explicit declarations exist a type is determined to be a PDU if it is not referenced by any other types In the employee sample program EmployeeNumber would not be considered to be a PDU because it is referenced as an element within the Employee production For the purpose of this discussion we will assume EmployeeNumber was explicitly declared to be a PDU via a configuration setting or command line specification ASNIC EmployeeNumber is the control class declaration The purpose of the control class is to provide a linkage between the message buffer object and the ASN 1 typed object containing the message data The class provides methods such as EncodeTo and DecodeFrom for encoding and decoding the contents to the linked objects It also provides other utility methods to make populating the typed variable object easier ASNIC always adds an ASNIC prefix to the production name to form the class name Most generated classes are derived from the standard ASN CType base class defined in asnIMessage h The fol
72. 203 ROSE OPERATION and ERROR 201 ROSE OPERATION and ERROR macros 1 ROSE OPERATION macro 5 87 rtBitClear 41 rtBitSet 41 rtBitTest 41 rtBMPToCString 63 rtBMPToNewCString 63 rtCToBMPsString 63 rtInitContext 109 165 171 rtInitContext function 111 172 rtMemAlloc 102 106 rtMemAllocZ 102 rtMemFree 102 106 113 121 123 129 180 rtMemFreePtr 103 180 rtMemHeapAlloc 104 rtMemHeapAllocZ 104 rtMemHeapCreate 104 rtMemHeapFreePtr 104 rtMemHeapRealloc 104 rtMemHeapRelease 104 rtMemRealloc 102 rtMemReset 123 129 rtNewContext 165 rtSetBit 42 rtSetFastCopy function 130 rtSetOID 70 rtStreamInit function 171 172 rtUTF8ToWCS 64 rtValidateUTF8 64 rtWCSToUTFS 64 rules Basic Encoding Rules 6 Distinguished Encoding Rules 7 Packed Encoding Rules 10 XML Encoding Rules 11 run time code porting to other platforms 24 211 run time library files 22 run time library ASN 1 22 S SAX 36 86 169 SAX API 175 SAX content handler interface 171 semantic errors 31 SEQUENCE value specification 71 SEQUENCE OF type C C mapping 55 dynamic 55 generating temporary types 57 list based SEQUENCE OF type 56 other constructed types 58 populating generated structures 56 static sized 56 SEQUENCE type C mapping 53 C C mapping 48 DEFAULT keyword 52 extension elements 53 OPTIONAL keyword 51 unnamed elements 51 SET OF type C C mapping 58 SET type C C mapping 54 setBuffer method 127 setErrorHandler method 198 setPrintStream method
73. 64 65 GeneralizedTime 64 INTEGER 37 NULL 46 OBJECT IDENTIFIER 47 OCTET STRING 42 Open Type 62 REAL 48 RELATIVE OID 48 SEQUENCE 48 SEQUENCE OF 55 SET 54 SET OF 58 TYPE IDENTIFIER 78 UniversalString 63 UTCTime 64 calling C BER or DER decode functions 120 calling C BER or DER encode functions 111 calling C BER stream oriented decode functions 141 calling C BER stream oriented encode functions 133 calling C PER decode functions 158 calling C PER encode functions 151 calling C XER decode functions 172 calling C XER encode functions 165 171 calling C XER decode functions 174 calling Java PER encode methods 91 95 calling parameters generated C for BER decode function 119 generated C for BER encode function 109 generated C for BER stream oriented decode function 140 generated C for BER stream oriented encode function 132 generated C for PER decode function 157 generated C for PER encode function 150 generated C for XER decode function 171 generated C for XER encode function 164 generated C for BER decode function 120 generated C for BER encode function 111 generated C for BER stream oriented decode func tion 145 generated C for BER stream oriented encode func tion 136 generated C for PER decode function 158 generated C for PER encode function 150 generated C for XER encode function 165 206 case importance in syntax errors 31 cfile 101 Character string type C C mapping 62 character string va
74. 8 lt valuePrefix gt prefix text This is used to specify a prefix that will be applied to all generated lt valuePrefix gt value constants within a module This can be used to prevent name clashes if multiple modules are involved that use a common name for two or more different value declarations lt classPrefix gt prefix text This is used to specify a prefix that will be applied to all generated lt classPrefix gt items in a module derived from an ASN 1 CLASS definition lt objectPrefix gt prefix text This is used to specify a prefix that will be applied to all generated lt objectPrefix gt items in a module derived from an ASN 1 Information Object definition lt objectsetPrefix gt prefix text This is used to specify a prefix that will be applied to all generated lt objectsetPrefix gt items in a module derived from an ASN 1 Information Object Set definition lt noPDU gt n a Indicates that this module contains no PDU definitions This is normally true in modules that are imported to get common type definitions for example InformationFramework This will prevent the C version of the compiler from generating any control class definitions for the types in the module lt intCType gt byte int16 uint16 This is used to specify a specific C integer type be used for all int32 uint32 int64 unconstrained integer type By default ASNIC will use the int32 string 32 bit integer type f
75. 86 For example ASNIT PersonnelRecord amp getCopy ASNIT PersonnelRecord pDstData 0 The pDstData argument is used to pass the pointer to a destination variable where the value will be copied It may be null in this case the new ASNIT lt name gt variable will be allocated via a call to the rtMemAlloc function e AnewCopy method that will create a new dynamically allocated copy of the referenced ASN T data member variable e Anassignment operator This is used to copy one instance of a control class to another one inline ASN1C name amp operator ASN1C name amp srcData srcData getCopy amp msgData return this For example inline ASN1C PersonnelRecord amp operator ASNIC PersonnelRecord amp srcData srcData getCopy amp msgData return this Finally the class declaration might look as follows class EXTERN ASN1C PersonnelRecord public ASN1CType protected ASNIT PersonnelRecord amp msgData public ASN1C PersonnelRecord ASN1MessageBuffer amp msgBuf ASNIT PersonnelRecord amp data ASNIC PersonnelRecord ASN1C PersonnelRecord amp original ASNIT PersonnelRecord amp getCopy ASNIT PersonnelRecord pDstData 0 ASN1T PersonnelRecord newCopy inline ASN1C PersonnelRecord amp operator ASN1C PersonnelRecord amp srcData ASNIC V5 8 187 srcData getCopy amp msgData return this The generated ASNIT lt name gt structure will also contai
76. E 71 SEQUENCE OF 71 SET 71 SET OF 72 type definition 68 valuePrefix attribute 29 variable type field 88 version 5 x compatible code generating 6 version brackets 53 212 VisibleString type C C mapping 62 W warnings 11 45 warnings output information 11 X X 208 201 X 209 201 xd setp 120 xe getp 111 xe setp 111 xer 36 XER decode function procedure for calling in C 174 procedure for using other C XML Parsers 175 XER encode function procedure for calling in C 165 171 procedure for calling in C 167 XER function prototypes 34 XERCES interface library 175 xerGetMsgLen 165 xerGetMsgPtr 165 xerSetEncBufPtr 165 xml 36 177 XML Encoding Rules 1 11 XML Parser 169 XML SAX content handler interface 86 xmlparser mk 191 xsd 11 177 ASNIC V5 7 213
77. EXTERN ASNIC EmployeeNumber public ASN1CType protected ASNIT EmployeeNumber amp msgData public ASNIC EmployeeNumber ASNIT EmployeeNumber data ASNI1C EmployeeNumber ASN1MessageBufferIF amp msgBuf ASNIT EmployeeNumber amp data standard encode decode methods defined in ASN1CType base class int Encode int Decode stream encode decode methods int EncodeTo ASN1MessageBufferIF amp msgBuf int DecodeFrom ASN1MessageBufferIF amp msgBuf EXTERN int asnlE EmployeeNumber ASNICTXT pctxt ASNIT EmployeeNumber pvalue ASN1TagType tagging EXTERN int asnlD EmployeeNumber ASNICTXT pctxt ASNIT EmployeeNumber pvalue ASN1TagType tagging int length ASNIC V5 8 34 Note the two main differences between this and the C version 1 The use of the ASN T_ prefix on the type definition The C version uses the ASN T_ prefix for the typedef and the ASN C_ prefix for the control class definition 2 The inclusion of the ASN C_EmployeeNumber control class As of ASNIC version 5 6 control classes are not automatically generated for all ASN 1 types The only types they are generated for are those determined to be Protocol Data Units or PDU s for short A PDU is a top level message type in a specification These are the only types control classes are required for because the only purpose of a control class is to provide the user
78. IC V5 8 180 Generated Print Functions The following options are available for generating code to print the contents of variables of generated types print This is the standard print option that causes print functions to be generated that output data to the standard output device stdout genPrtToStr This option causes print functions to be generated that write their output to a memory buffer genPrtToStrm This option causes print functions to be generated that write their output to an output stream via a user defined print callback function Print to Standard Output The print option causes functions to be generated that print the contents of variables of generated types to the standard output device It is possible to specify the name of a c or cpp file as an argument to this option to specify the name of the file to which these functions will be written This is an optional argument If not specified the functions are written to separate files for each module in the source file The format of the name of each file is lt module gt Print c If an output filename is specified after the print qualifier all functions are written to that file The format of the name of each generated print function is as follows asnlPrint prefix prodName where lt prodName gt is the name of the ASN 1 production for which the function is being generated and prefix is an optional prefix that can be set via a configuration file sett
79. INTEGER OSINT32 arg OSINT32 msgData argument decoded else error processing In this case the type of the decoded argument can be determined by testing the key field value In the example as shown the SupportedAttributes information object set is not extensible therefore the type of the argument must be one of the two shown If the set were extensible indicated by a in the definition then it is possible that an unknown opcode could be received which would mean the type can not be determined In this case the original encoded message data would be present in msgData argument encoded field and it would be up to the user to determine how to process it The decoding procedure for C requires one additional step This is a call to the module initialization functions after context initialization is complete All module initialization functions for all modules in the project must be invoked The module initialization function definitions can be found in the lt ModuleName gt Table h file A C program fragment that could be used to decode the nvoke example is as follows include TestTable h include file generated by ASNIC main OSOCTET msgbuf 1024 ASNITAG msgtag int msglen ASNICTXT ctxt Invoke invoke ASNIOBJID oidl 3 0 1 1 ASNIOBJID oid2 3 0 1 2 logic to read message into msgbuf Step 1 Initialize a context variable for decoding if rtInitContex
80. N int asnlD EmployeeNumber ASNICTXT pctxt EmployeeNumber pvalue ASN1TagType tagging int length This corresponds to the following ASN 1 production specification EmployeeNumber APPLICATION 2 IMPLICIT INTEGER In this definition TV EmployeeNumber is the tag constant Doing a logical OR on the class form and identifier fields forms this constant This constant can be used in a comparison operation with a tag parsed from a message ASNIC V5 8 33 The following line typedef OSINT32 EmployeeNumber declares EmployeeNumber to be of an integer type note OSINT32 and other primitive type definitions can be found in the osSysTypes h header file asnlE EmployeeNumber and asn1D_EmployeeNumber are function prototypes for the encode and decode functions respectively These are BER function prototypes If the per switch is used PER function prototypes are generated The PER prototypes begin with the prefix asn1PE and asn1PD for encoder and decoder respectively XER function prototypes begin with asn XE_ and asn1XD A sample section from a C header file for the same production is as follows RR KR KR KKK KKK KK KR KK KK KK IR OK KK IR RK RK kk k koe k koe ke ke e ke ke x JP a EmployeeNumber e is ist RR RR KK RK KKK KK KR KK RK KK RK KKK IK kk kk ko kk kc ko k koe ke ke ke ke ke x x fdefine TV EmployeeNumber TM APPL TM PRIM 2 typedef OSINT32 ASNIT EmployeeNumber class
81. Name c asnll These contain the functions to decode Name and encode Name respectively Similar files would be generated for the other productions in the module as well Generated C files In general the generation logic for C is similar to the logic for C Instead of the c file extension cpp is used ASNIC V5 8 99 lt moduleName gt cpp Common definitions and functions for example asnlFree_ lt type gt and or global value constant definitions This file also contains constructors destructors and all methods for ASNIC Type and ASNIT_ lt Type gt control classes lt moduleName gt Enc cpp C encode functions and C encode methods lt moduleName gt Dec cpp C decode functions and C decode methods If additional options are used such as genPrint genCopy etc additional files will be generated lt moduleName gt Copy cpp copy functions generated if genCopy is specified lt moduleName gt Print cpp print functions generated if genPrint is specified lt moduleName gt Compare cpp comparison functions generated if genCompare is specified lt moduleName gt PrtToStr cpp print to string functions generated if genPrtToStr is specified lt moduleName gt PrtToStrm cpp print to stream functions generated if genPrtToStrm is specified lt moduleName gt Table cpp table constraint functions generated if genTable option is specified lt moduleName gt Test cpp test functions generate
82. NamedBS bs memset amp bs 0 sizeof bs rtSetBit bs data 10 NamedBS bitOne The statement to clear the bit using rtClearBit would be as follows rtClearBit bs data 10 NamedBS bitOne Finally the bit could be tested using rtTestBit with the following statement if rtTestBit bs data 10 NamedBS bitOne bit is set Note that the compiler generated a fixed length data array for this specification It did this because the maximum size of the string is known due to the named bits it must only be large enough to hold the maximum valued named bit constant ASNICBitStr Control Class When C code generation is specified a control class is generated for operating on the target bit string This class is derived from the ASN CBitStr class This class contains methods for operating on bits within the string Objects of this class can also be declared inline to make operating on bits within other ASN 1 constructs easier For example in a SEQUENCE containing a bit string element the generated type will contain a public member variable containing the ASN T type that holds the message data If one wanted to operate on the bit string contained within that element they could do so by using the ASNI CBitStr class inline as follows ASNICBitStr bs seqVar element bs set 0 In this example lt seqVar gt would represent a generated SEQUENCE variable type and element would represent a bit string element within this typ
83. R stream oriented encode function generated C encode method format and calling pa rameters 136 generated stream oriented C function format and call ing parameters 132 procedure for calling C stream oriented encode func tions 133 procedure for calling in C 133 big integers 38 binary string value specification 69 bit string for specifying named constants for bit positions 41 BIT STRING type C C dynamic 39 C C mapping 39 C C static sized 40 Named Bits 41 bitMacros 6 BMPString type C C mapping 63 BOOLEAN type C C mapping 37 C c 6 c 6 c 6 C control class 35 84 C control class decode method procedure for using in generated XER decode func tions 174 C control class decode method procedure for using 124 C control class encode method procedure for using in generated BER encode func tions 115 procedure for using in generated BER stream orient ed encode functions 136 procedure for using in generated PER encode func tions 153 160 procedure for using in generated XER encode func tions 167 C control class interface decoding a series of message 125 148 decoding a series of PER messages 162 encoding a series of BER messages 114 117 137 encoding a series of PER messages 157 ASNIC V5 7 C control class stream oriented decode method proce dure for using 146 C C mapping ABSTRACT SYNTAX 78 BIT STRING 39 BMPsString 63 BOOLEAN 37 Character strings 62 CHOICE 58 ENUMERATED 45 EXTERNAL
84. Support In C and C the maximum size for an integer type is normally 64 bits or 32 bits on some older platforms ASN 1 has no such limitation on integer sizes and some applications security key values for example demand larger sizes In order to accommodate these types of applications the ASN1C compiler allows an integer to be declared a big integer via a configuration file variable the lt isBigInteger gt setting is used to do this see the section describing the configuration file for full details When the compiler detects this setting it will declare the integer to be a character string variable instead of a C int or unsigned int type The character string would then be populated with a character string representation of the value to be encoded Supported character string representations are hexadecimal strings starting with Ox octal strings starting with 00 and decimal no prefix For example the following INTEGER type might be declared in the ASN 1 source file SecurityKeyType APPLICATION 2 INTEGER Then in a configuration file used with the ASN 1 definition above the following declaration can be made lt production gt lt name gt SecurityKeyType lt name gt lt isBigInteger gt lt production gt ASNIC V5 8 38 This will cause the compiler to generate the following type declaration typedef const char SecurityKeyType The SecurityKeyType variable can now be populated with a hexadecima
85. a in encoded form For the above complete example the nvoke type s argument element will be decoded as one of the types in the SupportedAttributes information object set 1 e either as a VisibleString or INTEGER type If the SupportedAttributes information object set is extensible then the argument element may be of a type not defined in the set In this case the decoder will set the Asn1 Object encoded field as before but the Asn 1 Object decoded field will be NULL indicating the value is of an unknown type A C program fragment that could be used to decode the Invoke example is as follows include Test h include file generated by ASNIC main OSOCTET msgbuf 1024 ASNITAG msgtag int msglen status step 1 logic to read message into msgbuf step 2 create decode buffer and msg data type ASNIBERDecodeBuffer decodeBuffer msgbuf len ASN1T_ Invoke msgData ASNIC Invoke invoke decodeBuffer msgData step 3 call decode function if status invoke Decode ASN OK decoding successful data in msgData use key field value to set type of message data ASNIOBJID oidl 3 0 1 1 ASNIC V5 8 95 ASNIOBJID oid2 3 0 1 2 if msgData opcode oidl argument is a VisibleString ASN1VisibleString pArg ASN1VisibleString msgData argument decoded else if msgData opcode o1id2 argument is an
86. a new file will be started with an 1 appended for example moduleName Enc l c Additional files will be numbered sequentially if necessary 2 3 etc Note that this limit is a lower threshold and not exact A complete compilation unit for example a function will not be split because of this threshold The way it works is the threshold is checked before the output of a compilation unit If it is found to be exceeded a new file is started at that time Therefore a user should plan for a reserve to be in place above the limit to compensate for this overflow The reason for having this limit is because some C C compilers have problems with very large c files For example one product will not allow the debugger to work on lines in a file over the 64k threshold Use of the maxcfiles Option The maxcfiles option allows generation of more compact code by putting each encode decode copy compare etc func tion into a separate file This allows the linker to link in only the required functions as opposed to all functions in a com piled object module This option might be useful for applications that have minimal space requirements for example embedded systems NOTE Some sophisticated linkers have the capability to pull individual functions out of an object module directly for final inclusion in the target executable or shared object file In this case the maxcfiles option does not provide any advantage in reducing the size of the a
87. a pointer to a variable of the item to the first item to be compared The pCmp Value argument is used to pass the second value The two items are then compared field by field for equality The errBuff and errBuffSize arguments are used to describe a text buffer into which information on what fields the comparison failed on is written These arguments specify a fixed size buffer if the generated text is larger than the given buffer size the text is terminated The return value of the function is a Boolean value that is true if the variables are equal and false if they are not ASNIC V5 8 185 Generated Copy Functions The genCopy option causes copy functions to be generated These functions can be used to copy the content of one generated type variable to another If no output file is specified with the genCopy qualifier the functions are written to separate c cpp files for each module in the source file The format of the name of each file is lt module gt Copy c cpp where lt module gt would be replaced with the name of the ASN 1 module If an output filename is specified after the genCopy qualifier all functions are written to that file The format of the name of each generated copy function is as follows asnlCopy_ prefix prodName where lt prodName gt is the name of the ASN 1 production for which the function is being generated and prefix is an optional prefix that can be set via a configuration file setting
88. ains message pointer and length from previous step Final encoded message On the decode side the process would be reversed with the message flowing up the stack 1 At the ROSE layer the header would be decoded producing information on the OPERATION type based on the MACRO definition and message type Invoke Result etc The invoke identifier would also be available for use in session management In our example we would know at this point that we got a login invoke request 2 Based on the information from step 1 the ROSE layer would know that the Open Type field contains a pointer and length to an encoded Login ARGUMENT component It would then route this information to the appropriate ASNIC V5 8 202 processor within the Application Layer for handling this type of message 3 The Application Layer would call the specific decoder associated with the Login ARGUMENT It would then have available to it the username password the user is logging in with It could then do whatever application specific processing is required with this information database lookup etc 4 Finally the Application Layer would begin the encoding process again in order to send back a Result or Error message to the Login Request A picture showing this is as follows Call specific function to decode Login ARGUMENT and process data Application Layer A Encoded message pointer and length Decode ROSE header message structure Invoke ROSE Layer Open typ
89. alues are defined in the asn type h include file Another way to decode message using the C class interface is to use the gt gt stream operator lt inputStream gt gt gt lt object gt Exceptions are not used in ASNIC C therefore the user must fetch the status value following a call such as this in order to determine if it was successful The getStatus method in the ASN InputStream class is used for this purpose Also the method Decode without parameters is supported for backward compatibility In this case it is necessary to create a control class object i e ASN1C_ lt prodName gt using an input stream reference as the first parameter and a reference to a variable of the generated type as the second parameter of the constructor Procedure for Using the Stream Oriented C Control Class Decode Method Normally the receiving message can be one of several different message types It is therefore necessary to determine the type of message that was received so that the appropriate decode function can be called to decode it The ASNIBERInputStream class has standard methods for parsing the initial tag length from a message to determine the type of message received These calls are used in conjunction with a switch statement on generated tag constants for the known message set Each switch case statement contains logic to create an object instance of a specific ASNIC generated control class and to invoke and then to invoke that object
90. ames are specified as an attribute list Name Values Description name module name This attribute identifies the module to which this section applies It is lt name gt required lt include ASN 1 type or value This item allows a list of ASN 1 types and or values to be included in the generated code By default the compiler generates code for all types and values within a specification This allows the user to reduce the size of the generated code base by selecting only a subset of the types values in a specification for compilation Note that if a type or value is included that has dependent types or values for example the element types in a SEQUENCE SET or CHOICE all of the dependent types will be automatically included as well types names values names names are specified as an attribute list include ASN 1 module name s This form of the include directive tells the compiler to only include importsFrom specified as an attribute types and or values in the generated code that are imported by the name 7 list given module s exclude ASN 1 type or values This item allows a list of ASN 1 types and or values to be excluded in the generated code By default the compiler generates code for all types and values within a specification This is generally not as useful as in include directive because most types in a specification are referenced by other types If an attempt is made to exclude a type or val
91. anana 114 Procedure for Using the C Control Class Encode Method celles 115 Encoding a Series of Messages Using the C Control Class Interface 0 0000005 117 GENERATED BER DECODE FUNCTIONS 1 ee e een eae 119 Generated C Function Format and Calling Parameters cesses 119 Generated C Decode Method Format and Calling Parameters eee eese 120 Procedure for Calling C Decode Functions essc 120 Decoding a Series of Messages Using the C Decode Functions cicli 122 Procedure for Using the C Control Class Decode Method 2c cece eee 124 Decoding a Series of Messages Using the C Control Class Interface sisse 125 BER Decode Performance Enhancement Techniques eee 128 BER DER Deferred Decoding esee 130 GENERATED BER STREAM ORIENTED ENCODE FUNCTIONS 0 sese 132 Generated Stream Oriented C Function Format and Calling Parameters lesus 132 Procedure for Calling Stream Oriented C Encode Functions eei c cece 133 Encoding a Series of Messages Using the Stream Oriented C Encode Functions 134 ite eee ane ss ct en ede ees ee chad eas fe ee ect ae ete oe a ee tae eat ee eda eka tS 136 Generated Stream Oriented C Encode Method Format and Calling Parameters 136 Procedure for Using the Stream Oriented C Control Class Encode Method 136 Encoding a Series of Messages Using the Stream Oriented C Control Class In
92. at are not referenced by any other types as PDU types This behavior can be overridden by using the pdu command line argument or lt isPDU gt configuration file element The significance of PDU types is that generated classes for these types are derived from the ASNITPDU base class This class holds a reference to a context object The context object is set by Decode and copy methods Thus even if control class and message buffer objects go out of scope the memory will not be freed until the destructor of an ASNITPDU inherited class is called The example above will work correctly without any modifications in this case Another way to keep data is to make a copy of the decoded object before it goes out of scope A method called newCopy is also generated in the control class for these types which can be used to create a copy of the decoded object This copy of the object will persist after the control class and message buffer objects are deleted The returned object can be deleted using the standard C delete operator when it is no longer needed Returning to the example above it can be made to work if the type being decoded is a PDU type by doing the following ASNI1T type func2 ASNIT type msgdata ASNIC V5 8 105 ASNIBERDecodeBuffer decbuf ASNIC_ lt type gt cc decbuf msgdata cc Decode Use newCopy to return a copy of the decoded item return cc newCopy The copy returned must be explicitly del
93. atch block must be used to catch SAX exceptions try steps 1 2 and 3 instantiate an instance of the XER decoding classes This example specifies an XML file as the message input source ASNIT PersonnelRecord employee ASNIXERDecodeBuffer decodeBuffer filename ASNIC PersonnelRecord employeeC decodeBuffer employee step 4 invoke the decode method ASNIC V5 8 174 stat employeeC Decode if ASN OK stat employeeC Print employee else printf stat d n stat step 5 catch SAX exceptions note the StrX constructor transcodes Unicode characters to ASCII All internal XML parser data is formatted as Unicode catch const SAXException amp toCatch cerr lt lt nAn error occured n Error lt lt StrX toCatch getMessage An endl stat ASN E XMLPARSE Ne step 6 dynamic memory is released when employeeC and decode buffer objects go out of scope return stat Procedure for Interfacing with Other C and C XML Parser Libraries As mentioned previously the Expat XML Parser library is the default XML parser library implementation used for decoding XER messages It is also possible to use the C SAX handlers generated by ASNIC with other XML parser library implementations The XER Run Time Library ASN1 XER provides a common interface to other parsers via a common adapter interface layer The
94. ate XER compatible Xml Schema Change target namespace lac Ro Em Generate an applnfo annotation for v Generate non native attributes for Al cmo uee This allows options specific to XML Schema to be selected The user can specify that annotation application information lt appinfo gt be added for ASN 1 tag values This application information can be used by an XML data binding application to generate BER or DER encoders decoders directly from the schema definition The user can also specify that the generated schema be compatible with the ASN 1 XML encoding rules XER By default the generated schema is compatible with the standard XML schema types Once complete click Next to proceed to the final page The final window is as follows ASNIC V5 8 20 ASN1C compiler 5 80 Objective Systems Inc 3 objective SYSTEMS INC ASNIC compiler command C Sacv580 SbinNasnlc exe C asnic devic sample_ber employee employee asn c ber 0 C asnic dev c sample_ber employee compile ASNIC Compiler Version 5 80 Copyright c 1997 2005 Objective Systems Inc All Rights Reserved License expire date is Thu Dec 15 08 39 39 2005 Parsing 4SN 1 definitions Writing C type definitions to file C asn1c dev c sample_beremployee Employee h Writing C common definitions functions to file C asn1c dev c sample_beremployee E mployee c Writing C encode functions to file C asnic dev c sampl
95. ate aa bb and cc parent gt a amp aa parent gt b amp bb parent gt c amp cc ASNIC V5 8 106 main Parent parent fillParent amp parent encodeParent amp parent error pointers in parent reference memory that is out of scope In this example the automatic variables aa bb and cc go out of scope when the fi Parent function exits Yet the parent structure is still holding pointers to the now out of scope variables this type of error is commonly known as dangling pointers Using the second technique 1 e using C malloc and free can solve this problem In this case the memory for each of the elements can be safely freed after the encode function is called But the downside is that a free call must be made for each corresponding malloc call For complex structures remembering to do this can be difficult thus leading to problems with memory leaks The third technique uses the compiler run time library memory management functions to allocate and free the memory The main advantage of this technique as opposed to using C malloc and free is that all allocated memory can be freed with a single rtMemFree call The rtMemAlloc macro can be used to allocate memory in much the same way as the C malloc function with the only difference being that a pointer to an initialized ASNICTXT structure 1s passed in addition to the number of bytes to allocate All allocated memory is tracked within the context structu
96. ate any structures or code related to the OPERATION itself for example code to encode the body and header in a single step The reason is because of the multi layered nature of the protocol It is assumed that the user of such a protocol would be most interested in doing the processing in multiple stages hence no single function or structure is generated Therefore to encode the login example the user would do the following 1 At the application layer the Login ARGUMENT structure would be populated with the username and password to be encoded 2 The encode function for Login ARGUMENT would be called and the resulting message pointer and length would be passed down to the next layer the ROSE layer 3 At the ROSE layer the Invoke structure would be populated with the OPERATION value invoke identifier and other header parameters The parameter numocts value would be populated with the length of the message passed in from step 2 The parameter data field would be populated with the message pointer passed in from step 2 4 The encode function for Invoke would be called resulting in a fully encoded ROSE Invoke message ready for transfer across the communications link The following is a picture showing this process Application Layer Populate specific message structure Login ARGUMENT and encode Encoded message pointer and length PopulateROSE header message structure Invoke and encode ROSE L s OS ayer Open type structure cont
97. bject For an Object Field class ClassName FieldName ASNIC V5 8 74 In each of these definitions lt FieldName gt would be replaced with the name of the field without the leading amp lt TypeName gt would be replaced with the C type name for the ASN 1 Type lt ClassName gt would be replaced with the C type name of the class for the Information Object lt ER gt would be replaced by an encoding rules type BER PER or XER As an example consider the following ASN 1 class definition ATTRIBUTE CLASS amp Type amp ParameterType OPTIONAL amp id OBJECT IDENTIFIER UNIQUE WITH SYNTAX WITH SYNTAX amp Type ID amp id This would result in the following definition in the C source file class EXTERN ATTRIBUTI protected ASNITObjId id GI ATTRIBUTE public virtual int encodeBERType ASNICTXT pctxt ASN1TObject amp object 0 virtual int decodeBERType ASNICTXT pctxt ASN1TObject amp object 0 OSBOOL isParameterTypePresent if m ParameterTypePresent return TRUE else return FALSE virtual int encodeBERParameterType ASNICTXT pctxt ASN1TObject amp object return 0 virtual int decodeBERParameterType ASNICTXT pctxt ASNITObject object return 0 inline OSBOOL idEquals ASNITObjId pvalue return 0 rtCmpTCOID amp id pvalue This assumes that o
98. by adjusting the given size value which represents the number of bits into the number of bytes required to hold the bits Dynamic BIT STRING ASN 1 production name BIT STRING Generated C code typedef ASN1DynBitStr lt name gt Generated C code typedef ASNI1TDynBitStr ASN1T lt name gt In this case different base types are used for C and C The difference between the two is the C version includes constructors that initialize the value and methods for setting the value The ASN DynBitStr type i e the type used in the C mapping is defined in the asn type h header file as follows typedef struct ASN1IDynBitStr OSUINT32 numbits const OSOCTET data ASN1DynBitStr The ASNITDynBitStr type is defined in the asn1 CppTypes h header file as follows ASNIC V5 8 39 struct ASN1ITDynBitStr public ASN1DynBitStr ctors ASNITDynBitStr numbits 0 ASNITDynBitStr OSUINT32 numbits OSOCTET data ASNITDynBitStr ASN1DynBitStr amp bs ASNiTDynBitStr Note that memory management of the byte array containing the bit string data is the responsibility of the user The wrapper class does not free the memory on destruction nor deep copy the data when a string is copied Static sized BIT STRING T ASN 1 production name BIT STRING SIZE len Generated C code typedef struct OSUINT32 numbits OSOCTET data lt adjusted len gt lt name gt Generated C code typ
99. by the nibble allocation algorithm can be changed By default this value is set to 4K bytes The run time function rtMemSetDefBlkSize can be called to change this size This takes a single argument the value to which the size should be changed It is also possible to change the underlying functions called from within the memory management abstraction layer to obtain or free heap memory By default the standard C malloc realloc and free functions are used These can be ASNIC V5 8 128 changed by calling the rtMemSetAllocFuncs function This function takes as arguments function pointers to the allocate reallocate and free functions to be used in place of the standard C functions Another run time memory management function that can improve performance is rtMemReset This function is useful when decoding messages in a loop It is used instead of rtMemFree at the bottom of the loop to make dynamic memory available for decoding the next message The difference is that rtMemReset does not actually free the dynamic memory It instead just resets the internal memory management parameters so that memory already allocated can be reused Therefore all the memory required to handle message decoding is normally allocated within the first few passes of the loop From that point on that memory is reused thereby making dynamic memory allocation a negligent issue in the overall performance of the decoder A more detailed explanation of these functions and oth
100. callback function and then the print stream is automatically directed to the callback function This makes it easier to support print to file or print to window type of functionalities It is possible to specify the name of a c or cpp file as an argument to this option to specify the name of the file to which these functions will be written This is an optional argument If not specified the functions are written to separate files for each module in the source file The format of the name of each file is lt module gt PrtToStrm c If an output filename is specified after the genPrtToStrm qualifier all functions are written to that file Before calling generated print to stream functions a callback function should be registered Otherwise a default callback function will be used that directs the print stream to the standard output device The callback function is declared as void rtPrintCallback void pPrntStrmInfo ASN1ConstCharPtr fmtspec va list arglist The first parameter is user defined data which will be passed to each invocation of the callback function This parameter can be used to pass print stream specific data for example a file pointer 1f the callback function is to output data to a file The second and third parameters to the callback function constitute the data to be printed in the form of format specification followed by list of arguments A simple callback function for printing to file can be defined as follows v
101. cation sik hee ey ii ITO A hake ed Beh ed be AE ES ed bee ag es 73 ABSTRACT SYNTAX and TYPE IDENTIFIER sssssssssss sss 78 Information Object iis ureslepiereiexieQertepebteverkeberesbefee erred edet 79 Information Object Set cesses m 81 Encode Decode Function Prototypes 0 06 00 ccc ee 83 Generated C Control Class Definition csse 84 Generated Methods uei ae Rm ee RR e tese Ne str dnt e Ree e Rote b deed 86 Generated Information Object Table Structures 0 0 000 ee 86 GENERATED C SOURCE FILES 1 eee nee cence teens 98 Maximum Lines per Fil 2 2 ee epg on eh eke ke Oh mE o ED ESAD E dax pep 98 Use of the maxcfiles Option 0 0 csse e 98 GENERATED CP EIDES unser watch ea d EORR HAIR HE ese RERO dt hak cea ede iue dee 99 GENERATED C C FILES AND THE COMPAT OPTION 0 0 00 eee e eee eee eens 100 ASNIC V5 7 i GENERAL PROCEDURES FOR ENCODING AND DECODING eA 102 Dynamic Memory Management cessisse eee e eens 102 Populating Generated Structure Variables for Encoding eee 106 Accessing Encoded Message Components sssssssssisssssssss ee 107 GENERATED BER ENCODE FUNCTIONS 2 0 eee cette 109 Generated C Function Format and Calling Parameters sess 109 Generated C Encode Method Format and Calling Parameters 0000 cece 111 Procedure for Calling C Encode Functions 2 ssec 111 Encoding a Series of Messages Using the C Encode Functions nnana nan
102. character string declaration would cause a C or C const char declaration to be generated ASN 1 production name string type value Generated code ASN1ConstCharPtr lt name gt value In this definition lt string type gt could be any of the standard 8 bit characters string types such as IA5String PrintableString etc note this version ofthe compiler does not contain support for value declarations of larger character string type such as BMPString The ASNI ConstCharPtr type used in the generated code is a type defined in asn type h designed to be a const char type for C or C ASNIC V5 8 69 Object Identifier Value Specification Object identifier values are somewhat different in that they result in a structure being populated in the C or C source file ASN 1 production lt name gt OBJECT IDENTIFIER lt value gt Generated code ASNIOBJID lt name gt value For example consider the following declaration oid OBJECT IDENTIFIER ccitt b 5 10 This would result in the following definition in the C or C source file ASNIOBJID oid 3 0 5 10 To populate a variable in a generated structure with this value the rtSetOID utility function can be used see the C C Run Time Library Reference Manual for a full description of this function In addition the C base type for this construct ASN TObjId contains constructors and assignment operators
103. command line option To better understand the support in this area the individual components of Information Object specifications are examined We begin with the CLASS specification that provides a schema for Information Object definitions A sample class specification is as follows OPERATION CLASS amp operationCode CHOICE local INTEGER global OBJECT IDENTIFIER amp ArgumentType amp ResultType amp Errors ERROR OPTIONAL Users familiar with ASN 1 will recognize this as a simplified definition of the ROSE OPERATION MACRO using the Information Object format When a class specification such as this is parsed information on its fields is maintained in memory for later reference In the simple form of code generation the class definition itself does not result in the generation of any corresponding C or C code It is only an abstract template that will be used to define new items later on in the specification In the table form if C is specified an abstract base class is generated off of which other classes are derived for information object specifications Fields from within the class can be referenced in standard ASN 1 types It is these types of references that the compiler is mainly concerned with These are typically header types that are used to add a common header to a variety of other message body types An example would be the following ASN 1 type definition for a ROSE invoke
104. ct A program fragment that could be used to encode an employee record is as follows finclude employee h include file generated by ASNIC main const OSOCTET msgptr OSOCTET msgbuf 1024 int msglen stat OSBOOL canonical FALSI GI step 1 instantiate an instance of the XER encode buffer class This example specifies a static message buffer ASNIXEREncodeBuffer encodeBuffer msgbuf sizeof msgbuf canonical step 2 populate msgData with data to be encoded ASNIT PersonnelRecord msgData msgData name givenName SMITH ASNIC V5 8 167 step 3 instantiate an instance of the ASN1C ProdName class to associate th ncode buffer and message data ASN1C PersonnelRecord employ encodeBuffer msgData steps 4 and 5 encode and check return status if stat employee Encode ASN OK printf encoded XML message Nn printf ASN1ConstCharPtr msgbuf printf in step 6 get start of message pointer and message length start of message pointer is start of msgbuf call getMsgLen to get message length msgptr encodeBuffer getMsgPtr will return amp msgbuf len encodeBuffer getMsgLen else printf Encoding failed n encodeBuffer printErrorInfo exit 0 msgptr and len now describe fully encoded messag ASNIC V5 8 168 Generated XER Decode Functio
105. ct This will cause the error status ASN E NOTINSET to be generated When the error handler sees this status it prints information on the error that was encountered to the console skips to the next element and then returns an ASN OK status that allows the decoder to continue If some other error occurred i e status was not equal to ASN E NOTINSET then the original status is passed out which forces the termination of the decoding process The full text of the handler is as follows int MyErrorHandler error ASNICTXT pCtxt ASNICCB pCCB int stat This handler is set up to look explicitly for ASN E NOTINSET errors because we know the SET might contain some bogus elements T if stat ASN E NOTINSET Print information on the error that was encountered ASNIC V5 8 197 printf decode error detected n rtErrPrint pCtxt printf n Skip element xd_NextElement pCtxt Return an OK status to indicate parsing can continue return ASN OK else return stat pass existing status back out Now we need to register the handler Unlike event handlers only a single error handler can be registered The method to do this in the message buffer class is setErrorHandler The following two lines of code in the reader program register the handler MyErrorHandler errorHandler decodeBuffer setErrorHandler amp errorHandler The error handlers can be as complicat
106. ct Sets defined within a specification in the form of a global array of structures Each structure in the array is an equivalent C structure representing the corresponding ASN 1 information object Additional encode and decode functions are also generated for each type that contains table constraints These functions have the following prototypes ASNIC V5 8 89 BER DER int asnlETC lt ProdName gt ASNICTXT pctxt lt ProdName gt pvalue int asnlDTC ProdName ASNICTXT pctxt lt ProdName gt pvalue PER int asnlPETC ProdName ASNICTXT pctxt lt ProdName gt pvalue int asnlPDTC ProdName ASNICTXT pctxt lt ProdName gt pvalue The purpose of these functions is to verify the fixed values within the table constraints are what they should be and to encode or decode the open type fields using the encoder or decoder assigned to the given table row Calls to these functions are automatically built into the standard encode or decode functions for the given type They should be considered hidden functions not for use within an application that uses the API C Code Generation For C code is generated for ASN 1 classes information objects and information object sets This code is then referenced when table constraint processing must be performed Each of the generated C classes builds on each other First the classes generated that correspond to ASN 1 CLASS definitions form the base class founda
107. d anIntPresent flags accordingly to indicate whether the elements are to be included in the encoded message or not Conversely when a message is decoded into this structure the developer must test the flags to determine if the element was provided in the message or not The C version of the compiler will generate a constructor for the structured type for a SEQUENCE if OPTIONAL elements are present This constructor will set all optional bits to zero when a variable of the structured type is declared The programmer therefore does not have to be worried about clearing bits for elements that are not used only with setting bits for the elements that are to be encoded DEFAULT keyword The DEFAULT keyword allows a default value to be specified for elements within the SEQUENCE ASNIC will parse this specification and treat it as it does an optional element Note that the value specification 1s only parsed in simple cases for primitive values It is up to the programmer to provide the value in complex cases For BER encoding a value must be specified be it the default or other value For DER or PER it is a requirement that no value be present in the encoding for the default value For integer and boolean default values the compiler automatically generates code to handle this requirement based on the value in the structure For other values an optional present flag bit is generated The programmer must set this bit to false on the encode side to specif
108. d as an ASN 1 production the generated C type definition would be typedef OSBOOL B Note that the tag information is not represented in the type definition It is handled within the generated encode decode functions The only difference between the C and C mapping is the addition of the ASNIT_ prefix on the C type INTEGER The ASN 1 INTEGER type is converted into one of several different C types depending on constraints specified on the type By default an INTEGER with no constraints results in the generation of an OSINT32 type In the global include file osSysTypes h OSINT32 is defined to be an int which is normally a signed 32 bit integer value on most computer systems ASN 1 production lt name gt INTEGER Generated C code typedef OSINT32 lt name gt Generated C code typedef OSINT32 ASN1T lt name gt Value range constraints can be used to alter the C type used to represent a given integer value For example the following declaration from the SNMP SMI specification would cause an OSUINT32 type mapped to a C unsigned int to be used Counter APPLICATION 1 IMPLICIT INTEGER 0 4294967295 In this case an OSINT32 could not be used because all values within the given range could not be represented Other value ranges would cause different integer types to be used that provide the most efficient amount of storage The following table shows the types that would be used for the dif
109. d directly if the type of message is known S stat rtStreamBufMark amp ctxt 32 if stat ASN OK rtErrPrint amp ctxt return stat stat berDecStrmTagAndLen amp ctxt amp msgtag amp msglen if stat ASN OK rtErrPrint amp ctxt return stat if msgtag TV PersonnelRecord stat rtStreamBufReset amp ctxt ASNIC V5 8 142 if stat ASN OK rtErrPrint amp ctxt return stat Step 4 Call decode function note last two args should always be ASNIEXPL and 0 status asnlBSD PersonnelRecord amp ctxt amp employee ASNIEXPL 0 Step 5 Check return status if status ASN OK process received data in employee variable else error processing else check for other known message types Step 6 Close the stream rtStreamBufClose amp ctxt Remember to release dynamic memory when done rtFreeContext amp ctxt Decoding a Series of Messages Using the Stream Oriented C Decode Functions The above example is fine as a sample for decoding a single message but what happens in the more typical scenario of having a long running loop that continuously decodes messages It will be necessary to put the decoding logic into a loop ASNIC V5 8 143 A code fragment showing a way to do this is as follows include employee h include file generated by ASNIC main ASNITAG msgtag
110. d if genTest is specified The maxcfiles option for C works very similar to how it works for C The only differences are a few additional files are generated and the cpp extension is used instead of c Additional files are generated to hold ASNIC_ lt Type gt and ASNIT Type control classes The format of the filenames of these files is as follows asnl suffix prodname cpp ASN1C prodname cpp ASNIT prodname cpp where lt suffix gt depends on encoding rules and function type encode decode free etc lt prodname gt is the ASN 1 production name For the example presented previously in the C Files section the following files would be generated for the Name pro duction in the Employee asn file asnlD Name cpp asnlE Name cpp ASNIT Name cpp ASN1C Name cpp These contain the functions to decode Name and encode Name respectively The ASNIT Name cpp file contains the type class methods and the ASNIC Name cpp files contains the control class methods Note that not all productions have a control class only PDU types do for BER or PER therefore the ASN C_ lt type gt cpp file may not be generated Similar files would be generated for the other productions in the module as well Note that for C the code reduction effect is less than that for pure C This is because most of the linkers cannot omit virtual methods even if they are not being used by the application These virtual methods refer to separate C functions
111. d parameter specifies whether implicit or explicit tagging should be used In practically all cases users of the generated function should set this parameter to ASN JEXPL explicit This tells the encoder to include an explicit tag around the encoded result The only time this would not be used is when the encoder or decoder is making internal calls to handle implicit tagging of elements The final parameter decode case only is length This is ignored when tagging is set to ASN EXPL explicit so users can ignore it for the most part and set it to zero In the implicit case this specifies the number of octets to be extracted from the byte stream This is necessary because implicit indicates no tag length pair precedes the data therefore it is up to the user to indicate how many bytes of data are present If PER encoding is specified the format of the generated prototypes is different The PER prototypes are of the following general form int asnlPE lt ProdName gt ASNICTXT pctxt lt ProdName gt value int asnlPD lt ProdName gt ASNICTXT pctxt lt ProdName gt pvalue In these prototypes the prefixes are different a P character is added to indicate they are PER encoders decoders and the tagging argument variables are omitted In the encode case the value of the production to be encoded may be passed by value if it is a simple type for example BOOLEAN or INTEGER Structured values will still be passed using a poi
112. d static elements to CHOICE constructs instead of pointer values The Generate code compatible option is for generating code compatible with an older release of the compiler The Generate code for main file and dependent IMPORT items option adds the depends option which causes code in the main file to be compiled as well as all of the dependent items from imported modules The Automatically generate unique names to resolve name clashes option cause unique names to be generated in instances where items in different modules have the same name Click on Help to get a summary of what each of these options do or read the section Running ASNIC from the Command line All of these items are optional Some items will be grayed out if they are not applicable to the encoding rules language combination selected on the previous page The PRO version Options tab is as follows ASNIC V5 8 16 ASN1IC compiler 5 80 Objective Systems Inc objective SYSTEMS INC Code Reduction Options Code Addition Alter Options PRO Version Options Other Options Choose additional compiler options NOTE All of these items are optional r PRO Version Options Generate test routines Generate separate file for each function Generate copy routines Generate print to text buffer routines Generate comparision routines Generate print to stream routines Generate makefile for project Generate BER stream based encode
113. d the locations of the errors A single error message is output to stderr after compilation on the unit is complete to indicate error conditions exist ASNIC V5 8 31 ASNIC V5 8 32 Generated C C Source Code Header h File The generated C or C include file contains a section for each ASN 1 production defined in the ASN 1 source file Different items will be generated depending on whether the selected output code is C or C In general C will add some additional items such as a control class definition onto what is generated for C The following items are generated for each ASN 1 production e Tag value constant e Choice tag constants CHOICE type only e Named bit number constants BIT STRING type only e Enumerated type option values ENUMERATED or INTEGER type only e C type definition e Encode function prototype e Decode function prototype e Other function prototypes depending on selected options for example print e C control class definition C only A sample section from a C header file is as follows RRR KKK KK KK KK KR KK KK KK OR KK IK OR KK KK OK ke ke ke ke e kx amp es hy EmployeeNumber ey a RRR KR RR KK KK KKK KK KK KK RR RK IR ORK KK KKK OK ORK KKK define TV EmployeeNumber TM APPL TM PRIM 2 typedef OSINT32 EmployeeNumber EXTERN int asnlE EmployeeNumber ASNICTXT pctxt EmployeeNumber pvalue ASN1TagType tagging EXTER
114. de generated is different In this case ASN OpenType above is replaced with ASN Object or ASNITObject for C This is defined in asn type h as follows typedef struct generic table constraint value holder ASN1OpenTyp ncoded void decoded OSINT32 index table index ASN10bject This allows a value of any ASN 1 type to be represented in both encoded and decoded forms Encoded form is the open type form shown above It is simply a pointer to a byte buffer and a count of the number of byes in the encoded message component The decoded form is pointer to a variable of a specific type The pointer is void because there could be a potentially large number of different types that can be represented in the table constraint used to constrain a type field to a given set of values The index member of the type is for internal use by table constraint processing functions to keep track of which row in a table is being referenced Character String Types ASNIC V5 8 62 As of version 5 0 and above character string types are now built into the compiler Previous versions used compiled definitions based on the OCTET STRING base type to model these types All 8 bit character character string types now are derived from the C character pointer const char base type This pointer is used to hold a null terminated C string for encoding decoding For encoding the string can either be static 1 e a string literal or address of a static buf
115. different base types are used for C and C The difference between the two is the C version includes constructors assignment operators and other helper methods that make it easier to manipulate binary data The ASN DynOctStr type 1 e the type used in the C mapping is defined in the asn type h header file as follows typedef struct ASN1IDynOctStr OSUINT32 numocts const OSOCTET data ASNIDynOctStr The ASN TDynOctStr type is defined in the ASN TOctStrh header file This class extends the C ASNI DynOctStr class and adds many additional constructors and methods See the C C Common Run time Reference Manual for a complete description of this class Static sized OCTET STRING I ASN 1 production lt name gt OCTET STRING SIZE lt len gt Generated C code typedef struct OSUINT32 numocts OSOCTET data lt len gt lt name gt Generated C code typedef struct OSUINT32 numocts OSOCTET data lt len gt ctors ASNIT name ASNIT name OSUINT32 numocts const OSOCTET data ASNIT name const char cstring assignment operators ASNIT name amp operator const char cstring ASNIC V5 8 43 ASNIC V5 8 ASNIT lt name gt 44 ENUMERATED The ASN 1 ENUMERATED type is converted into different types depending on whether C or C code is being generated The C mapping is either a C enum or integer type depending on whether or not the ASN
116. ds The ASNITPDUSeqOfList is similar except that it also extends the ASNITPDU base class to add additional memory management capabilities needed by PDU types to automatically release memory on destruction In addition to the Asn1 RTDList C structure and C functions a C class is provided for linked list support This is the ASNICSeqOfList class This class provides methods for adding and deleting elements to and from lists and an iterator interface for traversing lists See the ASN CSeqOfList section in the C C Common Run time Reference Manual for details on all of the methods available in this class Populating Linked List Structures ASNIC V5 8 56 Populating generated list based SEQUENCE OF structures for the most part requires the use of dynamic memory to allocate elements to be added to the list note that it is possible to use static elements for this but this is unusual The recommended method is to use the built in run time memory management facilities available within the ASNIC run time library This allows all list memory to be freed with one call after encoding is complete In the case of C the rtMemAlloc or rrMemAllocType function would first be used to allocate a record of the element type This element would then be initialized and populated with data The rtDListAppend function would then be called to append it to the given list For C the compiler generates the helper methods NewElement and Append in the generated control
117. du command line switch to explicitly declare the PDU types The lt isPDU gt flag is used to declare a type to be a PDU in a configuration file An example of this is as follows lt asnlconfig gt lt module gt lt name gt H323 MESSAGES lt name gt lt production gt lt name gt H323 UserInformation lt name gt lt isPDU gt lt production gt lt module gt lt asniconfig gt This will cause only a single ASN C control class definition to be added to the generated code for the H323 UserInformation production If the module contains no PDUs i e contains support types only the lt noPDU gt empty element can be specified at the module level to indicate that no control classes should be generated for the module XER Class Definition For the XML encoding rules XER the generated class definition is as follows class ASN1C name public ASN1CType ASNIXERSAXHandler protected ASNIT name amp msgData additional control variables public ASNIC name ASNIT lt name gt amp data ASN1C name ASN1MessageBufferIF amp msgBuf ASNIT name amp data standard encode decode methods defined in ASN1CType base class int Encode ASNIC V5 8 85 int Decode stream encode decode methods int EncodeTo ASN1MessageBufferIF amp msgBuf int DecodeFrom ASN1MessageBufferIF amp msgBuf SAX Content Handler Interface virtual void startEle
118. e error processing decodeBuffer PrintErrorInfo step 6 free dynamic memory will be done automatically when both the decodeBuffer and employ objects go out of scope ASNIC V5 8 161 Decoding a Series of Messages Using the C Control Class Interface The above example is fine as a sample for decoding a single message but what happens in the more typical scenario of having a long running loop that continuously decodes messages The logic shown above would not be optimal from a performance standpoint because of the constant creation and destruction of the message processing objects It would be much better to create all of the required objects outside of the loop and then reuse them to decode and process each message A code fragment showing a way to do this is as follows include employee h include file generated by ASNIC main OSOCTET msgbuf 1024 int msglen sta OSBOOL aligned TRU EM Gl ct En step 1 instantiate a PER decode buffer object ASNIPERDecodeBuffer decodeBuffer msgbuf msglen aligned step 2 instantiate an ASNIT lt ProdName gt object ASNIT PersonnelRecord msgData step 3 instantiate an ASN1C ProdName object ASNI1C PersonnelRecord employ decodeBuffer msgData loop to continuously decode records for logic to read message into msgbuf stat employee Decode step 5 check the return status if
119. e include lt stdlib h gt include rtMemory h OSUINT32 g defBlkSize XM K MEMBLKSIZ OSMallocFunc g_malloc func malloc OSReallocFunc g_realloc_fune realloc OSFreeFunc g_free func free The malloc realloc and free functions must have the same prototype as the standard C functions The g defBlkSize variable contains the default memory heap chunk size This is the amount of memory allocated when the system needs a new block of memory The default value is 4K 4096 bytes The value can be set lower for space constrained systems and higher to improve performance in systems that have sufficient memory resources Some systems do not have a realloc like function In this case it is necessary to set theg realloc func variable to NULL In this case the pair of malloc free will be used i e g malloc func g free func pair To add these definitions to an application program compile the C source file it can have any name and link the resulting object file OBJ or O in with the application C Memory Management In the case of C the ownership of memory is handled by the control class and message buffer objects These classes share a context structure and use reference counting to manage the allocation and release of the context block When a message buffer object is created a context block structure is created as well When this object is then passed into a ASNIC V5 8 104 control class constructor its reference count
120. e See the section on the ASNICBitStr class in the ASNIC C C Common Run time User s Manual for details on all of the methods available in this class OCTET STRING The ASN 1 OCTET STRING type is converted into a C structured type containing an integer to hold the number of octets and an array of unsigned characters OCTETs to hold the octet string contents The number of octets integer specifies the actual number of octets in the contents field The allocation for the contents field depends on how the octet string is specified in the ASN 1 definition If a size constraint is used a static array of that size is generated otherwise a pointer variable is generated to hold a dynamically ASNIC V5 8 42 allocated string The decoder will automatically allocate memory to hold a parsed string based on the received length of the string For C constructors and assignment operators are generated to make assigning variables to the structures easier In addition to the default constructor a constructor is provided for string or binary data An assignment operator is generated for direct assignment of a null terminated string to the structure note this assignment operator copies the null terminator at the end of the string to the data Dynamic OCTET STRING ASN 1 production lt name gt OCTET STRING Generated C code typedef ASN1DynOctStr lt name gt Generated C code typedef ASNITDynOctStr ASNIT lt name gt In this case
121. e INTEGER and REAL value specifications cause define statements to be generated BOOLEAN Value Specification A BOOLEAN value causes an extern statement to be generated in the header file and a global declaration of type OSBOOL to be generated in the C or C source file The mapping of ASN 1 declaration to global C or C value declaration is as follows ASN 1 production lt name gt BOOLEAN lt value gt Generated code OSBOOL lt name gt lt value gt INTEGER Value Specification The INTEGER type causes a define statement to be generated in the header file of the form ASN V_ lt valueName gt where lt valueName gt would be replaced with the name in the ASN 1 source file The reason for doing this is the common use of INTEGER values for size and value range constraints in the ASN 1 specifications By generating define statements the symbolic names can be included in the source code making it easier to adjust the boundary values on the fly For example the following declaration ivalue INTEGER 5 will cause the following statement to be added to the generated header file define ASN1V ivalue 5 The reason the ASNIV_ prefix is added is to prevent collisions with INTEGER value declarations and other declarations such as enumeration items with the same name REAL Value Specification ASNIC V5 8 68 The REAL type causes a define statement to be generated in the header file of the form ASN V_ lt val
122. e applied at all of the different levels global module and individual production Global Level These attributes can be applied at the global level by including them within the asnlconfig section ASNIC V5 8 26 Name Values Description lt storage gt lt storage gt dynamic static list array or dynamicArray keyword If dynamic it indicates that dynamic storage i e pointers should be used everywhere within the generated types where use could result in lower memory consumption These places include the array element for sized SEQUENCE OF SET OF types and all alternative elements within CHOICE constructs If static it indicates static type should be used in these places In general static types are easier to work with If list a linked list type will be used for SEQUENCE OF SET OF constructs instead of an array type If array an array type will be used for SEQUENCE OF SET OF constructs The maxSize attribute can be used in this case to specify the size of the array variable for example storage maxSize 12 gt array lt storage gt If dynamicArray a dynamic array will be used for SEQUENCE OF SET OF constructs A dynamic array is an array that uses dynamic storage for the array elements ASNIC V5 8 27 Module Level These attributes can be applied at the module level by including them within a lt module gt section types names values names n
123. e constraint checks in code ASNIC V5 8 3 list nodecode noencode noIndefLen noOpen Ext notypes o directory pdu type print generate listing do not generate decode functions do not generat ncode functions do not generate indefinite length tests do not generate open extension elements do not generate type definitions set output file directory designate type to be a Protocol Data Unit PDU type may be to select all type definitions lt filename gt shortnames trace uniquenames warnings C C options hfile lt filename gt cfile lt filename gt genBitMacros genInit genFree genMake maxlines num oh directory static w32 Java options pkgpfx text pkgname text dirs genjsources getset genbuild compare C options nspfx lt text gt namespace lt text gt dirs gencssources pro options events stream tables strict generate print functions reduce the length of compiler generated names add trace diag msgs to generated cod resolve name clashes by generating unique names output compiler warning messages C or C header h filename default is ASN 1 Module Name gt h C or C source c or cpp filename default is ASN 1 Module Name gt c generate named bit set clear test macros generate initialization functio
124. e provided The user can re run the compilation with the I flag specified to see the lines listed as they are parsed This can be quite helpful in tracking down a syntax error The most common types of syntax errors are as follows e Invalid case on identifiers module name must begin with an uppercase letter productions types must begin with an uppercase letter and element names within constructors SEQUENCE SET CHOICE must begin with lowercase letters e Elements within constructors not properly delimited with commas either a comma is omitted at the end of an element declaration or an extra comma is added at the end of an element declaration before the closing brace e Invalid special characters only letters numbers and the hyphen character are allowed C programmers tend to like to use the underscore character _ in identifiers This is not allowed in ASN 1 Conversely C does not allow hyphens in identifiers To get around this problem ASNIC converts all hyphens in an ASN 1 specification to underscore characters in the generated code Semantics errors occur on the compiler back end as the code 1s being generated In this case parsing was successful but the compiler does not know how to generate the code These errors are flagged by embedding error messages directly in the generated code The error messages always begin with an identifier with the prefix ASN so a search can be done for this string in order to fin
125. e structure contains message pointer and length of encoded Login ARGUMENT Encoded ROSE message The login OPERATION also contains references to ERROR definitions These are defined using a separate MACRO that is built into the compiler The definition of this MACRO is as follows ERROR MACRO BEGIN TYPE NOTATION Parameter VALUE NOTATION value VALUE INTEGER Parameter PARAMETER NamedType empty NamedType identifier type type END In this definition an error is assigned an identifying number as well as on optional parameter type to hold parameters associated with the error An example of a reference to this MACRO for the authenticationFailure error in the login operation defined earlier would be as follows applicationError ERROR PARAMETER SEQUENCE errorText IA5String The ASNIC compiler will generate a type definition for the error parameter and a value constant for the error value The format of the name of the type generated will be lt name gt PARAMETER where lt name gt is the ERROR name applicationError in this case with the first letter set to uppercase The name of the value will simply be the ERROR name ASNIC V5 8 203 SNMP OBJECT TYPE The SNMP OBJECT TYPE MACRO is one of several MACROs used in Management Information Base MIB definitions It is the only MACRO of interest to ASNIC because it is the one that specifies the object identifiers and data that are co
126. e to the encoding rules language combination selected on the previous page The Code Addition Alter Options tab is as follows ASNIC V5 8 15 ASN1IC compiler 5 80 Objective Systems Inc objective SYSTEMS INC Code Reduction Options Code Addition Alter Options PRO Version Options Other Options Choose additional compiler options NOTE All of these items are optional Options to Generate Additional Code Generate named bit macros Generate free routines Add trace diagnostic messages to generated code Generate print routines m Options to Alter Generated Code Generate strict constraints check Generate static elements Generate code compatible with older compiler version Y Generate code for main file and dependent IMPORT items Automatically generate unique names to resolve name clashes lt Back Cancel Help This tab contains additional optional items that allow additional code to be generated and that alters the type of code generated in some cases to be specified Named bit macros control the generation of special macros for setting clearing and testing bits in BIT STRING types Print routines are special functions for printing the contents of generated type variables Trace diagnostic messages are added to encode decode functions to trace the sequence of function calls used in the encoding or decoding of a message The Generate static elements option is used to ad
127. e used to encode an employee record is as follows ASNIC V5 8 165 include employee h include file generated by ASNIC main OSOCTET msgbuf 1024 int msglen stat ASNICTXT ctxt OSBOOL cxer FALSE canonical XER flag OSBOOL aligned TRUE Employee employee typedef generated by ASNIC Initialize context and set encode buffer pointer if rtInitContext amp ctxt ASN OK return 1 xerSetEncBufPtr amp ctxt msgbuf sizeof msgbuf cxer Populate variable with data to be encoded mployee name givenName John Encode data stat asnlXE Employee amp ctxt amp employee 0 0 if stat ASN OK msglen xerGetMsgLen amp ctxt else error processing rtFreeContext amp ctxt release the context pointer After encoding is complete msgbuf contains the XML textual representation of the data By default a UTF 8 encoding is used For the ASCII character set this results in a buffer containing normal textual data Therefore the contents of the buffer are represented as a normal text string and can be displayed using the C printf run time function or any other function capable of displaying text ASNIC V5 8 166 Procedure for Using the C Control Class Encode Method The procedure to encode a message using the C class interface is as follows 1 Instantiate an ASN 1 XER encode buffer object
128. e_beremployee E mployeeE nc c Writing C decode functions to file C asnlc devscSsample beremployee E mployeeDec c Cancel Hep As can be seen the GUI has constructed an ASNIC command line using the specified options The user can now click Compile to execute the compilation The Back button can be used to step back through the sequence of screens in order to change any of the previous inputs After Compile is clicked the results of the compilation are shown in the results text window If the compilation was successful the generated code is written to the files in the given output directory Clicking the Finish or Cancel button will terminate the GUI wizard ASNIC V5 8 21 Compiling and Linking Generated Code C C source code generated by the compiler can be compiled using any ANSI standard C or C compiler The only additional option that must be set is the inclusion of the ASN 1 C C header file include directory with the I option When linking a program with compiler generated code it is necessary to include the ASN 1 run time libraries It is necessary to include at least one of the encoding rules libraries asnlber asnl per or asnlxer as well as the common run time functions library asnlrt See the ASNIC C C Run time Reference Manual for further details on these libraries For static linking on Windows systems the name of the library files are asn ber_a lib asnlper_a lib or as
129. ecode the message 3 Free the context after use of the decoded data is complete to free allocated memory structures ASNIC V5 8 158 Before a PER decode function can be called the user must first initialize a context block structure The context block is initialized by either calling the rtNewContext function to allocate a dynamic context block or by calling rt nitContext to initialize a static block The pu_setBuffer function must then be called to specify a message buffer that contains the PER encoded message to be decoded This function also allows for the specification of aligned or unaligned decoding A decode function can then be called to decode the message If the return status indicates success ASN_OK then the message will have been decoded into the given ASN 1 type variable The decode function may automatically allocate dynamic memory to hold variable length variables during the course of decoding This memory will be tracked in the context structure so the programmer does not need to worry about freeing it It will be released when the context is freed The final step of the procedure is to free the context block This must be done regardless of whether the block is static declared on the stack and initialized using rt nitContext or dynamic created using rtNewContext The function to free the context is rtFreeContext A program fragment that could be used to decode an employee record is as follows include employee h
130. ect definition and will fully decode all type fields and store pointers to the decoded type variables in the ASN TObject decoded fields 3 Ifamatch is not found and the information object set is not extensible then a table constraint error status will be returned If the information object set is extensible a normal status is returned Simple Table Constraint 1 This function will verify all the fixed type values match what is defined in the table constraint object set If an element value does not exist in the table i e the information object set and the object set 1s not extensible then a table constraint violation exception will be thrown General Procedure for Table Constraint Encoding The general procedure to encode an ASN 1 message with table constraints 1s the same as without table constraints The only difference is in the open type data population procedure The tables option will cause ASN TObject fields to be inserted in the generated code instead of Asn OpenType declarations Refer to the BER DER PER encoding procedure for further information ASNIC V5 8 91 The procedure to populate the value for an ASN TObject item is as follows 1 Check the ASN 1 specification or generated C code for the type of the type field value in the information object set that corresponds to the selected key field value 2 Create a variable of that type and assign a pointer to it to the Asn Object decoded member variable as void 3 Fo
131. ect exists within the ASNIC installation directory tree The generation logic tries to determine the root directory of the installation by traversing upward from the project directory in an attempt to locate the rtsrc subdirectory which is assumed to be the installation root directory The makefile variable OSROOTDIR is then set to this value A similar traversal is done to locate the platform mk and xmlparser mk files These paths are then set in the makefile If the project directory is located outside of the ASNIC directory tree the user must set the OSROOTDIR environment variable to point at the ASNIC root directory in order for the makefile generation to be successful If this is done it is assumed that the platform mk and xmlparser mk files are located in this directory as well If the compiler is unable to determine the root directory using any of the methods described above an error will be generated and the user will need to manually edit the makefile to set the required root directory parameters and makefile include file paths ASNIC V5 8 191 ASNIC V5 8 192 Event Handler Interface The events command line switch causes hooks for user defined event handlers to be inserted into the generated decode functions What these event handlers do is up to the user They fire when key message processing events or errors occur during the course of parsing an ASN 1 message They are similar in functionality to the Simple API for XML SAX that was
132. ed as you need them to be You can use them in conjunction with event handlers in order to figure out where you are within a message in order to look for a specific error at a specific place Or you can be very generic and try to continue no matter what Example 3 A Pure Parser to Convert PER encoded Data to XML A pure parser is created by using the notypes option along with the events option In this case no backing data types to hold decoded data are generated Instead parsing functions are generated that store the data internally within local variables inside the parsing functions This data is dispatched to the callback functions and immeditely disposed of upon return from the function It is up to the user to decide inside the callback handler what they want to keep and they must make copies at that time The result is a very fast and low memory consuming parser that is ideal for parsing messages in which only select parts of the messages are of interest Another use case for pure parser functions is validation These functions can be used to determine if a PER message is valid without going through the high overhead operation of decoding They can be used on the front end of an application to reject invalid messages before processing of the messages is done In some cases this can result in significantly increased performance An example of a pure parser can be found in the cpp sample_per per2xmlEH directory This program uses a pure parser
133. ed decode method format BER decode method 145 generated C stream oriented encode method format BER encode method 136 generated C table constraint function prototypes 90 generated C C source code BER stream oriented decode functions 140 BER stream oriented encode functions 132 event handler interface 193 generated BER decode functions 119 generated BER encode functions 109 generated compare methods 185 generated copy methods 186 generated initialization functions 179 generated makefile 191 generated memory free functions 180 generated PER decode functions 157 generated PER encode functions 150 generated print methods 181 generated test functions 189 generated XER decode functions 169 generated XER encode functions 164 176 header file 33 IMPORT EXPORT of types 200 ROSE OPERATION and ERROR 201 SNMP OBJECT TYPE 204 generated compare functions 185 generated copy functions 186 generated information object definition 86 generated initialization functions 179 generated makefile 191 generated methods 86 generated PER decode function generated C function format and calling parameters 157 generated C decode method format and calling pa rameters 158 performance consideration of dynamic memory man agement 163 procedure for calling C decode functions 158 generated PER encode function decoding a series of messages using C interface 162 encoding a series of messages using C interface 157 generated C function format and calling parameter
134. ed to generated classes The lt filename gt argument to this option is optional If not specified the functions will be written to lt modulename gt Copy c where lt modulename gt is the name of the module from the ASN 1 source file genFree None This option instructs the compiler to generate a memory free function for each ASN 1 production Normally memory is freed within ASNIC by using the rtMemFree run time function to free all memory at once that is held by a context Generated free functions allow finer grained control over memory freeing by just allowing the memory held for specific objects to be freed genInit None This option instructs the compiler to generate an initialization function for each ASN 1 production A variable of a generated structure can always be initialized by memset ing the variable to zero However this is not usually the most efficient way to initialize a variable because if it contains large byte arrays a significant amount of processing is required to set all bytes to zero and they don t need to be Initialization functions provide a smart alternative to memset ing in that only what needs to be set to zero is actually done genMake None This option instructs the compiler to generate a portable makefile for compiling the generated C or C code If used with the w32 command line option a makefile that is compatible with the Microsoft Visual Studio nmake utilit
135. edef struct OSUINT32 numbits OSOCTET data lt adjusted len gt ctors ASNIT name ASNIT name OSUINT32 numbits const OSOCTET data ASNIT lt name gt adjusted len lt len gt 1 8 1 For example the following ASN 1 production GI ay oo BS PRIVATE 220 BIT STRING SIZI Would translate to the following C typedef typedef struct ASNIT BS OSUINT32 numbits OSOCTET data 3 ASN1T BS In this case three octets would be required to hold the 18 bits eight in the first two bytes and two in the third Note that for C ASNIC generates special constructors and assignment operators to make populating a structure easier In this case two constructors were generated a default constructor and one that takes numbits and data as arguments ASNIC V5 8 40 Named Bits In the ASN 1 standard it is possible to define an enumerated bit string that specifies named constants for different bit positions ASNIC provides support for this type by generating symbolic constants and optional macros that can be used to set clear or test these named bits These symbolic constants equate the bit name to the bit number defined in the specification They can be used with the rtBitSet rtBitClear and rtBitTest run time functions to set clear and test the named bits In addition generated C code contains an enumerated constant added to the control class with an entry f
136. elements in a message Note that stream and memory buffer based encode decode functions cannot be used combined in any way The two are mutually exclusive If the stream option is selected then only stream based run time functions can be used with the generated code ASNIC V5 8 10 strict None This option instructs the compiler to generate code for strict validation of table constraints By default generated code will not check for value field constraints It should be noted that real world messages typically do not strictly follow value field table constraint definitions Therefore this option should be used with care trace None This option is used to tell the compiler to add trace diagnostic messages to the generated code These messages cause print statements to be added to the generated code to print entry and exit information into the generated functions This is a debugging option that allows encode decode problems to be isolated to a given production processing function Once the code is debugged this option should not be used as it adversely affects performance uniquenames None This option instructs the compiler to automatically generate unique names to resolve name collisions in the generated code Name collisions can occur for example if two modules are being compiled that contain a production with the same name A un ique name is generated by prepending the module name to one of the
137. ement a custom memory management scheme This is done by implementing some or all of the C rrMemHeap functions defined in the following interface note a default implementation is shown that replaces the ASNIC memory manager with direct calls to the standard C run time memory management functions include lt stdlib h gt include rtMemory h Create a memory heap int rtMemHeapCreate void ppvMemHeap return ASN OK Allocate memory void rtMemHeapAlloc void ppvMemHeap int nbytes return malloc nbytes Allocate and zero memory void rtMemHeapAllocZ void ppvMemHeap int nbytes void ptr malloc nbytes if 0 ptr memset ptr 0 nbytes return ptr Free memory pointer void rtMemHeapFreePtr void ppvMemHeap void mem p free mem p Reallocate memory void rtMemHeapRealloc void ppvMemHeap void mem p int nbytes return realloc mem p nbytes Clears heap memory frees all memory reset all heap s variables void rtMemHeapFreeAll void ppvMemHeap should remove all allocated memory there is no analog in standard memory management Frees all memory and heap structure as well if was allocated void rtMemHeapRelease void ppvMemHeap ASNIC V5 8 103 should free all memory allocated free memory heap object if exists In most cases it is only necessary to implement the following functions rtMemHeapAlloc rtMemHeapAllocZ
138. er memory management functions can be found in the C C Common Run Time Library Reference Manual Compact Code Generation Using the compact code generation option compact and lax validation option ax can also improve decoding performance The compact option causes code to be generated that contains no diagnostic or error trace messages In addition some status checks and other non critical code are removed providing a slightly less robust but faster code base The ax option causes all constraint checks to be removed from the generated code Performance intensive applications should also be sure to link with the compact version of the base run time libraries These libraries can be found in the ib_opt for optimized subdirectory These run time libraries also have all diagnostics and error trace messages removed as well as some non critical status checks Decode Fast Copy Fast Copy is a special run time flag that can be set for the decoder that can substantially reduce the number of copy operations that need to be done to decode a message The copy operations are reduced by taking advantage of the fact that the data contents of some ASN 1 types already exist in decoded form in the message buffer Therefore there is no need to allocate memory for the data and then copy the data from the buffer into the allocated memory structure As an example of what fast copy does consider a simple ASN 1 SEQUENCE consisting of an element
139. er will search for import files By default the compiler looks for files in the current working directory with the name of the module being imported and extension asn Additional directories can be searched for these files by adding them here User defined configuration files are specified in the third pane These allow further control of the compilation process They are optional and are only needed if the default compilation process is to be altered for example if a type prefix 1s to be added to a generated type name See the Compiler Configuration File section for details on defining these files After specification of these files and directories is complete click the Next button to proceed to the next window The next window is as follows ASNIC V5 8 13 ASN1IC compiler 5 80 Objective Systems Inc 3 objective SYSTEMS INC Choose ASN 1 Standard Catagory 1997 2002 ASN 1 standard C 18980 ASN 1 standard if specification has MACRO definitions Choose Application Language Bir C Java C Ce C XML Schema Choose Encoding Decoding Rule C BER C PER select aligned or unaligned at run time C DER C CER C XER C XML Cancel Help In this window the encoding rules target language and ASN 1 syntax version 1990 or later options are specified Encoding rules are BER DER PER XER or XML and can be specified using check boxes This allows multiple sets of rules to be specified
140. erated BER Encode Functions NOTE This section assumes standard memory buffer based encoding is to be done If stream based encoding is to be done specified by adding stream to the ASNIC command line see the Generated BER Stream Oriented Encode Functions section for correct procedures on using the stream based encode functions For each ASN 1 production defined in the ASN 1 source file a C encode function is generated This function will convert a populated C variable of the given type into an encoded ASN 1 message If C code generation is specified a control class is generated that contains an Encode method that wraps this function This function is invoked through the class interface to convert a populated msgData attribute variable into an encoded ASN 1 message Generated C Function Format and Calling Parameters The format of the name of each generated encode function is as follows 5 asnlE lt prefix gt lt prodName gt where lt prodName gt is the name of the ASN 1 production for which the function is being generated and prefix is an optional prefix that can be set via a configuration file setting The configuration setting used to set the prefix is the lt typePrefix gt element This element specifies a prefix that will be applied to all generated typedef names and function names for the production The calling sequence for each encode function is as follows len asnlE lt name gt ASNICTXT pctxt
141. error processing else check for other known message types Need to reset all memory for next iteration rtMemReset amp ctxt end of loop Step 6 Close the stream rtStreamBufClose amp ctxt Remember to release dynamic memory when done rtFreeContext amp ctxt The only changes were the addition of the for loop and the call to rtMemReset that was added at the bottom of the loop This function resets the memory tracking parameters within the context to allow previously allocated memory to be reused for the next decode operation Optionally rtMemF ree can be called to release all memory This will allow the loop to start again with no outstanding memory allocations for the next pass Generated Stream Oriented C Decode Method Format and Calling Parameters Generated C stream oriented decode functions are invoked through the C class interface by calling the generated DecodeFrom method The calling sequence for this method is as follows ASNIC V5 8 145 status lt object gt DecodeFrom lt inputStream gt In this definition lt object gt is an instance of the control class i e ASN1C_ lt prodName gt generated for the given production The lt inputStream gt placeholder represents an input stream object type This is an object derived from an ASNI1 InputStream class The function result variable stat returns the completion status Error status codes are negative Return status v
142. ess received data else error processing case TV handle other known messages Note that the call to free memory is not required to release dynamic memory when using the C interface This is because the control class hides all of the details of managing the context and releasing dynamic memory The memory is automatically released when both the message buffer object ASN BERMessageBuffer and the control class object ASNIC_ lt ProdName gt are deleted or go out of scope Reference counting of a context variable shared by both interfaces 1s used to accomplish this Decoding a Series of Messages Using the C Control Class Interface The above example is fine as a sample for decoding a single message but what happens in the more typical scenario of having a long running loop that continuously decodes messages The logic shown above would not be optimal from a performance standpoint because of the constant creation and destruction of the message processing objects It would be much better to create all of the required objects outside of the loop and then reuse them to decode and process each message ASNIC V5 8 125 A code fragment showing a way to do this is as follows include employee h include file generated by ASNIC main OSOCTET msgbuf 1024 ASNITAG msgtag int msglen status Create message buffer ASNIT and ASNIC objects ASNIBERDecodeBuffer decodeBuffer msgbuf len ASNIT Pers
143. est is the JookupObject method This was generated for the id field because it was identified asakey field This determination was made because id was declared to be UNIQUE in the class definition above A field can also be determined to be a key field if it is referenced via the notation in a table constraint in a standard type definition For example in the following element assignment argument OPERATION amp Type SupportedAttributes opcode the opcode element s ATTRIBUTE class field is identified as a key field ASNIC V5 8 82 Encode Decode Function Prototypes If BER or DER encoding is specified a BER encode and decode function prototype is generated for each production DER uses the same form there are only minor differences between the two types of generated functions These prototypes are of the following general form int asnlE lt ProdName gt ASNICTXT pctxt lt ProdName gt data p ASNlTagType tagging int asnlD ProdName ASNICTXT pctxt lt ProdName gt data p ASN1TagType tagging int length The prototype with the asn E_ prefix is for encoding and the one with asn1D is for decoding The first parameter is a context variable used for reentrancy This allows the encoder decoder to keep track of what it is doing between function invocations The second parameter is for passing the actual data variable to be encoded or decoded This is a pointer to a variable of the generated type The thir
144. eted using the C delete operator Populating Generated Structure Variables for Encoding Prior to calling a compiler generated encode function a variable of the type generated by the compiler must be populated This is normally a straightforward procedure just plug in the values to be encoded into the defined fields However things get more complicated when more complex constructed structures are involved These structures frequently contain pointer types which means memory management issues must be dealt with There are three alternatives for managing memory for these types 1 Allocate the variables on the stack and plug the address of the variables into the pointer fields Use the standard malloc and free C functions or new and delete C operators to allocate memory to hold the data and 3 Use the rtMemAlloc and rtMemFree run time library functions or their associated macros Allocating the variables on the stack is an easy way to get temporary memory and have it released when it is no longer being used But one has to be careful when using additional functions to populate these types of variables A common mistake is the storage of the addresses of automatic variables in the pointer fields of a passed in structure An example of this error is as follows assume A B and C are other structured types typedef struct A a B b Cee Parent void fillParent Parent parent A aa B bb o oct logic to popul
145. f messages using the stream ori ented C decode functions 122 143 generated C function format and calling parameters 140 generated stream oriented C decode method for mat and calling parameters 145 generated BER stream oriented encode function encoding a series of messages using C control class interface 137 encoding a series of messages using the stream ori ented C encode functions 134 generated stream oriented C function format and call ing parameters 132 generated stream oriented C encode method for mat and calling parameters 136 procedure for calling C stream oriented encode func tions 133 procedure for using stream oriented C control class encode method 136 generated C code for Table Constraints 89 generated C function format BER decode method 119 BER encode method 109 BER stream oriented decode method 140 PER decode method 157 PER encode method 150 XER decode method 171 XER encode method 164 generated C source files 98 generated C table constraint function prototypes 89 generated C class definition for BER DER PER 84 generated C class definition for XER 85 generated C classes for table constraints 90 generated C copy constructor 188 generated C decode method format BER decode method 120 PER decode method 158 208 generated C destructor 188 generated C encode method format BER encode method 111 PER encode method 150 XER encode method 165 generated C source files 99 generated C stream orient
146. f the given type If C code generation is specified a control class is generated that contains a Decode method that wraps this function This function is invoked through the class interface to decode an ASN 1 message into the variable referenced in the msgData component of the class Generated C Function Format and Calling Parameters The format of the name of each decode function generated is as follows asnlD prefix prodName where lt prodName gt is the name of the ASN 1 production for which the function is being generated and prefix is an optional prefix that can be set via a configuration file setting The configuration setting used to set the prefix is the lt typePrefix gt element This element specifies a prefix that will be applied to all generated typedef names and function names for the production The calling sequence for each decode function is as follows status asnlD lt name gt ASNICTXT pctxt lt name gt pvalue ASN1TagType tagging int length In this definition lt name gt denotes the prefixed production name defined above The pctxt argument is used to hold a context pointer to keep track of decode parameters This is a basic handle variable that is used to make the function reentrant so it can be used in an asynchronous or threaded application The user is required to supply a pointer to a variable of this type declared somewhere in his or her program The variable must be initialized using the
147. fer or dynamic The decoder allocates dynamic memory from within its context to hold the memory for the string This memory is released when the rtMemFree function is called The useful character string types in ASN 1 are as follows UTF8String UNIVERSAL 12 IMPLICIT OCTET STRING NumericString UNIVERSAL 18 IMPLICIT IA5String PrintableString UNIVERSAL 19 IMPLICIT IA5String T6l1String UNIVERSAL 20 IMPLICIT OCTET STRING VideotexString UNIVERSAL 21 IMPLICIT OCTET STRING TA5String UNIVERSAL 22 IMPLICIT OCTET STRING UTCTime UNIVERSAL 23 IMPLICIT GeneralizedTim GeneralizedTime UNIVERSAL 24 IMPLICIT IA5String GraphicString UNIVERSAL 25 IMPLICIT OCTET STRING VisibleString UNIVERSAL 26 IMPLICIT OCTET STRING GeneralString UNIVERSAL 27 IMPLICIT OCTET STRING UniversalString UNIVERSAL 28 IMPLICIT OCTET STRING BMPString UNIVERSAL 30 IMPLICIT OCTET STRING ObjectDescriptor UNIVERSAL 7 IMPLICIT GraphicString Of these all are represented by const char pointers except for the BMPString and UniversalString types The BMPString is a 16 bit character string for which the following structure is used typedef struct OSUINT32 nchars OSUNICHAR data Asnll 6oBitCharString The OSUNICHAR type used in this definition represents a Unicode character UTF 16 and is defined to bea C
148. fer for stream oriented encoding all octets are written to the stream The buffer in the context structure is used only as a cache If C code generation is specified a control class is generated that contains an EncodeTo method that wraps the stream encode C function This function is invoked through the class interface to convert a populated msgData attribute variable into an encoded ASN 1 message Generated Stream Oriented C Function Format and Calling Parameters The format of the name of each generated stream oriented encode function is as follows asnlBSE lt prefix gt lt prodName gt where lt prodName gt is the name of the ASN 1 production for which the function is being generated and lt prefix gt is an optional prefix that can be set via a configuration file setting The configuration setting used to set the prefix is the lt typePrefix gt element This element specifies a prefix that will be applied to all generated typedef names and function names for the production The calling sequence for each encode function is as follows stat asnlBSE lt name gt ASNICTXT pctxt lt name gt pvalue ASN1TagType tagging In this definition lt name gt denotes the prefixed production name defined above The pctxt argument is used to hold a context pointer to keep track of encode parameters This is a basic handle variable that is used to make the function reentrant so it can be used in an asynchronous or threaded appl
149. ferent range values Min Lower Bound Max Upper Bound ASNIC Type C Type 128 127 OSINT8 char signed 8 bit int 0 255 OSUINTS8 unsigned char unsigned 8 bit number 32768 32767 OSINT 16 short signed 16 bit int 0 65535 OSUINT16 unsigned short unsigned 16 bit int ASNIC V5 8 37 2147483648 2147483647 OSINT32 int signed 32 bit integer 0 4294967295 OSUINT32 unsigned int unsigned 32 bit integer The C type that is used to represent a given integer value can also be altered using the lt ctype gt configuration variable setting This allows any of the integer types above to be used for a given integer type as well as a 64 bit integer type The values that can be used with lt ctype gt are byte int16 uint16 int32 uint32 and int64 An example of using this setting is as follows Suppose you have the following integer declaration in your ASN 1 source file MyIntType APPLICATION 1 INTEGER You could then have ASNIC use a 64 bit integer type for this integer by adding the following declaration to a configuration file to be associated with this module lt production gt lt name gt MyIntType lt name gt lt intCType gt int64 lt intCType gt lt production gt The lt intCType gt setting is also available at the module level to specify that the given C integer type be used for all unconstrained integers within the module Large Integer
150. fixed type field member variables with the values specified in the information object The classes also implement the virtual methods generated for the information object type fields All non optional methods are required to be implemented The optional methods are only implemented if they are defined in the information object definition ASNIC V5 8 79 An example of an information object definition that is derived from the ASN 1 class above is as follows name ATTRIBUTI y oes La oe WITH SYNTAX VisibleString ID O 1 yg This results in the generation of the following C class class EXT ERN name public name public ATTRIBUTI Gl na virtual int encodeBERType ASNICTXT pctxt ASN1TObject amp object virtual int decodeBERType ASNICTXT pctxt ASN1TObject amp object The constructor implementation for this class not shown sets the fixed type fields id to the assigned values 0 J 17 The class also implements the virtual methods for the type field virtual methods defined in the base class These methods simply call the BER encode or decode method for the assigned type this example assumes ber was specified for code generation other encode rules could have been used as well Generated Type Assignments If the information object contains an embedded type definition it is extracted from the definition to form a new type to be added to the generated C or C code
151. follows status asnlPD name ASNICTXT pctxt lt name gt pvalue ASNIC V5 8 157 In this definition lt name gt denotes the prefixed production name defined above The pctxt argument is used to hold a context pointer to keep track of decode parameters This is a basic handle variable that is used to make the function reentrant so it can be used in an asynchronous or threaded application The user is required to supply a pointer to a variable of this type declared somewhere in his or her program The pvalue argument is a pointer to a variable to hold the decoded result This variable is of the type generated from the ASN 1 production The decode function will automatically allocate dynamic memory for variable length fields within the structure This memory is tracked within the context structure and is released when the context structure is freed The function result variable stat returns the status of the decode operation Status code 0 ASN_OK indicates the function was successful A negative value indicates decoding failed Return status values are defined in the asnltype h include file The reason text and a stack trace can be displayed using the rtErrPrint function described later in this document Generated C Decode Method Format and Calling Parameters Generated decode functions are invoked through the class interface by calling the base class Decode method The calling sequence for this method is as follows stat
152. for C and C The difference between the two is the C version includes constructors and assignment operators that make setting the value a bit easier The ASN OBJID type i e the type used in the C mapping is defined in asn1type h to be the following typedef struct OSUINT32 numids number of subidentifiers OSUINT32 subid ASN K MAXSUBIDS subidentifier values ASN1OBJID The constant ASN K MAXSUBIDS specifies the maximum number of sub identifiers that can be assigned to a value of the type This constant is set to 128 as per the ASN 1 standard The ASNITObjId type used in the C mapping is defined in ASNITObjId h This class extends the C ASNI OBJID structure and adds many additional constructors and helper methods See the ASN C C C Common Run time Reference Manual for more details ASNIC V5 8 47 RELATIVE OID The ASN 1 RELATIVE OID type is converted into a C or C structured type that is identical to that of the OBJECT IDENTIFIER described above ASN 1 production lt name gt RELATIVE OID Generated C code typedef ASNIOBJID lt name gt Generated C code typedef ASN1TObjId ASNIT lt name gt A RELATIVE OID is identical to an OBJECT IDENTIFIER except that it does not contain the restriction on the initial two arc values that they fall within a certain range see the X 680 standard for more details on this REAL The ASN 1 REAL type is mapped to the C type OSREAL In the global inc
153. for a single compiler run Target language and syntax version have radio button controls that only allow a single choice in each of these categories to be specified It is required that at least one item from each of these categories be specified Once these items have been specified click Next to proceed to the next window The next window is as follows ASNIC V5 8 14 ASN1C compiler 5 80 Objective Systems Inc objective SYSTEMS INC Code Reduction Options Code Addition Alter Options PRO Version Options Other Options Choose additional compiler options NOTE All of these items are optional r Code Reduction Options Generate compact code Do not generate encode functions Do not generate decode functions Do not generate indefinite length tests Do not generate open extension elements Do not generate code to check constraints lt Back Cancel Help This dialog contains additional optional tabs that allow code reduction options code addition alter options PRO version options and other options to be specified Select the Code Reduction Options tab These options reduce the amount of code generated at the expense of some features that are normally added to the code Click on Help to get a summary of what each of these options do or read the section Running ASNIC from the Command line Al of these items are optional Some items will be grayed out 1f they are not applicabl
154. getp Note that this is not the start of the allocated memory that is maintained within the context structure To free the memory the rtMemFree run time macro must be called The following code fragment illustrates encoding using a dynamic buffer include employee h include file generated by ASNIC main OSOCTET msgptr int msglen ASNICTXT ctxt Employee employee typedef generated by ASNIC if rtInitContext amp ctxt ASN OK initialization failed could be a license problem printf context initialization failed check license n return 1 xe setp amp ctxt NULL 0 mployee name numocts 5 mployee name data SMITH msglen asnlE Employee amp ctxt amp employee ASNIEXPL if msglen gt 0 ASNIC V5 8 ay 113 msgptr xe getp amp ctxt rtMemFree amp ctxt don t call free msgptr else error processing Encoding a Series of Messages Using the C Encode Functions A common application of BER encoding is the repetitive encoding of a series of the same type of message over and over again For example a TAP3 batch application might read billing data out of a database table and encode each of the records for a batch transmission If a user was to repeatedly allocate free memory and reinitialize the C objects involved in the encoding of a message performance would suffer This is not necessary howe
155. gt If additional options are used such as genPrint genCopy etc additional files will be generated lt moduleName gt Copy c copy functions generated if genCopy is specified lt moduleName gt Print c print functions generated if genPrint is specified lt moduleName gt Compare c comparison functions generated if genCompare is specified lt moduleName gt PrtToStr c print to string functions generated if genPrtToStr is specified lt moduleName gt PrtToStrm c print to stream functions generated if genPrtToStrm is specified lt moduleName gt Table c table constraint functions generated if genTable option is specified lt moduleName gt Test c test functions generated if genTest is specified If genCopy genPrint etc have a filename parameter then the code will be written to the given file instead of the default one If the cfile filename option is used and genCopy genPrint etc options do not have parameters then all code will be placed in one source file with name lt filename gt Maximum Lines per File In each of the cases above it is possible to specify an approximate maximum number of lines that each of the generated c files may contain This is done using the maxlines option If maxlines is specified with no parameter a default maximum number of lines 50 000 will be set otherwise the given value will be used If the given maximum lines limit is surpassed in a file
156. he next window is as follows ASNIC V5 8 18 ASN1IC compiler 5 80 Objective Systems Inc objective SYSTEMS INC More options related to C C code generation Generate initialization functions Change Code Generation filenames Change source filename Change header filename Change print routine filename Change print to buffer routine filename Change print to stream routine filename Change comparision routine filename Change copy routine filename TE a This window is specific to the target language C C Java or XML Schema that was selected earlier The window shown here is for C C If Java or XML Schema was selected a different window will be presented allowing selection of options specific to those languages The C C window allows additional code generation options and output filenames to be chosen The output filenames are optional the compiler will create default names using the name of the ASN 1 modules being compiled Once again options may be grayed out based on selections made on previous pages Click Next to move to the next window If XML Schema was selected as the target language the following window would be displayed ASNIC V5 8 19 ASN1IC compiler 5 80 Objective Systems Inc objective SYSTEMS INC More Options related to XML Schema code ml Schema Generate an SD mapping for ASN 1 table constraints Gener
157. hen the argument element may have a value of a type that is not in the defined set In this case if the index element value is outside the information object set then the argument element will be assumed to be an Asn OpenType The Invoke type encode function call will use the value from argument encoded data field i e it will have to be pre encoded because the encode function will not be able to determine from the table constraint how to encode it A C program fragment that could be used to encode an instance of the nvoke type is as follows ASNIC V5 8 92 include TestTable h include file generated by ASNIC main const OSOCTET msgptr OSOCTET msgbuf 1024 int msglen step 1 construct ASN1C C generated class this specifies a static encode message buffer ASN1B I REncodeBuffer encodeBuffer msgbuf sizeof msgbuf step 2 populate msgData structure with data to be encoded ASNIT Invoke msgData ASNI1C Invoke invok encodeBuffer msgData msgData opcode numids 3 msgData opcode subid 0 0 msgData opcode subid 1 1 msgData opcode subid 2 1 ASN1VisibleString argument objsys msgData argument decoded void amp argument note opcode value is 011 so argument must be ASN1IVisibleString type step 3 invoke Encode method if msglen invoke Encode gt 0 encoding successful get pointer to start of me
158. i to SUA s Sesto RO RRG ERR SERRA BEBE Gi ORE Ue Xa E RR GN EUR 182 PAn FOYm t esee vitis ren a haga vende bina a anert es timet qus es eub wags dte Mete qup ats 183 GENERATED COMPARE FUNCTIONS ssssssssssse e ee ees 185 GENERATED COPY FUNCTIONS a2 irotentebjePeotes ho E SEPEN ESSE STENE UE SERO Ee tiara 186 GENERATED TEST FUNCTIONS 4 ara ap ROI ERHEUC EORR HE EROR CAT REL AE EEE RC dC d 189 GENERATED MAKEFILE didus iden hth etg ERR d CO d 4 wh ed diclo dal eoe teat 191 EVENT HANDLER INTERFACE lesse hh s 193 PLOW AE Works ette tette eeu LU E SIE eae tM I LM UE 193 HOW to Use dts sre dial eine S ee 8 Oe AE GAS EE Os SPP ERU S ng BES E ees 194 IMPORT EXPORT OF TYPES ei aiat deve rl E RU AUD THEN HER UA ee eee AURI EAD OR 200 ROSE and SNMP Macro Support cc cece ce eee eee e cece reer cere ees 201 ROSE OPERATION and ERROR 0 0 0 cette s 201 SNMP OBJEGT TYPE kd edes eo lue os Bho ers obese beue 204 Index PEPENDIT ASNIC V5 7 iii ASNIC V5 7 Overview of ASN1C The ASNIC code generation tool translates an Abstract Syntax Notation 1 ASN 1 source file into computer language source files that allow ASN 1 data to be encoded decoded This release of the compiler includes options to generate code in four different languages C C C or Java This manual discusses the C and C code generation capabilities The ASNIC Java User Manual discusses the Java code generation capability The ASNIC C User S Manual discusse
159. ialize an encoding context This is a variable of type ASNICTXT This variable holds all of the working data used during the encoding of a message The context variable is declared as a normal automatic variable within the top level calling function It must be initialized before use This can be accomplished by using the rt nitContext function as follows ASNICTXT ctxt if rtInitContext amp ctxt ASN OK initialization failed could be a license problem printf context initialization failed check license n return 1 The next step 1s to specify an encode buffer into which the message will be encoded This is accomplished by calling the xe setp run time function The user can either pass the address of a buffer and size allocated in his or her program referred to as a static buffer or set these parameters to zero and let the encode function manage the buffer memory allocation referred to as a dynamic buffer Better performance can normally be attained by using a static buffer because this eliminates the high overhead operation of allocating and reallocating memory After initializing the context and populating a variable of the structure to be encoded an encode function can be called to encode the message If the return status indicates success positive length value the run time library function xe getp can be called to obtain the start address of the encoded message Note that the returned address is not the s
160. ic to all type of encode decode functions If the cfile command line option 1s used the functions are written to the specified c or cpp file along with all other generated functions If maxcfiles is specified each generated function is written to a separate c file The format of the name of each generated memory free function is as follows asnlFree prefix prodName where lt prodName gt is the name of the ASN 1 production for which the function is being generated and prefix is an optional prefix that can be set via a configuration file setting The configuration setting used to set the prefix 1s the lt typePrefix gt element This element specifies a prefix that will be applied to all generated typedef names and function names for the production The calling sequence for each generated memory free function is as follows asnlFree name ASNICTXT pctxt name pvalue In this definition lt name gt denotes the prefixed production name defined above The pctxt argument is used to hold the context pointer that the memory to be freed was allocated with This is a basic handle variable that is used to make the function reentrant so it can be used in an asynchronous or threaded application The user is required to supply a pointer to a variable of this type declared somewhere in his or her or her program The pvalue argument is used to pass a pointer to a variable of the item that contains the dynamic memory to be freed ASN
161. ication The user is required to supply a pointer to a variable of this type declared somewhere in his or her program This variable must be initialized using both the rt nitContext and rtStreamBufInit run time library functions see the C C Common Run Time Library Reference Manual for a description of these functions The pvalue argument holds a pointer to the data to be encoded and is of the type generated from the ASN 1 production The tagging argument is for internal use when calls to encode functions are nested to accomplish encoding of complex variables It indicates whether the tag associated with the production should be applied or not implicit versus explicit tagging At the top level the tag should always be applied so this parameter should always be set to the constant ASNIEXPL for EXPLICIT The function result variable stat returns the completion status of the operation 0 ASN OK means the success ASNIC V5 8 132 Procedure for Calling Stream Oriented C Encode Functions This section describes the step by step procedure for calling a stream oriented C BER encode function This method must be used if C code generation was done This method can also be used as an alternative to using the control class interface if C code generation was done Before any encode function can be called the user must first initialize an encoding context This is a variable of type ASNICTXT This variable holds all of the working data used during
162. ich the buffer already contains multiple messages encoded back to back it is necessary to advance the buffer pointer in each iteration main OSOCTET msgbuf 1024 ASNITAG msgtag int offset 0 msglen len ASNICTXT ctxt PersonnelRecord employee FILE fp Step 1 Initialize a context variable for decoding if rtInitContext amp ctxt ASN OK initialization failed could be a license problem printf context initialization failed check license n return 1 if fp fopen filename rb msglen fread msgbuf 1 sizeof msgbuf fp else handle error ASNIC V5 8 123 for offset lt msglen xd setp amp ctxt msgbuf offset msglen offset amp msgtag amp len Decode if tag TV PersonnelRecord Call compiler generated decode function stat asnlD PersonnelRecord amp ctxt amp employee ASNIEXPL 0 if stat ASN OK decoding successful data in employee else error handling return l else printf unexpected tag hx received n tag offset ctxt buffer byteIndex rtMemReset amp ctxt Procedure for Using the C Control Class Decode Method Normally when a message is received and read into a buffer it can be one of several different message types So the first job a programmer has before calling a decode function is determining which function to call The ASNIBERDecodeB
163. ific to XER Before an XER encode function can be called the user must first initialize an encoding context block structure The context block is initialized by either calling the rtNewContext function to allocate a dynamic context block or by calling rt nitContext to initialize a static block The user then must call the xerSetEncBufPtr function to specify a message buffer to receive the encoded message Specification of a dynamic message buffer is possible by setting the buffer address argument to null and the buffer size argument to zero This function also also allows specification of whether standard XER or canonical XER encoding should be done An encode function can then be called to encode the message If the return status indicates success ASN_OK then the message will have been encoded in the given buffer XER encoding starts from the beginning of the buffer and proceeds from low memory to high memory until the message is complete This differs from BER where encoding was done from back to front Therefore the buffer start address is where the encoded XER message begins The length of the encoded message can be obtained by calling the xerGetMsgLen run time function If dynamic encoding was specified i e a buffer start address and length were not given the run time routine xerGetMsgPtr can be used to obtain the start address of the message This routine will also return the length of the encoded message A program fragment that could b
164. ified on the command line For each ASN 1 production defined in the ASN 1 source file a C PER encode function is generated This function will convert a populated C variable of the given type into a PER encoded ASN 1 message If C code generation is specified a control class is generated that contains an Encode method that wraps this function This function is invoked through the class interface to encode an ASN 1 message into the variable referenced in the msgData component of the class Generated C Function Format and Calling Parameters The format of the name of each generated PER encode function is as follows asnlPE lt prefix gt lt prodName gt where lt prodName gt is the name of the ASN 1 production for which the function is being generated and prefix is an optional prefix that can be set via a configuration file setting The configuration setting used to set the prefix is the lt typePrefix gt element This element specifies a prefix that will be applied to all generated typedef names and function names for the production The calling sequence for each encode function is as follows status asnlPE name ASNICTXT pctxt lt name gt value In this definition lt name gt denotes the prefixed production name defined above The pctxt argument is used to hold a context pointer to keep track of encode parameters This is a basic handle variable that is used to make the function reentrant so it can be used in a
165. iguration File section ASNIC V5 8 depends None This option instructs the compiler to generate a full set of header and source files that contain only the productions in the main file being compiled and items those productions depend on from IMPORT files der None This option instructs the compiler to generate functions that implement the Distinguished Encoding Rules DER as specified in the X 690 ASN 1 standard events None Generate extra code to invoke user defined event and error handler callback methods see the Event Handlers section When combined with the notypes option causes pure parser functions to be generated genCompare compare lt filename gt This option allows the specification of a C or C source c or cpp file to which generated compare functions will be written Compare functions allow two variables of a given ASN 1 type to be compared for equality The lt filename gt argument to this option is optional If not specified the functions will be written to lt modulename gt Compare c where lt modulename gt is the name of the module from the ASN 1 source file genCopy copy lt filename gt This option allows the specification of a C or C source c or cpp file to which generated copy functions will be written Copy functions allow a copy to be made of an ASNIC generated variable For C they cause copy constructors and assignment operators to be add
166. ing The configuration setting used to set the prefix is the lt typePrefix gt element This element specifies a prefix that will be applied to all generated typedef names and function names for the production The calling sequence for each generated print function is as follows asnlPrint name ASN1ConstCharPtr name lt name gt pvalue In this definition lt name gt denotes the prefixed production name defined above The name argument is used to hold the top level name of the variable being printed It is typically set to the same name as the pvalue argument in quotes for example to print an employee record a call to asn Print Employee employee amp employee might be used The pvalue argument is used to pass a pointer to a variable of the item to be printed If C code generation is specified a Print method is added to the ASNIC control class for the type This method takes only a name argument the pvalue argument is obtained from the msgData reference contained within the class Print to String The genPrtToStr option causes functions to be generated that print the contents of variables of generated types to a given text buffer This buffer can then be used to output the information to other mediums such as a file or window display It is possible to specify the name of a c or cpp file as an argument to this option to specify the name of the file to which these functions will be written This is an optional argument If
167. ing the control class interface if C code generation was done Before any decode function can be called the user must first initialize a context variable This is a variable of type ASNICTXT This variable holds all of the working data used during the decoding of a message The context variable is declared as a normal automatic variable within the top level calling function It must be initialized before use This can be accomplished by using the rt nitContext function Also the context must be initialized for streaming operations by calling the rtStreamBufInit function ASNICTXT ctxt context variable if rtInitContext amp ctxt ASN_OK initialization failed could be a license problem printf context initialization failed check license n return 1 rtStreamBufInit amp ctxt Initialize stream The next step is to create a stream object within the context This object is an abstraction of the output device to which the data is to be encoded and is initialized by calling one of the following functions e riStreamFileOpen riStreamFileAttach r StreamSocketAttach e rtStreamMemoryCreate r tStreamMemoryAttach The flags parameter of these functions should be set to the OSRTSTRMF INPUT constant value to indicate an input stream is being created see the C C Common Run Time Library Reference Manual for a full description of these functions After initializing the context and populating
168. inkedOperationNames OperationList empty OperationList Operation OperationList Operation Operation value OPERATION shall reference an operation value type shall reference an operation type if no operation value is specified NamedType identifier type type END This MACRO does not need to be defined in the ASN 1 specification to be parsed In fact any attempt to redefine this MACRO will be ignored Its definition is hard coded into the compiler The compiler uses this definition to parse types and values out of OPERATION definitions An example of an OPERATION definition is as follows login OPERATION RGUMENT SEQUENCE ESULT SEQUENCE A R username IA5String password IA5String ticket OCTET STRING welcomeMessag IA5String ERRORS authenticationFailure s 1 A SNIC V5 8 insufficientResources 201 In this case there are two embedded types an ARGUMENT type and a RESULT type and an integer value 1 that identifies the OPERATION There are also error definitions The ASNIC compiler generates two types of items for the OPERATION 1 It extracts the type definitions from within the OPERATION definitions and generates equivalent C C structures and encoders decoders and 2 It generates value constants for the value associated with the OPERATION i e the value to the right of the in the definition The compiler does not gener
169. ins three nesting levels X SEQUENCE a SEQUENCE aa SEQU ENCE x INTEGER y BOOLEAN bb INTEG ER In this case the generation of temporary types results in the following equivalent type definitions X a aa SEQU ENCE x INTEGER y BOOLEAN X a SEQUENC E aa X a aa bb INTEGER X SEQUENCE X a a Note that the name for the aa element type is X a aa It contains both the name for a at level 1 and aa at level 2 The concatanation of all of the intermdeiate element names can lead to very long names in some cases To get around the problem the shortnames command line option can be used to form shorter names In this case only the type name and the last element name are used In the example above this would lead to an element name of X aa The disadvantage of this is that the names may not always be unique If using this option results in non unique names an 7 suffix is added where n is a sequential number to make the names unique Note that although the compiler can handle embedded constructed types within productions it is generally not considered good style to define productions this way It is much better to manually define the constructed types for use in the final production definition For example the production defined at the start of this section can be rew
170. int main int stat ASNICTXT ctxt Employee employee typedef generated by ASNIC const char filename message dat Step 1 Initialize the context and stream if rtInitContext amp ctxt ASN OK ASNIC V5 8 133 initialization failed could be a license problem printf context initialization failed check license n return 1 rtStreamBufInit amp ctxt Step 2 create a file stream object within the context stat rtStreamFileOpen amp ctxt filename OSRTSTRMF OUTPUT if stat ASN OK rtErrPrint amp ctxt return stat Step 3 Populate the structure to b ncoded mployee name numocts 5 mployee name data SMITH Step 4 Call the generated encode function stat asnlBSE Employee amp ctxt amp employee ASNIEXPL Step 5 Check the return status and close the stream if stat ASN OK error processing rtStreamBufClose amp ctxt In general stream oriented encoding is slower than memory buffer based encoding However in the case of stream oriented encoding it is not necessary to implement code to write or send the encoded data to an output device The stream oriented functions also use less memory because there is no need for a large destination memory buffer For this reason the final performance of the stream oriented functions may be the same or better than buffer oriented funct
171. into the encoder is a null buffer pointer and zero size This tells the encoder that it is to allocate memory for the message It does this by allocating an initial amount of memory and when this is used up it expands the buffer by reallocating This can be an expensive operation in terms of performance ASNIC V5 8 107 especially if a large number of reallocations are required For this reason run time helper functions are provided that allow the user to control the size increment of buffer expansions See the C C Run Time Library Reference Manual for a description of these functions In either case after a message is encoded it is necessary to get the start address and length of the message Even in the static buffer case the message start address may be different then the buffer start address see the section on encoding BER messages For this reason each set of encoding rules has a run time C function for getting the message start address and length See the C C Run Time Library Reference Manual for a description of these functions The C message buffer classes contain the getMsgPtr getMsgCopy and getMsgLength methods for this purpose A stream message buffer can be used for BER encoding This type of buffer is used when the stream option was used to generate the encode functions See the section on BER stream encoding for a complete description on how to set up an output stream to receive encoded data ASNIC V5 8 108 Gen
172. introduced to provide a simple interface for parsing XML messages The notypes option can be used in conjunction with the events option to generate pure parsing functions In this case no C types or encode or decode functions are generated for the productions within the given ASN 1 source file Instead only a set of parser functions are generated that invoke the event handler callback functions This gives the user total control over what is done with the message data Data that is not needed can be discarded and only the parts of the message needed for a given application need to be saved How it Works Users of XML parsers are probably already quite familiar with the concepts of SAX Significant events are defined that occur during the parsing of a message As a parser works through a message these events are fired as they occur by invoking user defined callback functions These callback functions are also known as event handler functions A diagram illustrating this parsing process is as follows Parser ASN 1 decode function The events are defined to be significant actions that occur during the parsing process We will define the following events that will be passed to the user when an ASN 1 message is parsed 1 startElement This event occurs when the parser moves into a new element For example if we have a SEQUENCE a b c construct type names omitted this event will fire when we begin parsing a b and c The name
173. ions Encoding a Series of Messages Using the Stream Oriented C Encode Functions A common application of BER encoding is the repetitive encoding of a series of the same type of message over and over again For example a TAP3 batch application might read billing data out of a database table and encode each of the records for a batch transmission Encoding a series of messages using the stream oriented C encode functions is very similar to encoding of one message All that is necessary is to set up a loop in which the asn BSE_ lt name gt functions will be called It is also possible to call different asn BSE_ lt name gt functions one after another An example showing how to do this is as follows ASNIC V5 8 134 include employee h include file generated by ASNIC int main int stat ASNICTXT ctxt Employee employee typedef generated by ASNIC const char filename message dat Step 1 Initialize the context and stream if rtInitContext amp ctxt ASN OK initialization failed could be a license problem printf context initialization failed check license n return 1 rtStreamBufInit amp ctxt stat rtStreamFileOpen amp ctxt filename OSRTSTRMF OUTPUT if stat ASN OK rtErrPrint amp ctxt return stat for Step 2 Populate the structure to b ncoded mployee name numocts 5 mployee name data SMITH Step 3 Call
174. is incremented Then when either the control class object or message buffer object are deleted or go out of scope the count is decremented When the count goes to zero i e when both the message buffer object and control class object go away the context structure is released What this means to the user is that a control class or message buffer object must be kept in scope when using a data structure associated with that class A common mistake is to try and pass a data variable out of a method and use it after the control and message buffer objects go out of scope For example consider the following code fragment ASNIT lt type gt func2 ASNIT type p new ASNIT type ASNIBERDecodeBuffer decbuf ASN1C type cc decbuf p cc Decode After return cc and decbuf go out of scope therefore all memory allocated within struct p is released return p void funcl ASNIT type pType func2 pType is not usable at this point because dynamic memory has been released As can be seen from this example once func2 exits all memory that was allocated by the decode function will be released Therefore any items that require dynamic memory within the data variable will be in an undefined state An exception to this rule occurs when the type of the message being decoded is a Protocol Data Unit PDU These are the main message types in a specification The ASNIC compiler designates types th
175. is is a basic handle variable that is used to make the function reentrant so it can be used in an asynchronous or threaded application The user is required to supply a pointer to a variable of this type declared somewhere in his or her program The variable must be initialized using the rt nitContext run time function before use To perform streaming operations the context pointer pctxt must be also initialized as a stream by using the rtStreamBuflnit run time library function see the C C Common Run Time Library Reference Manual for a description of this function The pvalue argument is a pointer to a variable of the generated type that will receive the decoded data ASNIC V5 8 140 The tagging and length arguments are for internal use when calls to decode functions are nested to accomplish decoding of complex variables At the top level these parameters should always be set to the constants ASNIEXPL and zero respectively The function result variable status returns the status of the decode operation The return status will be zero ASN_ OK if decoding is successful or negative if an error occurs Return status values are defined in the asnltype h include file Procedure for Calling Stream Oriented C Decode Functions This section describes the step by step procedure for calling a stream oriented C BER decode function This procedure must be followed if C code generation was done This procedure can also be used as an alternative to us
176. ists all of the command line options and what they are used for The options are shown in alphabetical order Note that the Java and C options are not shown here They are shown in their respective documents Option Argument Description ASNIC V5 8 5 asnstd x208 x680 mixed This option instructs the compiler to parse ASN 1 syntax conforming to the specified standard x680 the default refers to modern ASN 1 as specified in the ITU T X 680 X 690 series of standards x208 refers to the now deprecated X 208 and X 209 standards This syntax allowed the ANY construct as well as unnamed fields in SEQUENCE SET and CHOICE constructs This option also allows for parsing and generation of code for ROSE OPERATION and ERROR macros and SNMP OBJECT TYPE macros The mixed option is used to specify a source file that contains modules with both X 208 and X 680 based syntax ber None This option instructs the compiler to generate functions that implement the Basic Encoding Rules BER as specified in the X 690 ASN 1 standard bitMacros None This option instructs the compiler to generate additional macros to set clear and test named bits in BIT STRING constructs By default only bit number constants are generated Bit macros provide slightly better performance because mask values required to do the operations are computed at compile time rather than run time None Generate C source code
177. ithin the structure This memory is tracked within the context structure and is released when the context structure is freed ASNIC V5 8 171 The function result variable stat returns the status of the decode operation Status code 0 ASN_OK indicates the function was successful A negative value indicates decoding failed Return status values are defined in the asn type h include file The reason text and a stack trace can be displayed using the rtErrPrint function Procedure for Calling C Decode Functions This section describes the step by step procedure for calling a C XER decode function This method must be used if C code generation was done This method cannot be used as an alternative to using the control class interface if C code generation was done Use the C procedure instead There are four steps to calling a compiler generated decode function Prepare a context variable for decoding Open a stream Call the appropriate compiler generated decode function to decode the message Free the context after use of the decoded data is complete to free allocated memory structures at Before a C XER decode function can be called the user must initialize a context variable This is a variable of type ASNICTXT This variable holds all of the working data used during the decoding of a message The context variable is declared as a normal automatic variable within the top level calling function It must be initialized before use This can
178. ition is the same as for the global case except that the specified storage type will only be applied to the generated C or C type for the given production lt typePrefix gt lt typePrefix gt prefix text This is used to specify a prefix that will be applied to all generated C and C typedef names note for C the prefix is applied after the standard ASNIT _ prefix This can be used to prevent name clashes if multiple modules are involved in a compilation and they all contain common names lt enumPrefix gt lt enumPrefix gt prefix text This is used to specify a prefix that will be applied to all generated enumerated identifiers within a module This can be used to prevent name clashes if multiple modules are involved in a compilation note this attribute is normally not needed for C enumerated identifiers because they are already wrapped in a structure to allows the type name to be used as an additional identifier lt isBigInteger gt This is a flag variable an empty element in XML terminology that specifies that this production will be used to store an integer larger than the C or C int type on the given system normally 32 bits A C string type char will be used to hold a textual representation of the value This qualifier can be applied to either an integer or constructed type If constructed all integer elements within the constructed type are flagged as big integers
179. ive value indicates encoding failed Return status values are defined in the asnltype h include file The error text and a stack trace can be displayed using the rtErrPrint function Generated C Encode Method Format and Calling Parameters Generated encode functions are invoked through the class interface by calling the base class Encode method The calling sequence for this method is as follows stat lt object gt Encode In this definition lt object gt is an object of the class generated for the given production The function result variable stat returns the status value from the XER encode function This status value will be ASN OK 0 if encoding was successful or a negative error status value if encoding fails Return status values are defined in the asnltype h include file The user must call the encode buffer class methods getMsgPtr and getMsgLen to obtain the starting address and length of the encoded message component Populating Generated Structure Variables for Encoding See the section Populating Generated Structure Variables for Encoding for a discussion on how to populate variables for encoding There is no difference in how it is done for any of the different encoding rules Procedure for Calling C Encode Functions This section describes the step by step procedure for calling C XER encode functions This procedure is similar to that for the other encoding methods except that some of the functions used are spec
180. l string for encoding such as the following SecurityKeyType secKey 0xfd09874da8875cc90240087cd12fd Note that in this definition the Ox prefix is required to identify the string as containing hexadecimal characters On the decode side the decoder will populate the variable with the same type of character string after decoding There are also a number of run time functions available for big integer support This set of functions provides an arbitrary length integer math package that can be used to perform mathematical operations as well as convert values into various string forms See the ASNIC C C Common Run time User s Manual for a description of these functions BIT STRING The ASN 1 BIT STRING type is converted into a C or C structured type containing an integer to hold the number of bits and an array of unsigned characters OCTETs to hold the bit string contents The number of bits integer specifies the actual number of bits used in the bit string and takes into account any unused bits in the last byte The type definition of the contents field depends on how the bit string is specified in the ASN 1 definition If a size constraint 1s used a static array is generated otherwise a pointer variable is generated to hold a dynamically allocated string The decoder will automatically allocate memory to hold a parsed string based on the received length of the string In the static case the length of the character array is determined
181. leString type ASN1VisibleString argument objsys msgData argument decoded void amp argument oe reste 1 1 so argument must be Step 4 Call the generated encode function msglen asnlE Invoke amp ctxt amp invoke ASNIEXPL Step 5 Check the return status note the test is 0 because the returned value is the length of the encoded message component if msglen gt 0 Step 6 If encoding is successful call xe getp to fetch a pointer to the start of th ncoded message msgptr xe getp amp ctxt else error processing ASNIC V5 8 94 General Procedure for Table Constraint decoding The general procedure to decode an ASN 1 message with table constraints is the same as without table constraints The only difference will exist in the decoded data for open type fields within the message In this case the Asn Object Asn1TObject s decoded member variable will contain the original decoded type and the encoded member variable will contain the original data in encoded form Refer to the BER DER PER decoding procedure for further information The procedure to retrieve the value for open type fields is as follow 1 Check the possible Type in the Information Object Set from index element value 2 Assign or cast the Asn Object decoded member variable void to the result type 3 The Asn1Object encoded field will hold the dat
182. ling the encode decode functions directly BER DER or PER Class Definition The general form of the class definition for BER DER or PER encoding rules is as follows class ASN1C name public ASNICType protected ASNIT name amp msgData public ASNIC name ASNIT lt name gt amp data ASN1C name ASN1MessageBufferIF amp msgBuf ASNIT name amp data standard encode decode methods defined in ASN1CType base class int Encode int Decode stream encode decode methods int EncodeTo ASN1MessageBufferIF amp msgBuf int DecodeFrom ASN1MessageBufferIF amp msgBuf 5 The name of the generated class is ASNIC name where lt name gt is the name of the production The only defined attribute 1s a protected variable reference named msgData of the generated type Two constructors are generated The first is for stream operations and allows the control class to be created using only a reference to a variable of the generated type The EncodeTo and DecodeFrom methods can then be used to encode or decode directly to and from a stream The and gt gt stream operators can be used as well The second constructor is the legacy form that allows a message buffer to be associated with a data variable at the time of creation The Encode and Decode methods defined in the ASN CType base class can be used with this construction form to encode and decode to the associated buffer
183. llow the common BER PER DER encode procedure A complete example showing how to assign an open type value is as follows Test DEFINITIONS BEGIN ATTRIBUTE CLASS amp Type amp id OBJECT IDENTIFIER UNIQUE WITH SYNTAX WITH SYNTAX amp Type ID amp id name ATTRIBUTE m d WITH SYNTAX VisibleString ID QOO 1 Ll y name ATTRIBUTE s WITH SYNTAX INTEGER ID 012 SupportedAttributes ATTRIBUTE name commonName Invoke SEQUENCE opcode ATTRIBUTE amp id SupportedAttributes argument ATTRIBUTE Type SupportedAttributes opcode END In the above example the nvoke type contains a table constraint Its element opcode refers to the ATTRIBUTE id field and argument element refers to the ATTRIBUTE Type field The opcode element is an index element for the Invoke type s table constraint The argument element is an open type whose type is determined by the opcode value In this example opcode is the key field The opcode element can have only two possible values 0 1 1 1 or 012 Ifthe opcode value is 0 1 1 then argument will have a VisibleString value and if the opcode value is 0 1 2 then argument will have an INTEGER value Any other value of the opcode element will be violation of the Table Constraint If the SupportedAttributes information object set was extensible indicated by a at the end of the definition t
184. lowing ASN 1 types cause code to be generated from different base classes e BIT STRING The generated control class is derived from the ASN CBitStr class e SEQUENCE OF or SET OF with linked list storage The generated control class is derived from the ASN1CSeqOfList base class e Defined Type The generated control class for defined types is derived from the generated base class for the reference type For example if we have A INTEGER and B A then B is a defined type and would inherit from the base class generated for A class ASNIC B public ASNIC A These intermediate classes are also derived from the ASN CType base class Their purpose is the addition of functionality specific to the given ASN 1 type For example the ASN CBitStr control class provides methods for setting clearing and testing bits in the referenced bit string variable In the generated control class the msgData member variable 1s a reference to a variable of the generated type The constructor takes two arguments an Asn MessageBufferIF message buffer interface object reference and a reference to a variable of the data type to be encoded or decoded The message buffer object is a work buffer object for encoding or decoding The interface reference can also be used to specify a stream Stream classes are derived from this same base class The data type reference is a reference to the ASN T variable that was generated for the data type ASNIC V5 8
185. lude file osSysTypes h OSREAL is defined to be a double ASN 1 production name REAL Generated C code typedef OSREAL name Generated C code typedef OSREAL ASNIT lt name gt SEQUENCE This section discusses the mapping of an ASN 1 SEQUENCE type to C The C mapping is similar but there are some differences These are discussed in the C Mapping of SEQUENCE subsection at the end of this section An ASN 1 SEQUENCE is a constructed type consisting of a series of element definitions These elements can be of any ASN 1 type including other constructed types For example it is possible to nest a SEQUENCE definition within another SEQUENCE definition as follows A SEQUENCE x SEQUENCE al INTEGER a2 BOOLEAN hy y OCTET STRING SIZE 10 In this example the production has two elements x and y The nested SEQUENCE x has two additional elements al and a2 The ASNIC compiler first recursively pulls all of the embedded constructed elements out of the SEQUENCE and forms new temporary types The names of the temporary types are of the form name element namel17 element name2 gt _ lt element nameN gt For example in the definition above two temporary types would be generated 4 x and A y A yis generated because a static OCTET STRING maps to a C struct type ASNIC V5 8 48 The general form is as follows ASN 1 production lt name gt
186. lue specification 69 CHOICE type C C mapping 58 populating generated choice structures 61 CLASS generated C code 73 generated C code 74 New generated assignments 77 OPTIONAL keyword 76 command line options 5 commas when to use 31 compact 6 9 compare functions function name format 185 generated 185 source file for 7 compat 6 100 compiler error reporting 31 running 3 compiling generated code 22 config 6 configuration file 25 arcCType element 29 ctype element 29 enumPrefix element 28 30 45 exclude types 28 include types 28 intCType element 29 isBigInteger element 30 isOpenType element 30 isPDU element 30 name attribute 28 29 30 namespace element 29 noPDU element 29 sourceFile element 28 storage element 27 28 30 typePrefix element 28 30 valuePrefix element 29 configuration specifications examples 26 configuration specifications See also attribute constants for named bits 41 contents method 193 copy functions function name format 186 generated 186 cpp 6 csharp 6 D decode function ASNIC V5 7 prototype 83 Decode method 84 decode method C control class 124 in generated C C source code 86 decode method C control class using in generated XER decode functions 174 DecodeFrom method 84 145 DecodeTo method 36 86 DEFAULT keyword in SEQUENCE 52 deferred decoding 30 130 der 7 DER decode function procedure for calling in C 120 DER decode function See also BER DER C decode func
187. mber variables for each of the fields within the class Derived information object classes are required to populate these variables with the values defined in the ASN 1 information object specification The C class also contains virtual methods representing each of the type fields within the ASN 1 class specification Ifthe field is not defined to be OPTIONAL in the ASN 1 specification then it is declared to be abstract in the generated class definition A class generated for an ASN 1 information object that references this base class is required to implement these abstract virtual methods For each of the following CLASS fields a corresponding member variable is generated in the C class definition as follows For a Value Field definition the following member variable will be added Also an Equals method will be added if required for table constraint processing lt TypeName gt lt FieldName gt inline OSBOOL idEquals lt TypeName gt pvalue For a Type Field definition a virtual method is added for each encoding rules type to call the generated C encode and decode functions If print is specified a print method is also generated virtual int encode lt ER gt lt FieldName gt ASNICTXT pctxt ASN1TObject amp object return 0 virtual int decode lt ER gt lt FieldName gt ASNICTXT pctxt ASN1TObject amp object return 0 virtual void print lt FieldName gt ASN1ConstCharPtr name ASN1TObject amp o
188. me where Name would be another type defined elsewhere within the module The compiler performs the substitution to create the proper C typedef for SignedName typedef struct SignedName Name toBeSigned ASNIOBJID algorithmOID Params paramsS ASN1DynBitStr signature SignedName When processing parameterized type definitions the compiler will first look to see if the parameters are actually used in the final generated code If not they will simply be discarded and the parameterized type converted to a normal type reference For example when used with information objects parameterized types are frequently used to pass information object set definitions to impose table constraints on the final type Since table constraints do not affect the code that is generated by the compiler the parameterized type definition is reduced to a normal type definition and references to it are handled in the same way as defined type references This can lead to a significant reduction in generated code in cases where a parameterized type is referenced over and over again For example consider the following often repeated pattern from the UMTS 3GPP specs ASNIC V5 8 66 ProtocollE Field RANAP PROTOCOL IES IEsSetParam SEQUENCE id RANAP PROTOCOL IES amp id IEsSetParam criticality RANAP PROTOCOL IES amp criticality IEsSetParam id value RANAP PROTOCOL IES amp Value IEsSetParam id
189. me VisibleString by value SeqType id 12 name abc This would result in the following definition in the C or C source file SeqType value Code generated in value unitization function value id 12 value name abc SET Value Specification SET value code generation is the same as SEQUENCE value code generation SEQUENCE OF Value Specification The mapping of the ASN 1 declaration to a global C or C value declaration is as follows ASN 1 production lt name gt SeqOfType value Generated code lt SeqOfType gt lt name gt The sequence of value will be initialized in the value initialization function For example consider the following declaration SeqOfType SEQUENCE OF SIZE 2 INTEGER value SeqOfType 1 2 This would result in the following definition in the C or C source file ASNIC V5 8 71 SeqOfType value Code generated in value initialization function value n 2 value element 0 1 value element 1 2 SET OF Value Specification SET OF value code generation 1s the same as SEQUENCE OF value code generation CHOICE Value Specification The mapping of ASN 1 declaration to global C or C value declaration is as follows ASN 1 production name ChoiceType value Generated code lt ChoiceType gt lt name gt The choice value will be initialized in the value initialization function F
190. ment const XMLCh const uri const XMLCh const localname const XMLCh const qname const Attributes amp attrs virtual void characters const XMLCh const chars const unsigned int length virtual void endElement const XMLCh const uri const XMLCh const localname const XMLCh const qname The main differences between the BER DER PER control class definition and this are 1 The class generated for XER inherits from the ASN XERSAXHandler base class and 2 The class implements the standard SAX content handler methods This allows an object of this class to be registered as a SAX content handler with any SAX compliant XML parser The parser would be used to read and parse XML documents The methods generated by ASNIC would then receive the parsed data via the SAX interface and use the results to populate the data variables with the decoded data Generated Methods For each production an EncodeFrom and DecodeTo method is generated within the generated class structure These are standard methods that initialize context information and then call the generated C like encode or decode function If the generation of print functions was specified by including print on the compiler command line a Print method is also generated that calls the C print function For XER additional methods are generated to implement a SAX content handler interface to an XML parser This includes a startElement characters and e
191. ment illustrates PER encoding using a dynamic buffer finclude employee h include file generated by ASNIC main OSOCTET msgptr int msglen sta OSBOOL aligned TRU e HJ ct Ne Create an instance of the compiler generated class This example does dynamic encoding no message buffer is specified ASN1PEREncodeBuffer encodeBuffer aligned ASNIT PersonnelRecord msgData ASN1C PersonnelRecord employ encodeBuffer msgData Populate msgData within the class variable msgData name givenName SMITH Encode if stat employee Encode ASN OK printf Encoding was successful n printf Hex dump of encoded record n ncodeBuffer hexDump printf Binary dump n encodeBuffer binDump employee ASNIC V5 8 156 Get start of message pointer and length msgptr encodeBuffer getMsgPtr len encodeBuffer getMsgLen else printf Encoding failed n encodeBuffer printErrorinfo exit 0 return 0 Encoding a Series of PER Messages using the C Interface When encoding a series of PER messages using the C interface performance can be improved by reusing the message processing objects to encode each message rather than creating and destroying the objects each time A detailed example of how to do this was given in the section on BER message encoding The PER case would be similar
192. ment is to collect any unknown items in a message If an application does not care about these unknown items it can use this option to reduce the size of the generated code notypes None This options suppresses the generation of type definitions It is used in conjunction with the events options to generate pure parser functions ASNIC V5 8 0 lt directory gt This option is used to specify the name of a directory to which all of the generated files will be written lt directory gt This option is used to specify the name of a directory to which only the generated header files h will be written param lt name gt lt value gt This option is used to instantiate all parameterized types with the ASN 1 modules that are being compiled with the given parameter value In this declaration lt name gt refers to the dummy reference in a parameterized type definition and lt value gt refers to an actual value pdu lt typeName gt Designate given type name to be a Protocol Definition Unit PDU type This will cause a C control class to be generated for the given type By default PDU types are determined to be types that are not referenced by any other types within a module This option allows that behavior to be overridden The wildcard character may be specified for lt typeName gt to indicate that all productions within an ASN 1 module should be treated as PDU
193. mplified form We don t even bother to check if the index argument is greater than or equal to zero This would determine if a x should be appended to the element name In the sample program that is included with the compiler distribution the implementation is complete In endElement we simply terminate our brace block as follows void PrintHandler endElement const char name int index mIndentLevel indent printf n ASNIC V5 8 195 All that each of the various value methods have to do is print a stringified representation of the value out to stdout For example the intValue callback would just print an integer value void PrintHandler intValue int value indent printf d n value Next we need to create an object of our derived class and register it prior to invoking the decode method In the reader cpp program the following lines do this Create and register an event handler object PrintHandler pHandler new PrintHandler employee decodeBuffer addEventHandler pHandler The addEventHandler method defined in the Asn 1 MessageBuffer base class is the mechanism used to do this Note that event handler objects can be stacked Several can be registered before invoking the decode function When this is done the entire list of event handler objects is iterated through and the appropriate event handling callback function invoked whenever a defined even
194. n an additional copy constructor if C is used and PDU generation is not disabled A destructor is also generated if the type contains dynamic memory fields This destructor will free the dynamic memory upon destruction of the type instance For example typedef struct EXTERN ASNIT PersonnelRecord public ASNITPDU ASNIT PersonnelRecord m uniPresent 0 m seqOfseqPresent 0 ASN1T_PersonnelRecord ASN1C PersonnelRecord amp srcData ASNIT PersonnelRecord ASNIT PersonnelRecord This constructor is used to create an instance of the ASNIT lt name gt type from an ASNIC lt name gt control class object Memory Management of Copied Items Prior to ASNIC version 5 6 dynamic memory of decoded or copied items would only be available as long as the control class instance and or the message buffer object used to decode or copy the item remained in scope or was not deleted This restriction no longer exists as long as the type being copied is a Protocol Data Unit PDU The copied item will now hold a reference to the context variable used to create the item and will increment the item s reference count This reference is contained in the ASNITPDU base class variable from which PDU data types are now derived The dynamic memory within the item will persist until the item is deleted ASNIC V5 8 188 Generated Test Functions The genTest option causes test functions to be generated These functions can be used t
195. n asynchronous or threaded application The user is required to supply a pointer to a variable of this type declared somewhere in his or her program The value argument contains the value to be encoded or holds a pointer to the value to be encoded This variable is of the type generated from the ASN 1 production The object is passed by value if it is a primitive ASN 1 data type such as BOOLEAN INTEGER ENUMERATED etc It is passed using a pointer reference if it is a structured ASN 1 type value Check the generated function prototype in the header file to determine how the value argument is to be passed for a given function The function result variable stat returns the status of the encode operation Status code 0 ASN OK indicates the function was successful Note that this return value differs from that of BER encode functions in that the encoded length of the message component is not returned only an OK status indicating encoding was successful A negative value indicates encoding failed Return status values are defined in the asn1type h include file The error text and a stack trace can be displayed using the rtErrPrint function Generated C Encode Method Format and Calling Parameters Generated encode functions are invoked through the class interface by calling the base class Encode method The calling sequence for this method is as follows stat lt object gt Encode ASNIC V5 8 150 In this definition lt object gt
196. nIxer_a lib for BER DER PER or XER respectively and asn rt_a lib for the common run time components On UNIX Linux the library names are libasnIber a libasnIper a libasnIxer a and libasnirt a The library files are located in the lib subdirectory For UNIX the L switch should be used to point to the subdirectory path and lasnlber lasnlper lasnixer and or lasnlrt used to link with the libraries For Windows the LIBPATH switch should be used to specify the library path There are several other variations of the C C run time library files for Windows The following table summarizes what options were used to build each of these variations Library Files Description asnirt a lib Static single threaded libraries These are built without MT multithreading and asniber a lib MD dynamic link libraries options These are not thread safe However they provide asnlper a lib the smallest footprint of the different libraries asnlxer a lib asnIrt lib DLL libraries These are used to link against the DLL versions of the run time libraries asnI1 ber lib asnIrt dll etc asnIper lib asnIxer lib asnirtmt a lib Static multi threaded libraries These libraries were built with the MT option They asnlbermt a lib should be used if your application contains threads and you wish to link with the static asnlpermt a lib libraries note the DLL s are also thread safe asnIxermt_a lib asnIrtmd_a lib DLL ready m
197. ncode Method Format and Calling Parameters When C code generation is specified the ASNIC compiler generates an Encode method in the generated control class that wraps the C function call This method provides a more simplified calling interface because it hides things such as the context structure and the tag type parameters The calling sequence for the generated C class method is as follows len lt object gt Encode In this definition lt object gt is an instance of the control class i e ASNIC_ lt prodName gt generated for the given production The function result variable len returns the length of the data actually encoded or an error status code if encoding fails Error status codes are negative to tell them apart from length values Return status values are defined in the asn type h include file Procedure for Calling C Encode Functions This section describes the step by step procedure for calling a C BER or DER encode function This method must be used if C code generation was done This method can also be used as an alternative to using the control class interface if C code generation was done Note that the procedures described here cannot be used if stream based encoding is to be done specified by the use of the stream ASN1C command line option In this case the procedures described in the Generated BER Stream Oriented Encode Functions section Before any encode function can be called the user must first init
198. ndElement method An init and finalize method may also be generated to initialize a variable prior to parsing and to complete population of a variable with decoded data Generated Information Object Table Structures Information Objects and Classes are used to define multi layer protocols in which holes are defined within ASN 1 types for passing message components to different layers for processing These items are also used to define the contents of various messages that are allowed in a particular exchange of messages The ASNIC compiler extracts the ASNIC V5 8 86 types involved in these message exchanges and generates encoders decoders for them The holes in the types are accounted for by adding open type holders to the generated structures These open type holders consist of a byte count and pointer for storing information on an encoded message fragment for processing at the next level The ASNIC compiler is capable of generating code in one of two forms for information in an object specification 1 Simple form in this form references to variable type fields within standard types are simply treated as open types and an open type placeholder is inserted 2 Table form in this form all of the classes objects and object sets within a specification result in the generation of code for parsing and formatting the information field references within standard type structures The second form is selected by specifying the tables
199. nly BER or DER was specified as the encoding rules type First notice that member variables have been generated for the fixed type fields in the definition These include the id field Information object classes derived from this definition are expected to populate these fields in their constructors ASNIC V5 8 75 Also virtual methods have been generated for each of the type fields in the class These include the Type fields The method generated for Type is abstract and must be implemented in a derived information object class The method generated for the ParameterType field has a default implementations that does nothing That is because it is a optional field Also generated are Equals methods for the fixed type fields These are used by the generated code to verify that data in a generated structure to be encoded or data that has just been decoded matches the table constraint values This method will be generated only if it is required to check a table constraint OPTIONAL keyword Fields within a CLASS can be declared to be optional using the OPTIONAL keyword This indicates that the field is not required in the information object An additional construct is added to the generated code to indicate whether an optional field is present in the information object or not This construct is a bit structure placed at the beginning of the generated structure This structure always has variable name m and contains single bit elements of the fo
200. not specified the functions are written to separate files ASNIC V5 8 181 for each module in the source file The format of the name of each file is lt module gt PrtToStr c If an output filename is specified after the genPrtToStr qualifier all functions are written to that file The calling sequence for each generated print to string function is as follows asnlPrtToStr lt name gt ASN1ConstCharPtr name lt name gt pvalue char buffer int bufSize The name and pvalue arguments are the same as they were in the print case The buffer and bufSize arguments are used to describe the memory buffer the text 1s to be written into These arguments specify a fixed size buffer If the generated text 1s larger than the given buffer size as much text as possible is written to the buffer and a 1 status value is returned If the buffer is large enough to hold the text output all text is written to the buffer and a zero status 1s returned For C a toString method is generated in the control class that calls the generated print to string function In addition to the name argument this method also takes a buffer and bufSize argument to describe the buffer to which the text is to be written Print to Stream The genPrtToStrm option causes functions to be generated that print the contents of variables of generated types to an output stream via a user defined callback function The advantage of these functions is that a user can register a
201. ns The code generated to decode XML messages is different than that of the other encoding rules This is because off the shelf XML parser software is used to parse the XML documents to be decoded This software contains a common interface known as the Simple API for XML or SAX that is a de facto standard that is supported by most parsers ASNIC generates an implementation of the content handler interface defined by this standard This implementation receives the parsed XML data and uses it to populate the structures generated by the compiler The default XML parser used is the EXPAT parser http www expat org This is a lightweight open source parser that was implemented in C The C SAX interface was added by adapting the headers of the Apache XERCES C XML Parser http xml apache org to work with the underlying C code These headers were used to build a common C SAX interface across different vendor s SAX interfaces unlike Java these interfaces are not all the same The ASNIC XER SAX C and C libraries come with the EXPAT parser as the default parser and also include plug in interfaces that allow the code to work with the Microsoft XML parser MSXML The GNOME libxml parser and the XERCES XML parser Interfacing to other parsers only requires building an abstraction layer to map the common interface to the vendor s interface ASNIC V5 8 169 A diagram showing the components used in the XML decode process is as follows
202. ns an open type ASN OpenType reference to hold a previously encoded component to be specified in the final message Simple Form Code Generation In the simple form of information object code generation the Invoke type above would result in the following C or C typedefs being generated typedef struct Invoke SEQUENCE OSINT32 invokeID OPERATION operationCode opcode ASNl1OpenType argument The following would be the procedure to add the Invoke header type to an ASN 1 message body Encode the body type 2 Get the message pointer and length of the encoded body 3 Plug the pointer and length into the numocts and data items of the argument open type field in the Invoke type variable 4 Populate the remaining Invoke type fields 5 Encode the Invoke type to produce the final message In this case the amount of code generated to support the information object references is minimal The amount of coding required by a user to encode or decode the variable type field elements however can be rather large This is a tradeoff that exists between using the compiler generated table constraints solution as we will see below and using the simple form Table Form Code Generation If we now add table constraints to our original type definition it might look as follows Invoke SEQUENCE invokeID INTEGER opcode OPERATION amp 0perationCode My ops argument OPERATION amp ArgumentType
203. ns for all types generate memory free functions for all types generate makefile to build generated cod set limit of number of lines per source file default value is 50000 set output directory for header files generate static elements not pointers generate code for Windows O S default GNU Java package prefix Java package name output Java code to module name dirs generate modulename mk for list of java files generate get set methods and protected member vars generate build script generate comparison functions C namespace prefix C namespace name output C4 code to module name dirs generate modulename mk for list of C4 files generate code to invoke SAX like event handlers generate stream based encode decode functions generate table constraint functions do strict checking of table constraint conformance prtToStr lt filename gt ASNIC V5 8 generate print to string functions C C prtToStrm lt filename gt generate print to stream functions C C genTest lt filename gt generate sample test functions reader generate sample reader program writer generate sample writer program compare lt filename gt generate comparison functions C C copy lt filename gt generate copy functions C C maxcfiles generate separate file for each function C C XSD options appinfo lt items gt generate applInfo for ASN 1 items items can be tags enum
204. nt RA ERES ah tER IE tn nan HEADER H FEE io gt hd deeem e rece adden EANA du d 4 ee dd acd a eed rani dus 33 BOOLEAN hii ERR P pR EAR IND ERES SRE EEMNARC CR REE ARE BO EY AES 37 INTEGER 5e essere eua es beda kgs oe ERI ORE E pe Dex bees persa tn pegas 37 BIT STRING ics xke ha Be eee Y gd eue ed rg 9 p EY gGnc3 Ree rvrebrteddews 39 OGTEDSTRING 33 tese tos ette Pos Es eot est ect unter UM edet Saas 42 ENUMERATED roe epe ae Osher dn erp du decli culo s Dd aded tor 45 NOL Eee ea ea deed Rods em ISO ol mb ud ui tette dete dut ee Siete uie 46 OBJECT IDENTIFIER esses hh ar rrr 47 RELATIVESOID x32 e Vete te eet s ot Cainer Bath ee ta Lt OR opos 48 REAT reu E MEE ne M 48 SEQUENCE 255i rl cet Avy PRGRE TERR REG EPEERRESCETRUEBRTSSRRSPARPPERLAIqGeGp 48 SET oae eaa E dibus d eee gne equo o tes dnd eset inten gasta na mus to A eden Dosen 54 SEQUENGE OF eie o ep REG Deen aa P eebrYed ea ten eR ERs 55 SEROR eB sh ie acd quet em EN red de on dM Det Ge RE ee Py een A tope EE 58 CHOICE IEEE eh Meade ek PAR eE ORE Geass HORDE ADEN EMAAR TES uer 58 Open TYPO Pr 62 Character String Types csse e e es 62 lime String Types 1 isses uso deseo E E Rr E recs ires dde decom ts Pre i ede 64 EX TERNAL VDO eh rr xe st M Io M mme LEM DN E MEE a ATE 64 EMBEDDED PDV Type 4 eee tete tx ie ERE ri eS Pee eee 65 Parameterized Types esses hh eh hehe 65 Value Specifications as ose RE ees EREG4 ERROR SERRE RR DG RUND RC ER Fe end 68 CLASS specifi
205. nt output to stdout If C code generation is specified setPrintStream and toStream methods are added to the ASNIC control class for the type The setPrintStream method takes only myCallback and pStrmInfo arguments the pctxt argument is obtained from the context pointer reference contained within the class The toStream method takes only a name argument the pctxt argument is derived from the context pointer reference within the class and the pvalue argument is obtained from the msgData reference contained within the class Print Format The prtfmt option can be used in conjunction with any of the genPrint options documented above to alter the format of the printed data The default print format 1s the details format which provide a line by line display of everything within a generated structure For example the following is an excerpt from a details display Employee name givenName John Employee name initial P Employee name familyName Smith Employee number 51 Employee title Director The alternative format bracetext provides a C like structure printout An example of this is as follows Employee name givenName John initial P familyName Smith number 51 title Director ASNIC V5 8 183 ASNIC V5 8 184 Generated Compare Functions The genCompare option causes comparison functions to be generated These functions can be used to compare the contents of two generated t
206. ntained in the MIB The version of the MACRO currently supported by this version of ASNIC can be found in the SMI Version 2 RFC RFC 2578 The compiler generates code for two of the items specified in this MACRO definition 1 The ASN 1 type that is specified using the SYNTAX command and 2 The assigned OBJECT IDENTIFIER value For an example of the generated code we can look at the following definition from the UDP MIB udpInDatagrams OBJECT TYPE SYNTAX Counter32 MAX ACCESS read only STATUS current DESCRIPTION The total number of UDP datagrams delivered to UDP users udp 1 In this case a type definition is generated for the SYNTAX element and an Object Identifier value is generated for the entire item The name used for the type definition is lt name gt _SYNTAX where lt name gt would be replaced with the OBJECT TYPE name i e udpInDatagrams The name used for the Object Identifier value constant is the OBJECT TYPE name So for the above definitions the following two C items would be generated typedef Counter32 udpInDatagrams SYNTAX ASNIOBJID udpInDatagrams 8 1 3 6 1 2 1 7 1 ASNIC V5 8 204 Index Symbols ASN prefix 31 Numerics 16 bit character string 63 8 bit character string derivation 63 A ABSTRACT SYNTAX C C mapping 78 accessing encoded message components 107 addEventHandler method 196 ANSI standard source code for base run time libraries 24 ANY da
207. nter argument If XER encoding is specified function prototypes are generated with the following format int asnlXE ProdName ASNICTXT pctxt lt ProdName gt value ASN1ConstCharPtr elemName ASN1ConstCharPtr attrs int asnlXD ProdName ASNICTXT pctxt lt ProdName gt pvalue The encode function signature includes arguments for the context and value as in the other cases It also has an element name argument elemName that contains the name of the element to be encoded and an attributes argument attrs that ASNIC V5 8 83 can be used to encode an attributes string The decode function is generated for PDU types only decoding of internally referenced types is accomplished through generated SAX handler callback functions which are invoked by an XML parser Generated C Control Class Definition A control class definition is generated for each defined production in the ASN 1 source file that is determined to be a Protocol Data Unit PDU By default any type defined in an ASN 1 source file that is not referenced by any other type isa PDU This default behavior can be overridden by using a configuration file setting lt isPDU gt or a command line option pdu to explicitly declare that certain types are PDU s The generated control class is derived from the ASN CType base class This class provides a set of common attributes and methods for encoding decoding ASN 1 messages It hides most of the complexity of cal
208. nvoked with the initialized context variable that will be used to decode a message This should be done once prior to entering the loop that will be used to decode a stream of messages Using Initialization Functions Initialization functions are generated by the ASNIC compiler when the gen nit option is added to the ASNIC command line These functions can be used as an alternative to memset ing a variable to zero to prepare it to receive decoded data The advantage is that the initialization functions are smarter and know exactly what within the structures needs to be zeroed as opposed to blindly clearing everything So for example large byte arrays used to hold OCTET STRING data will not be zeroed This can add up to significant performance improvements in the long run particular in complex deeply nested ASN 1 types If initialization functions are generated the generated decode logic will use them wherever it can in place of calls to zero memory BER DER Deferred Decoding Another way to improve decoding performance of large messages is through the use of deferred decoding This allows for the selective decoding of only parts of a message in a single decode function call When combined with the fast copy procedure defined above this can significantly reduce decoding time because large parts of messages can be skipped Deferred decoding can be done on elements defined within a SEQUENCE SET or CHOICE construct It is done by designating
209. o populate variables of generated types with random test data The main purpose is to provide a code template to users for writing code to populate variables This is quite useful to users because generated data types can become very complex as the ASN 1 schemas become more complex It is sometimes difficult to figure out how to navigate all of the lists and pointers Using genTest can provide code that simply has to be modified to accomplish the population of a data variable with any type of data The generated test functions are written to a c or cpp file with a name of the following format asniModuleName Test c where lt asn1ModuleName gt is the name of the ASN 1 module that contains the type definitions The format of the name of each generated test function is as follows asnlTest prefix prodName where lt prodName gt is the name of the ASN 1 production for which the function is being generated and prefix is an optional prefix that can be set via a configuration file setting The configuration setting used to set the prefix 1s the lt typePrefix gt element This element specifies a prefix that will be applied to all generated typedef names and function names for the production The calling sequence for each generated test function is as follows lt typeName gt pvalue testFunc ASNICTXT pctxt In this definition lt testFunc gt denotes the formatted function name defined above The pctxt argument is
210. oStr 8 181 genPrtToStrm 181 182 genTest 189 genTestInstance method 189 getByteIndex method 127 getCopy method 186 GetMsgCopy method 116 getMsgCopy method 116 getMsgLen method 167 GetMsgPtr method 115 getMsgPtr method 167 getStatus method 146 global level attributes 26 graphical user interface 12 GUI Wizard 12 209 H header file 8 differences between C and C versions 35 sample from a C header file 33 sample from a C header file 34 hexadecimal string value specification 69 hyphens See special characters invalid I I 9 import of types 200 Information Object generated C code 79 generated C code 79 generated type assignments 80 information object definition generated 86 Information Object Set generated C code 81 generated C code 82 information objects type definition 86 initialization functions function name format 179 generated 179 integer for holding bit number 39 size big integer 38 INTEGER type C C mapping 37 INTEGER type large integer support 38 INTEGER value specification 68 ITU X 680 ASN 1 sstandard 5 J java 9 L lax 9 library run time 22 libxml2 interface library 175 linking dynamic 22 static 22 linking generated code 22 list based SEQUENCE OF type generating 56 lowercase letters when to use 31 M macro ROSE OPERATION 5 87 ROSE OPERATION and ERROR 201 SNMP OBJECT TYPE 204 makefile generated 191 maxcfiles 98 100 180 ASNIC V5 7 maxlines 98 maxSize attribu
211. objective SYSTEMS INC ASNIC ASN 1 Compiler Version 5 8 C C Compiler User s Manual Objective Systems Inc August 2005 The software described in this document is furnished under a license agreement and may be used only in accordance with the terms of this agreement Copyright Notice Copyright 1997 2005 Objective Systems Inc All Rights Reserved This document may be distributed in any form electronic or otherwise provided that it is distributed in its entirety and that the copyright and this notice are included Author s Contact Information Comments suggestions and inquiries regarding ASNIC may be submitted via electronic mail to info obj sys com CHANGE HISTORY Date Author Version Description 8 20 2005 ED 5 8 Initial version TABLE OF CONTENTS Overview of ASNIC 2 ccc ccc ccc ccc cc cece cece cere cet e n s nnn gg gs Using the Compiler i i 6u rca dO EO OY RC Ae odd pede o p XC oa seep Elser tc Roe RUNNING ASN1C FROM THE COMMAND LINE 0 000000 cece cece e 3 USING THE GUI WIZARD TO RUN ASNIC ssssseeeeeeeeee eee 12 COMPILING AND LINKING GENERATED CODE ssseeee e 22 PORTING RUN TIME CODE TO OTHER PLATFORMS 00 000 cee cece eee 24 COMPILER CONFIGURATION FILE llle rr rrr rrr rrr r rnrn 25 COMPILER ERROR REPORTING s Ia uhi dre PERCY A pee ed dr er OES GOEL Rao id n 3l Generated C C Source Code 1i es sce
212. ode fragment illustrates encoding using a dynamic buffer This also illustrates using the getMsgCopy method to fetch a copy of the encoded message include employee h include file generated by ASNIC main 0 OSOCTET msgptr int msglen ASNIC V5 8 116 construct encodeBuffer class with no arguments ASNIBEREncodeBuffer encodeBuffer ASNIT PersonnelRecord msgData ASN1C PersonnelRecord employ encodeBuffer msgData populate msgData structure msgData name SMITH call Encode method if msglen employee Encode gt 0 encoding successful get copy of message msgptr encodeBuffer getMsgCopy delete msgptr free the dynamic memory else error processing Encoding a Series of Messages Using the C Control Class Interface A common application of BER encoding is the repetitive encoding of a series of the same type of message over and over again For example a TAP3 batch application might read billing data out of a database table and encode each of the records for a batch transmission If a user was to repeatedly instantiate and destroy the C objects involved in the encoding of a message performance would suffer This is not necessary however because the C objects can be reused to allow multiple messages to be encoded As example showing how to do this is as follows include employee h include file generated by ASNIC main
213. ode is activated by using the asnstd x208 command line option Although the X 208 and X 209 standards are no longer supported by the ITU T they are still in use today This version of ASNIC contains logic to parse some common MACRO definitions that are still in widespread use despite the fact that MACRO syntax was retired with this version of the standard The types of MACRO definitions that are supported are ROSE OPERATION and ERROR and SNMP OBJECT TYPE ROSE OPERATION and ERROR ROSE stands for Remote Operations Service Element and defines a request response transaction protocol in which requests to a conforming entity must be answered with the result or errors defined in operation definitions Variations of this are used in a number of protocols in use today including CSTA and TCAP The definition of the ROSE OPERATION MACRO that is built into the ASNIC is as follows OPERATION MACRO BEGIN TYPE NOTATION Parameter Result Errors LinkedOperations VALUE NOTATION value VALUE INTEGER Parameter ArgKeyword NamedType empty ArgKeyword ARGUMENT PARAMETER Result RESULT ResultType empty Errors ERRORS ErrorNames empty LinkedOperations LINKED LinkedOperationNames empty ResultType NamedType empty ErrorNames ErrorList empty ErrorList Error ErrorList Error Error value ERROR shall reference an error value type shall reference an error type if no error value is specified L
214. ode performance These include adjusting memory allocation parameters using compact code generation using decode fast copy and using initialization functions Dynamic Memory Management By far the biggest performance bottleneck when decoding ASN 1 messages is the allocation of memory from the heap Each call to new or malloc is very expensive The decoding functions must allocate memory because the sizes of many of the variables that make up a message are not known at compile time For example an OCTET STRING that does not contain a size constraint can be an indeterminate number of bytes in length ASNIC does two things by default to reduce dynamic memory allocations and improve decoding performance Uses static variables wherever it can Any BIT STRING OCTET STRING character string or SEQUENCE OF or SET OF construct that contains a size constraint will result in the generation of a static array of elements sized to the max constraint bound 2 Uses a special nibble allocation algorithm for allocating dynamic memory This algorithm allocates memory in large blocks and then splits up these blocks on subsequent memory allocation requests This results in fewer calls to the kernel to get memory The downside is that one request for a few bytes of memory can result in a large block being allocated Common run time functions are available for controlling the memory allocation process First the default size of a memory block as allocated
215. oid writeToFile void pPrntStrmInfo ASN1ConstCharPtr fmtspec va list arglist FILE fp FILE pPrntStrmInfo vfprintf fp fmtspec arglist Once the callback function 1s defined it has to be registered with the runtime library There are two types of registrations possible 1 global which applies to all print streams and 2 context level which applies to print streams associated with a particular context ASNIC V5 8 182 For registering a global callback use rtSetGlobalPrintStream rtPrintCallback myCallback void pStrmInfo For registering a context level callback use rtSetPrintStream ASNICTXT pctxt rtPrintCallback myCallback void pStrmInfo Once the callback function is registered the calling of each generated print to stream function will result in output being directed to the callback function The print to stream functions are declared as follows asnlPrtToStrm name ASNICTXT pctxt ASN1ConstCharPtr name lt name gt pvalue The name and pvalue arguments are the same as they were in the print case The pctxt argument 1s used to specify an ASNIC context If a valid context argument is passed and there is a context level callback registered then that callback will be used If there is no context level callback registered or the pctxt argument is NULL then the global callback will be used If there is no global callback registered the default callback will be used which writes the pri
216. onnelRecord employeeData ASN1C PersonnelRecord employ decodeBuffer employeeData for logic to read message into msgbuf status decodeBuffer ParseTagLen msgtag msglen if status ASN OK handle error Now switch on initial tag value to determine what type of message was received Switch msgtag case TV PersonnelRecord compiler generated constant if status employee Decode ASN OK decoding successful data in employeeData process received data else error processing break default handle unknown message type her switch Need to reinitialize objects for next iteration ASNIC V5 8 126 if isLastIteration employee memFreeAll end of loop This is quite similar to the first example Note that we have pulled the ASNIT Employee and ASNIC Employee object creation logic out of the switch statement and moved it above the loop These objects can now be reused to process each received message The only other change was the call to employee memFreeAll that was added at the bottom of the loop Since we can t count on the objects being deleted to automatically release allocated memory we need to do it manually This call will free all memory held within the decoding context This will allow the loop to start again with no outstanding memory allocations for the next pass If the buffer already contains multiple
217. or all unconstrained integers lt arcCType gt int32 int64 The is used to specify a specific C integer type be used for the arc types in Object Identifier definitions By default int32 32 bit integer arc values are generated lt namespace gt namespace URI This is used to specify the target namespace for the given module lt namespace gt when generating XSD and or XML code By default the compiler will not include a targetNamespace directive in the generated XSD code i e all items will not be assigned to any namespace This option only has meaning when used with the xml xsd command line options Production Level These attributes can be applied at the production level by including them within a lt production gt section int32 uint32 int64 string Name Values Description lt name gt module name This attribute identifies the module to which this section applies It is lt name gt required lt ctype gt byte int16 uint16 This is used to specify a specific C integer type be used in place of the default integer definition generated by ASNIC In general ASNIC will try and use the smallest integer type available based on the value or value range constraint on the integer type If the integer is not constrained the int32 32 bit integer type will be used ASNIC V5 8 29 lt storage gt lt storage gt dynamic static list array or dynamicArray keyword The defin
218. or each of the bit numbers These entries can be used in calls to the methods of the ASN CBitStr class to set clear and test bits The genBitMacros command line option can be used to generate macros to set clear or test the named bits in a bit string structure These macros offer better performance then using the run time functions because all calculations of mask and index values are done at compile time The drawback is they can result in a large amount of additional generated code For example the following ASN 1 production NamedBS BIT STRING bitOne 1 Would translate to the following if genBitMacros was specified Named bit constants define NamedBS bitOne 1 define SET BS3 bitOne bs lt code to set bit gt define CLEAR BS3 bitOne bs code to clear bit gt define TEST BS3 bitOne bs code to test bit gt define NamedBS bitTen 10 define SET BS3 bitTen bs lt code to set bit gt define CLEAR BS3 bitTen bs code to clear bit gt define TEST BS3 bitTen bs lt code to test bit gt Type definitions typedef struct ASNIT NamedBS OSUINT32 numbits OSOCTET data 2 NamedBS ASNIC V5 8 bitTen 10 41 The named bit constants would be used to access the data array within the ASNIT NamedBS type If bit macros were not generated the rtSetBit function could be used to set the named bit bitOne with the following code
219. or example consider the following declaration ChoiceType CHOICE oid OBJECT IDENTIFI ER id INT EG ER value ChoiceType id 1 This would result in the following definition in the C or C source file ChoiceType value Code generated in value initialization function value t T ChoiceType id value u id 1 ASNIC V5 8 72 CLASS specification NOTE Class code generation is available for tables option only This additional code is generated to support the processing required to verify table constraints This is intended for use only in compiler generated code Therefore it is not necessary for the average user to understand the mappings in order to use the product The information presented here is informative only to provide a better understanding of how the compiler handles table constraints All of the Class code will be generated in a module class header file with the following filename format lt ModuleName gt Class h In this definition lt ModuleName gt would be replaced with the name of the ASN 1 module name for this class definition C Code generation The C struct definition generated to model an ASN 1 class contains member variables for each of the fields within the class For each of the following class fields the corresponding member variable is included in the generated C structure as follows For a Value Field lt TypeName gt lt FieldName
220. ow dummy parameters to be declared that will be replaced with actual parameters when the type is referenced This is similar to templates in C A simple and common example of the use of parameterized types is for the declaration of an upper bound on a sized type as follows ASNIC V5 8 65 SizedOctetString INTEGER ub OCTET STRING SIZE 1 ub In this definition ub would be replaced with an actual value when the type is referenced For example a sized octet string with an upper bound of 32 would be declared as follows OctetString32 SizedOctetString 32 The compiler would handle this in the same way as if the original type was declared to be an octet string of size 1 to 32 That is it will generate a C structure containing a static byte array of size 32 as follows typedef struct OctetString32 OSUINT32 numocts OSOCTET data 32 OctetString32 Another common example of parameterization is the substitution of a given type inside a common container type For example security specifications frequently contain a signed parameterized type that allows a digital signature to be applied to other types An example of this would be as follows SIGNED ToBeSigned SEQUENCE toBeSigned ToBeSigned algorithmOID OBJECT IDENTIFIER params Params signature BIT STRING An example of a reference to this definition would be as follows SignedName SIGNED Na
221. ows lt storage gt dynamicArray lt storage gt The array keyword is used to specify that a static array is to be generated to hold the data In this case if the SEQUENCE OF production does not contain a size constraint the maxSize attribute must be used to specify the maximum size of the array For example storage maxSize 100 array storage If maxSize is not specified and the ASN 1 production contains no size constraint then a dynamic array is used The ist keyword can also be used in a similar fashion to specify the use of a linked linked structure to hold the elements lt storage gt list lt storage gt See the section entitled Compiler Configuration File for further details on setting up a configuration file Dynamic SEQUENCE OF Type ASN 1 production lt name gt SEQUENCE OF lt type gt Generated C code typedef struct OSUINT32 n lt type gt elem lt name gt Generated C code typedef struct public ASNITPDU OSUINT32 n lt type gt elem ASNIT lt name gt ASNIC V5 8 55 ASNIT name ASNIT lt name gt Note that parsed values can be accessed from the dynamic data variable just as they would be from a static array variable i e an array subscript can be used ex elem 0 elem 1 In the case of C a constructor is generated to initialize the element count to zero If the type represents a PDU type either by default by not referencing any other ty
222. p 2 construct ASNI1C C generated class ASNIT PersonnelRecord msgData ASN1C PersonnelRecord employ msgData step 3 populate msgData structure with data to be encoded note this uses the generated assignment operator to assign a string msgData name SMITH step 4 invoke operator or EncodeTo method out employee or employee EncodeTo out can be used here step 5 check status of the operation if out getStatus ASN OK printf Encoding failed Status i n out getStatus out printErrorInfo return 1 if trace printf Encoding was successful n Encoding a Series of Messages Using the Stream Oriented C Control Class Interface ASNIC V5 8 137 Encoding a series of messages using the stream oriented C control class is similar to the C method of encoding All that is necessary is to create a loop in which EncodeTo or Encode methods will be called or the overloaded lt lt streaming operator It is also possible to call different EncodeTo methods or Encode or operator lt lt one after another An example showing how to do this is as follows include employee h include file generated by ASNIC int main const OSOCTET msgptr OSOCTET msgbuf 1024 int msglen const char filename message dat step 1 construct stream object ASNIBERFileOutputStream out filename if out getStatus ASN OK
223. pdu 84 per 10 34 PER encode function format of generated prototype 83 procedure for calling in C 151 PER encode method procedure for calling 91 95 PER function prototypes 34 platform mk 24 191 platform mk editing 24 populating generated structure variables for PER encoding 151 for XER encoding 165 populating generated structure variables for encoding 106 Porting Run time Code to Other Platforms 24 prefix ASN 31 ASNIC_ 35 ASNIT_ 37 60 ASNIV_ 68 69 enumPrefix 45 for generated BER decode function 119 for generated BER encode function 109 132 for generated BER stream decode function 140 for generated C C source code 180 181 for generated PER decode function 157 for generated PER encode function 150 for PER generated prototypes 83 for PER prototypes 34 type for attirubtes specified in more than one section 25 valuePrefix 29 print 181 print functions function name format 180 181 189 generated 181 source file for 8 Print method 36 print to stream function 182 print to stream functions source file for 8 print to string functions ASNIC V5 7 source file for 8 procedures for encoding data 102 production specification 25 Protocol Data Unit 84 85 105 188 Protocol Data Units 35 prtfmt 10 prtToStr 8 R REAL type C C mapping 48 RELATIVE OID type C C mapping 48 Remote Operations Service Element 201 Remote Operations Service Element ROSE 201 ROSE 201 decode process 202 encode process 202 ERROR MACRO
224. pes or explicitly via the pdu command line option the ASN TPDU base class is extended and a destructor is added This destructor ensures that memory allocated for elements is freed upon destruction of the object Static sized SEQUENCE OF Type ASN 1 production lt name gt SEQUENCE SIZE lt len gt OF lt type gt Generated C code typedef struct OSUINT32 n lt type gt elem lt len gt lt name gt Generated C code typedef struct OSUINT32 n lt type gt elem lt len gt ASNIT lt name gt List based SEQUENCE OF Type A doubly linked list header type 4sn RTDList is used for the typedef if the list storage configuration setting is used see above This can be used for either a sized or unsized SEQUENCE OF construct The generated C or C code is as follows Generated C code typedef AsnlRTDList lt name gt Generated C code typedef ASN1TSeqOfList ASNIT lt name gt The type definition of the Asn RTDList structure can be found in the asn type h header file The common run time utility functions beginning with the prefix rtDList are available for initializing and adding elements to the list See the C C Common Run time Reference Manual for a full description of these functions For C the ASNITSeqOfList class is used or in the case of PDU types the ASNITPDUSeqOfList class The ASNITSeqOfList extends the C Asn1 RTDList structure and adds constructors and other helper metho
225. piler was successfully installed enter asn1c with no parameters as follows note if you have not updated your PATH variable you will need to enter the full pathname asnlc You should observe the following display or something similar ASN1C Compiler Version 5 8x Copyright c 1997 2005 Objective Systems Inc All Rights Reserved Usage asnic filename options filename ASN 1 source file name s Multiple filenames may be specified and wildcards are allowed language options g generate C code C generate C cod c generate C code java generate Java code xsd lt filename gt generate XML schema definitions encoding rule options ber generate BER encode decode functions cer generate CER encode decode functions der generate DER encode decode functions per generate PER encode decode functions xer generate XER encode decode functions xml generate XML encode decode functions basic options asnstd lt std gt set standard to be used for parsing ASN 1 source file Possible values x208 x680 mixed default is x680 compact generate compact code compat lt version gt generate code compatible with previous compiler version lt version gt format is x x for example 5 3 config lt file gt specify configuration file depends compile main file and dependent IMPORT items I lt directory gt set import file directory lax do not generat
226. ple above the generated code would be as follows typedef OSINT32 AnInt typedef struct Aseq OSINT32 x AnInt anInt Aseq OPTIONAL keyword Elements within a sequence can be declared to be optional using the OPTIONAL keyword This indicates that the element is not required in the encoded message An additional construct is added to the generated code to indicate whether an optional element is present in the message or not This construct is a bit structure placed at the beginning of ASNIC V5 8 51 the generated sequence structure This structure always has variable name m and contains single bit elements of the form lt element name gt Present as follows struct unsigned lt element namel gt Present 1 unsigned lt element name2 gt Present 1 m In this case the elements included in this construct correspond to only those elements marked as OPTIONAL within the production If a production contains no optional elements the entire construct is omitted For example the production in the previous example can be changed to make both elements optional Aseq PRIVATE 2 SEQUENCE x INTEGER OPTIONAL AnInt OPTIONAL I I In this case the following C typedef is generated typedef struct Aseq struct 1 unsigned xPresent 1 unsigned anIntPresent 1 m OSINT32 X3 AnInt anInt Aseq When this structure is populated for encoding the developer must set the xPresent an
227. pplication program ASNIC V5 8 98 To achieve the best results it is necessary to put all compiled object files into an object library a or lib file and include this library in the link command The genMake option when used in conjunction with maxcfiles will generate a make file that will compile each of the generated files and add them to a library with a name based on the name of the ASN 1 module being compiled lt moduleName gt lib for Windows or lib lt moduleName gt a for NIX The format of each generated c file name is as follows asnl suffix lt prodname gt c where lt suffix gt depends on encoding rules and function type encode decode free etc lt prodname gt is the ASN 1 production name For example consider one type definition within the Employee asn ASN 1 specification Employee DEFINITIONS BEGIN Name APPLICATION 1 IMPLICIT SEQUENCE givenName TA5String initial TA5String familyName IA5String END By default the following c files would be generated note this assumes no additional code generation options were selected Employee c EmployeeEnc c EmployeeDec c If maxcfiles was selected as in the following command line The ASNIC with naxcfiles option will generate the following files asnlc employee asn c ber trace maxcfiles the following c files for this type would be generated for the Name type asnlD Name c
228. quired program module object files maxlines lt number gt This option is used to specify the maximum number of lines per generated c or cpp file If this number is exceeded a new file is started with a n suffix where n is a sequential number The default value if this is not specified is 50 000 lines which will prevent the VC Maximum line numbers exceeded warning that is common when compiling large ASN 1 source files Note that this number is approximate the next file will not be started until this number is exceeded and the compilation unit that is currently being generated is complete noencode None This option suppresses the generation of encode functions nodecode None This option suppresses the generation of decode functions noIndefLen None This option instructs the compiler to omit indefinite length tests in generated decode functions These tests result in the generation of a large amount of code If you know that your application only uses definite length encoding this option can result in a much smaller code base size noObjectTypes None This option suppresses the generation of application language types corresponding to ASN 1 types embedded within information object definitions noOpenExt None This option instructs the compiler to not add an open extension element extElem1 in constructs that contain extensibility markers The purpose of the ele
229. r to understand the mappings in order to use the product The information presented here is informative only to provide a better understanding of how the compiler handles table constraints Information Object code will be generated in a header and source file with a C struct C class to hold the values The name of the header and source file are of the following format lt ModuleName gt Table h lt ModuleName gt Table c cpp In this definition lt ModuleName gt would be replaced with the name of the ASN 1 module in which the information object is defined C Code Generation For C a global variable is generated to hold the information object definition This is very similar to the code generated for a value definition An example of an information object definition that is derived from the ASN 1 ATTRIBUTE class above is as follows name ATTRIBUTE iem WITH SYNTAX VisibleString ID 011 This results in the generation of the following C constant ATTRIBUTE name Code generated in information object initialization function name TypeSize sizeof name Type name encodeType amp asnlE name Type name decodeType amp asnlD name Type name id numids 3 name id subid 0 0 name id subid 1 1 name id subid 2 1 C Code Generation The C classes generated for ASN 1 information objects are derived from the ASN 1 class objects The constructors in these classes populate the
230. re is a special XML interface object file for each of the following supported XML parsers e RTXMLLIBXML2ZIF interface to LIBXML2 e RTXMLMSXMLIF interface to MSXML e RTXMLXERCESIF interface to XERCES e RTXMLEXPATIF interface to EXPAT The XER Run Time Library is completely independent from the XML readers because the adapter layer within these libraries defines a common SAX API If an application 1s linked statically then the static variant of one of these interface objects their names have suffix A should be linked cooperatively with the XML parser ASNIXER and ASNIRT libraries If the application is linked dynamically using dynamically linked libraries DLL in Windows or shared objects SO or SL in UNIX Linux then it is necessary to link the application with the dynamic variant of the interfaces without suffix A dynamic version of the XML parser ASNIXER and ASNIRT dynamic libraries ASNIC V5 8 175 Generated XML Encode and Decode Functions XML C encode and decode functions are generated when the xml switch is specified on the command line These are very similar to the XER encode functions described earlier Like XER this function allows data in a populated variable to be formatted into an XML document Unlike the XER variant this function will produce XML that adheres more closely to the Worldwide Web Consortium W3C XML conventions In particular the following differences exist e Lists of numbers enumera
231. re so that when the rtMemFree function is called all memory is released at once Accessing Encoded Message Components After a message has been encoded the user must obtain the start address and length of the message in order to do further operations with it Before a message can be encoded the user must describe the buffer the message 1s to be encoded into by specifying a message buffer start address and size There are three different types of message buffers that can be described l static this is a fixed size byte array into which the message is encoded 2 dynamic in this case the encoder manages the allocation of memory to hold the encoded message 3 stream in this case the encoder writes the encoded data directly to an output stream The static buffer case is generally the better performing case because no dynamic memory allocations are required However the user must know in advance the amount of memory that will be required to hold an encoded message There is no fixed formula to determine this number ASN 1 encoding involves the possible additions of tags and lengths and other decorations to the provided data that will increase the size beyond the initial size of the populated data structures The way to find out is either by trial and error an error will be signaled if the provided buffer is not large enough or by using a very large buffer in comparison to the size of the data In the dynamic case the buffer description passed
232. ritten as the following set of productions X SEQUENCE al INTEGER a2 BOOLEAN ASNIC V5 8 50 Y OCTET STRING A SEQUENCE X x Y y This makes the generated code easier to understand for the end user Unnamed Elements Note as of X 680 unnamed elements are not allowed elements must be named ASNIC still provides backward compatibility support for this syntax however In an ASN 1 SEQUENCE definition the lt element name gt tokens at the beginning of element declarations are optional It is possible to include only a type name without a field identifier to define an element This is normally done with defined type elements but can be done with built in types as well An example of a SEQUENCE with unnamed elements would be as follows AnInt PRIVATE 1 INTEGER Aseq PRIVATE 2 SEQUENCE x INTEGER AniInt In this case the first element x is named and the second element is unnamed ASNIC handles this by generating an element name using the type name with the first character set to lower case For built in types a constant element name is used for each type for example a nt is used for INTEGER There is one caveat however ASNIC cannot handle multiple unnamed elements in a SEQUENCE or SET with the same type names Element names must be used in this case to distinguish the elements So for the exam
233. rm lt field name Present as follows struct unsigned field namel Present 1 unsigned lt field name2 gt Present 1 m In this case the fields included in this construct correspond to only those fields marked as OPTIONAL within the CLASS Ifa CLASS contains no optional fields the entire construct is omitted For example we will change the CLASS in the previous example to make one field optional ATTRIBUTE CLASS amp Type OPTIONAL amp id OBJECT IDENTIFIER UNIQUE In this case the following C typedef is generated in C struct or C class definition struct unsigned TypePresent 1 m When this structure is populated for encoding the information object processing code will set TypePresent flag accordingly to indicate whether the field 1s present or not In C code generation an additional method is generated for an optional field as follows OSBOOL is lt FieldName gt Present if m lt FieldName gt Present return TRUE else return FALSE This function is used to check if the field value is present in an information object definition ASNIC V5 8 76 Generation of New ASN 1 Assignments from CLASS Assignments During CLASS definition code generation the following new assignments are created for C or C code generation 1 A new Type Assignment is created for a TypeField s type definition as follows _ lt ClassName gt lt FieldName gt RE Type
234. roduction The format of this temporary type name is as follows lt prodName gt element In this definition lt prodName gt refers to the name of the production containing the SEQUENCE OF type For example a simple and very common single level nested SEQUENCE OF construct might be as follows A SEQUENCE OF SEQUENCE a INTEGER b BOOLEAN In this case a temporary type is generated for the element of the SEQUENCE OF production This results in the following two equivalent ASN 1 types A element SEQUENCE a INTEGER b BOOLEAN A SEQUENCE OF A element These types are then converted into the equivalent C or C typedefs using the standard mapping that was previously described ASNIC V5 8 57 SEQUENCE OF Type Elements in Other Constructed Types Frequently a SEQUENCE OF construct is used to define an array of some common type in an element in some other constructed type for example a SEQUENCE An example of this is as follows SomePDU SEQUENCE addresses SEQUENCE OF AliasAddress Normally this would result in the addresses element being pulled out and used to create a temporary type with a name equal to SomePDU addresses as follows SomePDU addresses SEQUENCE OF AliasAddress SomePDU SEQUENCE addresses SomePDU addresses However when the SEQUENCE OF
235. rray is used to hold the objects but this could be changed to something like a linked list or hash An example of an Information Object Set definition that is derived from the ASN 1 ATTRIBUTE class above is as follows SupportedAttributes ATTRIBUTE name commonName E This results in the generation of the following C constant ATTRIBUTE SupportedAttributes 2 int SupportedAttributes Size 2 Code generated in the Information Object Set initialization function SupportedAttributes 0 TypeSize sizeof name Type SupportedAttributes 0 encodeType amp asnlE name Type SupportedAttributes 0 decodeType amp asnlD name Type SupportedAttributes 0 id numids 3 SupportedAttributes 0 id subid 0 0 SupportedAttributes 0 id subid 1 1 SupportedAttributes 0 id subid 2 1 SupportedAttributes 1 TypeSize sizeof _commonName Type SupportedAttributes 1 encodeType amp asnlE commonName Type SupportedAttributes 1 decodeType amp asnlD commonName Type ASNIC V5 8 81 SupportedAttributes 1 id numids 3 SupportedAttributes 1 id subid 0 0 SupportedAttributes 1 id subid 1 1 SupportedAttributes 1 id subid 2 1 SupportedAttributes 1 id subid 3 1 C Code Generation In C ASN 1 information object sets are mapped to C classes In this case a C singleton class is generated This class contains a container to hold an instance of each
236. s 150 generated C encode method format and calling pa rameters 150 populating generated structure variables for encoding control class control class ASNIC V5 7 151 procedure for calling C encode functions 151 procedure for using C control class encode method 153 160 generated print functions 180 181 generated stream oriented BER decode function procedure for calling C decode functions 141 procedure for using C control class decode method 146 generated stream oriented C function encoding a series of BER messages 134 generated stream oriented C function format BER stream oriented encode method 132 generated stream oriented C encode method format BER encode method 136 generated structure variables populating for encoding 106 populating for PER encoding 151 populating for XER encoding 165 generated test functions 189 generated XER decode function generated C function format and calling parameters 171 procedure for calling C decode functions 172 procedure for calling C decode functions 174 procedure for using C control class encode method 174 generated XER encode function generated C function format and calling parameters 164 generated C encode method format and calling pa rameters 165 populating generated structure variables for encoding 165 procedure for calling C encode functions 165 171 procedure for using C control class encode method 167 genFree 180 genInit 179 genmake 191 genPrtT
237. s 140 performance consideration of dynamic memory man agement 128 procedure for calling C decode functions 120 procedure for calling in C 120 procedure for using C control class decode method 124 BER decode function See also BER DER C decode func tions BER encode function encoding a series of messages using C control class interface 114 117 encoding a series of messages using stream oriented C control class interface 137 encoding a series of messages using the stream ori ented C encode functions 134 generated C function format and calling parameters 109 generated C encode method format and calling pa rameters 111 procedure for calling C encode functions 111 procedure for calling in C 111 procedure for using C control class encode method 115 procedure for using C control class stream orient ed encode method 136 BER encode function See also BER DER C encode func tions BER encoded message diagram 111 BER stream oriented decode function decoding a series of message 122 143 decoding a series of messages using C control class interface 148 decoding a series of messages using the stream ori 205 ented C decode functions 122 143 generated C decode method format and calling pa rameters 145 procedure for calling C stream oriented decode func tions 141 procedure for calling in C 141 procedure for using C control class decode method 146 BER stream oriented decode function See also BER DER C decode functions BE
238. s ANSI standard source code for the base run time libraries This code can be used to build binary versions of the run time libraries for other operating environments Included with the source code is a portable makefile that can be used to build the libraries on the target platform with minimal changes All platform specific items are isolated in the platform mk file in the root directory of the installation The procedure to port the run time code to a different platform is as follows note this assumes common UNIX or GNU compilation utilities are in place on the target platform 1 Create a directory tree containing a root directory the name does not matter and lib src rt src and build lib subdirectories note in these definitions is a wildcard character indicating there are multiple directories matching this pattern The tree should be as follows build lib 2 Copy the files ending in extension mk from the root directory of the installation to the root directory of the target platform note if going from DOS to UNIX or vice versa FTP the files in ASCII mode to ensure lines are terminated properly 3 Copy all files from the src and the different rt src subdirectories from the installation to the src and rt src directories on the target platform note if going from DOS to UNIX or vice versa FTP the files in ASCII mode to ensure lines are terminated properly 4 Copy the makefile from the build lib subdirectory of
239. s Encode Method iilis 160 Decoding a Series of Messages Using the C Control Class Interface 0 00545 162 Performance Considerations Dynamic Memory Management ees sisse 163 ASNIC V5 7 ii GENERATED XER ENCODE FUNCTIONS 0 000 c cece cece tE nr arni cence eran 164 Generated C Function Format and Calling Parameters c esses 164 Generated C Encode Method Format and Calling Parameters 000 cece eee 165 Populating Generated Structure Variables for Encoding eese 165 Procedure for Calling C Encode Functions esses 165 Procedure for Using the C Control Class Encode Method iiis 167 GENERATED XER DECODE FUNCTIONS ssssssssssssesss eee 169 Procedure for Using the C Interface esses e 171 Generated C Function Format and Calling Parameters sese 171 Procedure for Calling C Decode Functions esses 172 Procedure for Using the C Interface lesse 174 Procedure for Interfacing with Other C and C XML Parser Libraries issus 175 GENERATED XML ENCODE AND DECODE FUNCTIONS 0 0 000 00000 c cece cee eee 176 GENERATED INITIALIZATION FUNCTIONS o oo anaana cence tenes 179 GENERATED MEMORY FREE FUNCTIONS ssssssssssssssess eee 180 GENERATED PRINT FUNCTIONS 00 0000 0 ccc ccc eee eaae 181 Print to Standard Output esses e 181 Prihtio Stine ig Ob Ter Rep EAS EE RE ed HOR ODE Ree DERG eA Ee EE hee 181 Prin
240. s being generated and prefix is an optional prefix that can be set via a configuration file setting The configuration setting used to set the prefix is the lt typePrefix gt element This element specifies a prefix that will be applied to all generated typedef names and function names for the production The calling sequence for each decode function is as follows status asnlXD name ASNICTXT pctxt lt name gt pvalue In this definition lt name gt denotes the prefixed production name defined above The pctxt argument is used to hold a context pointer to keep track of decode parameters This is a basic handle variable that is used to make the function reentrant so that it can be used in an asynchronous or threaded application The user is required to supply a pointer to a variable of this type declared somewhere in his or her program The variable must be initialized using the rt nitContext run time function before use C XER decoding is stream oriented To perform streaming operations the context pointer pctxt must also be initialized as a stream by using the rtStreamInit run time library function see the C C Common Run Time Library Reference Manual for a description of the run time stream C functions The pvalue argument is a pointer to a variable to hold the decoded result This variable is of the type generated from the ASN 1 production The decode function will automatically allocate dynamic memory for variable length fields w
241. s can then be generated using the xml option to format or parse XML documents that conform to this schema This level of support is closer to the W3C definition of XML then is the ITU T X 693 XER definition The compiler is capable of parsing all ASN 1 syntax as defined in the standards It is capable of parsing advanced syntax including Information Object Specifications as defined in the ITU T X 681 standard as well as Parameterized Types as defined in ITU T X 683 This version of the compiler is also capable of using table constraints as defined in ITU T X 682 to generate single step encoders and decoders that can encode or decode multi part messages in a single function call This release of the compiler contains a special command line option asnstd x208 that allows compilation of deprecated features from the older X 208 and X 209 standards These include the ANY data type and unnamed fields in SEQUENCE SET and CHOICE types This version can also parse type syntax from common macro definitions such as the OPERATION and ERROR macros in ROSE ASNIC V5 8 1 ASNIC V5 8 Using the Compiler Running ASNIC from the Command line The ASNIC compiler distribution contains command line compiler executables as well as a graphical user interface GUI wizard Windows version only that can aid in the specification of compiler options This section describes how to run the command line version the next section describes the GUI To test if the com
242. s the C code generation capability Each ASN 1 module that is encountered in an ASN 1 source file results in the generation of the following two types of C C language files 1 An include h file containing C C typedefs and classes that represent each of the ASN 1 productions listed in the ASN 1 source file and 2 A set of C C source c or cpp files containing C C encode and decode functions One encode and decode function is generated for each ASN 1 production The number of files generated can be controlled through command line options These files when compiled and linked with the ASN 1 low level encode decode function library provide a complete package for working with ASN 1 encoded data ASNIC works with the version of ASN 1 specified in ITU T international standards X 680 through X 683 It generates code for encoding decoding data in accordance with the following encoding rules e Basic Encoding Rules BER Distinguished Encoding Rules DER or Canonical Encoding Rules CER as published in the ITU T X 690 standard e Packed Encoding Rules PER as published in the ITU T X 691 standard Both aligned and unaligned variants are supported via a switch that 1s set at run time e XML Encoding Rules XER as published in the ITU T X 693 standard Additional support for XML is provided in the form of an option to generate an equivalent XML Schema Definitions XSD file for a given ASN 1 specification Encoders and decoder
243. set via a configuration file setting The configuration setting used to set the prefix is the lt typePrefix gt element This element specifies a prefix that will be applied to all generated typedef names and function names for the production The calling sequence for each generated initialization function is as follows asnlInit name lt name gt pvalue In this definition lt name gt denotes the prefixed production name defined above The pvalue argument is used to pass a pointer to a variable of the item to be initialized ASNIC V5 8 179 Generated Memory Free Functions The genFree option causes functions to be generated that free dynamic memory allocated using the ASNIC run time memory management functions and macros rtMem By default all memory held with a context is freed using the rtMemFree run time function It is also possible to free an individual memory item using the rtMemPFreePtr function But it is not possible to free all memory held within a specific generated type container For example a SEQUENCE type could contain elements that require dynamic memory These elements in turn can reference other types that require dynamic memory The generated memory free functions make it possible to release all memory held within a variable of the type with a single call Generated memory free functions are written to the main lt module gt c file This file contains common constants global variables and functions that are gener
244. ss object for the data in the populated type variable to be encoded 2 Ifamatch is found the table constraint encode function as defined above is invoked This function will verify all fixed type values match what is defined in the information object definition and will encode all type fields and store the resulting encoded data in the ASN TObject encoded fields 3 Ifamatch is not found and the information object set is not extensible then a table constraint error status will be returned If the information object set is extensible a normal status is returned Simple Table Constraint 1 This function will verify all the fixed type values match what is defined in the table constraint information object set If an element value does not exist in the table 1 e the information object set and the object set is not extensible then a table constraint violation exception will be thrown The normal encode logic is then performed to encode all of the standard and open type fields in the message On the decode side the logic is reversed The normal decode logic is performed to populate the standard and open type fields in the generated structure Relative Table Constraint 1 The lookupObject method is invoked on the decoded key field value to find an object match 2 Ifa match is found the table constraint decode function as defined above is invoked This function will verify all fixed type values match what is defined in the information obj
245. ssage msgptr encodeBuffer getMsgPtr else error processing The encoding procedure for C requires one extra step This is a call to the module initialization functions after context initialization is complete All module initialization functions for all modules in the project must be invoked The module initialization function definitions can be found in the lt ModuleName gt Table h file The format of each module initialization function name is as follows void ModuleName init ASNICTXT pctxt Here ModuleName would be replaced with name of the module A C program fragment that could be used to encode the nvoke record defined above is as follows finclude TestTable h include file generated by ASNIC ASNIC V5 8 93 int main OSOCTET msgbuf 1024 msgptr int msglen ASNICTXT ctxt Invoke invoke typedef generated by ASNIC Step 1 Initialize the context and set the buffer pointer if rtInitContext amp ctxt ASN OK initialization failed could be a license problem printf context initialization failed check license Nn return i xe setp amp ctxt msgbuf sizeof msgbuf step 2 call module initialization functions Test init amp ctxt Step 3 Populate the structure to b ncoded msgData opcode numids 3 msgData opcode subid 0 msgData opcode subid 1 msgData opcode subid 2 note opcode value is ASN1Visib
246. stat ASN OK process received data else error processing decodeBuffer PrintErrorInfo step 6 free dynamic memory mployee memFreeAll ASNIC V5 8 162 The only difference between this and the previous example is the addition of the decoding loop and the modification of step 6 in the procedure The decoding loop is an infinite loop to continuously read and decode messages from some interface such as a network socket The decode calls are the same but before in step 6 we were counting on the message buffer and control objects to go out of scope to cause the memory to be released Since the objects are now being reused this will not happen So the call to the memFreeAll method that is defined in the ASN C_Type base class will force all memory held at that point to be released Performance Considerations Dynamic Memory Management Please refer to Performance Considerations Dynamic Memory Management in the BER Decode Functions section for a discussion of memory management performance issues All of the issues that apply to BER and DER also apply to PER as well ASNIC V5 8 163 Generated XER Encode Functions XER C encode functions are generated when the xer switch is specified on the command line For each ASN 1 production defined in the ASN 1 source file a C XER encode function is generated This function will convert a populated C variable of the given type into an XER encoded ASN 1 message i e an XML
247. stat ASN OK printf rtInitContext failed check license n rtErrPrint amp ctxt return stat pu_setBuffer amp ctxt msgbuf msglen aligned if stat asnlPE Employee amp ctxt amp employee ASN OK msglen pe GetMsgLen amp ctxt else error processing In general static buffers should be used for encoding messages where possible as they offer a substantial performance benefit over dynamic buffer allocation The problem with static buffers however is that you are required to estimate in advance the approximate size of the messages you will be encoding There is no built in formula to do this the size of an ASN 1 message can vary widely based on data types and other factors If performance is not a significant issue then dynamic buffer allocation is a good alternative Setting the buffer pointer argument to NULL in the call to pu_setBuffer specifies dynamic allocation This tells the encoding functions to allocate a buffer dynamically The address of the start of the message is obtained after encoding by calling the run time function pe GetMsgPtr ASNIC V5 8 152 The following code fragment illustrates PER encoding using a dynamic buffer include employee h include file generated by ASNIC main OSOCTET msgptr int msglen stat ASNICTXT ctxt OSBOOL aligned TRUE Employee employee typedef generated by ASNIC mployee name givenName
248. successful a pointer to the encoded message can be obtained by using the getMsgPtr or getMsgCopy methods available in the ASN BEREncodeBuffer class The getMsgPtr method is faster as it simply returns a pointer to ASNIC V5 8 115 the actual start of message that is maintained within the message buffer object The getMsgCopy method will return a copy of the message Memory for this copy will be allocated using the standard new operator so it up to the user to free this memory using delete when finished with the copy A program fragment that could be used to encode an employee record is as follows This example uses a static encode buffer include employee h include file generated by ASNIC main 0 const OSOCTET msgptr OSOCTET msgbuf 1024 rnt msglen step 1 construct ASN1C C generated class this specifies a static encode message buffer ASNIBEREncodeBuffer encodeBuffer msgbuf sizeof msgbuf ASNIT PersonnelRecord msgData ASN1C PersonnelRecord employ encodeBuffer msgData step 2 populate msgData structure with data to be encoded note this uses the generated assignment operator to assign a string msgData name SMITH step 3 invoke Encode method if msglen employee Encode gt 0 encoding successful get pointer to start of message msgptr encodeBuffer getMsgPtr else error processing The following c
249. t amp ctxt ASN OK initialization failed could be a license problem printf context initialization failed check license Nn return 1 ASNIC V5 8 96 xd_setp amp ctxt msgbuf 0 amp msgtag amp msglen step 2 call module initialization functions Test init amp ctxt Step 3 Call decode function status asnlD Invoke amp ctxt amp invoke ASNIEXPL 0 Step 4 Check return status if status ASN OK process received data in invoke variable if rtCmpTCOID amp invoke opcode amp oidl 0 argument is a VisibleString ASN1VisibleString pArg ASN1VisibleString msgData argument decoded else if rtCmpTCOID amp invoke opcode amp oid2 0 argument is an INTEGER OSINT32 arg OSINT32 msgData argument decoded Remember to release dynamic memory when done ASNIMEMFREE amp ctxt else error processing ASNIC V5 8 97 Generated C Source Files By default the ASNIC compiler generates the following set of c source files for a given ASN 1 module note the name of the module would be substituted for lt moduleName gt lt moduleName gt c common definitions and functions for example asnlFree_ lt type gt and or global value constant definitions lt moduleName gt Enc c encode functions asnlE_ lt type gt lt moduleName gt Dec c decode functions asn1D_ lt type
250. t is encountered The implementation is now complete The program can now be compiled and run When this is done the resulting output is as follows employee name givenName John initial pn familyName Smith This can certainly be improved For one thing it can be changed to print primitive values out in a name value format i e without the braces But this should provide the general idea of how it is done Example 2 An Error Handler Despite the addition of things like extensibility and version brackets ASN 1 implementations get out of sync For situations such as this the user needs some way to intervene in the parsing process to set things straight This is fault tolerance the ability to recover from certain types of errors The error handler interface is provided for this purpose The concept is simple Instead of throwing an exception and immediately terminating the parsing process a user defined callback function is first invoked to allow the user to check ASNIC V5 8 196 the error If the user can fix the error all he or she needs to do is apply the appropriate patch and return a status of ASN OK The parser will be none the wiser It will continue on thinking everything is fine This interface is probably best suited for recovering from errors in BER or DER instead of PER The reason is the TLV format of BER makes it relatively easy to skip an element and continue on It
251. t name gt where lt name gt is the name of the ASN 1 production and lt e ement name gt is the name of the CHOICE alternative If a CHOICE alternative is not given an explicit name then lt element name gt is automatically generated by taking the type name and making the first letter lowercase this is the same as was done for the ASN 1 SEQUENCE type with unnamed elements If the generated name is not unique a sequential number is appended to make it unique The union of choice alternatives is made of the equivalent C or C type definition followed by the element name for each of the elements The rules for element generation are essentially the same as was described for SEQUENCE above Constructed types or elements that map to C structured types are pulled out and temporary types are created Unnamed elements names are automatically generated from the type name by making the first character of the name lowercase One difference between temporary types used in a SEQUENCE and in a CHOICE is that a pointer variable will be generated for use within the CHOICE union construct GI ASN 1 production lt name gt CHOICE lt elementl name gt lt elementl type gt lt element2 name gt lt element2 type gt Generated C code define T lt name gt lt elementl name gt 1 fdefine T name lt element2 name gt 2 typedef struct int tr union typel elementl name lt type2 gt element2 name Four name
252. t step 1s the specification of a buffer containing a message to be decoded This is accomplished by calling the xd setp run time library function This function takes as an argument the start address of the message to be decoded The function returns the starting tag value and overall length of the message This makes it possible to identify the type of message received and apply the appropriate decode function to decode it A decode function can then be called to decode the message If the return status indicates success the C variable that was passed as an argument will contain the decoded message contents Note that the decoder may have allocated ASNIC V5 8 120 dynamic memory and stored pointers to objects in the C structure After processing on the C structure is complete the run time library function rtMemFree should be called to free the allocated memory A program fragment that could be used to decode an employee record is as follows include employee h include file generated by ASNIC main OSOCTET msgbuf 1024 ASNITAG msgtag int msglen ASNICTXT ctxt PersonnelRecord employee if xd_ if ASNIC V5 8 logic to read message into msgbuf Step 1 Initialize a context variable for decoding rtInitContext amp ctxt ASN OK initialization failed could be a license problem printf context initialization failed check license n return 1
253. ta component of the class In this version there are three types of streams file socket and memory The most useful are file and socket streams It is possible to decode data directly from a file or socket without intermediate copying into memory If the full amount of data 1s not available for reading then the behavior of these streams will be different the file and memory input streams will report an error the socket input stream will block until data 1s available or an I O error occurs for example the remote side closes the connection Generated Stream Oriented C Function Format and Calling Parameters The format of the name of each stream oriented decode function generated is as follows asnlBSD lt prefix gt lt prodName gt where lt prodName gt is the name of the ASN 1 production for which the function is being generated and prefix is an optional prefix that can be set via a configuration file setting The configuration setting used to set the prefix is the lt typePrefix gt element This element specifies a prefix that will be applied to all generated typedef names and function names for the production The calling sequence for each decode function is as follows status asnlBSD name ASNICTXT pctxt name pvalue ASN1TagType tagging int length In this definition lt name gt denotes the prefixed production name defined above The pctxt argument is used to hold a context pointer to keep track of decode parameters Th
254. ta type 1 ANY or ANY DEFINED BY constructs 62 array 55 ASN 1 run time library 22 ASN K MAXSUBIDS 47 ASNIBERDecodeBuffer 120 124 ASNIBEROutputStream 136 ASNIC ASN 1 source file specification 5 command line options 5 ASNIC GUI ASN 1 file selection 13 Output directory name 18 setting ASN 1 syntax version 14 setting code addition alter options 15 setting code reduction options 15 setting encoding rules 14 setting target language 14 ASNICBitStr control class 35 42 ASN1CGeneralizedTime 64 ASNICSeqOfList base class 35 ASNICTXT argument 119 120 140 141 ASNICType 84 ASNICTyYype base class 35 36 ASNICUTCTime 64 ASNIDynBitStr 39 ASN1DynOctStr 43 AsnlErrorHandler 194 ASNIEXPL 83 109 ASN InputStream 146 AsnlMessageBufferIF 35 AsnlNamedEventHandler 194 ASN1Object 62 89 ASN1Object structure 62 ASNIOBJID 47 ASNIOpenType 89 ASNITDynBitStr 39 ASN1TDynOctStr 43 ASNITObject 62 89 ASNIC V5 7 ASNITObjlId 47 70 ASNITPDU base class 188 ASNITSeqOfList 55 ASNIXEREncodeBuffer 167 ASNIXERSA XHandler base class 86 asnstd 6 asnstd x208 1 5 201 attribute global level 26 specified in more than one section 25 B Basic Encoding Rules 1 6 ber 6 BER decode function decoding a series of messages using C control class interface 125 generated C function format and calling parameters 119 generated C decode method format and calling pa rameters 120 generated stream oriented C function format and call ing parameter
255. tart address of the target buffer BER encoded messages are constructed from back to front i e starting at the end of the buffer and working backwards so the start point will fall somewhere in the middle of the buffer after encoding is complete Thisis illustrated in the following diagram ASNIC V5 8 111 Encode buffer size 1K Buffer start Start of S Encode this way End of Buffer address Message 0x500 0x100 0x200 In this example a 1K encode buffer is declared which happens to start at address 0x100 When the context is initialized with a pointer to this buffer and size equal to 1K it positions the internal encode pointer to the end of the buffer address 0x500 Encoding then proceeds from back to front until encoding of the message is complete In this case the encoded message turned out to be 0x300 768 bytes in length and the start address fell at 0x200 This is the value that would be returned by the xe getp function A program fragment that could be used to encode an employee record is as follows finclude employee h include file generated by ASNIC int main OSOCTET msgbuf 1024 msgptr int msglen ASNICTXT ctxt Employee employee typedef generated by ASNIC Step 1 Initialize the context and set the buffer pointer if rtInitContext amp ctxt ASN OK initialization failed could be a license problem printf context initialization failed check license n
256. te 55 memory dynamic 102 memory free functions generated 180 memory management allocating variables on the stack 106 C interface 102 C interface 104 using C malloc and free functions 107 using run time library functions 107 memory management API 102 memory management dynamic performance considerations in generated BER decode functions 128 performance considerations in generated PER decode functions 163 messages BER encoded diagram 111 repetitive BER encoding 114 117 134 repetitive PER encoding 157 method contents 193 generated 86 GetMsgCopy 116 getMsgPtr 115 module specification 25 msgData member variable 35 MSXML interface library 175 N named bit constants 42 newCopy method 187 nibble allocation algorithm 102 noencode 9 noIndefLen 9 noOpenExt 9 53 noPDU attribute 29 notypes 7 9 193 NULL type C C mapping 46 O o 10 OBJECT IDENTIFIER type C C mapping 47 object identifier value specification 70 OCTET STRING type C C dynamic 43 C C mapping 42 C C static sized 43 octet for holding bit string contents 39 open extension element 9 open extension field 53 Open type 210 C C mapping 62 OPTIONAL keyword in SEQUENCE 51 OSROOTDIR 191 OSUNICHAR 63 P Packed Encoding Rules 1 10 parameterized type definition 65 parse errors finding by generating a listing 9 parsing functions 193 parsing process diagram of significant events 193 events passed to user 193 PDU 35 84 85 105 188
257. ted tokens and named bits are expressed in space separated list form instead of as individually wrapped elements or value lists For example the ASN 1 specification A SEQUENCE OF INTEGER with value 1 2 3 would produce the following encoding in XER lt A gt lt INTEGER gt 1 lt INTEGER gt lt INTEGER gt 2 lt INTEGER gt lt INTEGER gt 3 lt INTEGER gt lt A gt in XML it would be the following lt A gt 1 2 3 lt A gt e The values of the BOOLEAN data type are expressed as the lower case words true or false with no delimiters In XER the values are lt TRUE gt and lt FALSE gt e Enumerated token values are expressed as the identifiers themselves instead of as empty XML elements i e elements wrapped in lt gt For example a value of the ASN 1 type Colors ENUMERATED red blue green equal to red would simply be lt color gt red lt color gt instead of lt color gt lt red gt lt color gt e The special REAL values lt PLUS INFINITY gt and lt MINUS INFINITY gt are represented as INF and INF respectively e GeneralizedTime and UTCTime values are transformed into the XSD representation for dateTime Y Y Y Y MM DDTHH MM SS SSSS Z HH MM when encoded to XML When an XML document is decoded the time format is transformed into the ASN 1 format e An unnamed element in a SEQUENCE OF construct will be wrapped with the fixed keyword element
258. terface 137 GENERATED BER STREAM ORIENTED DECODE FUNCTIONS 00 00000 cee ee eee eae 140 Generated Stream Oriented C Function Format and Calling Parameters lesus 140 Procedure for Calling Stream Oriented C Decode Functions licei ss 141 Decoding a Series of Messages Using the Stream Oriented C Decode Functions 143 Generated Stream Oriented C Decode Method Format and Calling Parameters 145 Procedure for Using the Stream Oriented C Control Class Decode Method 146 Decoding a Series of Messages Using the C Control Class Interface isses 148 GENERATED PER ENCODE FUNCTIONS aes opistodioicorite dreia birit ae 150 Generated C Function Format and Calling Parameters sese 150 Generated C Encode Method Format and Calling Parameters 0000 cece 150 Populating Generated Structure Variables for Encoding eese 151 Procedure for Calling C Encode Functions iiis esses 151 Procedure for Using the C Control Class Encode Method ii iiiississss 153 Encoding a Series of PER Messages using the C Interface cesses se 157 GENERATED PER DECODE FUNCTIONS sssssssssssssssess esae 157 Generated C Function Format and Calling Parameters csse 157 Generated C Decode Method Format and Calling Parameters ee eese 158 Procedure for Calling C Decode Functions 00 000 ccc eee 158 Procedure for Using the C Control Clas
259. the encoding of a message The context variable is within the top level calling function It must be initialized before use This can be accomplished by using the rtinitContext function The context also must be initialized for streaming operations by calling the rtStreamBufInit function ASNICTXT ctxt if rtInitContext amp ctxt ASN OK initialization failed could be a license problem printf context initialization failed check license n return 1 rtStreamBufInit amp ctxt The next step is to create a stream object within the context This object is an abstraction of the output device to which the data is to be encoded and is initialized by calling one of the following functions rtStreamFileOpen rtStreamFileAttach e rtStreamSocketAttach r tStreamMemoryCreate e rtStreamMemoryAttach The flags parameter of these functions should be set to the OSRTSTRMF OUTPUT constant value to indicate an output stream is being created see the C C Common Run Time Library Reference Manual for a full description of these functions After initializing the context and populating a variable of the structure to be encoded an encode function can be called to encode the message to the stream The stream must then be closed by calling the rtStreamBufClose function A program fragment that could be used to encode an employee record is as follows finclude employee h include file generated by ASNIC
260. the generated encode function stat asnlBSE Employee amp ctxt amp employee ASNIEXPL Step 4 Check the return status and break the loop if error occurs if stat ASN OK error processing break Step 5 Close the stream rtStreamBufClose amp ctxt ASNIC V5 8 135 Generated Stream Oriented C Encode Method Format and Calling Parameters C code generation of stream based encoders is selected by using the c and stream compiler command line options In this case ASNIC generates an EncodeTo method that wraps the C function call This method provides a more simplified calling interface because it hides things such as the context structure and tag type parameters The calling sequence for the generated C class method is as follows stat lt object gt EncodeTo lt outputStream gt In this definition lt object gt is an instance of the control class i e ASN1C_ lt prodName gt generated for the given production The lt outputStream gt placeholder represents an output stream object type This is an object derived from an ASN OutputStream class The function result variable stat returns the completion status Error status codes are negative Return status values are defined in the asn 1type h include file Another way to encode a message using the C classes is to use the lt lt streaming operator lt outputStream gt lt lt object Exceptions are
261. the type in Class s ValueField This value is used as a defined value in the information object definition for an absent value of the field This new value assignment is used for compiler internal code generation purpose It is not required for user to understand this logic ASNIC V5 8 77 ABSTRACT SYNTAX and TYPE IDENTIFIER The ASN 1 ABTRACT SYNTAX and TYPE IDENTIFIER classes are useful ASN 1 definitions These classes are described using the following ASN 1 definitions TYPE IDENTIFIER CLASS amp id OBJECT IDENTIFIER UNIQUE amp Type WITH SYNTAX amp Type IDENTIFIED BY amp id ABSTRACT SYNTAX CLASS amp id OBJECT IDENTIFIER UNIQUE amp Type amp property BIT STRING handles invalid encoding 0 DEFAULT WITH SYNTAX amp Type IDENTIFIED BY amp id HAS PROPERTY amp property The ASNIC compiler generates code for these constructs when they are referenced in the ASN 1 source file that is being compiled The generated code for these constructs is written to the RtClass h and c cpp source files ASNIC V5 8 78 Information Object NOTE Information Object code generation is available for tables option only This additional code is generated to support the processing required to verify table constraints This is intended for use only in compiler generated code Therefore it is not necessary for the average use
262. tion Then C classes derived from these base classes corresponding to the information objects are generated Finally C singleton classes corresponding to the information object sets are generated Each of these classes provides a container for a collection of C objects that make up the object set Additional encode and decode functions are also generated as they were in the C code generation case for interfacing with the object definitions above These functions have the following prototypes BER DER int asnlETC lt ProdName gt ASNICTXT pctxt lt ProdName gt pvalue lt ClassName gt pobject int asnlDTC lt ProdName gt ASNICTXT pctxt lt ProdName gt pvalue lt ClassName gt pobject PER int asnlPETC lt ProdName gt ASNICTXT pctxt ProdName pvalue ClassName pobject int asnlPDTC ProdName ASNICTXT pctxt lt ProdName gt pvalue ClassName pobject ASNIC V5 8 90 These prototypes are identical to the prototypes generated in C code generation case except for the addition of the pobject argument This argument is for a pointer to the information object that matches the key field value for a given encoding These functions have different logic for processing Relative and Simple table constraints The logic associated with each case is as follows On the encode side Relative Table Constraint 1 The lookupObject method is invoked on the object set instance to find the cla
263. to convert PER encoded data into XML The steps in creating an event handler are the same as in Example 1 above An implementation of the Asn NamedEventHandler interface must be created This is done in the xm Handler h and xmlHandler cpp files A detailed discussion of this code will not be provided here What it does in a nutshell is adds the ASNIC V5 8 198 angle brackets lt gt around the element names in the startElement and endElement callbacks The data callbacks simply output a textual representation of the data as they do in the print handler case The only difference in reader cpp from the other examples is that 1 There is no declaration of an employee variable to hold decoded data because no type for this variable was generated and 2 The Parse method is invoked instead of the Decode method This is the generated method definition for a pure parser If one examines the generated class definitions they will see that no Encode or Decode methods were generated Compiling and running this program will show the encoded PER message written to stdout as an XML message The resulting message is also saved in the message xmi file ASNIC V5 8 199 IMPORT EXPORT of Types ASNIC allows productions to be shared between different modules through the ASN 1 IMPORT EXPORT mechanism The compiler parses but ignores the EXPORTS declaration within a module As far as it is concerned any type defined within a module is available for import b
264. to indicate the element was received The complete set of received elements is then checked after the loop is completed to verify all required elements were received ASNIC V5 8 54 SEQUENCE OF The ASN 1 SEQUENCE OF type is converted into one of the following C C types e A doubly linked list structure Asn RTDList for C or ASNITSeqOfList a class derived from Asn1RTDList for C A structure containing an integer count of elements and a pointer to hold an array of the referenced data type a dynamic array e A structure containing an integer count of elements and a fixed sized array of the referenced data type a static array The linked list option is the default for constructed types An array is used for a sequence of primitive types The allocation for the contents field of the array depends on how the SEQUENCE OF is specified in the ASN 1 definition If a size constraint is used a static array of that size is generated otherwise a pointer variable is generated to hold a dynamically allocated array of values The decoder will automatically allocate memory to hold parsed SEQUENCE OF data values The type used for a given SEQUENCE OF construct can be modified by the use of a configuration item The storage qualifier is used for this purpose The dynamicArray keyword can be used at the global module or production level to specify that dynamic memory i e a pointer is used for the array The syntax of this qualifier is as foll
265. to msgbuf xd setp amp ctxt msgbuf 0 amp msgtag amp msglen Step 2 Test message tag for type of message received note this is optional the decode function can be called directly if the type of message is known xy Now switch on initial tag value to determine what type of message was received switch msgtag case TV PersonnelRecord compiler generated constant status asnlD PersonnelRecord amp ctxt amp employee ASNIEXPL 0 if status ASN OK decoding successful data in employee ASNIC V5 8 122 process received data else error processing break default handle unknown message type here switch Need to reinitialize objects for next iteration rtMemReset amp ctxt The only changes were the addition of the for loop and the call to rtMemReset that was added at the bottom of the loop This function resets the memory tracking parameters within the context to allow previously allocated memory to be reused for the next decode operation Optionally rtMemFree can be called to release all memory This will allow the loop to start again with no outstanding memory allocations for the next pass The example above assumes that logic existed that would read each message to be processed into the same buffer for every message processed inside the loop i e the buffer is reused each time In the case in wh
266. ts are unnamed The problem is that generated tag constants are not guaranteed to be unique since only the production and end element names are used The compiler gets around this problem by checking for duplicates If the generated name is not unique a sequential number is appended to make it unique The compiler outputs an informational message when it does this An example of this can be found in the following production C n CHOICE 0 INTEGER 1 CHOICE 0 INTEGER 1 BOOLEAN This will produce the following C code define T C aInt define T C aChoice define T C aInt 1 define T C aBool N FN FR typedef struct int t union OSINT32 aInt struct int t union OSINT32 aInt OSBOOL aBool f u aChoice ASNIC V5 8 60 lcg Note that _ was appended to the second instance of T C alnt Developers must take care to ensure they are using the correct tag constant value when this happens Populating Generated Choice Structures Populating generated CHOICE structures is more complex then for other generated types due to the use of pointers within the union construct As previously mentioned the use of pointers with C can be prevented by using the static command line option If this is done the elements within the union construct will be standard inline variable declarations and can be populated directly Otherwise the methods listed below can be used to populate the
267. types per None This option instructs the compiler to generate functions that implement the Packed Encoding Rules PER as specified in the ASN 1 standards prtfmt bracetext details Sets the print format for generated print functions The details option which is the default causes a line by line display of all generated fields in a generated structure to be printed The bracetext option causes a more concise printout showing only the relevant fields in a C like brace format shortnames None Generate a shorter form of an element name for a deeply nested production By default all intermediate names are used to form names for elements in nested types This can lead to very long names for deeply nested types This options causes only the production name and the last element name to be used to form a generated type name static None This has the same effect as specifying the global lt storage gt static lt storage gt configuration item The compiler will insert static elements instead of pointer variables in generated structures stream None This option instructs the compiler to generate stream based encoders decoders instead of memory buffer based This makes it possible to encode directly to or decode directly from a source or sink such as a file or socket In the case of BER it will also cause forward encoders to be generated which will use indefinite lengths for all constructed
268. uction is a PDU the following would be specified in a production section lt isPDU gt ASNIC V5 8 25 3 Anattribute list can be associated with some items This is normally used as a shorthand form for specifying lists of names For example to specify a list of type names to be included in the generated code for a particular module the following would be used include types TypeNamel TypeName2 TypeName3 The following are some examples of configuration specifications lt asnlconfig gt lt storage gt dynamic lt storage gt lt asnlconfig gt This specification indicates dynamic storage should be used in all places where its use would result in significant memory usage savings within all modules in the specified source file lt asnlconfig gt lt module gt lt name gt H323 MESSAGES lt name gt lt sourceFile gt h225 asn lt sourceFile gt lt typePrefix gt H225 lt typePrefix gt lt module gt lt asniconfig gt This specification applies to module H323 MESSAGES in the source file being processed For IMPORT statements involving this module it indicates that the source file h225 asn should be searched for specifications It also indicates that when C or C types are generated they should be prefixed with H225 This can help prevent name clashes if one or more modules are involved and they contain productions with common names The following tables specify the list of attributes that can b
269. ue referenced by another item the directive will be ignored storage dynamic static list The definition is the same as for the global case except that the lt storage gt array or dynamicArray specified storage type will only be applied to generated C and C keyword types from the given module lt sourceFile gt source file name Indicates the given module is contained within the given ASN 1 lt sourceFile gt source file This is used on IMPORTS to instruct the compiler where to look for imported definitions This replaces the module txt file used in previous versions of the compiler to accomplish this function lt typePrefix gt prefix text This is used to specify a prefix that will be applied to all generated C lt typePrefix gt and C typedef names note for C the prefix is applied after the standard ASNIT_ prefix This can be used to prevent name clashes if multiple modules are involved in a compilation and they all contain common names lt enumPrefix gt prefix text This is used to specify a prefix that will be applied to all generated lt enumPrefix gt enumerated identifiers within a module This can be used to prevent name clashes if multiple modules are involved in a compilation note this attribute is normally not needed for C enumerated identifiers because they are already wrapped in a structure to allows the type name to be used as an additional identifier ASNIC V5 8 2
270. ueName gt where lt valueName gt would be replaced with the name in the ASN 1 source file By generating define statements the symbolic names can be included in the source code making it easier to adjust the boundary values on the fly For example the following declaration rvalue REAL 555 will cause the following statement to be added to the generated header file define ASN1V_rvalue 5 5 The reason the ASNIV prefix is added is to prevent collisions with other declarations such as enumeration items with the same name Enumerated Value Specification The mapping of an ASN 1 enumerated value declaration to a global C or C value declaration is as follows ASN 1 production lt name gt lt EnumType gt lt value gt Generated code OSUINT32 lt name gt lt value gt Binary and Hexadecimal String Value Specification These value specifications cause two global C variables to be generated a numocts variable describing the length of the string and a data variable describing the string contents The mapping for a binary string is as follows note BIT STRING can also be used as the type in this type of declaration ASN 1 production lt name gt OCTET STRING lt bstring gt B Generated code OSUINT32 lt name gt numocts lt length gt OSOCTET name data data Hexadecimal string would be the same except the ASN 1 constant would end in a R Character String Value Specification A
271. uffer class has a standard method for parsing the initial tag length from a message to determine the type of message received This call is used in conjunction with a switch statement on generated tag constants for the known message set in order to pick a decoder to call Once it is known which type of message has been received an instance of a generated message class can be instantiated and the decode function called The start of message pointer and message length 1f known must be specified either in the constructor call or in the call to the decode function itself A program fragment that could be used to decode an employee record is as follows finclude employee h include file generated by ASNIC main OSOCTET msgbuf 1024 ASNITAG msgtag int msglen status ASNIC V5 8 124 logic to read message into msgbuf Use the ASNIBERDecodeBuffer class to parse the initial tag length from the message ASNIBERDecodeBuffer decodeBuffer msgbuf len status decodeBuffer ParseTagLen msgtag msglen if status ASN OK handle error Now switch on initial tag value to determine what type of message was received switch msgtag case TV PersonnelRecord compiler generated constant ASNIT PersonnelRecord msgData ASN1C PersonnelRecord employ decodeBuffer msgData if status employee Decode ASN OK decoding successful data in msgData proc
272. uffer is possible by setting the buffer address argument to null and the buffer size argument to zero The pu setBuffer function also allows for the specification of aligned or unaligned encoding An encode function can then be called to encode the message If the return status indicates success ASN OK then the message will have been encoded in the given buffer PER encoding starts from the beginning of the buffer and proceeds from low memory to high memory until the message is complete This differs from BER where encoding was done from back to front Therefore the buffer start address is where the encoded PER message begins The length of the encoded message can be obtained by calling the pe GetMsgLen run time function If dynamic encoding was specified 1 e a buffer start address and length were not given the run time routine pe GetMsgPtr can be used to obtain the start address of the message This routine will also return the length of the encoded message A program fragment that could be used to encode an employee record is as follows finclude employee h include file generated by ASNIC main OSOCTET msgbuf 1024 int msglen stat ASNICTXT ctxt OSBOOL aligned TRUE Employee employee typedef generated by ASNIC Populate employee C structure ASNIC V5 8 151 mployee name givenName SMITH Allocate and initialize a new context pointer stat rtInitContext amp ctxt if
273. ule from the ASN 1 source file hfile lt filename gt This option allows the specification of a header h file to which all of the generated typedef and function prototypes will be written If not specified the default is lt modulename gt h where lt modulename gt is the name of the module from the ASN 1 source file ASNIC V5 8 I directory This option 1s used to specify a directory that the compiler will search for ASN 1 source files for IMPORT items Multiple I qualifiers can be used to specify multiple directories to search java None Generate Java source code See the ASNIC Java User s Guide for more information on Java code generation lax None This option instructs the compiler to not generate code to check constraints When used in conjunction with the compact option it produces the smallest code base for a given ASN 1 specification list None Generate listing This will dump the source code to the standard output device as it is parsed This can be useful for finding parse errors maxcfiles None Maximize number of generated C files This option instructs the compiler to generate a separate c file for each generated C function In the case of C a separate cpp file is generated for each control class type and C function This is a space optimization option it can lead to smaller executable sizes by allowing the linker to only link in the re
274. ulename lt name gt lt production gt lt name gt Identifier lt name gt lt element gt lt name gt id lt name gt lt isOpenType gt lt element gt lt production gt lt module gt lt asnlconfig gt In the generated code the element id type will be replaced with an open type Asn OpenType for C or Asn1TOpenType for C and the following additional function is generated EXTERN int asnlD Identifier id OpenType ASNICTXT pctxt OSINT32 pvalue In the dentifier decode function element id is decoded as an open type ASNIC V5 8 131 Generated BER Stream Oriented Encode Functions BER messages can be encoded directly to an output stream such as a file network or memory stream The ASNIC compiler has the stream option to generate encode functions of this type For each ASN 1 production defined in the ASN 1 source file a C stream encode function is generated This function will encode a populated C variable of the given type into an encoded ASN 1 message and write it to a stream If the return status indicates success ASN_OK the message will have been encoded to the given stream Stream oriented BER encoding starts from the beginning of the message until the message is complete This is sometimes referred to as forward encoding This differs from regular BER where encoding is done from back to front Indefinite lengths are used for all constructed elements in the message Also there is no permanent buf
275. ulti threaded libraries These libraries were built with the MD option asnlbermd a lib They allow linking additional object modules in with the ASNIC run time modules to asnlpermd a lib produce larger DLL s asnixermd a lib For dynamic linking on UNIX Linux a shared object version of each run time library is included in the lib subdirectory This file typically has the extension so for shared object or sl for shared library See the documentation for your UNIX compiler to determine how to link using these files it varies for different types of UNIX systems Compiling and linking code generated to support the XML encoding rules XER is more complex then the other rules because XER requires the use of third party XML parser software This requires the use of additional include directories when compiling and libraries when linking The C sample programs that are provided use the EXPAT XML parser http www expat org All of the necessary include files and binary libraries are included with the ASNIC V5 8 22 distribution for using this parser If a different parser is to be used consult the vendor s documentation for compile and link procedures See the makefile in any of the sample subdirectories of the distribution for an example of what must be included to build a program using generated source code ASNIC V5 8 23 Porting Run time Code to Other Platforms The run time source version of the compiler include
276. ument header as well as namespace attributes in the main element tag ASNIC V5 8 177 ASNIC V5 8 178 Generated Initialization Functions The genlnit option causes functions to be generated that initialize the contents of variables of generated types These initialization functions are optional a variable can be initialized by simply setting its contents to zero for example by using the C run time memset function The advantage of initialization function is that they provide smarter initialization which can lead to improved application performance For example it is not necessary to set a large byte array to zero prior to its receiving a populated value The use of memset in this situation can result in degraded performance Generated initialization functions are written to the main lt module gt c file This file contains common constants global variables and functions that are generic to all type of encode decode functions If the cfile command line option is used the functions are written to the specified c or cpp file along with all other generated functions If maxcfiles is specified each generated initialization function is written to a separate c file The format of the name of each generated initialization function is as follows asnlInit lt prefix gt lt prodName gt where lt prodName gt is the name of the ASN 1 production for which the function is being generated and prefix is an optional prefix that can be
277. unctions Time String Types The ASN 1 GeneralizedTime and UTCTime types are mapped to standard C C null terminated character string types The C version of the product contains additional control classes for parsing and formatting time string values When C code generation is specified a control class is generated for operating on the target time string This class is derived from the ASN CGeneralizedTime or ASNICUTCTime class for GeneralizedTime or UTCTime respectively These classes contain methods for formatting or parsing time components such as month day year etc from the strings Objects of these classes can be declared inline to make the task of formatting or parsing time strings easier For example in a SEQUENCE containing a time string element the generated type will contain a public member variable containing the ASNIT type that holds the message data If one wanted to operate on the time string contained within that element they could do so by using one of the time string classes inline as follows ASN1CGeneralizedTime gtime msgbuf seqVar element gtime setMonth ASN1CTime November In this example lt seqVar gt would represent a generated SEQUENCE variable type and lt element gt would represent a time string element within this type See the ASNI CTime ASNICGeneralizedTime and ASN CUTCTime subsections in the C C Run Time Library Reference Manual for details on all of the methods available in these
278. unsigned short type See the rtBMPToCString rrBMPToNewCString and the rtCToBMPString run time function descriptions for information on utilities that can convert standard C strings to and from BMP string format The UniversalString type is a 32 bit character string for which the following structure is used typedef struct OSUINT32 nchars OS32BITCHAR data Asni32BitCharString The OS32BITCHAR type used in this definition is defined to be a C unsigned int type See the rtUCSToCString rtUCSToNewCString and the rtCToUCSString run time function descriptions for information on utilities that can convert standard C strings to and from Universal Character Set UCS 4 string format See also the rtUCSToWCSString and rtWCSToUCSString for information on utilities that can convert standard wide character string to and from UniversalString type ASNIC V5 8 63 Utilities are also provided for working with UTF 8 string data The contents of this string type are assumed to contain the UTF 8 encoding of a character string The UTF 8 encoding for a standard ASCII string is simply the string itself For Unicode strings represented in C C using the wide character type wchar_t the run time functions rtUTF8ToWCS and rtWCSToUTFS can be used for converting to and from UTF 8 format The function rtValidateUTFS can be used to ensure that a given UTF 8 encoding is valid See the C C Run Time Library Reference Manual for a complete description of these f
279. ure For C this means that an initialized context block is required for all memory allocations and deallocations All allocations are done using this block as an argument to routines such as rtMemAlloc All memory can be released at once when a user is done with a structure containing dynamic memory items by calling rtMemFree Other functions are available for doing other dynamic memory operations as well See the C C Run time Reference Manual for details on these High Level Memory Management API The high level memory management API consists of C macros and functions called in gemerated code and or in application programs to allocate and free memory within the ASNIC run time At the top level are a set of macro definitions that begin with the prefix rtMem These are mapped to a set of similar functions that begin with the prefix rrMemHeap A table showing this basic mapping is as follows Macro Function Description rtMemAlloc rtMemHeapAlloc Allocate memory rtMemAllocZ rtMemHeapAllocZ Allocate and zero memory rtMemRealloc rtMemHeapRealloc Reallocate memory rtMemFree rtMemHeapFreeAll Free all memory in context ASNIC V5 8 102 Description Function rtMemHeapFreePtr rtMemFreePtr Free a specific memory block See the ASNIC C C Common Runtime Reference Manual for further details on these functions and macros It is possible to replace the high level memory allocation functions with functions that impl
280. us lt object gt Decode In this definition lt object gt is an object of the class generated for the given production An ASNIPERDecodeBuffer object must be passed to the lt object gt constructor prior to decoding This is where the message start address and length are specified A Boolean argument is also passed indicating whether the message to be decoded was encoded using aligned or unaligned PER The function result variable status returns the status of the decode operation The return status will be zero ASN_OK if decoding is successful or a negative value if an error occurs Return status values are defined in Appendix A of the C C Common Functions Reference Manual of this document and online in the asn type h include file Procedure for Calling C Decode Functions This section describes the step by step procedure for calling a C PER decode function This method must be used if C code generation was done This method can also be used as an alternative to using the control class interface if C code generation was done Unlike BER the user must know the ASN 1 type of a PER message before it can be decoded This is because the type cannot be determined at run time There are no embedded tag values to reference to determine the type of message received There are three steps to calling a compiler generated decode function 1 Prepare a context variable for decoding 2 Call the appropriate compiler generated decode function to d
281. used as a test mechanism to determine if a corrupt or partial message was received If the parsed message length is greater than this value an error is returned If the value is specified to be zero the default then this test is bypassed The function result variable status returns the status of the decode operation The return status will be zero ASN_OK if decoding is successful or a negative value if an error occurs Return status values are defined in Appendix A of the C C Common Functions Reference Manual and online in the asn type h include file Procedure for Calling C Decode Functions This section describes the step by step procedure for calling a C BER or DER decode function This method must be used if C code generation was done This method can also be used as an alternative to using the control class interface if C code generation was done Before any decode function can be called the user must first initialize a context variable This is a variable of type ASNICTXT This variable holds all of the working data used during the decoding of a message The context variable is declared as a normal automatic variable within the top level calling function It must be initialized before use This can be accomplished as follows ASNICTXT ctxt if rtInitContext amp ctxt ASN OK initialization failed could be a license problem printf context initialization failed check license n return 1 The nex
282. used to hold a context pointer to keep track of dynamic memory allocation parameters This is a basic handle variable that is used to make the function reentrant so that it can be used in an asynchronous or threaded application The user is required to supply a pointer to a variable of this type declared somewhere in his or her program The variable must have been previously initialized using the rt nitContext run time function The pvalue argument is a pointer to hold the populated data variable This variable is of the type generated for the ASN 1 production The test function will automatically allocate dynamic memory using the run time memory management for the main variable as well as variable length fields within the structure This memory is tracked within the context structure and is released when the context structure is freed In the case of C a method is added to the generated control class for test code generation The name of this method is genTestInstance The prototype is as follows lt typeName gt pvalue object genTestInstance where lt typeName gt is the ASNIT name type name of the generated type and lt object gt is an instance of the ASNIC name generated control class Generated Sample Programs In addition to test functions it is possible to generate writer and reader sample programs These programs contain sample code to populate and encode an instance of ASN 1 data and then read and decode this data
283. variables The recommended way to populate the pointer elements is to declare variables of the embedded type to be used on the stack prior to populating the CHOICE structure The embedded variable would then be populated with the data to be encoded and then the address of this variable would be plugged into the CHOICE union pointer field Consider the following definitions AsciiString PRIVATE 28 OCTET STRING EBCDICString PRIVATE 29 OCTET STRING String CHOICE AsciiString EBCDICString This would result in the following type definitions typedef ASN1DynOctStr AsciiString typedef ASN1DynOctStr EBCDICString typedef struct String int t union JA qm gy AsciiString asciiString pom oy EBCDICString eBCDICString jou String To set the AsciiString choice value one would first declare an AsciiString variable populate it and then plug the address into a variable of type String structure as follows AsciiString asciiString String string asciiString Hello string t T String AsciiString string u asciiString amp asciiString It is also possible to allocate dynamic memory for the CHOICE union option variable but one must be careful to release this memory when done with the structure If the built in memory management functions macros are used 7tMem all memory used for the variables is automatically released when rtMemFree is called ASNIC V5 8 61 Open Type Note
284. ver because the C objects and memory heap can be reused to allow multiple messages to be encoded As example showing how to do this is as follows include employee h include file generated by ASNIC main const OSOCTET msgptr OSOCTET msgbuf 1024 int msglen ASNICTXT ctxt PersonnelRecord data Init context structure if stat rtInitContext amp ctxt ASN OK printf rtInitContext failed stat d n stat return 1 Encode loop starts here this will repeatedly use the objects declared above to encode the messages for xe setp amp ctxt msgbuf sizeof msgbuf logic here to read record from some source database flat file socket etc populate structure with data to be encoded data name SMITH ASNIC V5 8 114 call encode function if msglen asnlE PersonnelRecord amp ctxt amp data ASNIEXPL gt 0 encoding successful get pointer to start of message msgptr xe getp amp ctxt do something with th ncoded message else error processing Call rtMemReset to reset the memory heap for the next iteration Note all data allocated by rtMemAlloc will become invalid after this call rtMemReset amp ctxt rtFreeContext amp ctxt Note the rtMemReset actually does not free the memory heap it just marks it as empty and it will be reused in the next iteration
285. version 1 message could be received that does not contain the elements Additional bits will be generated in the bit mask if version brackets are present These are groupings of extended elements that typically correspond to a particular version of a protocol An example would be as follows TestSequence SEQUENCE item code INTEGER 0 254 item name TA5String SIZE 3 10 OPTIONAL le sb urgency ENUMERATED normal high DEFAULT normal alternate item cod INTEGER 0 254 alternate item nam TA5String SIZE 3 10 OPTIONAL 1 In this case a special bit flag will be added to the mask structure to indicate the presence or absence of the entire element block This will be of the form v ExtPresent where would be replaced by the sequential version number In the example above this number would be three two would be the version extension number of the urgency field Therefore the generated bit mask would be as follows struct unsigned item namePresent 1 unsigned urgencyPresent 1 unsigned v3ExtPresent 1 unsigned alternate item namePresent 1 m In this case the setting of the v3ExtPresent flag would indicate the presence or absence of the entire version block Note that it is also possible to have optional items within the block alternate item name C Mapping of SEQUENCE ASNIC V5 8 53 As mentioned earlier
286. void endElement const char name int index 0 The name argument is used pass the element name The index argument is used for SEQUENCE OF SET OF constructs only It is used to pass the index of the item in the array This argument is set to 1 for all other constructs There is one contents method for passing each of the ASN 1 data types Some methods are used to handle several different types For example the charValue method is used for values of all of the different character string types IA5String NumericString PrintableString etc as well as for big integer values Note that this method is overloaded The second implementation 1s for 16 bit character strings These strings are represented as an array of unsigned short integers in ASNIC All of the other contents methods correspond to a single equivalent ASN 1 primitive type The error handler base class has a single virtual method that must be implemented This is the error method and this has the following signature virtual int error ASNICTXT pCtxt ASNICCB pCCB int stat 0 In this definition pCtxt is a pointer to the standard ASN 1 context block that should already be familiar The pCCB structure is known as a Context Control Block This can be thought of as a sub context used to control the parsing of nested constructed types within a message It is included as a parameter to the error method mainly to allow access to the seqx field This is the sequence element inde
287. with the PER function calls substituted for the BER calls As was the case for BER the encode message buffer object init method can be used to reinitialize the encode buffer between invocations of the encode functions Generated PER Decode Functions PER encode decode functions are generated when the per switch is specified on the command line For each ASN 1 production defined in the ASN 1 source file a C PER decode function is generated This function will parse the data contents from a PER encoded ASN 1 message and populate a variable of the corresponding type with the data If C code generation is specified a control class is generated that contains a Decode method that wraps this function This function is invoked through the class interface to encode an ASN 1 message into the variable referenced in the msgData component of the class Generated C Function Format and Calling Parameters The format of the name of each generated PER decode function is as follows asnlPD lt prefix gt lt prodName gt where lt prodName gt is the name of the ASN 1 production for which the function is being generated and lt prefix gt is an optional prefix that can be set via a configuration file setting The configuration setting used to set the prefix is the lt typePrefix gt element This element specifies a prefix that will be applied to all generated typedef names and function names for the production The calling sequence for each decode function is as
288. x used when parsing a SEQUENCE construct If parsing a particular element is to be retried this item must be decremented within the error handler How to Use It To define event handlers two things must be done 1 One or more new classes must be derived from the Asn NamedEventHandler and or the Asn ErrorHandler base classes All pure virtual methods must be implemented 2 Objects of these classes must be created and registered prior to calling the generated decode method or function The best way to illustrate this procedure is through examples We will first show a simple event handler application to provide a customized formatted printout of the fields in a PER message Then we will show a simple error handler that will ignore unrecognized fields in a BER message Example 1 A Formatted Print Handler The ASNIC evaluation and distribution kits include a sample program for doing a formatted print of parsed data This code can be found in the cpp sample per eventHandler directory Parts of the code will be reproduced here for reference but refer to this directory to see the full implementation The format for the printout will be simple Each element name will be printed followed by an equal sign and an open brace 1 and newline The value will then be printed followed by another newline Finally a closing brace 3 followed ASNIC V5 8 194 by another newline will terminate the printing of the element An indentation count will
289. xplanation and stack trace of where the error occurred ASNIC V5 8 153 If encoding was successful get the start of message pointer and message length The start of message pointer is obtained by calling the getMsgPtr method of the encode buffer object If static encoding was specified i e a message buffer address and size were specified to the PER Encode Buffer class constructor the start of message pointer is the buffer start address The message length is obtained by calling the getMsgLen method of the encode buffer object ASNIC V5 8 154 A program fragment that could be used to encode an employee record is as follows include employee h main 0 include file generated by ASN1C const OSOCTET msgptr OSOCTET msgbuf 1024 int msglen sta OSBOOL aligned TRU e Br Gt Ne step 1 instantiate an instance of the PER encode buffer class This example specifies a static message buffer ASNIPEREncodeBuffer encodeBuffer msgbuf sizeof msgbuf aligned step 2 populate msgData with data ASNIT PersonnelRecord msgData msgData name givenName SMITH step 3 instantiate an instance of class to associate th ncode buff to be encoded the ASNIC ProdName r and message data ASN1C PersonnelRecord employ encod Buffer msgData steps 4 and 5 encode and check return status if stat employee Encode
290. y another module When ASNIC sees an IMPORT statement it first checks its list of loaded modules to see if the module has already been loaded into memory If not it will attempt to find and parse another source file containing the module The logic for locating the source file is as follows 1 The configuration file if specified is checked for a lt sourceFile gt element containing the name of the source file for the module 2 If this element is not present the compiler looks for a file with the name lt ModuleName gt asn where module name is the name of the module specified in the IMPORT statement In both cases the I command line option can be used to tell the compiler where to look for the files The other way of specifying multiple modules is to include them all within a single ASN 1 source file It is possible to have an ASN 1 source file containing multiple module definitions in which modules IMPORT definitions from other modules An example of this would be the following ModuleA DEFINITIONS BEGIN IMPORTS B From ModuleB A oS B END ModuleB DEFINITIONS BEGIN B INTEGER END This entire fragment of code would be present in a single ASN 1 source file ASNIC V5 8 200 ROSE and SNMP Macro Support The ASNIC compiler has a special processing mode that contains extensions to handle items in the older 1990 version of ASN 1 i e the now deprecated X 208 and X 209 standards This m
291. y default value selected If this is done a value is not encoded into the message On the decode ASNIC V5 8 52 side the developer must test for present bit not set If this is the case the default value specified in the ASN 1 specification must be used and the value in the structure ignored Extension Elements If the SEQUENCE type contains an open extension field i e a at the end of the specification or a in the middle a special element will be inserted to capture encoded extension elements for inclusion in the final encoded message This element will be of type Asn1 RTDList and have the name extElem This is a linked list of open type fields Each entry in the list is of type ASN OpenType The fields will contain complete encodings of any extension elements that may have been present in a message when it is decoded On subsequent encode of the type the extension fields will be copied into the new message The noOpenExt command line option can be used to alter this default behavior If this option is specified the extElem1 element is not included in the generated code and extension data that may be present in a decoded message is simply dropped If the SEQUENCE type contains an extension marker and extension elements then the actual extension elements will be present in addition to the extE em element These elements will be treated as optional elements whether they were declared that way or not The reason is because a
292. y is generated otherwise a GNU compatible makefile is generated ASNIC V5 8 genPrint print lt filename gt This option allows the specification of a C or C source c or cpp file to which generated print functions will be written Print functions are debug functions that allow the contents of generated type variables to be written to stdout The lt filename gt argument to this option is optional If not specified the print functions will be written to lt modulename gt Print c where lt modulename gt is the name of the module from the ASN 1 source file genPrtToStr prtToStr lt filename gt This option allows the specification of a C or C source c or cpp file to which generated print to string functions will be written Print to string functions are similar to print functions except that the output is written to a user provided text buffer instead of stdout This makes it possible for the use to display the results on different output devices for example in a text window The lt filename gt argument to this option is optional If not specified the functions will be written to lt modulename gt Print c where lt modulename gt is the name of the module from the ASN 1 source file genPrtToStrm prtToStrm lt filename gt This option allows the specification of a C or C source c or cpp file to which generated print to stream functions will be written Print
293. ynamic memory The memory is automatically released when both the input stream object ASN BERInputStream and derived classes and the control class object 4SNIC ProdName7 are deleted or go out of scope Reference counting of a context variable shared by both interfaces is used to accomplish this ASNIC V5 8 147 Decoding a Series of Messages Using the C Control Class Interface The above example is fine as a sample for decoding a single message but what happens in the more typical scenario of having a long running loop that continuously decodes messages The logic shown above would not be optimal from a performance standpoint because of the constant creation and destruction of the message processing objects It would be much better to create all of the required objects outside of the loop and then reuse them to decode and process each message A code fragment showing a way to do this is as follows finclu int ma ASN int con OSB ASN if ASN ASN for ASNIC V5 8 de employee h in 1TAG tag i len st char filename message dat OOL trace TRUE Decode 1BERFileInputStream in filename in getStatus ASN OK in printErrorinfo return 1 1T PersonnelRecord msgData 1C PersonnelRecord employ msgData 77 if in mark 32 ASN OK printf mark failed n in printErrorInfo return 1 if in decodeTagAndLen tag len ASN OK printf
294. ype variables If no output file is specified with the genCompare qualifier the functions are written to separate c files for each module in the source file The format of the name of each file is lt module gt Compare c If an output filename is specified after the genCompare qualifier all functions are written to that file The format of the name of each generated compare function is as follows asnlCompare_ lt prefix gt lt prodName gt where lt prodName gt is the name of the ASN 1 production for which the function is being generated and lt prefix gt is an optional prefix that can be set via a configuration file setting The configuration setting used to set the prefix is the lt typePrefix gt element This element specifies a prefix that will be applied to all generated typedef names and function names for the production The calling sequence for each generated compare function is as follows OSBOOL asnlCompare lt name gt ASN1ConstCharPtr name lt name gt pvalue lt name gt pCmpValue char errBuff int errBufSize In this definition lt name gt denotes the prefixed production name defined above The name argument is used to hold the top level name of the variable being compared It is typically set to the same name as the pvalue argument in quotes for example to compare employee records a call to asn Compare_ Employee employee amp employee etc might be used The pvalue argument is used to pass

ASN.1 Compiler Version 5.8 C/C++ Compiler User`s Manual

Contents

Download Pdf Manuals

Related Search

Related Contents