Home

Generated C Function Format and Calling Parameters

1. UTF8String Sis UNIVERSAL 12 IMPLICIT OCTET STRING NumericString UNIVERSAL 18 IMPLICIT IA5String PrintableString UNIVERSAL 19 IMPLICIT IA5String T6lString i UNIVERSAL 20 IMPLICIT OCTET STRING VideotexString pe UNIVERSAL 21 IMPLICIT OCTET STRING TA5String ae UNIVERSAL 22 IMPLICIT OCTET STRING UTCTime gt UNIVERSAL 23 IMPLICIT GeneralizedTim GeneralizedTim n UNIVERSAL 24 IMPLICIT IA5String GraphicString ae UNIVERSAL 25 IMPLICIT OCTET STRING VisibleString io UNIVERSAL 26 IMPLICIT OCTET STRING GeneralString oS UNIVERSAL 27 IMPLICIT OCTET STRING UniversalString rie UNIVERSAL 28 IMPLICIT OCTET STRING BMPString oa UNIVERSAL 30 IMPLICIT OCTET STRING 78 ASN 1 To C C Mappings ObjectDescriptor UNIVERSAL 7 IMPLICIT GraphicString Of these all are represented by const char pointers or std string except for the BMPString UniversalString and UTFS8String types The BMPString type is a 16 bit character string for which the following structure is used typedef struct OSUINT32 nchars OSUNICHAR data Asn1ll 6BitCharString The OSUNICHAR type used in this definition represents a Unicode character UTF 16 and is defined to be a C unsigned short type See the rt BMPToCString rtBMPToNewCString and the rtCToBMPSt ring 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
2. The My ops constraint on the opcode element specifies an information object set 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 An example of the information object set and corresponding information objects would be as follows My ops OPERATION makeCall fwdCall 131 Generated Encode Decode Function and Methods makeCall OPERATION ArgumentType MakeCallArgument amp 0perationCode local 10 fwdCall OPERATION amp ArgumentType FwdCallArgument amp 0perationCode local 11 The C or C type generated for the SEQUENCE above when table unions is specified would be as follows typedef struct EXTERN Invoke OSINT32 invokelID _OPERATION_operationCode opcode struct information object selector My_ops_TVALUE t My_ops information objects Ay union operationCode local 10 MakeCallArgument makeCall operationCode local 11 xy FwdCallArgument fwdCall ASN1OpenType extElem1 u argument Invoke Each of the options from the information object set are enumerated in the union structure All a user needs to do to encode a variable of this type is to set
3. 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 174 Generated BER Functions Simple a 123 Simple b numocts 3 Simple b data ptr Message buffer ae or m fo fo fo om 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 invoked with the initialized context variable that w
4. 00sec cee ceee nee cece teen eenes 238 Generated C Encoding Methods e eere a eeen E ceca cece cena eens pE EEEE E PEES SER EES 238 Decoding a Series of Messages using the C Control Class 1 0 0 0 cece cece ceeceeeceeeceeeeeeeeneeenes 239 15 Generated 3 GPP Layer 3 3GE3 FUNCIONS ey is cas ernn eera e ea a E E EE i SE e E 240 Generated 3GPP Layer 3 Encode Functions 00 ccccece cece secceece eee eceeeeeeeeeeeceeeeaeseaeeea sees seas eeaes 240 Generated C Function Format and Calling Parameters ccccsecceec ence ee ce eeceeeceeeea teen sean scans 240 Populating Generated Structure Variables for Encoding 1 c1ccseccsecenecenece ence ence eeeeeeeeeeeaees 241 Procedure for Calling C Encode Functions cccccceccveccnee cece nce e cence eee eeeeeneeeeeaeeeaeseaeeages 241 Generated 3GPP Layer 3 Decode Functions cece eceee cece eee ece eee eeceeeeeeeceeeeeeseaeeeaesea seas eeae cogs 242 Generated C Function Format and Calling Parameters 1ccccec cece eece ence ence eeceeecaeeea sean scans 242 Procedure for Calling C Decode Functions 0 cseccseceeecceece ence ee ceeeceeeca ceca cena cena eeaeeeneeeenees 243 16 CSN Described ges 3 aig si fest siect Sed dase gases Seve hee SS es vee Soe day dec eae DRARS Sate haes Souk deh Mee edak See TRA aed ned awe eee Ses 246 IB ETKA TO o Kn A E eat ars egentyscectavaice tony tongt ay sovnaaue re enet noe A E tapaeesiay tents
5. Step 5 Check return status if status 0 process received data in employee variable else error processing else check for other known message types Step 6 Close the stream rtxStreamClose amp ctxt Remember to release dynamic memory when done rtFreeContext amp ctxt 179 Generated BER Functions Decoding a Series of Messages Using the Functions Streaming C Decode 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 into a loop A code fragment showing a way to do this is as follows includ include employee h f will be necessary to put the decoding logic il include rtxsrc rtxStreamFile h main Q ASNITAG msgtag int msglen stat OSCTXT ctxt PersonnelRecord employ const char filenam f message dat Step 1 Initialize a context variable f if berStrmInitContext amp ctxt 0 initialization failed could be a li printf context initialization failed return 1 Step 2 Open the input stream to read d stat rtxStreamFileCreateReader amp ctxt f if stat 0 rtxErrPrint amp ctxt return stat generated by ASNIC or decoding cense problem check license n ata ilename
6. XSD Simple Type ASN 1 Type anyURI UTF8String base64Binary OCTET STRING boolean 0 BOBANS SE byte INTEGER 128 127 date UTF8String datetime UTF8String decimal L UTES double REAL duration UTF8String ENTITIES SEQUENCE OF UTF8String ENTITY o TRS float REAL gDay UTF8String gMonth UTF8String g8MonthDay a UTF8Sttings li stsi lt lt is sSCST gYear UTF8String gYearMonth UTF8String hexBinary OCTET STRING ID String itsi isCSCT IDREF UTF8String IDREFS SEQUENCE OF UTF8String integer INTEGER jin INTEGER 2147483648 2147483647 language UTF8String long INTEGER 9223372036854775808 9223372036854775807 Name UTF8String NCName UTF8String negativelnteger INTEGER MIN 1 103 XSD to C C Type Mappings XSD Simple Type ASN 1 Type NMTOKEN UTF8String NMTOKENS SEQUENCE OF UTF8String nonNegativelnteger INTEGER 0 MAX nonPositiveInteger INTEGER MIN 0 normalizedS tring UTF8String positiveInteger INTEGER 1 MAX short INTEGER 32768 32767 string UTF8String time UTF8String token UTF8String unsignedByte INTEGER 0 255 unsignedShort INTEGER 0 65535 unsignedInt INTEGER 0 4294967295 unsignedLong INTEGER 0 18446744073709551615 The C C mappings for these types can be found in the section above on ASN 1 type mappings XSD Complex Types XSD complex types and selected simple types are mapped to equivalent ASN 1 constr
7. keywords dynamic static list array dynamicArray std list std vector Std deque lt rootdir gt lt rootdir gt lt ASNIC root directory gt This configuration item is used to specify the root directory of the ASN1C installation for makefile or Visual Studio project generation It is only needed if generation of these items is done outside of the ASNIC installation lt storage gt lt storage gt One of the following If dynamic it indicates that dynamic storage ie 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 types should be used in these places In general static types are easier to work with If dist 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 lt 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 If std array the result is the same as for array except that std array will be used instead of a plai
8. c 11 or cpp11 None Generate code that uses C 11 features This includes the use of std string for character strings std list for lists and std array for static arrays For more information refer to the sections on type mappings for SEQUENCE OF and for character strings See also the section on Considerations When Using C Standard Library features cer None This option isued to generate encode decode functions that implement the Canonical Encoding Rules CER as specified in the X 690 ASN 1 standard cfile lt filename gt 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 is used 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 ASNIC The compiler will attempt to generate code more closely aligned with the given previous release of the compiler Using the Compiler Option Argument Description lt versionNumber gt is specified as x x for example compat 5 2 config lt
9. cccccec cece eee eeceeeceeecaeeea teen sean scans 205 Procedure for Calling C Decode Functions cceccsec cece ence eeceeeceeeceeeca ceca cena een ecaeeeaeeenees 206 Decoding a Series of Messages Using the C Decode Functions ceseceeseeceneceeeeeeeuneeeeees 207 Two Phase Messaging 2 2 5 c sescet vinden tect ite de acess be chteds dada an be ots heads bol as See EN EEI 207 ASNIC Ewo phase Encoding s sc sscosecasu asses secasebasvaesens ten ghee ween dgenh A Sveume seater ES EER E SA ANE 208 Two phase Decoding 2icci fi vega cape vee dts os ood Walaa Po Ss E des LST lace ab hac te bot ie 210 13 Generated XML FUNCIONS 4 sy scseh eset irs debe Steere Ses case tenet eet debe stunted E s e heed a e le S R e 212 COMELVICW gt 225236 eect suas iistarctto dees a S EE erecta 212 Differences between OSys XER and XER BASIC XER 0 0 cee ceeeee cece eeceeeneeeeeeeaeeneeaeeneeaeenes 213 EX TENDED XER iciic taser eke dag cieesste S ee ahieen ade ies ee Mediate eed asda deat eet 213 Generated XER Encode Functions Old Style Deprecated 20 00 00 cece cc escent ceeeceeeeeeeeeeeeeeeeaees 215 Generated C Function Format and Calling Parameters 1 1 0 1ccccecceece nec eeceeeceeecaeeea seca cena scans 215 Generated C Encode Method Format and Calling Parameters ooo 216 Procedure for Calling C Encode Functions 0 cccccecceeec ence nece nce e cen eeeneceenceeeeeeeeeeesaeseaeeeges 216 Procedure for Using
10. 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 if stat berDecStrmPeekTagAndLen amp ctxt amp tag amp len 0 rtxErrPrint amp ctxt return stat if msgtag TV_PersonnelRecord Step 4 Call decode function note last two args should always be ASNIEXPL and 0 stat asnlBSD_PersonnelRecord amp ctxt amp employee ASNIEXPL 0 180 Generated BER Functions Step 5 Check return status if stat 0 process received data in employee variable else error processing else check for other known message types Need to reset all memory for next iteration rtxMemReset amp ctxt end of loop Step 6 Close the stream rtxStreamClose 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 rtxMemReset 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 rtxMemFree 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 Streaming C Decode Method For
11. 5 Simple enough All we are doing is providing an implementation of the error method 289 Event Handler Interface 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 construct 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 0 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 OSCTXT pCtxt ASN1CCB 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 if stat ASN_E _NOTINSET Pr
12. else error processing rtxErrPrint amp ctxt step 4 free the context rtFreeContext amp ctxt An input stream can be used instead of a memory buffer as the data source by replacing the rtxFileReadBinary code block above with one of the rtxStreamCreateReader functions to set up a file memory or socket stream as input 202 Chapter 12 Generated Medical Device Encoding Rules MDER Functions Note MDER is available only as a professional compiler option The encoding and decoding functions are built on top of ASN1C s streaming functions and will not work with the typical buffer based implementations seen in BER or PER When introduced in version 6 4 no C implementation for MDER was available The Medical Device Encoding Rules MDER are described in IEEE standard 11073 20601 2008 Annex F This standard describes a simplified encoding to be used across medical devices ASN1C can generate encoders and decoders for specifications based on the IEEE standard which uses a strict subset of ASN 1 To generate encoding and decoding functions use the mder switch on the command line or select the appropriate option in the GUI The following sections describe the generated encoding and decoding functions Descriptions of the MDER run time functions may be found in our C MDER Runtime Library Reference Manual Generated MDER Encode Functions Generated C Function Format and Calling Parameters The form
13. 121 Generated C C Source Code public ASNIC_A ASN1C_A OSRTMessageBufferIF amp msgBuf ASNIC_A OSRTContext amp context standard encode decode methods defined in ASN1CType base class int Encode int Decode stream encode decode methods int EncodeTo OSRTMessageBufferIF amp msgBuf int DecodeFrom OSRTMessageBufferIF amp msgBuf ba It is very similar to the Symbian class definition class ASN1C_A public ASN1CType protected public EXTERN ASNIC_A EXTERN ASNIC_A OSRTMessageBufferIF amp msgBuf EXTERN ASNIC_A OSRTContext amp context standard encode decode methods defined in ASN1CType base class int Encode int Decode stream encode decode methods EXTERN int EncodeTo OSRTMessageBufferIF amp msgBuf EXTERN int DecodeFrom OSRTMessageBufferIF amp msgBuf 3 Note the use of EXTERN in the generated code it prefixes the constructors and the encoding and decoding functions but not the class declaration These prefixes are repeated in the implementation EXTERN ASN1C_A ASN1C_A ASN1CType Users should not have to modify generated code for use on the Symbian platform but should be aware of these particular differences when writing Symbian applications Considerations When Using C Standard Library When cpp is specified on the command
14. 196 Generated PER Functions 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 ASN1C_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 197 Chapter 11 Generated Octet Encoding Rules OER Functions Generated OER Encode Functions OER encode decode functions are generated when the oer switch is specified on the command line For each ASN 1 production defined in the ASN 1 source file a C OER encode function is generated This function will convert a populated C variable of the given type into an OER encoded ASN 1 message C is not directly supported for OER however it is possible to call the generated C functions from a C program Generated C Function Format and Calling Parameters The format of the name of each generated PER encode function is as follows OEREnc_ lt prefix gt lt prodName gt where lt prodName gt is the
15. d index printf n gs_IndentSpaces 3 void printEndElement const char name int index gs_IndentSpaces 3 indent printf n As in Example 1 a variable gs_IndentSpaces is used to keep track of indentation Next the reader program will need to create an Asn NamedCEventHandler variable populate it via initializePrintHandler and add it to the decode context int main int argc PersonnelRecord employ OSCTXT ctxt int i len stat char argv r 288 Event Handler Interface AsnilNamedCEventHandler printHandler ASNITAG tag initialize print handler initializePrintHandler amp printHandler employee Add event handler to list rtAddEventHandler amp ctxt amp printHandler Call compiler generated decode function stat asnlD_PersonnelRecord amp ctxt amp employee ASN1EXPL 0 The rtAddEventHandler function used to push the event handler into the decode context is defined in asn1 CEvtHndIr h This can be done multiple times as with C and every event will trigger the appropriate callback function of each event handler Example 3 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 faulttolerance the ability to
16. step 3 invoke Encode method if msglen invoke Encode gt 0 encoding successful get pointer to start of message 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 lt ModuleName gt _init OSCTXT pctxt Here ModuleName would be replaced with name of the module A C program fragment that could be used to encode the Invoke record defined above is as follows include TestTable h include file generated by ASNIC int main OSOCTET msgbuf 1024 msgptr int msglen OSCTXT ctxt Invoke invoke typedef generated by ASNIC Step 1 Initialize the context and set the buffer pointer if rtInitContext amp ctxt 0 initialization failed could be a license problem printf context initialization failed check license n return 1 xe_setp amp ctxt msgbuf sizeof msgbuf step 2 call module initialization functions 137 Generated Encode Decode Function and Methods Test init amp ctxt Step
17. 153 Generated BER Functions 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 pap A 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 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 rtxMemReset to reset the memory heap for the next iteration Note all data allocated by rtxMemAlloc will become invalid after this call rtxMemReset amp ctxt rtFreeContext amp ctxt The rtxMemReset call does not free memory instead it marks it as empty so that it may be reused in the next iteration Thus all memory allocated by rtxMemAlloc will be overwritten and data will be lost Generated C Encode Method Format and Calling Parameters When C code generation is specified the ASN1C 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 contex
18. 241 Generated 3GPP Layer 3 3GL3 Functions Populate C structure pdu 1l3HdrOpts t T_TS24007L3_L3HdrOptions_skipInd pdu 13HdrOpts u skipiInd 0 asnlSetTC_TS24008Msg_PDU_obj_IdentityRequest amp ctxt amp pdu amp idReq OSCRTLMEMSET amp idReq 0 sizeof idReq idReq value typeOfIdent TS24008I1E_IdentityTypeValue_typeOfIdent_imei Encode rtxCtxtSetBufPtr amp ctxt msgbuf sizeof msgbuf stat NASEnc_TS24008Msg_PDU amp ctxt amp pdu if 0 stat printf encode PDU failed status d n ret rtxErrPrint amp ctxt return ret msgptr rtxCtxtGetMsgPtr amp ctxt len rtxCtxtGetMsgLen amp ctxt In general static buffers should be used for encoding messages where possible as they offer a substantial performance benefit over dynamic buffer allocation In the case of L3 messages most are small because the length field is sized to hold a single octet It is therefore possible to size the buffer at 256 bytes which is the maximum size Generated 3GPP Layer 3 Decode Functions 3GPP Layer 3 decode functions are generated when the 3g 3 switch is specified on the command line For each ASN 1 production defined in the ASN 1 source file a C 3GL3 decode function is generated This function will parse the data contents from a 3GPP layer 3 binary message and populate a variable of the corresponding type with the data Generated C Function Format and Ca
19. Calls to rtInitContext should be replaced by calls to rtXmlInitContext e If you are not using one of the XmlDec_ lt Type gt methods you must use rtxCtxtSetFlag to set the OSASN1XER flag This signals the generated and runtime code that XER and not OSys XER rules apply e xerSetDecBufPtr is replaced by using one of the rtxStream methods For example if the buffer was read from a file you can use stat rtxStreamFileOpen pctxt filename OSRTSTRMF_INPUT Use rtxCtxtSetFlag to set the OSXMLCIA4N flag if you want to encode using canonical XER the OSASNIXER flag must still also be set e ASNIXERDecodeBuffer is replaced with OSXMLDecodeBuffer Note that OSXMLDecodeBuffer can be created on streams there is no OSKMLDecodeStream corresponding to ASN1 XERDecodeStream e OSXMLDecodeBuffer does not have a gt gt operator Replace buffer gt gt myOb ject with myOb ject DecodeFrom buffer Generated XML Encode Functions Note As of version 6 5 1 this section applies to XER encoding rules See the Overview section above XML C encode and decode functions allow data in a populated variable to be formatted into an XML document For each ASN 1 production defined in the ASN 1 source file a C XML encode function is generated In the case of XML schema a C encode function is generated for each type and global element declaration This function will convert a populated C variable of the given type into an XML encoded message i e an XML d
20. SEQUENCE OF The ASN 1 SEQUENCE OF type is converted into one of the following C C types e A doubly linked list structure OSRTDList for C or ASN1TSeqOfList a class derived from OSRTDList for C e 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 e A C Standard Library container class such as std list when cpp11 is specified on the command line 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 default type may be altered through the use of command line options The array option may be used to indicate an array type should be used as the default instead of a linked list for all types If the type does not contain a size constraint a dynamic array will be used otherwise a static array of the given size will be used The arraySize option may be used to force use of a static array for all types SEQUENCE
21. WITH SYNTAX VisibleString ID 011 This results in the generation of the following C class class EXTERN name public ATTRIBUT public name GI a virtual int encodeBERType OSCTXT pctxt ASN1TObject amp object virtual int decodeBERType OSCTXT pctxt ASN1TObject amp object ba The constructor implementation for this class not shown sets the fixed type fields id to the assigned values 0 1 1 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 The format of the new type name is as follows 100 ASN 1 To C C Mappings _ lt ObjectName gt _ lt FieldName gt where lt Ob ject Name gt is replaced with the information object name and lt F ie1dName gt is replaced with the name of the field from within the object Information Object Set 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 follow
22. 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 rtxMem all memory used for the variables is automatically released when rtxMemFree is called Open Type Note 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
23. value n 2 value element 0 1 value element 1 2 CHOICE Value The mapping of an ASN 1 CHOICE value declaration to a global C or C value declaration is as follows ASN 1 production lt name gt lt ChoiceType gt lt value gt Generated code lt ChoiceType gt lt name gt The choice value will be initialized in the value initialization function For example consider the following declaration ChoiceType CHOICE oid OBJECT IDENTIFIER id INTEGER value ChoiceType id 1 This would result in the following definition in the C or C source file ChoiceType value 87 ASN 1 To C C Mappings Code generated in the value initialization function would be as follows value t T_ChoiceType_id value u id 1 Table Constraint Related Structures The following sections describe changes to generated code that occur when the tables or table unions option is specified on the command line or when Table Constraint Options are selected from the GUI This option causes additional code to be generated for items required to support table constraints as specified in the X 682 standard This includes the generation of structures and classes for Information Object Classes Information Objects and Information Object Sets as specified in the X 681 standard Most of the additional items that are generated are read only tables for use by the run time for data validation purposes However
24. 3 If a match 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 is 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 is the same as without table constraints The only difference is in the open type data population procedure The table unions option will cause union structure to be generated for open type field containing relationsal table constraints These are populated for encoding in much the same way CHOICE onstructs are handled The tables option will cause ASN TObject fields to be inserted in the generated code instead of Asn OpenType declarations The procedure to populate the value for an ASNITObject 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 Follow t
25. 4 Free the context after use of the decoded data is complete to free allocated memory structures Before an OER decode function can be called the user must first initialize a context block structure The context block is initialized by calling the rtInitContext function The user then has the option to do stream based or memory based decoding If stream based is to be done the user must call a rtxStreamCreateReader function for the type of stream from which data will be read For example if the user wishes to read data from a file the rtxStreamFileCreateReader function would be called To do memory based decoding the rtxInitContextBuffer function would be called The message to be decoded must reside in memory The arguments to this function would then specify the message buffer in which the data to be decoded exists The variable that is to receive the decoded data must then be initialized This can be done by either initializing the variable to zero using memset or by calling the ASNIC generated initialization function A decode function can then be called to decode the message If the return status indicates success 0 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 b
26. Dynamic OCTET STRING ASN 1 production lt name gt OCTET STRING Generated C code typedef ASN1IDynOctStr lt name gt Generated C code typedef ASN1TDynOctStr ASNIT_ 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 assignment operators and other helper methods that make it easier to manipulate binary data The ASNI DynOctStr type i e the type used in the C mapping is defined in the asn type h header file as follows typedef struct ASN1DynOctStr OSUINT32 numocts const OSOCTET data ASN1DynOctStr The ASNITDynOctStr type is defined in the ASN TOctStr h header file This class extends the C ASNIDynOctStr 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 ASN 1 production 59 ASN 1 To C C Mappings lt name gt OCTET STRING SIZE lt len gt Generated C code typedef struct OSUINT32 numocts OSOCTET data lt len gt lt name gt If the strict size command line option is used the numocts component within this type definition may be of a different type OSUINTS8 or OSUINT16 or eliminated completely if the type is constrained to be a fixed size Generated C code typedef struct OSUINT32 numocts OSOCTET data lt len gt ctors AS
27. T_pathSwitchRequest 93 ASN 1 To C C Mappings 3 In this case the type module and object set names are not needed because the class name provides for unambiguous enumerated item names Generated Helper Methods For C special asnlAppend_ lt name gt and asnlGet IE_ lt name gt functions are generated to help a user append information elements IE s to a list and get an indexed IE respectively For C these are added as methods to the generated control class for the list type For example for the HandoverRequired_protocollEs type the following methods are added to the control class A GI class EXT RN ASNIC_HandoverRequired_protocollEs public ASN1CSeqOfList Eal Append IE with value type ASN1T_MME_UE_S1AP_ID to list int Append_id_MME_UE_S1AP_ID ASN1T_MME_UE_S1AP_ID value Append IE with value type ASN1T_HandoverType to list int Appendid_eNB_UE_S1AP_ID ASN1T_HandoverType value Get IE using id key value ASN1T_HandoverRequired_protocolIEs_element GetIE ASN1T_ProtocolIE_ID id bi Legacy Table Constraint Model T The primary difference as to what a user sees and works with in the legacy model as opposed to the unions model lies in the representation of open type elements that contain a table constraint The standard form of an open type element constrained wi
28. compiler generated constant ASN1T_PersonnelRecord msgData ASN1C_PersonnelRecord employ msgData 182 Generated BER Functions in gt gt employee if in getStatus 0 printf decode of PersonnelRecord failed n in printErroriInfo 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 dynamic memory The memory is automatically released when both the input stream object ASN BERDecodeStream and derived classes 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 is 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 pr
29. step 2 open an input stream stat rtxStreamFileCreateReader amp ctxt filename if stat 0 rtxErrPrint amp ctxt return 1 step 3 attempt to match the start tag to a known value if 0 rtXmlpMatchStartTag amp ctxt OSUTF8 Employee Note that it is necessary to mark the last event active in the pull parser to that it can be parsed again in the PDU decode function rtXmlpMarkLastEventActive amp ctxt step 4 call the decode function 231 Generated XML Functions stat XmlDec_PersonnelRecord_PDU amp ctxt amp data if stat 0 process received data else error processing rtxErrPrint amp ctxt can check for other possible tag matches here step 5 free the context rtFreeContext amp ctxt Generated C Decode Method Format and Calling Parameters Generated decode functions are invoked through the class interface by calling the base class Decode or DecodeFrom methods The calling sequence for this method is as follows status lt object gt Decode In this definition lt object gt is an object of the class generated for the given production An OSXMLDecodeBuffer object must be passed to the lt object gt constructor prior to decoding This is where the message stream containing the XML document to be decoded is specified Several constructors are available allowing th
30. A SEQUENCE xX xX 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 AnInt 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 example above the generated code would be as follows typedef OSINT32 AnInt typedef struct Aseg OSINT32 x 66 ASN 1 To C C Mappings AnInt anInt Aseq OPTI
31. C Output all code to a single c h file E ah C Output each generated function to its own source file Max lines per file For C or C target languages C C Output Options controls how generated code is distributed across source files C Code Organization File name Output code to directories based on module names Code generation option For C C Code Organization controls how generated code is distributed across source files and how files are organized into directories Java Code Organization to directories based on module na For Java Java Code Organization allows generated code to be organized into directories based on the ASN 1 module for which they were generated Alternatively generated files will be placed directly into the output directory 43 Function Generation Constraints and Debugging Code Modifications Generated Function Types Printing Functions Decoding l Comparison l Copy Stream l Standard Output Streaming M Str Print Format Bracetext C Detail Sample Program Generation I Specify a POU for the sample programs CS Generate run time test code for populating data structures I Generate code for populating test instances Generate reader sample program _ Generate writer sample program ASNI1C GUI Users Guide The Function Generation tab provides settings for what functionality to include in generated
32. CSN1String CSN1String CSN1String The l and or operators are equivalent An Alternation matches any string that is matched by either of the operands The operator is similar to the other operators except that a match on the right hand operand is counted as an error Concatenation Concatenation CSN1String BasicString Exponen CSN1String BASIC_NAM Expr J A a Eal ExponentExpr 249 CSN 1 Described There is no operator for the concatenation operation Instead one simply lists the things to be concatenated together The lack of a concatenation operator together with the allowance of spaces in a BASIC_NAME gives rise to an ambiguity is foo bar a single BASIC_NAME BASIC_NAM an error if a multi word name is used The BASTC_NAM Exponents Exponents are used to indicate repetition EA Tki Tki Expressio Addi Tki ParenExpo emp Mult ExponentExpr ExpressionOrStar ExprTerm tx nOrStar EXpr nentOpt ty Addl AddE Expr xpr Expr tCExpr ExprTerm ExpressionOrStar m4 tExpr txt by rTerm EGER Addl nctionCall Expr FunctionCall IDENTIFIER res yt wy MultExpr MultExpr MultExprTerm MultExprTerm 1 EXT END Eal ED_NAM or the concatenation of two names To resolve this we let
33. If minOccurs is absent its default value is 1 X 694 specifies that a SEQUENCE OF type be formed for this element and then the element renamed to familyName list to reference this element The C code produced by this transformation is as follows typedef struct EXTERN Name const OSUTF8CHAR givenName const OSUTF8CHAR initial struct OSUINT32 n const OSUTF8CHAR elem 2 familyName_list Name In this case an array was used to represent familyName_list In others a linked list might be used to represent the repeating item 107 XSD to C C Type Mappings xsd list Another way to represent repeating items in XSD is by using xsd list This is a simple type in XSD that refers to a space separated list of repeating items When the list is converted to ASN 1 it is modeled as a SEQUENCE OF type For example lt xsd simpleType name MyType gt lt xsd list itemType xsd int gt lt xsd simpleType gt results in the generation of the following C type typedef struct EXTERN MyType OSUINT32 n OSINT32 elem MyType Special code is added to the generated XML encode and decode function to ensure the data is encoded in spaceseparated list form instead of as XML elements xsd any The xsd any element is a wildcard placeholder that allows an occurence of any element definition to occur at a given location It is similar to the ASN 1 open type and can be modeled as such however ASN
34. Invalid object identifier This error code is returned when an object identifier is encountered that is not valid Possible reasons for being invalid include invalid first and second arc identifiers first must be 0 1 or 2 second must be less than 40 not enough subidentifier values must be 2 or more or too many arc values maximum number is 128 Invalid length This error code is returned when a length value is parsed that is not consistent with other lengths in a BER or DER message This typically happens when an inner length within a constructed type is larger than the outer length value 102 ASN_E BADTAG Bad tag value This error code is returned when a tag value is parsed with an identifier code that is too large to fit in a 32 bit integer variable 103 ASN_E_INVBINS Invalid binary string This error code is returned when decoding XER data and a bit string value is received that contains something other than 1 or 0 characters 104 105 ASN_E_INVINDEX ASN_E_ INVTCVAL Invalid table constraint index This error code is returned when a value is provided to index into a table and the value does not match any of the defined indexes Invalid table constraint value This error code is returned when a the value for an element in a table constrained message instance does not match the value for the element defined in the table 106 ASN_E_CONCMODF Concurrent list modification error Thi
35. OSCTXT pctxt mployeeNumber pvalue ASNl1TagType tagging LEG EXTERN int asnlD_EmployeeNumber OSCTXT pctxt ASN1T_EmployeeNumber pvalue ASN1TagType tagging int length Note the two main differences between this and the C version 1 The use of the ASNIT_ 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 ASN1C_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 116 Generated C C Source Code 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 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 If no explicit declarations exist a type is determined to be a PDU if it is not referenced
36. The data describe the size of the allocated blocks but not the content Internally these data are used to navigate through the memory heap and they must be retained until the blocks are resized e g by a user call to rt xMemF ree or by a request that causes an available block to be joined to another 149 Chapter 9 Generated BER Functions Generated 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 Streaming 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 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 lt prefix gt is an optional prefix that can be set vi
37. This status code is returned by the decoder when a value in an XML instance does not match the pattern facet defined in the XML schema It can also be returned by numeric encode functions that cannot format a numeric value to match the pattern specified for that value 36 RTERR_ATTRMISRQ Missing required attribute This status code is returned by the decoder when an XML instance is missing a required attribute value as defined in the XML schema 302 ASNIC Error Codes Error Code Error Name Description 37 38 RTERR_HOSTNOTFOU RTERR_HTTPERR Host name could not be resolved This status code is returned from run time socket functions when they are unable to connect to a given host computer HTTP protocol error This status code is returned by functions doing HTTP protocol operations such as SOAP functions It is returned when a protocol error is detected Details on the specific error can be obtained by calling rtxErrPrint 39 RTERR_SOAPERR SOAP error This status code when an error is detected when tryingto execute a SOAP operation RTERR_EXPIRED Evaluation license expired This error is returned from evaluation versions of the run time library when the hard coded evaluation period is expired RTERR_UNEXPELEM RTERR_INVOCCUR Unexpected element encountered This status code is returned when an element is encountered in a position where something else for
38. XmlEnc_PersonnelRecord_PDU amp ctxt amp employee if stat 0 Note message can be treated as a null terminated string in memory printf encoded XML message n puts char msgbuf printf n else error processing rtFreeContext amp ctxt release the context pointer Generated C Encode Method Format and Calling Parameters 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 document header as well as namespace attributes in the main element tag 227 Generated XML Functions 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 XML encode function This status value will be zero if encoding was successful or a negative error status value if encoding fails Return status values are defined in the rtxErrCodes 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 Procedure for Using the C Control Class Encode Method The
39. choice 1 NULL first INTEGER 0 1 second INTEGER 0 3 third NULL maybe INTEGER 0 15 OPTIONAL possibly INTEGER 0 7 OPTIONAL questionable INTEGER 0 3 OPTIONAL Concat SEQUENCE el INTEGER 0 1 e2 INTEGER 0 3 7 1 e3 INTEGER 0 e4 INTEGER 0 7 a pad bit INTEGE 0 1 DEFAULT 0 some literal bits INTEGER 41 DEFAULT 41 single bit INTEGER 0 1 single octet INTEGER 0 255 ref to a name Naming two bit value using more done bit list SEQUENCE OF INTEGER 0 3 named list SEQUENCE OF INTEGER 0 3 list of 10 SEQUENCE SIZE 10 OF INTEGER 0 15 list ending with container SEQUENCE OF INTEGER 0 7 Length Constrained Content SEQUENCE length INTEGER 0 127 willy nilly INTEGER 0 15 component INTEGER 0 7 OPTIONAL T T SingleComponent SEQUENCE fields SEQUENCE fieldl INTEGER 0 15 273 Compiling CSN 1 field2 INTEGER 0 7 OPTIONAL Things With Exponents SEQUENCE a 23 bit int INTEGER 0 8388607 a fixed length bit string BIT STRING SIZE 45 a var length bit string BIT STRING SIZE 0 838
40. in the list based on the key field The general format for this type of lt ProtocollIE FieldType gt asniGet_ lt Protocoll function is as follows EsType gt 92 PRE PRI ENCE ENCE ASN 1 To C C Mappings lt KeyFieldType gt lt key gt lt ProtocollEsType gt plist In this definition lt ProtocollEsType gt refers to the main list type SEQUENCE OF defining the information element list lt ProtocolIE FieldType gt is the type of an element within this list and lt KeyFieldType gt is the type of index key field An example of this type of function from the S1AP definitions is as follows Get IE using id key value HandoverRequired_protocollEs_element asnilGet_HandoverRequired_protocoll ProtocolIE_ID id HandoverRequired_protocollEs plist GI n Generated Set Table Constraint SetTC Function The set table constraint helper function sets the fixed type value fields the table union tag t value and sets a pointer to the variable typed value field to be encoded The general format for this type of function is as follows void asnlSetTC_ lt Type gt _ lt InfoObject gt OSCTXT pctxt lt Type gt pElem lt ValueType gt value In this definition lt IType gt refers to the container type in which the table constrained items are defined and lt ValueType gt is the type of the value for the indexed information object set item An example o
41. 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 is to be written into These arguments specify a fixed size buffer If the generated text is 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 is returned If there is text already in the buffer the function will append to this text rather than overwrite it starting at the first null character So in this case there must be enough space in the buffer starting from the first null character to hold all of the generated text otherwise a status of 1 is returned For this reason initializing a newly allocated buffer with zeroes before passing it to the function is a good idea For C two toString methods are generated in the control class that call the generated print to string function With the first signature in addition to the name argument the method also takes a buffer and bufSize argument to describe the buffer to which the text is to be written The second signature does not take a name argument instead the name of the item that the control class instance describes is defaulted Print to Stream The genPrtToStrm option causes functions to be generated that print the cont
42. the vcproj option takes an optional argument the release year of the version of Visual Studio used This modifies the resulting project to link against the appropriate set of libraries distributed with ASNIC If no year is specified the project will link against the usual c and cpp directories If 2003 is specified the project will us the c_vs2003 and cpp_vs2003 directories If 2005 is specified c_vs2005 and cpp_vs2005 will be used Likewise if 2008 is specified c_vs2008 and cpp_vs2008 will be used 125 Chapter 7 Generated Encode Decode Function and Methods 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 OSCTXT pctxt lt ProdName gt pvalue ASN1TagType tagging int asnlD_ lt ProdName gt OSCTXT pctxt lt ProdName gt pvalue ASNiTagType 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 g
43. type gt and lt element 2 type gt respectively This form of the structure will be generated if the internal types are primitive lt tempName1 gt 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 typedef struct A_x OSINT32 al OSBOOL a2 A_x typedef struct A y OSUINT32 numocts OSOCTET data 10 A_y typedef struct A A_X X A_y 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 contains three nesting levels X SEQUENCE a SEQUENCE aa SEQUENCE x INTEGER y BOOLEAN bb INTEGER In this case the generation of temporary types results in the following equivalent type definitions X a aa SEQUENCE x INTEGER y BOOLEAN X a SEQUENCE 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
44. 208 and X 209 standards This mode 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 ASNI1C 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 ErrorL
45. 266 18 Compiling CSN erir erna EN T EN E E UL E adeno EENS 267 IBASICS ntanna ea a a a e a eek Lad e a E E cn EE EAN A 267 Usme CSNel ad ASN 1 TOTAA E e Santee a ee BE EE 267 Tips n Working with CSN Desrosiers e E AR E EEE AEE ES TREERE 268 Error Alternatives acess rs i e E a E E eee E ade CR ee 268 The lt send Operator oo en ea e E a e e Aa E Aee a a AEE EESE 269 Problems with Names 3c30secesvevseceaias seceenveyecetins pavete ne EE E E ERT EEE EER p TRA 270 SUDCIASSING sep neeesa E R EE E E uted ER EESE E ENA EES ER E 270 User Defined Functions sonn e a e E EE E E O E a a e 270 CSN Tetov ASN 1 Example nioni a ena ea AE E AEA EE REE 271 19 Additional Generated Functions 2 0 2 cceceeceeceee cece eeceeeeeceereeceeceeaeceecseceeaserecesereeeeereeeereseseresaeneees 275 Generated Initialization FUNCtions sessed E a A aE EEE EEES 275 Generated Memory Free Functions sieisen E eE E a EE E E E EE A 275 Generated Print FUNCHONS somoses iii ee a e a a e A a A E e E AEN a a a TEENE 276 Printto Standard Output x scctey ested as Sec E E EA E E T E de wip Eek eae a E ee 276 Print tO SHIN grener she Sevadon vane sedensteeo ph tates ne Sense EENE on wee bsp SE EEE E RN se deed ss 277 Print to SUP CGI sorrisi isine a BO aaah Nees Ub OL NSO Ch pA UGA SE NN Og Sa vod Ea Sea EE EEE 277 Prnt Formal gee tees gout ck ae eRe PRA eR r 6k A ERNEST NR SORE NE EN Naa ANG a Oia aR La nae ea eRe 278 Generated Compare Functions ie i een eee cty
46. 32 bit character string for which the following structure is used typedef struct OSUINT32 nchars OS32BITCHAR data Asn1l32BitCharString The OS32BITCHAR type used in this definition is defined to be a C unsigned int type See the rtUCSToCString rtUCSToNewCSt ring and the rt CToUCSSt ring 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 rt UCSToWCSSt ring and rtWCSToUCSSt ring for information on utilities that can convert standard wide character string to and from UniversalString type The UTF8String type is represented as a string of unsigned characters using the OSUTF 8CHAR data type This type is defined to be unsigned char This makes it possible to use the characters in the upper range of the UTF 8 space as positive numbers The contents of this string type are assumed to contain the UTF 8 encoding of a character string For the most part standard C character string functions such as strcpy strcat etc can be used with these strings with some type casting Utility functions are provided for working with UTF 8 string data 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 rt xUTF8ToWCS and rt xWCSToUTF8 can be used for converting to and from UTF 8 format The function rtxValidateUTF8 c
47. ASN 1 types are defined in the 2002 X 680 standard For example lt BOOLEANS gt is the default element name for the BOOLEAN built in type 6699 3 If the name is empty i e equal to is applied to the encoded data a zero length string not to be confused with null then no element name The function result variable stat returns the status of the encode operation Status code zero indicates the function was successful A negative value indicates encoding failed Return status values are defined in the rtxErrCodes h include file The error text and a stack trace can be displayed using the rtvErrPrint 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 zero if encoding was successful or a negative error status value if encoding fails Return status values are defined in the rtxErrCodes 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 Procedure for Calling C Encode Functions This section describes
48. Asn NamedEventHandler interface must be created This is done in the xmlHandler 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 angle brackets lt gt around the element names in the startElement and endElement callbacks The data ASN1CCB pCCB 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 pureparser int stat 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 291 Chapter 21 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 by another module When ASNIC sees an IMPORT statement it first checks its list of loaded modules to see if
49. 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 5 Release dynamic memory that was allocated by the decoder All memory associated with the decode context is released when both the ASNIXERDecodeBuffer and ASN1C_TypeName 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 steps 1 2 and 3 instantiate an instance of the XER decoding classes This example specifies an XML file as the message input source ASN1T_PersonnelRecord employee ASN1IXERDecodeBuffer decodeBuffer filename ASN1C_PersonnelRecord employeeC decodeBuffer employee step 4 invoke the decode method stat employeeC Decode if 0 stat employeeC Print employee else decodeBuffer printErroriInfo step 5 dynamic memory is released when employeeC and decode buffer objects go out of scope return stat Procedure for Interfacing with Other C and C X ML 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 ASN1C with other XML parser library implementations The
50. E match as many characters as possible and then in contexts where there is possible ambiguity we report F in the second alternative shall not be a multi word name o 1 An exponent can be wrapped in parenthesis first alternative of ExponentExpr or else introduced by an asterisk second alternative The third alternative is equivalent to and is used to indicate 0 to infinity repetitions All exponent expressions other than and indicate a fixed number of repetitions though this fixed number may not be known statically if the exponent uses a function 2 Exponents may use the usual mathematical operators 250 CSN 1 Described 3 3GPP 24 007 does not discuss the use of functions in exponents The following information about functions is based on non official sources 4 The function name is given by the IDENTIFIER The name really can be anything including user defined functions but the definition of the functions is not part of the CSN 1 notation All functions take a single argument an EXTENDED_NAME which is a reference to a labeled string that appears in the encoding prior to the string having the exponent 5 There are two predefined functions val and len In practice we have only seen val used Function val returns the integer value of the referenced string interpreted as a non negative binary integer Function len returns the number of bits for the referenced string Exclu
51. Encoding Rules for more information 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 laxsyntax None This option instructs the compiler to not do a thorough syntax check when compiling a specification and to generate code even if the specification contains non fatal syntax errors Use of the code generated in this case can have unpredictable results however if a user knows that certain parts of a specification are not going to be used this option can save time libdir lt directory gt This option is used in conjunction with the genMake option to specify the name of the library directory to be added to the makefile lickey lt key value gt This option is used to enter a license key value that was provided to the user to enable the compiler for either evaluation or permanent use linkedList none This option specifies that a linked list type is to be used for SEQUENCE OF SET OF constructs 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 c
52. OF types not having a size constraint will result in a static array being generated of the size specified in the arraySize option The cpp11 option will alter the code to use std array instead of plain C static arrays The dynamicArray option will result in the use of a dynamic array for all SEQUENCE OF types The linkedList option will result in the use of a linked list for all of these types The cpp option will result in using std list wherever a linked list would have been used othewise 69 ASN 1 To C C Mappings The type used for a given SEQUENCE OF construct can be modified by the use of a configuration item The lt storage gt 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 follows 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 lt storage maxSize 100 gt array lt storage gt If maxSize is not specified and the ASN 1 production contains no size constraint then a dynamic array is used The std array keyword is identical to the array keyword except that it specifies use of std array
53. 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 In this case LESSet Paramrefers 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 Protocol IE 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 Protocol IE Field becomes the following ProtocollIE Field SEQUENCE id ProtocollIE ID criticality Criticality value ASN 1 OPEN TYPE References to the field are simply replaced with a reference to the Protocol1ID Field typedef If tables is specified the parameters are used and a new type instance is created in accordance with the rules above Value Mappings ASNIC can parse any type of ASN 1 value specification but it will only generate code for following value specifications e BOOLEAN e INTEGER 82 ASN 1 To C C Mappings e REAL e ENUMERATED e Binary String e Hexadecimal String e C
54. Sea eehe sete bagel ey sey NE be Sea TEER EES see aE 104 KS call aie eee eb aes oie sada deh nose Seeda A al niente ack EE SAIR cca Soh vase nh Meek aedslet 105 XSA choice and XSAsUMION ee E haa deeb ston sewed tae Mebane se ed sa neuen tes 105 Repeating Groups 3 23 2 5 ie en en ii a ees eee tee 106 Repeating Elements 253 3030 esn n an aaas oE EE ec be se gest eh oo esa EEEE aE NEETER 107 KSC USO ir ea ete a E a a A E e A batted A E o e E ai 108 KSC ANY os sos seed esis etd sole E ddan E EEEO E E tie E a EESO ES SOE EE E ESS 108 XME Attribute Declarations p eiir rei anae e EE aoaea SEE TOETEREN ES EPRA ES 109 KSdianyA ttrib te soiien ennaii he e eel eee E Tee seen E bested 110 xsd simpleContent cesi a ee e T E A E E ae aa ES 111 xsd complexContent nicsen ei Sita Si a Ba en ee a EE T EE 112 Substitution Groups see rae oaee versa ccd cas REE E EEE SEE com ade S EAE OAS 113 6 Generated C C Source Code x issnin rneer EEn E EEEE ESE SEEE EASE EAEE E EEEE NIUE SENSES 115 Header C A E e aa aaa a a E E A Ea bane E RA 115 Generated C Sources Files Vosse soser na n o E e cess ecb SEE Mobs EAN EEE Ee E EE rE aE 118 Maximii Lines per File vse somrer esseere rnea tomoan pro o Sia Sade PEIEE Op S pepa SE Ten eSEE EE ES EEU 118 Use of the maxcfiles Option sorie onie en aE EEE E EE EEES E EEEE KE S 118 Generated CHA files eeror i ea a e barbs E bes veda E E a E dee E SES 119 Generated C C files and the compat Option seessesessse
55. Set from index element value 2 Assign or cast the Asn Object decoded member variable void to the result type 3 The Asn1 Object encoded field will hold the data in encoded form For the above complete example the Invoke type s argument element will be decoded as one of the types in the SupportedAttributes information object set i 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 Asn Object encoded field as before but the Asn1Object decoded field will be NULL indicating the value is of an unknown type 138 Generated Encode Decode Function and Methods 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 ASN1C_Invoke invok decodeBuffer msgData step 3 call decode function if status invoke Decode 0 decoding successful data in msgData use key field value to set type of message data ASNIOBJID oidl 3 0 1 1 ASNIOBJID oid2 3 0 1 2 if msgDat
56. Structures sseesseeersseesresesrrsrrsrrerrsrerrrsresrerrerrerrsrrerrsreneere 129 Simple Form Code Generation i ses05 0 assns boi ter eroarea Teie E E been E ETTE E T E E ES 131 Unions Table Form Code Generation se sseersseesesersrrerrsrrerrrresrrresreresrrerrsrererrresreererreees 131 Legacy Table Form Code Generation c scsssssecsgssetscesesscussasseden ose snsessisevecesssseovasaieedsansesnotes 132 Additional Code Generated with the tables option cee e cece cece cece cece ce eeae een eeneeeeeeeee ea 133 General Procedure for Table Constraint Encoding cece cece ceee cece eeeeca cece cena cena ceneeneeeenees 135 General Procedure for Table Constraint Decoding 10 00 0000 0c eee ceee cece cece a eee a eene een eeneeeeeeeeees 138 General Procedures for Encoding and Decoding 0 cece eee cece cence ence ence eeceeeeaeeeaeeeu seen een eeaeeegs 141 Populating Generated Structure Variables for Encoding ce cee eeeceee cee ce eeceeeea seca sean eeuee 141 Accessing Encoded Message Components ccseececeeeceeeeeeceeeeeeeeeeeeeeaeeea esau sean eeu eegs 142 8 Memory Management in C C oo cece ec cece nce e Rere EO EEEE EESO SEEST EEEE ES e EEES 144 The ASNIC Default Memory Manager 0 3 cc0 sccssssecesesssereeng seccee ses sesvasgsbectessssesvandsacosscsasususcapeass 144 High Level Memory Management API cceceeeeeceeeeceeeeeceeececeeecseeeeeseee
57. Values Description lt name gt element name This attribute identifies the element within a SEQUENCE lt name gt SET or CHOICE construct to which this section applies It is required lt addarg name name Argument name function This item adds an argument to the generated C encode and or decode function that is invoked to encode or decode the element The name attribute specified the value to be passed The func attribute is optional and only required if the argument should be added to either the encode or decode function only By default the argument is added to both the encode and decode function This item is only supported for C 3GPP layer 3 code generation lt aligned gt n a This item is used to specify that byte alignment is to be done after encoding or decoding this element This item is only supported for C 3GPP layer 3 code generation lt cDecSrcName gt lt cDecSrcName gt lt C source file name This item is used to substitute the C source code contained within the given file for what would have been generated for decoding the element The code in this case is not a complete function but rather a snippet to be inserted within a larger function The current include path is searched for the given filename This item is only supported for C 3GPP layer 3 code generation lt lt cEncSrcName gt cEncSrcName gt lt C source file name This item is used to substitute the C sourc
58. X 208 ASN E UNDEFOBJ ASN E ABSCLSFLD This indicates that the named object is not defined within context of the requested module This indicates that the specified field is absent in an information object definition ASN E UNDEFCLAS This indicates that the specified class is not defined within context of the module that uses it ASN E INVFIELD This indicates the specified class field is not valid it must be defined ASN E UNDEFOSET ASN E INVV ALELM This indicates that ASN1C was unable to find the specified object set in the context of the module in which it s used An invalid value was supplied for an element in a type ASN E MIS VALELM This indicates that a non optional element is missing a value when it should have one ASN E INVLIDENT This indicates that an invalid identifier was specified in an enumeration ASN E FILNOTFOU ASN E INVSIZE This indicates that the requested file was not found This indicates that an invalid size specification for a type was provided check size constraints for base types ASN E UNRESOBJ This indicates that the specified information object could not be resolved within the context of the named module 298 ASNIC Error Codes Error Code Error Description ASN E TOOMANY ASN E LOOPDETECTED This indicates that too many sub elements for the specified type were provided This indicates a loop was detected in
59. a void pointer to hold a link to a variable of the typed data structure This is inconvenient for the developer because he would need to consult the object set definition within the ASN 1 specification in order to determine what type of data is to be used with each procedure code It is also error prone in that the void pointer provides for no type checking at compile time In the new model the generated structure is designed to be similar as to what is used to represent a CHOICE type That is to say the structure is a union with a choice selector value and all possible types listed out in a union structure This is the general form typedef struct lt Type gt lt Element1Type gt lt element1 gt lt Element2Type gt lt element2 gt information object selector aif lt SelectorEnumType gt t lt ObjectSet gt information objects Ay union lt elementl gt lt objectl element1 value gt lt element2 gt lt objectl element2 value gt lt objectl element3 type gt lt objectl name gt lt element1l gt lt object2 element1 value gt lt element2 gt lt object2 element2 value gt xy lt object2 element3 type gt lt object2 name gt In this definition the first two elements of the sequence would use the equivalent C or C type as defined in the fixed type field in the information object This is the same as in the legacy model The open type field
60. aE ss eda ph estes wee sta EEE eedndal tesa weeedabeuce ier od 279 Generated Copy Functions erosa e a vee de shee geee ps tenes oy oan E EAS dosppswaasent een deeb sete gs 280 Generated Test Functions oi u csicecssessedek pnencu oievon cd ede rE ov ouee ges Saari sb E ER oven ee E abees 282 20 Event Handler Interface irren a cordate dss chao AS a bea Men eanenteon dade choedueneroeednadsersacnsneess 284 How 1 Works nare rein E E E E A E EENE ENERE E tip oeeoed ep retel need es 284 HOW 10 O AREE EA E E AE E E AEA tone nee AAE AE OS EAEE nets 285 21 IMPORT EXPORT Of Typi Sen a R a a E EE N 292 vii ASNIC 22 ROSE and SNMP Macro Support uo c s s5 sde edorsseeacees a RER OEE RE EPEAN EEES SES EEVEE ERASE 293 ROSE OPERATION and ERROR srn en e a des ade dah E O R os EEN OTEA ae 293 SNMP OBJECTATY PB visera se Seve e a a a E Aa E a A E E N ARE RASE 296 A ASNO POT O OE S T r ar a E eaten N E r E 297 Code Generation Errot Mess tes sirene yenes E eaaa ty E E S EE E ERE Toe 297 General Runtime Error Messages isi s gccuscse fu vsaty oo o E E cade AE 299 ASN 1 specific Status Messages Vili List of Tables 16 1 CSN 1 Operations from highest to lowest precedence 2 0 0 0 cece cece eee cence eeceeecaeeeaeeee eeu eeueeeneeennees 249 1X List of Examples 18 1 18 2 18 3 18 4 18 5 18 6 MAIN CSIDL Hors NS EE TE EAE E aawie se apatobensetndeden manta dasseminsn oe E E E E tess tea E A 267 Mamas mI ic ors
61. and is also an unlabeled non truncated concatenation then concat inner is replaced in concat outer by its operands The requirement that concat inner be unlabeled is so that all possible semantic information is carried over into the ASN 1 The requirement that concat outer be unlabeled is probably not really necessary and could be taken up for futher study For each operand that is an Intersection do the following Repeat these steps until any Intersections that remain require no additional action a Invoke the Intersection Analysis procedure on the Intersection b If the Intersection has a length determinant do the following i Verify that the Intersection is the final operand in the Concatenation This limitiation is motivated by the internal working of our code generator relative to length constrained content ii If the Intersection s constrained operand is a Concatenation replace the Intersection with the operands of that Concatenation Otherwise replace the Intersection with the constrained operand c Otherwise the Intersection does not have a length determinant no additional action is required Do the following for each of the operands of the Concatenation in order The purpose of this step is to determine the ASN 1 type or ASN 1 component that each operand maps to or whether the operand instead represents either padding or a literal bit string If an operand does not do any of these it is an error Note if the Alter
62. 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 ASN1T_ lt type gt func2 ASNIT_ lt type gt p new ASNIT_ lt type gt ASNIBERDecodeBuffer decbuf ASN1C_ lt type gt 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 ASN1T_ lt type gt 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 ASN1C compiler designates types that are not referenced by any 147 Memory Management in C C 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 ASN1TPDU base class This class holds a reference to a context object The
63. 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 lt lt and gt gt stream operators can be used as well 127 Generated Encode Decode Function and Methods 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 ASN1CType base class can be used with this construction form to encode and decode to the associated buffer The constructor arguments are a reference to an ASN1MessageBufferlF 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 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 ASN C_ 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 constru
64. be passed using a pointer argument If XER encoding is specified function prototypes are generated with the following format int asnlXE_ lt ProdName gt OSCTXT pctxt lt ProdName gt value const char elemName const char attributes int asnlXD_ lt ProdName gt OSCTXT 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 attributes 126 Generated Encode Decode Function and Methods that 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 If XML functions are generated using the xml switch the function prototypes are as follows int XmlEnc_ lt ProdName gt OSCTXT pctxt lt ProdName gt value const OSUTF8CHAR elemName const OSUTF8CHAR nsPrefix int XmlDec_ lt ProdName gt OSCTXT pctxt lt ProdName gt pvalue In this case the encode function contains an argument for XML element name e emName and also namespace prefix nsPrefix 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 Un
65. be tuned by setting the default memory heap block size The way memory management works is that a large block of memory is allocated up front on the first memory management call This block is then subdivided on subsequent calls until the memory is used up A new block is then started 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 To set the block size the following run time function should be used void rtxMemSetDefB1lkSize OSUINT32 b1kSize This function must be called prior to context initialization 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 control class constructor its reference count 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
66. 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 ASN C_prefix to the production name to form the class name Most generated classes are derived from the standard ASN CType base class defined in asn1 Message h The following ASN 1 types cause code to be generated from different base classes BIT STRING The generated control class is derived from the ASNI CBitStr class SEQUENCE OF or SET OF with linked list storage The generated control class is derived from the ASN1ICSeqOfList base class 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 generat
67. by specifying module production and element in an XML hierarchy An example of this is as follows lt asnilconfig gt lt module name TS24008IES gt lt production name BackupBearerCapOctetGroup5 gt lt element name octet5a gt lt end3GExtElem name octet5 ext gt lt element gt lt production gt lt module gt lt asniconfig gt At the outer level of the markup is the lt asniconfig gt lt asnlconfig gt 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 lt storage gt 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 19 Using the Compiler 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 asn1lconfig 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 lt module name MyModule gt Other attributes specified within the lt module gt section apply only to that module and not to other modules specified within the specification A complete list of all module attributes is provided
68. call returned error RTERR_ATTRFIXEDV AL Attribute fixed value mismatch The attribute contained a value that was different than the fixed value defined in the schema for the attribute 303 ASNIC Error Codes Error Code Error Name Description 50 RTERR_MULTIPLE RTERR_NOTYPEINFO Multiple errors occurred during an encode or decode operation See the error list within the context structure for a full list of all errors This error is returned when decoding a derived type definition and no information exists as to what type of data is in the element content When decoding XML this normally means that an xsi type attribute was not found identifying the type of content RTERR_ADDRINUSE Address already in use This status code is returned when an attempt is made to bind a socket to an address that is already in use RTERR_CONNRESET Remote connection was reset This status code is returned when the connection is reset by the remote host via explicit command or a crash RTERR_UNREACHABLE RTERR_NOCONN Network failure This status code is returned when the network or host is down or otherwise unreachable Not connected This status code is returned when an Operation is issued on an unconnected socket RTERR_CONNREFUSED Connection refused This status code is returned when an attempt to communicate on an open socket is refused by the host RTERR_INVSOCKOPT
69. configuration items see the Compiler Configuration File section for more details Previous versions of ASNIC did not generate unique names by default The compiler option uniquenames has been deprecated in favor of nouniquenames O lt directory gt This option is used to specify the name of a directory to which all of the generated files will be written objdir lt directory gt This option is used in conjunction with the genMake option to specify the name of the object file directory to be added to the makefile Compiled object files will be output to this directory prjdir lt directory gt This option is used to create an automatic project directory structure If no other directories are specified on the command line sane defaults are chosen for generated libraries lib binaries bin sources src and objects obj This may be useful for those who want a well defined logical structure to their output without code generation and build artifacts in the top level directory oh 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 oer None This option is used to generate encode decode functions that implement the Octet Encoding Rules OER as specified in the NTCIP 1102 2004 standard Currently only the C language is supported param lt name gt lt value gt This option is used to instantiate all parameterized types wit
70. const OSUTF8CHAR lt name gt _ToString OSINT32 value int lt name gt _ToEnum OSCTXT pctxt const OSUTF8CHAR value lt name gt pvalue 61 ASN 1 To C C Mappings The first function would be used to convert an enumerated value into string form The second would do the opposite convert from string to enumerated C Mapping ASN 1 production lt name gt ENUMERATED lt idl gt lt vall gt lt id2 gt lt val2 gt Generated code struct lt name gt enum Root idl vall id2 val2 enum Ext extidl extvall typedef OSUINT32 ASN1T_ lt name gt 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 ensu
71. 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 ASN1C_ lt Type gt 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 Filename Description 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 generated 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 ASNJC_ lt Type gt a
72. 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 uper None This option is used to specify the generation of code to support the unaligend variant of the Packed Encoding Rules PER This provides for slightly more compact code than the per option because alignment checks are removed from the generated code use enum types None This option is used to specify that generated enumerated types are to be used directly in the code as opposed to integer types The advantages of integer types are a they are of a known size and b they can store unknown identifiers that may be received for extensible enumerated types However the direct use of enumerated types makes it easier to inspect variables using the debugger in various IDE s usepdu lt PDU type name gt This option is used to specify the name of the Protocol Data Unit PDU type to be used in generated reader and writer programs 15 Using the Compiler Option Argument Description vcproj This option is used to generate Visual C or Visual vc6 Studio compatible project files to compile generated 2003 source code This is a Windows only option By passing 2005 one of the listed years the compiler will generate a project 2008 that links against libraries provided for those versions o
73. 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 143 Chapter 8 Memory Management in C C This chapter describes ASN1C s memory manager Users are encouraged to read this chapter when they need to replace ASNIC s memory manager or wish to have a deeper understanding of how memory is managed by the runtime context structure Dynamic memory is managed by ASNIC to improve the overall performance of encoding and decoding procedures and understanding this management is imperative to avoiding memory problems in applications ASN1C also supports replacing the memory manager with user written objects at two levels the high level API called by the generated code and the low level API that provides the core memory functionality The ASN1C Default Memory Manager The default ASN1C run time memory manager uses an algorithm called the
74. ede VEST OS WIN Se EO a tA oe ECE LISS ies Oe EEN OIE Ea oie OA Sete 267 COMMMON CSti ll 2 siete ect conn dee ne cia camer r ee cae nen ou aanea cere mama ace contin tere nt eames 268 COMMON ASTI EEE EE EEE E AEE ood edela pecbond Wisk cbela EO EE cheb EEEO 268 CSN Example cnini en a tests sas batho cates ciss E A a E yatnagises bane etn satis sok bat aaRS 271 The resultng A SNe Iaeiae roir E E E IEE A EE dies gees Saud EEIT engin ie deree SNE 272 Chapter 1 Overview of ASN1C The ASNIC code generation tool translates an Abstract Syntax Notation 1 ASN 1 or XML Schema Definitions XSD 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 s Manual discusses the Java code generation capability The ASN C C User s Manual discusses 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 T
75. 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 286 Event Handler Interface void PrintHandler endElement const char name int index mindentLevel indent printf n 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 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 event 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 RER 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 t
76. encode and decode the variable correctly 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 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 60 ASN 1 To C C Mappings ASN 1 production ENUMERATED lt idl gt lt vall gt lt id2 gt lt val2 gt lt name gt Generated code typedef enum idl vall id2 val2 lt name gt _Root typedef OSUINT32 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 n
77. et 246 CSN DT Eexical Items wrens eenaa e o e edhe sen a E sum dss etea weeny sutacsey necebe eh AAE ds Seeduedy E Er S 246 Literals saries hs petvesiives tala dosage RO E S A a ER ERENS 246 vi ASNIC NAMES EE ANE E N A stops EE E E seven pos veregber teh Soteh euauhe ENE EEP EEE E 246 Mod le a e E T E A E A E a N O r E E EN 247 Lab ls and Referentes enet eevee dna deco e A doe tevok hee beue canta at ce we gaande veh heateanaeeaceuetncs os 247 Basics trie cic acd ota earners EE tela re peat cant Nos a E set weatiuuvce ot voaiSeen EN ERSS 248 CONUS int 55 Seeders swansisn ten a fee a een ates eimecedy navevey sade op teegeepe masse hyadsyes suaai ens Sen test 249 Alteration annenin Sask ede eg oe taeda dae Sos edad Sabha nag oe Nu conde ue ad ea ons ned ed otea wea ne eased N Som A 249 CONnCALEMALION sienen ken see a emer eye hecdeb a vest hams dee saemenoutaaadcetetonciees hac geben overt benatenn aes 249 Bxponents EEE A err dsce tet ccs eit oi Poke eek oe dt aN ea tart a ite eT tate 250 BXCIUSION Gy dscheensace e e cornea be neteeenuess abate A eheed Sc ee temeeenvedegboee E OANE ns TE ES 251 IMTS CHION seen eea te ace A vee behing veces Urvncepeh bbw cub an eewaced onducs Guy aed peneea Gest NO eens E Aia 251 Send EXpressiOneiacosssssassseueisenssvhedss save gnesquwelaastaue a a Aver davegive taredons luce o E sonvanchoeredacstene dies 251 Subclass EX pressions ed 308 wesgs Se acd itageece ain este ead es deca eee Seg Atl
78. 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 mIndentLevel 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 simplified 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
79. 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 Configuration File section cppns lt namespace gt This option is used to add a C namespace name to generated C files depends None This option is used 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 is used to generate encode decode functions that implement the Distinguished Encoding Rules DER as specified in the X 690 ASN 1 standard dll None When used in conjunction with the genMake command line option the generated makefile uses dynamically linked libraries DLLs in Windows or so files in UNIX instead of statically linked libraries dynamicArray none This option specifies that a dynamic array type is to be used for SEQUENCE OF SET OF constructs genbuild None This option is used to generate a build script when producing Java source code The generated build script is either a batch file Windows or a shell script UNIX 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
80. for list of java files getset generate get set methods and protected member vars Using the Compiler noevents disable generation of event handler code Also disables element tracking for error handling pkgname lt text gt Java package name pkgpfx lt text gt Java package prefix tables generate table constraint functions genmetadata generate methods for accessing ASN 1 meta data like value range constraints and optional elements C options nspfx lt text gt C namespace prefix namespace lt text gt C namespace name dirs output C code to module name dirs csfile lt filename gt generate one cs file or one per module cs gencssources generate lt modulename gt mk for list of C files genMake generate makefile to build generated cod tables generate table constraint functions vcproj version generate Visual Studio C project files version is 2012 2010 default 2008 2005 Windows only genmetadata generate methods for accessing ASN 1 meta data like value range constraints and optional elements XSD options appinfo lt items gt generate appInfo for ASN 1 items lt items gt can be tags enum and or ext ex appinfo tags enum ext default all if lt items gt not given attrs lt items gt generate non native attributes for lt items gt lt items gt is same as for appinfo targetns lt namespace gt Specify target namespace lt nam
81. fully encoded messag 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 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 fragment illustrates PER encoding using a dynamic buffer include employee h include file generated by ASNIC main OSOCTET msgptr int msglen stat OSBOOL aligned TRU GI 189 Generated PER Functions Create an instance of the compiler generated class This example does dynamic encoding no message buffer is specified ASN1PEREncodeBuffer encodeBuffer aligned ASN1T_PersonnelRecord msgData ASN1C_PersonnelRecord employ encodeBuffer msgData Populate msgData within the class variable msgData name givenName SMITH E
82. generated structures for types that use table constraints are different than when table constraint code generation is not enabled These differences will be pointed out There are two models currently supported for table contraint generation Unions and Legacy These are documented in the following sections Unions Table Constraint Model The unions table constraint model originated from common patterns used in a series of ASN 1 specifications in use in 3rd Generation Partnership Project GPP standards These standards include Node Application Part B NBAP Radio Access Network Application Part RANAP and Radio Network Subsystem Application Part RNSAP in the current 3G network and in S1AP and X2AP protocols in the newer 4G network LTE standards This model was later extended to generate these type of structures for other specifications that made use of table constraints including security and legacy telecom speifications Generated C Type Definitions for Message Types The standard message type used by many specifications that employ table constraints is usually a SEQUENCE type with elements that use a relational table constraint that uses fixed type and type fields The general form is as follows lt Type gt SEQUENCE lt elementl gt lt Class gt amp lt fixed type field gt lt ObjectSet gt lt element2 gt lt Class gt amp lt fixed type field gt lt ObjectSet gt element1 lt element3 gt lt Class gt
83. gt imperative part 3GPP layer 3 message These are optional elements with single byte tags The tag is the IEI hex value specified at the value of the item The format attribute specifies if the item is a tag t tag value tv or tag length value tlv The length attribute is only required if format if tv to specify the length of the value This item is only supported for C 3GPP layer 3 code generation lt inline gt n a This item is used to indicate that code generated for a nested item within a constructed type should be expanded inline rather than pulled out to create a separate new type lt is3GExtList pre eol 0I1 n a This item specifies that this element will be modelled as a post eol 0I1 gt 3G extended list This can only be applied to elements of type SEQUENCE OF It is used in 3G layer 3 messages when the extension of a repeating type is controlled by an extension bit that occurs either before or after the record If the pre eol attribute short for preceding end of list is specified it indicate a bit before the record signals whether another record follows The value 0 or 1 indicates which bit value signal end of list The post eol attribute is the same except that it indicates the control bit follows after the record This item is only supported for C 3GPP layer 3 code generation lt is3GLength n a This item is used to mark an element as a 3GPP length bitFieldSize nbits field element Normally this an el
84. have to know your position relative to the start of the entire encoding Names CSN 1 complicates names by allowing many symbols to appear in names e g including even spaces Without some additional rules this can create ambiguities We didn t have access to a formal specification so we invented some rules We define three kinds of names IDENTIFIER An identifier is used as a function name It must begin with an alphabetic character then may be followed by any number of alphanumerics or underscores BASIC_NAME A basic name is just that basic It consists of alphanumeric underscore and space characters It may not begin or end with a space Additionally the characters 0 1 L and H are excluded because of their use as literals and potential ambiguities 246 CSN 1 Described EXTENDED_NAMEAn extended name allows for an extended set of characters compared to BASIC_NAME In fact vores it allows any character except for lt gt and It must begin and end with a non space character There are two places where an EXTENDED_NAME may appear e as the argument for a function in an exponent mre e inside angle brackets after the lt and before any or gt character Every BASIC_NAME is also an EXTENDED_NAME When the grammar calls for an EXTENDED_NAME any name that is also a BASIC_NAME is valid Module CSN 1 does not have the notion of a module We have introduced
85. header file define ASN1V_ivalue 5 83 ASN 1 To C C Mappings The reason the ASN1V_ prefix is added is to prevent collisions with INTEGER value declarations and other declarations such as enumeration items with the same name REAL Value The REAL type causes a define statement to be generated in the header file of the form ASN1V_ lt valueName gt where lt valueName gt would be replaced with the name in the ASN 1 source file By generating def ine statements the symbolic names can be included in the source code making it easier to adjust the boundary values This mapping is defined as follows ASN 1 production lt name gt REAL lt value gt Generated code define ASN1V_ lt name gt lt value gt For example the following declaration rvalue REAL 5 5 will cause the following statement to be added to the generated header file define ASN1V_rvalue 5 5 The reason the ASN1V_ 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 Binary and hexadecimal string value specifications cause two global C variables to be generated a numoct s var
86. information object specification The C class also contains virtual methods representing each of the type fields within the ASN 1 class specification If the 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 OSCTXT pctxt ASNITObject amp object return 0 virtual int decode lt ER gt lt FieldName gt OSCTXT pctxt ASN1ITObject amp object return 0 virtual void print lt FieldName gt ASN1ConstCharPtr name ASN1ITObject amp object For an Object Field class lt ClassName gt lt FieldName gt In each of these definitions lt FieldName gt would be replaced with t
87. 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 Tag value constant Choice tag constants CHOICE type only Named bit number constants BIT STRING type only Enumerated type option values ENUMERATED or INTEGER type only C type definition Encode function prototype Decode function prototype Other function prototypes depending on selected options for example print C control class definition C only A sample section from a C header file is as follows ROR KR KKK KK KR KI RR RK I OR RK EmployeeNumber oh fF ROR KR KKK KK OK RK RR RK I OR OR KK define TV_EmployeeNumber TM_APPL TM_PRIM 2 typedef OSINT32 m mployeeNumber EXTERN int asnlE_EmployeeNumber OSCTXT pctxt EmployeeNumber pvalue ASN1TagType tagging EXTERN int asnlD_EmployeeNumber OSCTXT 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 The following line 115 Gen
88. is a minimal format for exchanging data In version 6 6 ASNIC introduces the capability of targeting JSON for encoding and decoding This marries a well known simple text format JSON with a robust and mature schema language ASN 1 and provides a possible interchange between JSON and ASN 1 binary formats like BER or PER To generate encoding and decoding functions use the json switch on the command line or select the appropriate option in the GUI The following sections describe the generated encoding and decoding functions Descriptions of the JSON run time functions may be found in our C JSON Runtime Library Reference Manual C classes are described in the C JSON Runtime Libarary Reference Manual Generated JSON Encode Functions Generated C Function Format and Calling Parameters The format of the name of each generated encode function is as follows asnlJsonEnc_ 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 follows stat asnlJsonEnc_ lt name gt OSCTXT pctxt lt name gt pvalue In this definit
89. 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 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 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 nsPrefix arguments are used to pass the XML element name and namespace prefix respectively The two arguments are combined to form a qualified name QName of the form lt nsPrefix elemName gt If elemName is null or empty then no element tag is added to the encoded content If nsPrefix is null or empty the element name is applied as a local name only without a prefix The function result variable st at returns the status of the encode operation Status code zero indicates the function was successful A negative value indicates encoding failed Return status values are defined in the rtxErrCode
90. kit Generated C Encoding Methods Generated C decoding methods use the control classes and the OSJSONDecodeBuffer and OSJSONInput St ream classes to accomplish decoding as in the following code snippet 238 Generated JavaScript Object Notation JSON Functions OSJSONDecodeBuffer encodeBuffer filename decodeBuffer setDiag verbose ASN1T_PersonnelRecord msgData ASN1C_PersonnelRecord employ decodeBuffer msgData Populate structure of generated type here Decode if stat employee Decode 0 if trace printf Encoding was successful n printf s n const char decodeBuffer getMsgPtr The generated control class ASN1C_PersonnelRecord contains methods for encoding Encode It unites the message data held in ASN1T_PersonnelRecord and the encoding buffer OSTSONEncodeBuf fer to encode the JSON message Decoding a Series of Messages using the C Control Class Decoding a series of messages is virtually identical in the C case as it is with C FOR pep A stat employee Decode if stat 0 decoding was successful else error handling decodeBuffer init The major difference in this case is that the init method is called at the end of the loop rather than the C runtime function rtxMemReset The init method serves the same purpose 239 Chapter 15 Generated 3GPP Layer 3 3GL3 Functions Generated 3GPP Lay
91. library function rt xMemF ree should be called to free the allocated memory A program fragment that could be used to decode a simple PDU type follows 237 Generated JavaScript Object Notation JSON Functions Init context structure if rtInitContext amp ctxt 0 printf Error initializing context n return 1 stat rtxStreamFileCreateReader amp ctxt filename if stat 0 printf Unable to open s for reading n filename rtxErrPrint amp ctxt rtFreeContext amp ctxt return stat rtxSetDiag amp ctxt verbose Decode asnlInit_PersonnelRecord amp employee stat asnlJsonDec_PersonnelRecord amp ctxt amp employee This example follows the employee sample in the distribution kit Decoding a Series of Messages Using the C Decode Functions Decoding a series of messages is very similar to the method used for other encoding rules Short pseudo code is shown below As in the encoding example rt xMemReset is used at the end of the loop to avoid allocating new memory for dynamic data structures This helps to improve performance initialize context et c for initialize data structure call asnlJsonDec_ lt name gt function perform operations on decoded structure reset memory stat rtxMemReset amp ctxt More details may be found in the sample programs included in the ASN1C software development
92. 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 ASN1T_ 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 prefix text This is used to specify a prefix that will be applied to enumPrefix gt 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 valuePrefix gt lt prefix text This is used to specify a prefix that will be applied to valuePrefix gt all generated 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 lt prefix text This is used to specify a prefix that will be applied to classPrefix gt all generated items in a module derived from an ASN 1 CLASS definition lt objectPrefix gt lt prefix text This is used to specify a prefix that will be applied to objectPrefix gt all generated items in a module derived from an ASN 1 Informatio
93. 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 is 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 using calls to the rtxMemAlloc function If C is used cpp option is specified and PDU generation is not disabled lt noPDU gt config option is not used then the control class ASN1C_ lt name gt 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 ASN1C_ lt name gt ASN1C_ lt name gt amp orginal For example ASN1C_PersonnelRecord ASN1C_PersonnelRecord original 280 Additional Generated Functions e A getCopy method that creates a copy of the ASN T_ lt name gt variable ASNIT_ lt name gt amp getCopy ASN1T_ lt name gt pDstData 0 For example ASN1T_PersonnelRecord amp getCopy ASN1IT_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 rtxMemAlloc function e A newCopy
94. 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 Compiler Configuration File In addition to command line options configuration commands can be used to apply specific compiler options to specific items within a schema These options can be applied to specific modules productions and elements as well as globally Configuration items may be specified in one or two ways or a combination of both e Using special comments embedded directly in an ASN 1 file or e Using an external XML configuration file A simple form of XML is used as the format for the configuration items XML 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 In the case of embeddeding directives directly in the ASN 1 source file the directive is included as a comment directly before the item to which it is to be applied For example BackupBearerCapOctetGroup5 SEQUENCE octet5 BearerCapOctet5 lt end3GExtElem name octet5 ext gt octet5a BearerCapOctet5a 7 na In this case the end3GExtElem configuration item would be applied to the octet 5a element An external configuration file would target the item to which the directive is to be applied
95. msgbuf 1024 ASN1TAG msgtag int msglen OSCTXT ctxt Invoke invoke ASN1OBJID oid1 f sap Ae O eb Te FF ASN1OBJID oid2 3 0 1 2 logic to read message into msgbuf Step 1 Initialize a context variable for decoding if rtInitContext amp ctxt 0 initialization failed could be a license problem printf context initialization failed check license n return 1 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 ASNI1EXPL 0 Step 4 Check return status if status 0 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 o0id2 0 argument is an INTEGER OSINT32 arg OSINT32 msgData argument decoded Remember to release dynamic memory when done ASNIMEMFREE amp ctxt 7 else error processing 140 Generated Encode Decode Function and Methods 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 en
96. msgptr int iy len stats const char filename message dat Populate employee C structure asnlInit_PersonnelRecord amp employee mployee name givenName SMITH Initialize context stat rtInitContext amp ctxt if stat 0 printf rtInitContext failed check license n rtxErrPrint amp ctxt return stat Create memory output stream stat rtxStreamMemoryCreateWriter amp ctxt 0 0 if stat lt 0 printf Create memory output stream failed n 199 Generated Octet Encoding Rules OER Functions rtxErrPrint amp ctxt rtFreeContext amp ctxt return stat Encode stat OEREnc_PersonnelRecord amp ctxt amp employee msgptr rtxStreamMemoryGetBuffer amp ctxt amp len if trace printf Hex dump of encoded record n rtxHexDump msgptr len 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 The use of streams is a good alternative for large messages as the entire encoded message does not need to fit into memory G
97. myExtendedType u MyType_derivations The derivations type is a choice between the base type and all derivations of that base type It will be used wherever the base type is referenced This makes it possible to use an instance of the extended type in these places The case of restriction is handled in a similar fashion In this case instead of creating a new type with additional elements a new type is created with all restrictions implemented This type may be identical to the base type definition Substitution Groups A substitution group is similar to a complex content type in that it allows derivations from a common base In this case however the base is an XSD element and the substitution group allows any of a set of elements defined to be in the group to be used in the place of the base element A simple example of this is as follows lt xsd element name MyElement type MyType gt lt xsd complexType name MyType gt lt xsd sequence gt lt xsd element ref MyBaseElement gt lt xsd sequence gt lt xsd complexType gt lt xsd element name MyBaseElement type xsd string gt lt xsd element name MyExtendedElement type xsd string substitutionGroup MyBaseElemen In this case the global element MyElement references MyType which is defined as a sequence with a single element reference to MyBaseElement MyBaseElement is the head element in a substitution group that also includes MyExtendedEl
98. 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 status OEBREnc_ lt name gt OSCTXT pctxt lt name gt value In this definition lt name gt denotes the prefixed production name defined above The pct xt 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 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 st at returns the status of the enc
99. occur on the compiler back end as the code is 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 soa search can be done for this string in order to find 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 30 Chapter 3 ASN1C GUI Users Guide Copyright 2015 Objective Systems Inc Quick Start In this section we will demonstrate running ACGUI creating a new ASN 1 schema and compiling it to C for BER data The process is similar for other languages First start ACGUI Once the program is running we ll create a new project to store all of our settings To do this select Project gt New Project from the menus 31 ASNIC GUI Users Guide Output Function Generation Constraints and Debugging Code Modifications Build Options Application Language Type None fe E C C C C Ct java F Target C 11 F Target Java 1 4 Targ l Generate HTML files for input ASN 1 Generate equivalent XML schema M Pretty print ASN 1 Additional Translations Encoding Rules fn CEA f DER l PER M JSON M XER M XML F MOER T F BER Output Directors Input Options Perform a lax synta
100. 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 function into a separate file This allows the linker to link in only the required functions as opposed to all functions in acompiled object module This option might be useful for applications that have minimal space requirements for example embedded systems 118 Generated C C Source Code 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 application program 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 makefile that will compile each of the generated files and add them
101. 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 Asn TOpenType for C and the following additional function is generated EXTERN int asnlD_Identifier_id_OpenType OSCTXT pctxt OSINT32 pvalue In the Identifier decode function element id is decoded as an open type Generated BER Streaming Decode Functions BER messages can be directly read and decoded from an input stream such as a file network or memory stream using BER streaming decode functions The ASN1C 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 streaming 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 msgData component of the class 176 Generated BER Functions 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
102. 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 const OSOCTET msgptr OSOCTET msgbuf 1024 int msglen ASN1IBEREncodeBuffer encodeBuffer msgbuf sizeof msgbuf ASN1T_PersonnelRecord msgData ASN1C_PersonnelRecord employ encodeBuffer msgData Encode loop starts here this will repeatedly use the objects declared above to encode the messages for rea i logic here to read record from some source database flat file socket etc populate structure with data to sbe encoded msgData name SMITH invoke Encode method if msglen employee Encode gt 0 encoding successful get pointer to start of message smsgptr 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 157 Generated BER Functions encodeBuffer init Generated BER Streaming Enc
103. 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 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 0 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 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 OSCTXT pCtxt ASNI1CCB pCCB int stat
104. rtMemSetDefBlkSize can be called to change this size This takes a single argument the value to which the size should be changed 173 Generated BER Functions 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 changed by calling the rfMemSetAllocFuncs 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 r MemReset 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 other memory management functions can be found in the C C Common Run Time Library Reference M
105. rtxMemSetAllocFuncs OSMallocFunc malloc_func OSReallocFunc realloc_func OSFreeFunc free_func The malloc realloc and free functions must have the same prototype as the standard C functions Some systems do not have a realloc like function In this case realloc_func may be set to NULL This will cause the malloc_func free_func pair to be used to do reallocations This function must be called before the context initialization function rt InitContext because context initialization requires low level memory management facilities be in place in order to do its work Note that this function makes use of static global memory to hold the function definitions This type of memory is not available in all run time environments most notably Symbian In this case an alternative function is provided for setting the memory functions This function is rt xInitContextExt which must be called in place of the standard context initialization function rt InitContext In this case there is a bit more work required to initialize a context because the ASN 1 subcontext must be manually initialized This is an example of the code required to do this ER int stat rtxInitContextExt pctxt malloc_func realloc_func free_func if 0 stat Add ASN 1 error codes to global table 146 Memory Management in C C rtErrASNlInit Init ASN 1 info block stat rtCtxtInitASNlInfo pctxt Memory management can also
106. runtime These two styles of code generation had different encode and decode method signatures and used different XML parsing techniques SAX vs pull parser As of version 6 5 1 these have been merged together The old style of XER code generation has now been deprecated XER is now supported using the same style of code and the same runtime that was previously used for OSys XER and extended XER via direct XSD compilation Depending on the circumstances the generated code may support more than one set of encoding rules In these cases the OSASN1XER and OSXMLC1 4N flags set using rt xCt xt Set Flag are used to choose at runtime which encoding rules to follow OSASN1 XER should be set when using BASIC XER canonical XER or EXTENDED XER For canonical XER OSXMLC14N must also be set The table below describes the possibilities Note that you may use the xsd switch when generating XML encoders and decoders 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 Compiler Invocation What is Generated xer flag is used to compile ASN 1 without XER encoding Generated code supports BASIC XER canonical XER instructions and OSys XER Set the flags described above to choose the desired encoding at runtime Generated PDU methods will automati
107. s ValueField and Type is 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 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 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 Information Object 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 n
108. simply be the ERROR name 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 contained 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 OBJECTTYPE name So for the above definitions the following two C items would be generated typedef Counter32 udpInDatagrams_SYNTAX ASN1OBJID udpInDatagrams 8 1 3 6 1 2 1 7 1 Pg 296 Appendix A ASN1C Er
109. the general type The identifier shall be determined according to the rules in ASN 1 Identifier Assignment Define an ASN 1 component DC It s CSN 1 name is the general determinant s label name DC type is DT j Define a second ASN 1 component CC It does not have a CSN 1 name CC type is the CHOICE type created above If this procedure was invoked by the Concatenation mapping then this procdure produces two ASN 1 components namely DC and CC Otherwise this procedure was not invoked by the Concatentation mapping then this procedure produces an ASN 1 SEQUENCE type having two component types which are DC and CC These components shall be named according to the rules in ASN 1 Identifier Assignment The encoding of the SEQUENCE shall be the encoding of DC followed by the encoding of CC If and only if DC has the value given by the particular determinant the chosen alternative for CC shall correspond to the particular alternative The encoding of CC s CHOICE type shall be the encoding of the chosen alternative A decoder will use the previous rule and the encoded value of the DC component to determine which alternative is present in an encoding Determinants The alternatives in an alternation are divided into two parts a determinant and a remainder Determinants are literal bit strings used to signal which of the alternatives is encoded in an encoding This section describes how to determine the determinant a
110. 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 Note that the lt oid gt configuration item can be used to distinguish modules that have the same names but different object identifiers 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 Ay te B END oduleB DEFINITIONS BEGIN B INTEGER END This entire fragment of code would be present in a single ASN 1 source file 292 Chapter 22 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
111. this rule as a way to assist in the mapping of CSN 1 to ASN 1 Module ASNIMODULE asnl_typeReference DefinitionList DefinitionList DefinitionList Definition Definition Eal Definition lt EXTENDED_NAM rh Net CSNPSt ring ty The Module production makes up the entire content of a CSN 1 specification It allows the CSN 1 author to specify the ASN 1 module into which the CSN 1 shall be mapped The asnl_typeReference specifies the ASN 1 module name asnl_typeReference must be a valid ASN 1 typereference Definition defines a CSN 1 string and gives it a name allowing it to be used elsewhere by reference Labels and References Angle brackets are used both for labeling substrings as well as for referencing defined strings by name Eal LabelPrefix EXTENDED_NAM AngleBracketString lt LabelPrefix BASIC_NAME ExponentExpr Subclass gt lt LabelPrefix CSN1String gt lt EXTENDED_NAME ParenExponentOpt SubclassOpt gt 1 The first two alternatives specify a label for the string that follows A label may be used to communicate to readers the semantics of the labeled string A label name may also be used as a reference to the labeled string by using its name in exactly one place the argument for a function inside an exponent 2 The first and third alternatives constitute a reference to a defined string In the case of the f
112. 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 lt suffix gt _ lt prodname gt c where lt suffix gt depends on encoding rules and the function type encode decode free etc and 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 IA5String initial IA5String 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 asnlc employee asn c ber trac maxcfiles Running ASNIC with the maxcfiles option the following c files for this type would be generated for the Name type asn1lD_Name c asnlE_Name c 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 119 Generated C C Source Code lt moduleName gt
113. to decode both the header and payload data in one call The following are the basic steps in calling the PDU decode function 1 Prepare a context variable for decoding 2 Initialize the data structure to receive the decoded data 3 Call the PDU decode function to decode the message 4 Free the context after use of the decoded data is complete to free allocated memory structures Before a 3GL3 decode function can be called the user must first initialize a context block structure The context block is initialized by calling the rtInitContext function Only memory buffer based encoding is supported for 3GPP layer 3 because the message sizes are generally small normally less than 256 bytes To do memory based decoding the rtxInitContextBuffer function would be called The message to be decoded must reside in memory The arguments to this function would then specify the message buffer in which the data to be decoded exists The PDU variable that is to receive the decoded data must then be initialized This can be done by either initializing the variable to zero using memset or by calling the ASNIC generated initialization function The PDU decode function can then be called to decode the message If the return status indicates success 0 then the message will have been decoded into the PDU type variable The decode function may automatically allocate dynamic memory to hold variable length variables during the course of decoding This memor
114. to know if the structures are different and not concerned with the details The return value of the function is a Boolean value that is true if the variables are equal and false if they are not 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_ 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 t ypePrefix 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 asnlCopy_ lt name gt OSCTXT pctxt lt name gt pSrcValue lt name gt pDstValue In this definition
115. to remove ASCII output formattedHexDump or to use a single line hexstring static generate static elements not pointers stream generate stream based encode decode functions strict size strictly interpret size constraints table unions generate union structures for table constraints us num types use generated enum types in code instead of integers C C makefile project options genMake lt filename gt generate makefile to compile generated cod genMakeDLL lt filename gt generate makefile to build DLL genMakeLib lt filename gt generate makefile to build static library make lt filename gt same as genMake as described above nmake lt filename gt generate Windows nmake fil same as genMak w32 vcproj lt version gt generate Visual Studio project files lt version gt is 2013 2012 2010 default 2008 2005 2003 vc6 Windows only builddll generate makefile project to build DLL dll usedll generate makefile project to use DLL s mt generate makefile project to use multithreaded libs w32 generate code for Windows 32 bit O S default GNU w64 generate code for Windows 64 bit O S default GNU Java options compare generate comparison functions copy generate clone methods dirs output Java code to module name dirs genbuild generate build script genant generate ant build xml script genjsources generate lt modulename gt mk
116. 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 lt object gt genTestInstance where lt typeName gt is the ASNIT_ lt name gt type name of the generated type and lt object gt is an instance of the ASN1IC_ lt name gt 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 respectively These programs are generated using the genwriter and genreader command line switches 283 Chapter 20 Event Handler Interface The events command line switch causes hooks for user defined event handlers t
117. 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 elements 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 75 ASN 1 To C C Mappings An example of this can be found in the following production C CHOICE 0 INTEGER 1 CHOICE 0 INTEGER 1 BOOLEAN R Ct This will produce the following C code define T_C_aInt define T_C_aChoice define T_C_aInt_1l define T_C_aBool NO rRPN FR typedef struct ink ty union OSINT32 alInt struct int t union OSINT32 alInt OSBOOL aBool u aChoice C Note that _1 was appended to the second instance of T_C_aInt Developers must take care to ensure they are using the correct tag constant value when this happens Populating Generated Choice Structures Populating generated CHOICE structure
118. variable referenced in the msgData component of the class 164 Generated BER Functions Generated C Function Format and Calling Parameters The format of the name of each decode function generated is as follows asnlD_ 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 follows status asnlD_ lt name gt OSCTXT pctxt lt name gt pvalue ASNiTagType tagging int length In this definition lt name gt denotes the prefixed production name defined above The pct xt 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 rtInitContext 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
119. were mapped to If asnlobjects has more than one member OR if any of the members is an OPTIONAL ASN 1 component OR if there is only a single member and that member is an ASN 1 component and the last operand is mapped to padding then do the following a Construct a SEQUENCE type as follows This will be the type produced by this Concatenation procedure b Add a NamedType to the SEQUENCE for each of the operands that mapped to an ASN 1 type or ASN 1 component in order If any of the operands mapped were mapped to two components add them both just as if they were produced by two operands c The identifier for the NamedType shall be determined according to the rules in ASN 1 Identifier Assignment If the operand was mapped to an ASN 1 type that shall be the type for the NamedType Otherwise the operand was mapped to a component with an ASN 1 type which shall be used d If the ASN 1 item is a component and the procedure that created the ASN 1 component specified it should be optional then it shall be optional That procedure shall have specified how the presence or absence is represented in the encoding If that procedure specified that a DEFAULT value shall be specified then it shall be specified e If the Concatenation is truncated all of the components added to the SEQUENCE shall be OPTIONAL with the optionality determined by the container A decoder shall recognize the component as present as long as there are more bits in the en
120. with the xml xsd command line options lt hFile gt lt hFile gt C C header filename This is used to specify the name of a C C header file to be used to store generated definitions for the module By default the header file name is set to the ASN 1 name of the module with h appended to the end lt alias asnlname name codename name gt ASN 1 to computer language name mapping This item allows a name in the ASN 1 specification being compiled to be mapped to an alternate name in the generated computer language files The primary use is to allow shorter names to be used in places where a combination of names may be very long In this release the only names that can be used in the alias statement are information object set names Production Level These attributes can be applied at the production level by including them within a lt production gt section Name Values Description lt name gt production name This attribute identifies the production type to which this lt name gt section applies It is required lt addarg name name Argument name type and This item adds an argument to the generated C encode and type type func encodel decode gt function attributes specified using or decode function The name and C type of the argument are specified in the name and type attributes respectively The func attribute is optional and only required if the argu
121. word has some lowercase letters lowercase the first character of the name d Otherwise if the name does not begin with a lowercase letter it begins with a hyphen or digit prepend the character a to the result 3 This completes the procedure The name is a valid ASN 1 identifier The name character conversion procedure ensures the name consists of characters that are valid for an ASN 1 identifier or typereference The procedure is as follows 1 Convert any character that is not legal in an ASN 1 identifier into a hyphen 2 Replace any sequence of hyphen characters with a single hyhpen 3 If the name ends with a hyphen remove it It cannot end with multiple hyphens due to the previous step Mapping CSN 1 name to ASN 1 typereference A CSN 1 name is mapped to an ASN 1 typereference as follows 1 Apply the name character conversion procedure to the name see the section on mapping CSN 1 name to an ASN 1 identifier 2 If the name begins with a lowercase letter uppercase the first letter 3 Otherwise if the name does not begin with an uppercase letter it begins with a hyphen or digit then prepend the character A to the name This completes the procedure The name is a valid ASN 1 typereference ASN 1 Identifier Assignment This section covers how the identifier for an ASN 1 NamedType is assigned when creating the components of an ASN 1 SEQUENCE or CHOICE First we need to determine whether there is a CSN 1 nam
122. 0 O O construct ASN1C C generated class ASN1T_PersonnelRecord msgData m ASN1C_PersonnelRecord G3 step 3 encoded for msgData name step 4 out lt lt employee or employee populate operator to assig invo ploy msgData msgData structure with data to be his uses the generated assignment n a string note t SMITH ke lt lt operator or EncodeTo method T EncodeTo out can be used here step 5 fetch and check status if out getStatus 0 printf Encoding failed Status i n out getStatus out print return 1 if trace printf O ErrorInfo r Encoding was successful n 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 Streaming 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 of 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
123. 1String mapping procedure for the base string a If an ASN 1 type is produced let T be that type b Otherwise if an ASN 1 component is produced wrap it ina SEQUENCE and let T be the result c Otherwise if the procedure specified that the base string is a pad bit and the exponent is infinite the string is considered padding The calling procedure shall specify what to do with the padding or else it is an error d Otherwise if the procedure specified that the base string is a pad bit the exponent is a constant integer less than or equal to 32 and the pad bit is a one bit or zero bit not an L or H then this procedure produces type INTEGER 0 k where k 2 exponent 1 The calling procedure shall create a component for this type with DEFAULT j where j 0 if the pad bit is a zero bit and k otherwise The calling procedure shall specify that this component must be present in the encoding This is useful for dealing with so called spare bits The encoding for this type encodes the integer in binary in exponent bits Normally the default value should be encoded 263 Mapping CSN 1 to ASN 1 as that was the intention expressed in the CSN 1 pad bits originate from the SEND expression but a decoder may encounter any value e Otherwise if the base is a literal bit and the exponent is infinite the calling procedure shall either recognize this as part of an INTEGER type with count bits encoding or else it is an error f O
124. 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 production is a PDU the following would be specified in a production section lt isPDU gt 3 An attribute 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 lt include types TypeNamel TypeName2 TypeName3 gt 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 asnilconfig 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
125. 3 Populate the structure to b ncoded msgData opcode numids 3 msgData opcode subid 0 0 msgData opcode subid 1 1 msgData opcode subid 2 1 note opcode value is 0 1 1 so argument must be ASN1VisibleString type ASN1VisibleString argument objsys msgData argument decoded void amp argument Step 4 Call the generated encode function msglen asnlE_Invoke amp ctxt amp invoke ASN1EXPL Step 5 Check the return status note the test is gt 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 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 AsnI Object AsnITObject 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
126. 32 elementTwo OSXSDAny elem MyType As per the X 694 standard the element was given the standard element name elem XML Attribute Declarations XML attribute declarations in XSD are translated into ASN 1 elements that are added to a SEQUENCE type In binary encodings there is no way to tell encoded attributes apart from encoded elements They just represent data fields in ASN 1 For XML special logic is added to the generated XML encoders and decoders to encode and decode the items as attributes An example of an attribute being added to an xsd sequence declaration is as follows lt xsd complexType name Name gt lt xsd sequence gt lt xsd element name givenName type xsd string gt lt xsd element name initial type xsd string gt lt xsd element name familyName type xsd string gt lt xsd sequence gt lt xsd attribute name occupation type xsd string gt lt xsd complexType gt This results in the following C type definition being generated typedef struct EXTERN Name struct unsigned occupationPresent 1 m const OSUTF8CHAR occupation const OSUTF8CHAR givenName const OSUTF8CHAR initial const OSUTF8CHAR familyName Name The attribute is marked as optional hence the occupationPresent flag in the bit mask since XML attributes are optional by default The attribute declarations also occur before the element declarations in the generated structure Attributes ca
127. 8607 a fixed length octet str OCTET STRING SIZE 4 a var len octet str OCTET STRING SIZE 0 8388607 repeating optional component SEQUENCE SIZE 5 OF SE 10 Ci opt comp INTEGER 0 15 OPTIONAL Fy five pad bits INTEGER 0 31 DEFAULT 0 count bit encoding INTEGER 0 255 fixed num of typ SEQUENCE SIZE 5 OF Naming var num of type SEQUENCE SIZE 0 8388607 OF Naming Truncated Concat SEQUENCE el INTEGER 0 1 OPTIONAL component 2 SEQUENCE e2 INTEGER 0 3 e3 INTEGER 0 7 OPTIONAL e4 INTEGER 0 15 OPTIONAL 274 Chapter 19 Additional Generated Functions Generated Initialization Functions As of ASNIC version 6 0 initialization functions are automatically generated in previous versions it was necessary to use the genJnit option to force this action If for some reason a user does want initialization functions to be generated the nolnit switch can be used to turn initialization function generation off The use of 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 initializatio
128. ASN 1 types and or values values names gt are specified as an attribute list to be excluded in the generated code By default the compiler generates code for all types and values within 22 Using the Compiler Name Values Description 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 value referenced by another item the directive will be ignored lt storage gt lt storage gt One of the following keywords dynamic static list array dynamicArray std list std vector Std deque The definition is the same as for the global case except that the specified storage type will only be applied to generated C and C types from the given module lt sourceFile gt lt sourceFile gt source file name Indicates the given module is contained within the given ASN 1 source file This is used on IMPORTs to instruct the compiler where to look for imported definitions lt prefix gt lt prefix gt prefix text This is used to specify a general prefix that will be applied to all generated C and C names note for C types the prefix is applied after the standard ASN1T_ prefix This can be used to prevent name clashes if multiple modules are involved in a compilation and they all contain common names lt typePrefix gt
129. ASNIEXPL for EXPLICIT 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 asniltype h include file 150 Generated BER Functions 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 Streaming Encode Functions section Before any encode function can be called the user must first initialize an encoding context This is a variable of type OSCTXT 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 OSCTXT ctxt if rtInitContext amp ctxt 0 initialization failed could be a license problem printf context initialization failed check lice
130. 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 added 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 rtxMemFree run time function to free all memory at once that is held by a context Generated free functions allow finer grained Using the Compiler Option Argument Description control over memory freeing by just allowing the memory held for specific objects to be freed genMake lt filename gt This option instructs the compiler to generate a portable makefile for compiling the generated C or C
131. ECT IDENTIFIER params Params signature BIT STRING An example of a reference to this definition would be as follows 81 ASN 1 To C C Mappings SignedName SIGNED Name 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 ASN1OBJID algorithmOID Params params 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 when table constraint code generation is not enabled 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 ProtocollIE Field RANAP
132. EEEF 59 ENUMERATED 3 3s cs0 sosbostissedictas es batada states soveecuiann a E aeeteg aabene 60 NUD eE E hes Stes Ses Soe EPA REN RS REISE SA AE SEES 62 OBJECT IDENTIFIER esis fcc sedsecosscadecoacegs cupee EEEE RES a EETA E SEE proves siadosaass sevens 62 REL ATIVE OUD 335 s550055 tees esth ecg Soa esc oes bs Soe ek ode eas eek bas Maddie SEE EEI loca ces EOE AE EES ET iE 63 READ teree a a a petcg aie sath sa padlaas asthe bes batons ates ea a ea seems A tte bates 63 SEQUENCE oher oier e see tsetse er E eset ea sae as a a E e a a Masti 64 SET E EEE E E E sas etaeadssssteaseseases 69 SEQUENCE OF te 255 shed an e eanes lob era a a e E e a e i eai 69 SET OF r a tats tees E T T E E A TE E a E E E EE a 74 CHOICE oes E SS SGA ans EESTI OSs EE coe hos LN a Uns 74 OpenType EE ces i aoies nes spe ee sh oohasdy seo usesedeanus subeetd Sotae 77 Character String Typeset eS E EE aE E is bvenods E E EEE ES ESEE obets 78 Time Strine Types siii ee E a a saa E EE E A vente ss wets 79 EXTERNAL haho eret aa es wens eE EE VE ETE EVE E E OEA de ids EE ER E E OA E ES 80 EMBEDDED PDV peresa sisi ise doeccssssouisateesdeap ses PTER Noa PREE shoes dangsyateVigasSeardsseosisedsssmeasss het 80 Parameterized TypES e eren vesises bec ar EEE EEEE EEE E EEE EEE EEEE AE EERE EEN TESS 81 Value Mappings eisenos tei er e ebeetextadeaw E E woos ats diate ask Paden teases T aboohadn 82 BOOLEAN Vale sett erd Scat ote ttt eet EEEE Rees Some EO eta estes lente geet ee 83 INTEG
133. ER V alesse oc siSeacsicctesdiscrea davcisaess cuss casieciacssterseed OENE EE AAE ORES sere deveosassbassoaads 83 REAL Valle norih enen eos bain cerned slcebisig eeges i tecos is tone EEEE EEEE EEEE ee detentions 84 Enumerated Value Specification sssr sserrep E a EE T E aE eE 84 Binary and Hexadecimal String Value nseesesseesneeessserrsrrerrerrsrrrrsrrrrrsrrerrsrrerrsresrrererreerereee 84 Character String ValNera orekaren rE EES na EEEE EEEE EE SPEAR a VEIN EEE EEES EEES KPEE 85 Object Identifier Value Specification eesssesseesesstesrrrrsrrerrsrrerrererrrressrerrsrrerreresrereesreerrt 85 Constructed Type Valles prsia ai aa bas oagaedattg saa batins sas mead ses E EA e akon vas ates 85 Table Constraint Related Structures 2 0 0 0 ccc ccec cece cece cece ceca cena een eeeeeeeeceeeseeesaeeeaeeeaeeea sean sean eegs 88 Unions Table Constraint Model sess ssseck sss scons caseedssesscvecesgseudeauss sebte ads STREE sePosngseedeessssoobaags 88 lil ASNIC Legacy Table Constraint Model 20 3 yose oe ene es EE Ep ea deehpseaugsavber shes veen acess cen EA 94 So XSD to C CE Type Mappings sien nee ae o ies cdak Setar dus ade A based Uy ala E ede E A SE 103 ASD Simple Types sive seat sscsshudncsahosshes seu e a cases goes i sedges awsrgectscacebeGaeesteathes Ga chwetesedtaardenvens 103 XSD Complex Dy E castes than Sher A E Misc ealg Cie cedtareeiedin atest 104 RSS SCQUCNICE ea sec seicby Sete ss os ved ees ss aE
134. GetMsgLen ASN1XEREncodeBuffer is replaced by OSXMLEncodeBuffer If you used the three or four argument constructor for ASN1XEREncodeBuffer to specify canonical XER or open type encoding then you will now need to set a flag on the context using rtxCtxtSetFlag For canonical XER set OSXMLCI4N and also OSASN1XER For open type encoding set OSXMLFRAG to prevent encoding an XML prolog OSXMLEncodeBuffer does not have a lt lt operator Replace buffer lt lt myObject with myOb ject EncodeTo buffer Generated XER Decode Functions Old Style Deprecated Note As noted in the Overiew the style of generated code that is discussed here is now deprecated To upgrade to the new style see the section below for some upgrade tips The old style XER decode functions can still be generated by specifying the xer compat 649 or lower switches on the command line This ability may be removed in some future version of ASN1C so you are encouraged to upgrade to the new style 219 Generated XML Functions The code generated to decode XML messages is different than that of the other encoding rules This is because off theshelf 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 impl
135. IC uses a special type for these items OSXSDAny that allows for either binary or xml textual data to be stored This allows items to be stored in binary form if binary encoding rules are being used and XML text form if XML text encoding is used The definition of the OSXSDAny type is as follows typedef enum OSXSDAny_binary OSXSDAny_xmlText OSXSDAnyAlt typedef struct OSXSDAny OSXSDAnyAlt t union OSOpenType binary const OSUTF8CHAR xmlText ou OSXSDAny The t value is set to either OSXSDAny_binary or OSXSDAny_xmlText to identify the content type If binary decoding is being done BER DER CER or PER the decoder will populate the binary alternative element if XML decoding is being done the xml Text field is populated It is possible to perform XML to binary transcoding of a multi part message for example a SOAP message by decoding each part and then reencoding in binary form and switching the content type within this structure An example of a sequence with a single wildcard element is as follows lt xsd complexType name MyType gt lt xsd sequence gt lt xsd element name ElementOne type xsd string gt lt xsd element name ElementTwo type xsd int gt lt xsd any processContents lax gt lt xsd sequence gt lt xsd complexType gt 108 XSD to C C Type Mappings The generated C type definition is as follows typedef struct EXTERN MyType const OSUTF8CHAR elementOne OSINT
136. INPUT if stat 0 rtErrPrint amp ctxt errInfo return 1 Step 3 decode the record stat asnlXD_PersonnelRecord amp ctxt amp employee if stat 0 if trace printf Decode of PersonnelRecord was successful n printf Decoded record n asnlPrint_PersonnelRecord Employee amp employee else printf decode of PersonnelRecord failed n rtxErrPrint amp ctxt rtxStreamClose amp ctxt return 1 Step 4 Close the stream and free the context rtxStreamClose amp ctxt 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 the other encoding rules It is as follows 1 Instantiate an ASN 1 XER decode buffer object ASNIXERDecodeBuffer to describe the message to be decoded Constructors exist that allow an XML file or memory buffer to be specified as an input source 2 Instantiate an ASN1T_TypeName object to hold the decoded message data 3 Instantiate an ASN1C_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 223 Generated XML Functions 4 Invoke the ASN1C_TypeName object
137. ION amp operationCode argument OPERATION amp ArgumentType T 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 is 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 130 Generated Encode Decode Function and Methods a 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 contains an open type A
138. In the case of integers ASN1C will normally 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 For character string ASNIC will use a character string pointer char by default The chararray item can be used on strings with size constrains to specify a static character array variable be used lt enumPrefix gt enumPrefix gt lt 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 format gt lt format gt lt is3GExtList pre eol 0I1 post eol 0I1 gt base64 hex xmllist This is used to set format options specific to XER encoding The base64 or hex alternative is used to set the output format that binary data in OCTET STRING variables is displayed in in XML markup The xmllist alternative is used with SEQUENCE OF or SET OF types to denote that items should be displayed in XML space separated list format as opposed to a using a separate element for each list item This item specifies that this production will b
139. Invalid option This status code is returned when an invalid option is passed to socket RTERR_SOAPFAULT RTERR_MARKNOTSUP This error is returned when the decoded SOAP envelope is a fault message This error is returned when an attempt is made to mark a stream position on a stream type that does not support it RTERR_NOTSUPP Feature is not supported This status code is returned when a feature that is currently not supported is encountered RTERR_CODESETCONVFAIL This status code is returned when transcoding from one character set to another one for example from UTF 8 to UTF 16 and a conversion error occurs ASN 1 specific Status Messages The following table describes status messages that may arise during the course of encoding or decoding an ASN 1 message The errors below indicate that while the system was able to read the data successfully it was unable to decode it properly Error Code Error Name Description 2 ASN_OK_FRAG Fragment decode success status This is returned when decoding is successful but only a fragment of the item was decoded User should repeat the decode operation in order to fully decode message 100 ASN_E_BASE Error base ASN 1 specific errors start at this base number to distinguish them from common and other error types 304 ASNIC Error Codes Error Code Error Name Description 100 101 ASN_E_INVOBJID ASN_E_INVLEN
140. Mappings ASNICBitStr bs lt seqVar gt lt element gt bs set 0 In this example lt seqVar gt would represent a generated SEQUENCE variable type and lt element gt would represent a bit string element within this type See the section on the ASN CBitStr 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 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
141. N1T_ lt name gt ASN1T_ lt name gt OSUINT32 _numocts const OSOCTET _data j ASN1T_ lt name gt const char cstring assignment operators ASN1T_ lt name gt amp operator const char cstring ASNIT_ lt name gt If the strict size command line option is used the numocts component within this type definition may be of a different type OSUINTS8 or OSUINT16 or eliminated completely if the type is constrained to be a fixed size Contents Constraint It is possible to specify a contents constraint on an OCTET STRING type using the CONTAINING keyword This indicates that the encoded contents of the specified type should be packed within the OCTET STRING container An example of this type of constraint is as follows ContainingOS OCTET STRING CONTAINING INTEGER ASNIC will generate a type definition that references the type that is within the containing constraint In this case that would be INTEGER therefore the generated type definition would be as follows typedef OSINT32 ContainingOS The generated encoders and decoders would handle the extra packing and unpacking required to get this to and from an OCTET STRING container This direct use of the containing type can be suppressed through the use of the noContaining command line argument In this case a normal OCTET STRING type will be used and it will be the users responsibility to do the necessary packing and unpacking operations to
142. NIC will generate a C structure in this case with an element called base that is of the simple type being extended An example of this is as follows lt xsd complexType name SizeType gt lt xsd simpleContent gt lt xsd extension base xsd integer gt lt xsd attribute name system type xsd token gt lt xsd extension gt lt xsd simpleContent gt lt xsd complexType gt this results in the following generated C type definition typedef struct EXTERN SizeType struct unsigned system_Present 1 m const OSUTF8CHAR system_ OSINT32 base SizeType In this case the attribute system was added first note the name change to syst em_ which was the result of system being determined to be a C reserved word The base element is then added and is of type OSINT32 the default type used for xsd integer In the case of a simple content restriction the processing is similar A complete new separate type is generated even if the result of the restriction leaves the original type unaltered i e the restriction is handled by code within the generated encode and or decode function This proves to be a cleaner solution in most cases than trying to reuse the type being restricted For example lt xsd complexType name SmallSizeType gt lt xsd simpleContent gt lt xsd restriction base SizeType gt lt xsd miniInclusive value 2 gt lt xsd maxInclusive value 6 gt lt xsd attribute name system t
143. O 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 of the ASN 1 information object C objects in a static array 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 101 ASN 1 To C C Mappings 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 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 OSCTXT pctxt public ATTRIBUTE lookupObject ASN1TObjJId _id static SupportedAttributes instance OSCTXT pctxt a 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
144. OCTET STRING or BIT STRING type is inserted as was done in previous ASNIC versions nodecode None This option suppresses the generation of decode functions noencode None This option suppresses the generation of encode 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 it is known that an application only uses definite length encoding this option can result in a much smaller code base size noInit None This option is used to suppress the generation of initialization functions 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 actually is Note that previous versions of ASNIC did not generate initialization functions by default The gen nit switch has been deprecated in favor of nolnit noEnumConvert None This option suppresses the generation of utility functions in C and C that assist in converting enumerated values to strings and vice versa XER and XML encodings are unaffected by this option since co
145. ONAL 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 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 Xx INTEGER OPTIONAL AnInt OPTIONAL T In this case the following C typedef is generated typedef struct Aseq struct unsigned xPresent 1 unsigned anIntPresent 1 m OSINT32 x AnInt anInt Aseq When this structure is populated for encoding the developer must set the xPresent and 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 t
146. OSCTXT my ErrorHandler Also just as in C there can be only one error handler set at a time Example 4 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 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
147. 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 77 ASN 1 To C C Mappings 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 code generated is different In this case ASN OpenType above is replaced with ASN Object or ASNITObject for C This is defined in asnItype h as follows typedef struct generic table constraint value holder ASN10penTyp ncoded void decoded OSINT32 index table index ASN1Ob ject 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 a 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 If the table unions c
148. QUENCE OF production This results in the following two equivalent ASN 1 types GI A element SEQUENCE a INTEGER b BOOL AN A SEQUENCE OF A element These types are then converted into the equivalent C or C t ypede fs using the standard mapping that was previously described 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 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 followin
149. SN 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 ASN10OpenType argument The following would be the procedure to add the Invoke header type to an ASN 1 message body 1 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 Unions 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 operationCode My ops argument OPERATION amp ArgumentType My ops opcode
150. TET msgbuf 1024 ASNITAG msgtag int msglen stat OSCTXT 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 0 printf rtInitContext failed check license n rtErrPrint amp ctxt return stat 193 Generated PER Functions pu_setBuffer amp ctxt msgbuf msglen aligned step 2 initialize the data variable asnlInit_PersonnelRecord amp employee step 3 call the decode function stat asnlPD_PersonnelRecord amp ctxt amp employee if stat 0 process received data else error processing rtxErrPrint amp ctxt step 4 free the context rtFreeContext amp ctxt An input stream can be used instead of a memory buffer as the data source by replacing the pu_setBuffer call above with one of the rtxStream CreateReader functions to set up a file memory or socket stream as input Procedure for Using the C Control Class Decode Method The following are the steps are involved in decoding a PER message using the generated C class il Instantiate an ASN 1 PER decode buffer object ASNIPERDecodeBuffer 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
151. TF 8 character encoding This status code is returned by the decoder when an invalid sequence of bytes is detected in a UTF 8 character string 19 RTERR_OUTOFBND Array index out of bounds This status code is returned when an attempt is made to add something to an array and the given index is outside the defined bounds of the array 20 RTERR_INVPARAM Invalid parameter passed to a function of method This status code is returned by a function or method when it does an initial check on the values of parameters passed in If a parameter is found to not have a value in the expected range this error code is returned 21 RTERR_INVFORMAT Invalid value format This status code is returned when a value is received or passed into a function that is not in the expected format For example the time string parsing function expects a string in the form nn nn nn where n s are numbers If not in this format this error code is returned 22 RTERR_NOTINIT Context not initialized This status code is returned when the run time context structure OSCTXT is attempted to be used without having been initialized This can occur if rtxInitContext is not invoked to initialize a context variable before use in any other API call It can also occur is there is a license violation for example evaluation license expired 23 RTERR_TOOBIG Value will not fit in target variable This status is returned by the decoder when a target variable is not larg
152. Type gt configuration setting This setting causes the 175 Generated BER Functions ASNIC compiler to insert an Asn OpenType placeholder in place of the type that would have normally been used for the 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 asn1lD_ lt ProdName gt _ lt ElementName gt _OpenType OSCTXT pctxt lt ElementType gt pvalue Here lt ProdName gt is replaced with name of the type assignment and lt 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 is 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 modulename lt name gt lt
153. UE SI1AP ID ITY reject TYP ts Ha ndoverType In this case the name is formed by combining the information object set name with the name of each key field within the set Generated IE Append Function A user would need to allocate objects of this structure populate them and add them to the protocol IE list In order to make this easier helper functions are generated assist in adding information items to the list The general format of these append functions is as follows int asnlAppend_ lt ProtocollEsType gt _ lt KeyValueName gt OSCTXT pctxt lt ProtocollIEsType gt plist lt ValueType gt value In this definition lt ProtocollEsType gt refers to the main list type SEQUENCE OF defining the information element list lt KeyValueName gt is the name of the primary key field defined in the associated information object set lt ValueType gt is the type of the value for the indexed information object set item An example of this type of function from the S1AP definitions is as Append IE with value type MME_UE_S1AP_I a follows D to list mi D int asnlAppend_HandoverRequired_protocolIEs_id_MME_UE_S1AP_ID HandoverRequired_protocolIEs plist MM E_UE_S1AP_ID value Generated IE Get Function OSCTXT pctxt In addition to the list append function a second type of helper function is generated to make it easier to find an item
154. XER Run Time Library ASN1XER provides a common interface to other parsers via a common adapter interface layer There is a special XML interface object file for each of the following supported XML parsers rtXmlLibxml2IF interface to LIBXML2 e rtXmlXercesIF interface to XERCES e rtXmlExpatIF interface to EXPAT e rtXmlMicrolF interface to custom small footprint microparser 224 Generated XML Functions 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 is 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 ASN1XER 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 ASN1XER and ASNIRT dynamic libraries Tips for Upgrading to the New Style e XmlIDec_ lt Type gt _PDU methods can be used to replace asnl XD_ lt Type gt methods e Unlike the asnlXD_ lt Type gt methods the XmlDec_ lt Type gt methods do not match an outer start tag but begin by decoding the content of the type You must use rtXmlpMatchStartTag to match the outer start tag yourself
155. _ lt name gt functions one after another An example showing how to do this is as follows include employee h include file generated by ASNIC 160 Generated BER Functions int main int stat OSCTXT ctxt Employee employee typedef generated by ASNIC const char filename message dat Step 1 Initialize the context and stream if berStrmInitContext amp ctxt 0 initialization failed could be a license problem printf context initialization failed check license n return 1 stat rtxStreamFileCreateWriter amp ctxt filename if stat 0 rtxErrPrint amp ctxt return stat for 77 Step 2 Populate the structure to b ncoded mployee name SMITH Step 3 Call 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 0 e rror processing break Step 5 Close the stream rtxStreamClose amp ctxt Generated Streaming 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
156. _ApduType amp ctxt2 amp apdu Again a memory stream writer is used here for encoding but other options exist to write to a file or a socket Two phase Decoding Two phase decoding is the reverse operation of two phase encoding In this scenario a message is received and decoded The header and payload are contained in the message and the payload type and content must be decoded after the message is received This example shows how to decode the message encoded in the previous section As before some setup is required to perform the decode ApduType data OSCTXT ctxt OSBOOL trace TRUE verbose FALSE const char filename message dat int i stat Initialize context structure stat rtInitContext amp ctxt if stat 0 rtxErrPrint amp ctxt return stat rtxSetDiag amp ctxt verbose In this case the content is read from an input file so a file stream is created using rt xSt reamF ileCreateReader Thereafter the PDU data type is initialized using its initialization function and the message is decoded with the generated MDERDec function Create file input stream stat rtxStreamFileCreateReader amp ctxt filename if 0 stat rtxErrPrint amp ctxt rtFreeContext amp ctxt return stat asnlInit_ApduType amp data Call compiler generated decode function stat MDERDec_ApduType amp ctxt amp data if st
157. a 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 OSCTXT pctxt lt name gt pvalue ASN1TagType tagging In this definition lt name gt denotes the prefixed production name defined above The pct xt 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 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
158. a flag indicating whether aligned encoding was used or not Instantiate an ASN1T_ lt ProdName gt object to hold the decoded message data Instantiate an ASN1C_ lt ProdName gt 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_ lt ProdName gt object Decode method Check the return status The return value is a status value indicating whether decoding was successful or not Zero 0 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 is released when both the ASNJ PERDecodeBuffer and ASNIC_ lt ProdName gt objects go out of scope A program fragment that could be used to decode an employee record is as follows include employee h include file generated by ASN1C 194 Generated PER Functions main A stream can be used as the data input source instead of a memory buffer by creating an OSRT input stream object in step1 and associating it with the decodeBuffer object For example to read from a file input stream the decodeBuffer OSOCTET msgbuf 1024 int
159. a opcode oidl argument is a VisibleString ASN1VisibleString pArg ASN1VisibleString msgData argument decoded else if msgData opcode oid2 argument is an 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 Invoke example is as follows 139 Generated Encode Decode Function and Methods include TestTable h include file generated by ASNIC main OSOCTET
160. able of this type declared somewhere in his or her program The variable must be initialized using the berStrmInitContext 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 if decoding is successful or negative if an error occurs Return status values are defined in the rtvErrCodes h include file Procedure for Calling Streaming C Decode Functions This section describes the step by step procedure for calling a streaming 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 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 OSCTXT 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 berStrmInitCont
161. ace format As of release version 6 0 bractext is the default details was the default or only option in previous versions 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 option 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 some generated structures stream None This option is used 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 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 14 Using the Compiler Option Argument Description strict strict size None T
162. alized 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 The variable that is to receive the decoded data must then be initialized This can be done by either initializing the variable to zero using memset or by calling the ASNIC generated initialization function A decode function can then be called to decode the message If the return status indicates success 0 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 rtInitContext 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 include file generated by ASNIC main OSOC
163. ame familyName type xsd string gt lt xsd sequence gt lt xsd complexType gt in this case ASNIC pulls the group out to form a type of form lt name gt element where lt name gt would be replaced with the complex type name In this case the name would be Names element ASEQUENCE OF type is then formed based on this newly formed type SEQUENCE OF Names element The generated C code corresponding to this is as follows typedef struct EXTERN Names_element const OSUTF8CHAR givenName const OSUTF8CHAR initial const OSUTF8CHAR familyName Names_element List of Names_element typedef OSRTDList Names This generated code is not identical to the code generated by performing an X 694 translation to ASN 1 and compiling the resulting specification with ASNIC it is much simpler The generated encoder and decoder make the necessary adjustments to ensure that the encodings are the same regardless of the process used Repeating Elements It is common in XSD to specify that elements within a composite group can occur a multiple number of times For example lt xsd complexType name Name gt lt xsd sequence gt lt xsd element name givenName type xsd string gt lt xsd element name initial type xsd string gt lt xsd element name familyName type xsd string maxOccurs 2 gt lt xsd sequence gt lt xsd complexType gt In this case the familyName element may occur one or two times
164. ame gt lt enumPrefix gt h225 lt enumPrefix gt lt module gt The fgenum fully qualified enum option may also be used to make C names unique When specified enumerated identifiers will be automatically prefixed with the enclosing type name In the specification above each of the identifiers would have the form lt name gt _ lt id gt This can be useful in situations where common identifiers are often repeated in different types This is not a problem in C because the identifiers are wrapped in a struct declaration which provides a namespace for the values see the C section below for more details The use enum types use enumerated types option causes the direct use of the generated enum type as the C type The general pattern in this case is typedef enum idl vall id2 val2 lt name gt _UNKNOWN_ lt name gt The advantages of the type generated in the former case are a the integer type is of a known size and b it can hold unknown values or PER index values in the case of an unknown extensible value being received However some users don t care about this and would prefer the second case which provide a more debug friendly format for modern IDE s which can normally shown the symbolic value rather than the numeric In addition to the generated type definition helper functions are also generated to make it easier to convert to from enumerated and string format The signatures of these functions are as follows
165. ame 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 99 ASN 1 To C C Mappings An example of an information object definition that is derived from the ASN 1 ATTRIBUTE class above is as follows name ATTRIBUTE 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 nam ncodeType 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 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 An example of an information object definition that is derived from the ASN 1 class above is as follows name ATTRIBUTE
166. amed 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 for 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 However they can result in a large amount of additional generated code For example the following ASN 1 production NamedBS BIT STRING bitOne 1 bitTen 10 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 lt code to clear bit gt define TEST_BS3_bitOne bs lt c
167. amically allocated memory that is directly or indirectly owned by the object If no asnlFree function was generated for the type in question there is no such memory that needs to be freed and this rule does not apply e If you dynamically allocate an object that is not owned by some other object make sure when you are finished with the object that you do the following three things in order 1 invoke the generated asn1Free function if there is one This will recursively destruct and free memory for objects directly or indirectly owned by the object 2 explicitly invoke the destructor for the object This will recursively destruct objects contained by the object 3 use rtxMemFreePtr to release the memory e Ifyou repeatedly use the same object to encode records use the asn1Init method with free TRUE to free previously allocated data before repopulating the object If you repeatedly decode into the same object invoke the Decode method with free TRUE e Do not use ASN1CType memReset You must use the asn1Free methods or else memory allocated by the C standard library will not be freed Also invoking an asn1Free method after ASN1CType memReset is likely to cause a segmentation fault as dangling pointers are followed A few code examples are given below EXAMPLE 1 Using a local variable A local variable s constructor amp destructor fire automatically You only need to make sure asnlFree is invoked Using a control cl
168. amilyName 3 N typedef struct EXTERN NamePart int t union t 1 const OSUTF8CHAR givenName E EIE 2 const OSUTF8CHAR initial t 3 const OSUTF8CHAR familyName u NamePart Similar to xsd choice is xsd union The main difference is that xsd union alternatives are unnamed As specified in X 694 special names are generated in this case using the base name alt The generated name for the first member is alt names for successive members are alt n where n is a sequential number starting at 1 An example of this naming is as follows lt xsd simpleType name MyType gt lt xsd union memberTypes xsd int xsd language gt lt xsd simpleType gt This generates the following C type definition define T_MyType_alt 1 define T_MyType_alt_1l 2 typedef struct EXTERN MyType ime union t 1 OSINT32 alt fA ee RY const OSUTF8CHAR alt_1 u MyType Repeating Groups Repeating groups are specified in XML schema definitions using the minOccurs and maxOccurs facets on sequence or choice definitions These items are converted to ASN 1 SEQUENCE OF types 106 XSD to C C Type Mappings An example of a repeating group is as follows lt xsd complexType name Names gt lt xsd sequence maxOccurs unbounded gt lt xsd element name givenName type xsd string gt lt xsd element name initial type xsd string gt lt xsd element n
169. amp lt type field gt lt ObjectSet gt element1 In this definition lt Class gt would be replaced with a reference to an Information Object Class lt fixed type field gt would be a fixed type field wtihin that class and lt t ype field gt would be a type field within the class lt ObjectSet gt would be a reference to an Information Object Set which would define all of the possibilities for content within the message The first element lt element1 gt would be used as the index element in the object set relation An example of this pattern from the S1AP LTE specification is as follows InitiatingMessage SEQUENCE procedureCode S1AP ELEMENTARY PROCEDURE amp procedureCode SLAP ELEMENTARY PROCEDURES criticality S1AP ELEMENTARY PROCEDURE amp criticality S1AP ELEMENTARY PROCEDURES procedureCode value S1AP ELEMENTARY PROCEDURE amp InitiatingMessage 88 ASN 1 To C C Mappings T H S1AP E EMENTARY PROCEDURES procedureCode In this definition procedureCode and criticality are defined to be a enumerated fixed types and value is defined to be an open type field to hold variable content as defined in the object set definition In the legacy model defined below a loose coupling would be defined for the open type field using the built in ASN1Object structure This structure uses
170. an 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 functions 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 ina SEQUENCE containing a time string element the generated type will contain a public member variable containing 79 ASN 1 To C C Mappings 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 lt seqVar gt lt element gt 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 e
171. an 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 be 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 Invalid special characters only letters numbers and the hyphen character are allowed The use of the underscore character _ in identifiers is not allowed in ASN 1 but is allowed in C Since C does not allow hyphens in identifiers ASNIC converts all hyphens in an ASN 1 specification to underscore characters in the generated code Semantics errors
172. and shall have been mapped to a constrained INTEGER type Let min and max be the range for that type Evaluate the exponent using RefString equal to min and max and order the results to give the minimum and maximum values for the exponent minexp and maxexp Add a size constraint to the type as SIZE minexp maxexp The encoding shall consist simply of the bits octets or encodings of type T based on the value depending on whether the type was a BIT STRING OCTET STRING or SEQUENCE OF T The RefString shall serve as a length determinant so that when the exponent expression is evaluated at the value of RefString the result is the number of bits octets occurrences of T in the encoding Intersection Procedures The intersection operator is often used as a way of specifying length constrained content One operand will be a variable length string and the other will be simply a bit string constrained to a certain number of bits possibly by reference to a preceding field For example LengthConstrExample lt len bit 4 gt lt some variable length stuff gt amp bit val In cases where the Intersection is an operand of a Concatenation we may view the length constrained string some variable length stuff in the above example as part of the Concatenation In other cases the Intersection will be considered on its own This gives rise to two separate operations for an Intersection analysis and mapping Intersection Analysis Procedure T
173. anual Compact Code Generation Using the compact code generation option compact and lax validation option lax 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 lax 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 lib_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 a an INTEGER and b an OCTET STRING Simple SEQUENCE a INTEGER b OCTET STRING
174. 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 OSCTXT pctxt lt ProdName gt pvalue lt ClassName gt pobject int asnlDTC_ lt ProdName gt OSCTXT pctxt lt ProdName gt pvalue lt ClassName gt pobject PER int asnlPETC_ lt ProdName gt OSCTXT pctxt lt ProdName gt pvalue lt ClassName gt pobject int asnlPDTC_ lt ProdName gt OSCTXT pctxt lt ProdName gt pvalue lt ClassName gt pobject 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 class object for the data in the populated type variable to be encoded 2 If a match is found the table constraint encode function as defined above is invoked This function will verify all fixed typ
175. 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 if decoding is successful or negative if an error occurs Return status values are defined in the asn1type 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 OSCTXT 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 OSCTXT ctxt if rtInitContext amp ctxt 0 initialization failed could be a license problem printf context initialization failed check license n return 1 The next step is the specification of a buffer containing a message to be decoded This is accomplished by calling the x
176. as evidenced by the protected constructor and instance methods Therefore the object set array is only initialized once the first time the instance method is invoked The other method of interest is the LookupObject method This was generated for the id field because it was identified as a key 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 102 Chapter 5 XSD to C C Type Mappings ASNIC can accept as input XML schema definition XSD specifications in addition to ASN 1 specifications If an XSD specification is compiled the compiler does internal translations of the XSD types into equivalent ASN 1 types as specified in ITU T standard X 694 The following sections provide information on the translations and the C C type definitions generated for the different XSD types XSD Simple Types The translation of XSD simple types into ASN 1 types is straightforward in most cases a one to one mapping from XSD simple type to ASN 1 primitive type exists The following table summarizes these mappings
177. as follows include employee h include file generated by ASNIC main OSOCTET msgbuf 4096 int msglen stat step 1 instantiate an instance of the XML encode buffer class This example specifies a static message buffer OSXMLEncodeBuffer encodeBuffer msgbuf sizeof msgbuf step 2 populate msgData with data to be encoded 228 Generated XML Functions ASN1T_PersonnelRecord msgData msgData name givenName SMITH step 3 instantiate an instance of the ASN1C_ lt ProdName gt 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 0 printf encoded XML message n printf const char msgbuf printf n 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 printErroriInfo exit 0 msgptr and len now describe fully encoded messag Generated XML Decode Functions Note As of version 6 5 1 this section applies also to XER encoding rules See the Overview section above A major difference between generated XER
178. ass as show here does that for y ASN1IT_PDU msgData ASNIC_PDU controlPDU encodeBuffer msgData Populate structure of generated typ Encode When controlPDU goes out of scope asnlFree_PDU will be invoked on msgData When msgDta goes out of scope its destructor will fire EXAMPLE 2 Assigning a dynamically allocated std string for a choice type OSCTXT pctxt 123 Generated C C Source Code set the selector indicating which alternative is chosen pvalue gt myChoice t 1 allocate memory for the chosen alternative pvalue gt myChoice u message rtxMemAllocTypeZ pctxt std string invoke the constructor using placement new expression new pvalue gt myChoice u message std string Assign the contents of the string pvalue gt myChoice u message Happy Birthday EXAMPLE 3 Dynamically allocating and freeing an object OSCTXT pctxt dynamically allocate and construct the object ASN1T_StringsInSequence pvalue rtxMemAllocType pctxt ASNIT_StringsInSequence if pvalue NULL return LOG_RTERR pctxt RTERR_NOMEM new pvalue ASN1IT_StringsInSequence do some work maybe decode into pvalue invoke asnlFree destruct and free memory asnlFree_StringsInSequence pctxt pvalue pvalue gt ASN1IT_StringsInSequence rtxMemFreePtr pctxt void pvalue Generated Build Files Generated Makefile The genmake option caus
179. at 0 printf decode of ApduType failed n rtxErrPrint amp ctxt 210 Generated Medical Device Encoding Rules MDER Functions rtFreeContext amp ctxt return 1 rtxStreamClose amp ctxt The second phase of the decode can now proceed Because the open type data can appear in a list a while loop is used to cycle through the data Decode APDU open type data if data t T_ApduType_aarq OSRTDListNode pnode data u aargq gt data_proto_list head while 0 pnode PhdAssociationInformation phdAssocInfo DataProto pDataProto DataProto pnode gt data Create memory input stream stat rtxStreamMemoryCreateReader amp ctxt OSOCTET pDataProto gt data_proto_info data pDataProto gt data_proto_info numocts Note here that the rt xSt reamMemoryCreateReader function is used to stream data from the previously decoded message It points to the octets held inside of the open type After initializing the stream reader the data can be decoded into the appropriate structure using the corresponding MDERDec function Decode PhdAssociationInformation asnlInit_PhdAssociationInformation amp phdAssocInfo stat MDERDec_PhdAssociationInformation amp ctxt amp phdAssocInfo if stat 0 printf decode of ApduType failed n rtxErrPrint amp ctxt rtFreeContext amp ctxt return 1 rtxStreamClose amp ctxt pnode pnode gt n
180. at of the name of each generated encode function is as follows MDEREnc_ 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 follows stat MDEREnc_ lt name gt OSCTXT pctxt lt name gt pvalue In this definition lt name gt denotes the prefixed production name defined above The pct xt 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 program The variable should be initialized using the rt InitContext run time library function see the CMDER Runtime 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 function result variable st at returns an error status code if encoding fails Return status val
181. ates 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 generate 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 p At the application layer the Login ARGUMENT structure would be populated with the username and password to be encoded N 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 W 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 D 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 structu
182. ave been specified by the procedure that produced C Finally if any of the procedures invoked for mapping the Definitions in the DefinitionList specified that the special LHType should be produced then produce the special LHT ype defined as follows 1 The ASN 1 definition is given as LHType ENUMERATION lbit 0 hbit 1 2 The encoding for LHType is a single bit an L for Ibit and and H for hbit see the discussion of L H bits in the section on CSN 1 syntax All of the ASN 1 items produced by these procedure are added to the ASN 1 module identified by the asnl_typeReference given in the Module Note The mapping procedures this one included do not ensure that type or component names are unique If unique names are not produced so that the ASN 1 is in error then the CSN 1 specification is considered to be in error as well for the purposes of the mapping To resolve this problem the CSN 1 must be adjusted Mapping CSN 1 name to ASN 1 identifier A CSN 1 name is mapped to an ASN 1 identifier as follows 1 Apply the name character conversion procedure see below to the name 254 Mapping CSN 1 to ASN 1 2 If the name begins with an uppercase character correct this as follows a Locate the end of the first word within the name For this purpose a word does not include a numeric digit or a hyphen b If the entire name has no lowercase letters lowercase the entire name c Otherwise if the first
183. ayed using the rtxErrPrint function It is possible to add extra arguments to 3GPP Layer 3 encode functions through the use of the lt addarg gt configuration setting This is normally done to pass data from container type member variables into an encode function 240 Generated 3GPP Layer 3 3GL3 Functions 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 The only difference in populating encode member variables for the general case and for 3GPP layer 3 has to do with an element configured to be a length variable via the lt is3GLength gt configuration setting A value populated in this field will be ignored and replaced with the actual length of the encoded data Procedure for Calling C Encode Functions This section describes the step by step procedure for calling a C 3GL3 encode function Before a 3GL3 encode function can be called the user must first initialize an encoding context block structure The context block is initialized by calling the rt nitContext function Only memory buffer based encoding is supported for 3GPP layer 3 because the message sizes are generally small normally less than 256 bytes To do memory based encoding the rtxInitContextBuffer function would be called This can be used to specify use of a static or dynamic memory buffer Specification of a dynamic buffer is
184. be decoded as an open type i e skipped Refer to the section on deferred decoding for further information Note that this variable can only be used with BER CER or DER encoding rules lt isPDU gt n a This item is used to indicate 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 lt isTBCDString gt n a This item is used to indicate that this production is to be encoded and decoded as a telephony binary coded string TBCD This is type is not part of the ASN 1 standards but is a widely used encoding format in telephony applications lt length fixed size number gt This item is used to configure a length field in an OCTET STRING type for 3GPP layer 3 messages By default a length field is a single byte but there are occasions where the field width may be different This allows a fixed size encoded field width to be specified The most common values are 0 no length field or 2 lt noDecoder gt n a Indicates that no decode function should be generated for this production This item is only supported for C 3GPP layer 3 code generation lt noEncoder gt n a Indicates that no encode function
185. be the CSN 1 name for C otherwise C does not have a CSN 1 name b If the alternation does not include a null alternative or it does but we are constructng the CHOICE type as mentioned above the mapping produces an ASN 1 CHOICE type as follows c For each alternative null alternatives excluded do the following i Add a NamedType N to the CHOICE The identifier for N is determined according to the rules in ASN 1 Identifier Assignment The type for N is specified in the following clauses ii If the alternative would produce a type invoke the CSN1String mapping procedure on the remainder part of that alternative Let N type be the type produced iii Otherwise let N type be the NULL type d The encoding of the CHOICE type shall depend upon the chosen alternative within the CHOICE It shall consist of the chosen alternative s determinant followed by the encoding of the chosen alternative s type It is an error if the determinants of the alternatives are non deterministic in decoding the determinant there must not be any ambiguity as to which alternative has been chosen or whether the end of the determinant has been reached If the alternation matches the Particular General pattern the result of the mapping depends on what procedure invoked this mapping If this procedure was invoked by the Concatentation mapping this procedure produces two ASN 1 components which will become components in a SEQUENCE created by the Concatenati
186. be used to encode an employee record is as follows include employee h include file generated by ASNIC main const OSOCTET msgptr OSOCTET msgbuf 1024 int msglen stat OSBOOL aligned TRU Gl 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 to be encoded ASN1T_PersonnelRecord msgData 188 Generated PER Functions msgData name givenName SMITH step 3 instantiate an instance of the ASN1C_ lt ProdName gt 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 0 printf Encoding was successful n printf Hex dump of encoded record n ncodeBuffer hexDump printf Binary dump n 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 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
187. beddedPDV 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 allow 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 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 is as follows SIGNED ToBeSigned SEQUENCE toBeSigned ToBeSigned algorithmOID OBJ
188. bjId h This class extends the C ASNIOBJID structure and adds many additional constructors and helper methods See the ASNIC C C Common Run time Reference Manual for more details 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 ASN1ITObj Id ASN1IT_ 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 include file osSysTypes h OSREAL is defined to be a double ASN 1 production ASN 1 production Generated C code typedef OSREAL lt name gt Generated C code 63 ASN 1 To C C Mappings typedef OSREAL ASN1T_ 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
189. ble of the item to be initialized Generated Memory Free Functions The genFree option causes functions to be generated that free dynamic memory allocated using the ASN1C run time memory management functions and macros rtxMem By default all memory held within a context is freed using the rtxMemFree run time function It is also possible to free an individual memory item using the rt MemFreePtr 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 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 function is written to a separate c file 275 Additional Generated Functions The format of the name of each generated memory free function is as follows asnlFree_ lt prefix gt lt prodName gt where lt prodName gt is the name of the ASN 1 production for which the function i
190. ble values x208 x680 mixed default is x680 compact generate compact code compat lt version gt generate code compatible with previous Using the Compiler 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 events generate code to invoke SAX lik vent handlers genTest lt filename gt generate sample test functions html generate HTML marked up version of ASN 1 I lt directory gt set import file directory lax do not generate constraint checks in code laxsyntax do not do a thorough ASN 1 syntax check list generate listing allow ambig tags allow ambiguous tags in input specifications noContaining do not generate inline type for CONTAINING lt type gt nodatestamp do not put date time stamp in generated files nodecode do not generate decode functions noencode do not generat ncode functions noIndefLen do not generate indefinite length tests noObjectTypes do not gen types for items embedded in info objects noOpenExt do not generate open extension elements notypes do not generate type definitions noxmins do not generate XML namespaces for ASN 1 modules 0o lt directory gt set output file directory also srcdir lt dir gt libdir lt directory gt set output libraries directory bin
191. burbs 2 rural 3 END Looking first at common asn1 and common csn1 we find that both are using the ASN 1 module Common So the ASN 1 module called Common will have both of these types Name and Location Next we look at main asn1 This imports Name and Location from the Common module into the Main module It does not matter that one of those was defined using CSN 1 and the other using ASN 1 You can see this file defines FooBar in module Main It also references Marker which is defined in the same ASN 1 module but using CSN 1 notation see main csn1 Finally we look at main csn1 This file defines My Pdu the ASN 1 name resulting from My Pdu and Marker in ASN 1 module Main It refers to Name Location FooBar and Marker We consider each of these in turn Marker is defined locally in the same file FooBar is defined in the same ASN 1 module but using ASN 1 notation Finally Name and Location which belong to another ASN 1 module are referenced This is legal because those types were imported for the Main module by main asn1 In conclusion the definitions for an ASN 1 module may be split into multiple files using different notations but in the end it is as if everything were specified in ASN 1 A CSN 1 file may contain references to types in other ASN 1 modules by using the ASN 1 notation to specify imports A caveat our tool does not accept ASN 1 based definitions of ASN 1 modules tha
192. butes information object set was extensible indicated by a at the end of the definition then 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 Invoke type is as follows include TestTable h include file generated by ASNI1C main const OSOCTET msgptr OSOCTET msgbuf 1024 int msglen step 1 construct ASN1C C generated class this specifies a static encode message buffer ASN1BEREncodeBuffer encodeBuffer msgbuf sizeof msgbuf step 2 populate msgData structure with data to be encoded 136 Generated Encode Decode Function and Methods ASN1T_Invoke msgData ASN1C_Invoke invok encodeBuffer msgData msgData opcode numids 3 msgData opcode subid 0 0 msgData opcode subid 1 Ty msgData opcode subid 2 1 ASN1VisibleString argument objsys msgData argument decoded void amp argument note opcode value is 0 1 1 so argument must be ASN1VisibleString type
193. cInfo system_type data 32 SystemType_sys_type_agent static const OSOCTET sysId 0x31 0x32 0x33 0x34 0x35 0x36 0x37 0x38 G phdAssocInfo system_id numocts OSUINT32 8 phdAssocInfo system_id data OSOCTET sysId 208 Generated Medical Device Encoding Rules MDER Functions phdAssocInfo dev_config_id extended_config_start phdAssocInfo data_req_mode_capab data_req_mode_flags numbits 16 phdAssocInfo data_req_mode_capab data_req_init_agent_count 1 phdAssocInfo data_req_mode_capab data_req_init_manager_count 0 Create memory output stream stat rtxStreamMemoryCreateWriter amp ctxt 0 0 if Stats 0 4 printf Create memory output stream failed n rtxErrPrint amp ctxt rtFreeContext amp ctxt return stat Encode stat MDEREnc_PhdAssociationInformation amp ctxt amp phdAssocInfo msgptr rtxStreamMemoryGetBuffer amp ctxt amp len T In brief the data structures used for the payload are initialized to zero using the OSCRTLMEMSET macro which here acts just like the C runtime library memset function The data used for populating this example are taken from a draft specification After filling in the necessary fields the rtxSt reamMemoryCreateWriter function is used to create a memory stream for encoding the payload More information on this function can be found in the C C Common Run Time Library manual In case
194. called To do memory based encoding the rtxInitContextBuffer function would be called This can be used to specify use of a static or dynamic memory buffer Specification of a dynamic buffer is possible by setting the buffer address argument to null and the buffer size argument to zero An encode function can then be called to encode the message If the return status indicates success 0 then the message will have been encoded in the given buffer or written to the given stream OER encoding starts from the beginning of the buffer and proceeds from low memory to high memory until the message is complete This differs from definite length BER where encoding was done from back to front Therefore the buffer start address is where the encoded OER message begins The length of the encoded message can be obtained by calling the rtxCtxtGetMsgLen run time function If dynamic encoding was specified i e a buffer start address and length were not given the rtxCtxtGetMsgPtr run time function can be used to obtain the start address of the message This routine will also return the length of the encoded message If a memory stream was used the message start address and length can be obtained by calling the rtxStreamMemoryGetBuffer function A program fragment that could be used to encode an employee record is as follows include employee h include file generated by ASNIC main PersonnelRecord employee OSCTXT GCEXE OSOCTET
195. cally set OSASN1XER for you xsd produces schema that validates BASIC XER encodings xer or xml flag is used to comple ASN 1 with supported Generated code supports EXTENDED XER only You XER encoding instructions if any instructions are not should set the OSASN1XER flag If you are using the PDU supported all instructions are ignored and the above entry methods it will be automatically set for you in this table applies xsd produces schema that validates EXTENDED XER encodings As of this writing this is not fully supported xml used to compile ASN 1 This is the same as the first entry using xer except that the generated PDU methods will NOT automatically set OSASN1XER for you This means you will get OSys XER encodings unless you set the flag yourself 212 Generated XML Functions Compiler Invocation What is Generated xsd produces schema that validates OSys XER encodings xml used to compile XSD Generated code supports EXTENDED XER only You should set the OSASN1XER flag If you are using the PDU methods it will be automatically set for you Differences between OSys XER and XER BASIC XER OSys XER differs from BASIC XER in the following ways e Lists of numbers enumerated 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
196. code If used with the w32 command line option a makefile that is compatible with the Microsoft Visual Studio nmake utility is generated otherwise a GNU compatible makefile is generated Note that the nmake option may now be used instead of the make w32 combination to produce a Visual Studio makefile genMakeDLL lt filename gt This option instructs the compiler to generate a portable makefile for compiling the generated C or C code into a Dynamic Link Library DLL genMakeLib lt filename gt This option instructs the compiler to generate a portable makefile for compiling the generated C or C code into a static library file genPrint lt filename gt This option allows the specification of a C or C source print 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 bu
197. code Options under Generated Function Types provide granular control of what functions to generate The printing functions allow for various printing schemes to be generated such as print to string and print to standard output and how the printed data should be formatted Sample Program Generation allows simple encoding and decoding programs which demonstrate using the generated code to be generated The sample writer program can optionally encode randomly generated test data Depending on the target language selected additional options may be shown here C C Generated Functions Generate Memory Free Functions Generate Named Bit Macros For C and C additional functions for memory management and macros for dealing with named bits in BIT STRINGs can be generated Java Function Options For Java get and set methods can be generated for members of generated classes 45 T al unction ASNI1C GUI Users Guide The Constraints and Debugging tab holds settings related to constraint handling event handling and logging in generated code Under Constraints various types of constraint checks can be added or removed from generated code In Debugging and Event Handling settings for adding debug tracing and event hooks are available In addition to enabling event callbacks generation of type structures can also be disabled in which case generated de
198. code functionality will simply call user created event handlers and not perform its own decoding operation 47 Output Function Generation Constraints and Debugging Code Modifications Space Optimizations r Generate compact code PF Bo not generate indefinite length processing code Do not generate code to save restore unknown extensions M Do not generate types for items embedded in information objects Do not generate XML namespaces for ASN 1 modules l Generate short form of type names Other Options Automatically create unique names for duplicate items _P Do not add date stamp to generated files l Generate code for dependent type definitions ASNI1C GUI Users Guide Under the Code Modifications tab are a number of options for generating simplified code In Space Optimizations these mainly regard the removal of unwanted or unneeded functionality and shortening names of generated types Other Options provide several miscellaneous settings including the option of generating code for types that have been imported into the current schema Depending on the target language selected additional options are shown at the bottom of the tab C C Code Modifications Add a header guard prefix Add a C namespace SEQUENCE OF SET OF use 0 linked list dynamic array static array T Generate static member variables in choice constructs Use enumerated ty
199. coding at the point where the component would appear If the component was already OPTIONAL its presence may have been determined by a presence flag In that case it is additionally determined by container as well In such a case the boundary of the container is used to determine whether the combination 262 Mapping CSN 1 to ASN 1 of the presence bit and the value are present and if present then the presence bit determines whether the value is present or not f Additionally if the Concatenation is truncated each operand shall either be padding or else be mapped to an ASN 1 type or ASN 1 component This requirement is so that the optionality of everything in the Concatenation implied by the truncation can be modeled in the ASN 1 g The encoding of the SEQUENCE shall consist of the encoding of its component types in order h If a length determinant was identified in the Concatenation see the section on Intersection Procedures then let encoded value be the encoded value for the corresponding component Let length value be the result of evaluating the constraining operand s exponent at encoded value Then length value shall be the length of the encoding for the components following the length determinant in the SEQUENCE including any padding bits The units for the length shall be bits or octets depending on the constraining operand s use of a reference to bit or octet i If the Concatenation ended with padding the interpr
200. coding 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 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 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 2 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 rtxMemAlloc and rtxMemFree run time libra
201. 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 ASN1TPDU 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 ASN1T_ lt type gt func2 ASN1T_ lt type gt msgdata ASNIBERDecodeBuffer decbuf ASN1C_ lt type gt cc decbuf msgdata cc Decode Use newCopy to return a copy of the decoded item return cc newCopy Memory Security ASNIC offers two primary tools to help secure memory operations a safe memory copy accessed using the OSCRTLSAFEMEMCPY macro and a memory heap flag RT_MH_ZEROONFREE that will cause the runtime context to zero out any freed memory Memory that is marked as available using rt xMemReset will also be zeroed out T Safe Memory Copy Safe memory co
202. cos cis eosases seeven deep seesaseetsbapecdsacasseesengaeesseugssscteSsboeds 30 3 ASNIC GUI USers Guide soie ae areo e Weedon Ere EEE E S E EOE E EEE E econ aa stele 31 OLEA ESAT a E E E E EE bat tote E E E A NES 31 Creating a Project eiri oo TE ETE EE O EE ER vies es oes bs hoki cae ETES A E ES 35 Editing Shemasi enee na Seer aN esn AAEE EE EE EOE ESEESE ATE OI PETE ETPP sdssetawedaseeeads ees 36 COM pM ese eieiaeo Bakes EEE E ese E a ER as E A E ESEE EENES EEES 36 Interface Secer onia e E E E E E E E E E des T a TE 37 11 0 ieee ee SS a RS E E E EE E S er 38 Project WINdOW lt sass sos 28s dag s asad esd staan neces sae Desa E EEE tesa ee opscentes she CIE EEES PEE EEP EEEREN TS ER eames 39 ASNI Tree Window sy lt is5 icvdedsie vocuess becdaests Cottehse hideous vosneds Meediieds ETEA renee ec detels Decco 40 Error Los WINdOW ai vavietsiesectessubeeteata ase ies padeetiek comes asa ben teins ania boa acaba stat te as Vere Seaaa aaa ANE 41 Project Settings oi e e leet ee Oe eee eee ea eee Ree een Ee 41 4 ASN 1 To C C H Mappings o sc2cvctesnsssvossissicoseees suovs aa Ee ASPE T AEOS ESEESE PERI EE TE RAA IES 53 Type Mappings ire seee aere NE E EE EA SEE EE E EEEE RESE bedhead REEE 53 BOOLEAN vaiu ener a a a E E E E E A AE RE E R Ea bene 53 INTEGER ceee a e E EEEE EEE EEE EEEE Cab ates haa EEE EEE EEN EE 53 BIT SPRING emise oetan anseo Eaa RO aa dey EEAO anges Eor dia OEE EEIEIE Eaa E yer 55 OCTET SIRING osc ies r EEE EE E E E E E E OEE E EE
203. ction stat NASDec_TS24008Msg_PDU amp ctxt amp data if stat 0 process received data 244 Generated 3GPP Layer 3 3GL3 Functions else error processing rtxErrPrint amp ctxt step 4 free the context rtFreeContext amp ctxt 245 Chapter 16 CSN 1 Described CSN 1 Concrete Syntax Notation 1 is a notation used to describe the concrete representation of data i e the encoding It is noteworthy for its use as the notation for describing message and information element encodings in various 3GPP technical specifications In this chapter we describe the CSN 1 notation In the following chapter we describe how we map CSN 1 to ASN 1 3GPP 24 007 Annex B describes CSN 1 In practice however this description is incomplete it does not cover all of the syntax actually used by the 3GPP technical specifications Other documents e g 3GPP 44 018 reference CSN 1 Specification Version 2 0 and provide a dead URL Searching the internet we did find some additional unofficial information on CSN 1 We also found an order form to order the specification from the author located in France In short an official description of CSN 1 is not readily available Therefore we ve made do with what information we could find and what could be inferred from usage our interpretation of CSN 1 may therefore not be entirely according to the official specification The CSN 1 grammar presented in
204. ctor 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 ASN1C where control classes were generated for all types This default behavior can be overridden by using a configuration file entry or the pdu 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 asnlconfig 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 1 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_ lt name gt public ASN1CTy
205. d dynamic memory and stored pointers to objects in the C structure After processing on the C structure is complete the run time library function rt xMemF ree should be called to free the allocated memory A program fragment that could be used to decode a simple PDU type follows 7 include IEI include rtxsrc rtxStreamFile h int main void ApduType data OSCTXT ctxt const char filename message dat int stat Step 1 Initialize a context variable for decoding stat rtInitContext amp ctxt if stat 0 initialization failed could be a license problem rtxErrPrint amp ctxt rtFreeContext amp ctxt 206 E 11073 20601 ASN1 h include file generated by ASNIC Generated Medical Device Encoding Rules MDER Functions return stat Step 2 Initialize a stream reader stat rtxStreamFileCreateReader amp ctxt filename if 0 stat rtxErrPrint amp ctxt rtFreeContext amp ctxt return stat Step 3 decode asnlInit_ApduType amp data stat MDERDec_ApduType amp ctxt amp data if stat 0 printf decode of data failed n rtxErrPrint amp ctxt rtFreeContext amp ctxt return 1 Decoding a Series of Messages Using the C Decode Functions Decoding a series of messages is very similar to the method used for other encoding rules MDER however is simpler Users need no
206. d JavaScript Object Notation JSON Functions asnlJsonDec_ 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 follows status asnlJsonDec_ lt name gt OSCTXT pctxt lt name gt pvalue In this definition lt name gt denotes the prefixed production name defined above The pct xt 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 rt InitContext 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 function result variable status returns the status of the decode operation The return status will be greater than or equal to zero if decoding is successful or negative if an error occurs Return status values are defined i
207. d identify the parts of the alternative that make up each of these parts Additionally if there is a determinant determine its name if it has one Refer to the subsection on determinants below 2 Determine the pattern that is matched by the alternation as follows a Optional component with presence bit The alternation matches this pattern if the following conditions are met e There are exactly two alternatives e One alternative would not produce an ASN 1 type and has a determinant which is either unamed or is not uniquely named The determinant has length 1 e The other alternative would produce an ASN 1 type and has a determinant The determinant has length 1 e The determinant values for the two alternatives are unique b Optional component with presence bit and container determined The alternation matches this pattern if the following conditions are met e There are exactly three alternatives e One alternative is a null alternative e One alternative would not produce an ASN 1 type and has a determinant which is either unamed or is not uniquely named The determinant has length 1 e The other alternative would produce an ASN 1 type and has a determinant The determinant has length 1 e The determinant values for the two alternatives having them are unique c Optional component container determined The alternation matches this pattern if the following conditions are met e There are exactly two alternatives e One alter
208. d 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 0 if decoding is successful or a negative value if an error occurs Return status values are documented in the C C Common Functions Reference Manual and in the rtxErrCodes 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 192 Generated PER Functions 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 The following are the basic steps in calling a compiler generated decode function 1 Prepare a context variable for decoding 2 Initialize the data structure to receive the decoded data 3 Call the appropriate compiler generated decode function to decode the message 4 Free the context after use of the decoded data is complete to free allocated memory structures Before a PER decode function can be called the user must first initialize a context block structure The context block is initi
209. d message A program fragment that could be used to encode an employee record is as follows include employee h include file generated by ASNIC main OSOCTET msgbuf 1024 int msglen stat OSCTXT ctxt OSBOOL aligned TRUE Employee employee typedef generated by ASNIC Populate employee C structure mployee name givenName SMITH Allocate and initialize a new context pointer stat rtInitContext amp ctxt if stat 0 printf rtInitContext failed check license n 186 Generated PER Functions rtxErrPrint amp ctxt return stat pu_setBuffer amp ctxt msgbuf msglen aligned if stat asnlPE_Employee amp ctxt amp employee 0 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 allocat
210. d string gt lt xsd element name initial type xsd string minOccurs 0 gt lt xsd element name familyName type xsd string gt 104 XSD to C C Type Mappings lt xsd sequence gt lt xsd complexType gt would result in the creation of the following C type definition typedef struct EXTERN Name struct unsigned initialPresent 1 m const OSUTF8CHAR givenName const OSUTF8CHAR initial const OSUTF8CHAR familyName Name xsd all The xsd all type is similar to an ASN 1 SET in that it allows for a series of elements to be specified that can be transmitted in any order However due to some technicalities with the type it is modeled in X 694 to be a SEQUENCE type with a special embedded array called order This array specifies the order in which XML elements were received if XML decoding of an XML instance was done If this information were then retransmitted in binary using BER or PER the order information would be encoded and transmitted followed by the SEQUENCE elements in the declared order If the data were then serialized back into XML the order information would be used to put the elements back in the same order in which they were originally received The mapping to C type would be the same as for xsd sequence above with the addition of the special order array An example of this is as follows lt xsd complexType name Name gt lt xsd all gt lt xsd element name givenNam
211. d 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_ lt name gt OSCTXT pctxt lt name gt value In this definition lt name gt denotes the prefixed production name defined above The pct xt 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 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 st at returns the status of the encode operation Status code 0 0 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 com
212. d_protocolIEs_element ProtocollIE_ID id Criticali ty criticality struct information object selector HandoverRequiredIEs_TVALUE t HandoverRequiredIEs information objects union id id MME UE S1AP ID criticality reject presence mandatory 7 91 ASN 1 To C C Mappings MME _UE_S1AP_ID _HandoverRequiredIEs_id_MME oa Gq E_S1AP id id HandoverType criticality reject presence mandatory ip HandoverType _HandoverRequiredIEs_id_HandoverType id id Cause criticality ignore presence mandatory ay u value HandoverRequired_protocollIEs_element ID In this case the protocol JE id field and criticality are generated as usual using the fixed type field type definitions The open type field once again results in the generation of a union structure of all possible type fields that can be used Note in this case the field names are automatically generated _HandoverRequiredIEs_id_MME_UE_SIAP_ID etc The reason for this was the use of inline information object definitions in the information object set as opposed to defined object definitions This is a sample from that set HandoverRequiredIEs S1AP PROTOCOL IES ID id MME UE S1AP ID CRITICAL ID id HandoverType CRITICAL ITY reject TYP eal MM E
213. d_setp run time library function This function takes as an argument the start address of the message to be decoded 165 Generated BER Functions 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 dynamic memory and stored pointers to objects in the C structure After processing on the C structure is complete the run time library function rtxMemFree 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 ASNI1TAG msgtag int msglen OSCTXT ctxt PersonnelRecord employee logic to read message into msgbuf Step 1 Initialize a context variable for decoding if rtInitContext amp ctxt 0 initialization failed could be a license problem printf context initialization failed check license n return 1 xd_setp amp ctxt msgbuf 0 amp msgtag amp msglen Step 2 Test message tag for type of message received note this is opti
214. dding elements to the list See the C C Common Run time Reference Manual for a full description of these functions For C the ASN TSeqOfList class is used or in the case of PDU types the ASNJTPDUSegOfList class The ASN1ITSeqOfList extends the C OSRTDList structure and adds constructors and other helper methods The ASNITPDUSeqOfList is similar except that it also extends the ASNJTPDU base class to add additional memory management capabilities needed by PDU types to automatically release memory on destruction See the 71 ASN 1 To C C Mappings ASN1CSeqOfList 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 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 ASN1C runtime library This allows all list memory to be freed with one call after encoding is complete In the case of C the rtxMemAlloc or rtxMemAllocType function would first be used to allocate a record of the element type This element would then be initialized and populated with data The rtxDListAppend function would then be called to append it to the given list For C the compiler gene
215. dditional formatting so that the hex content is printed in a single string prefixed by Ox hfile lt filename gt This option allows the specification of a header h file to which all of the generated typedefs 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 html None This option is used to generated HTML markup for every compiled ASN 1 file This markup contains hyperlinks to all referenced items within the specifications One HTML file is generated for each corresponding ASN 1 source file lt directory gt This option is 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 It is also possible to provide a list of import directories by adding all directory specifications to a text file one per line and then providing the path to 10 Using the Compiler Option Argument Description the text file prefixed with an character for example I incdirs txt java None Generate Java source code See the ASNIC Java User s Guide for more information on Java code generation json None This option is used to generate encode decode functions for Javascript Object Notation JSON See our whitepaper Javascript Object Notation JSON
216. declared as void rtxPrintCallback void pPrntStrminfo const char 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 if 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 void writeToFile void pPrntStrmiInfo const char fmtspec va_list arglist GI FILE fp FILE pPrntStrmiInfo vfprintf fp fmtspec arglist Once the callback function is 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 For registering a global callback use rtxSetGlobalPrintStream rtxPrintCallback myCallback void pStrmInfo For registering a context level callback use rtxSetPrintStream OSCTXT pctxt rtxPrintCallback 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 dec
217. decode functions and generated XML decode functions in ASNIC version 6 0 and later is that the XML functions no longer use the Simple API for XML SAX interface Instead the XML runtime now uses an XML pull parser developed in house for improved efficiency The pull parser also provides a similar interface to that of binary encoding rules such as BER or PER meaning easier integration with existing encoding rules Finally the pull parser interface does not require integration with any 3rd party XML parser software For each ASN 1 production defined in the ASN 1 source file a C XML decode function is generated This function will parse the data contents from an XML message of the corresponding ASN 1 or XML schema type and populate a variable of the C type with the data 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 encode an ASN 1 message into the variable referenced in the msgData component of the class 229 Generated XML Functions Generated C Function Format and Calling Parameters The format of the name of each generated XML decode function is as follows lt namespace gt XmlDec_ lt prefix gt lt prodName gt where lt namespace gt is an optional C namespace prefix 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
218. decoding failed Return status values are defined in the rtvErrCodes h include file The reason text and a stack trace can be displayed using the rtxErrPrint function Procedure for Calling C Decode Functions This section describes the step by step procedure for calling a C XML 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 These are the steps involved calling a compiler generated decode function 1 Prepare a context variable for decoding 2 Open an input stream for the XML document to be decoded 3 Decode the initial tag value to figure out what type of message was received optional 4 Call the appropriate compiler generated decode function to decode the message 5 Free the context after use of the decoded data is complete to free allocated memory structures Before a C XML decode function can be called the user must first initialize a context block structure The context block structure is initialized by calling the rtXmlInitContext function An input stream is then opened using one of the rtxStream functions If the data is to be read from a file the rtxStreamFileCreateReader function can use used Similar functions exist for opening a memory or socket based stream 230 Generated XML Functions If the user knows the type of XML message that is to be processed he can directly call th
219. 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 6 Release dynamic memory that was allocated by the decoder All memory associated with the decode context is released when both the OSXMLDecodeBuffer and ASNIC_ lt ProdName gt objects go out of scope A program fragment that could be used to decode an employee record is as follows include employee h include file generated by ASNIC main const char filename message xml OSBOOL verbose FALSE trace TRUE int i stat logic to read message into msgbuf step 1 instantiate an XML decode buffer object OSXMLDecodeBuffer decodeBuffer filename step 2 instantiate an ASN1T_ lt ProdName gt object ASN1T_PersonnelRecord msgData step 3 instantiate an ASN1C_ lt ProdName gt object ASN1C_PersonnelRecord employ decodeBuffer msgData step 4 decode the record stat employee Decode step 5 check the return status if stat 0 process received data else error processing decodeBuffer PrintErroriInfo step 6 free dynamic memory will be done automatically when both the decodeBuffer and employ objects go out of scope 233 Chapter 14 Generated JavaScript Object Notation JSON Functions JavaScript Object Notation JSON
220. ded 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 Wek urgency ENUMERATED normal high DEFAULT normal alternate item cod INTEGER 0 254 alternate item nam TA5String SIZE 3 10 OPTIONAL l 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 The C mapping of an ASN 1 SEQUENCE type is very similar to the C mapping However there are some important differences 68 ASN 1 To C C Mappings 1 As with all C types the prefix ASN1T_ is added before the ty
221. ding any bits these constructions could consume could also be consumed by lt spare bit gt On encoding these constructions don t encode anything and may as well not be there In short these constructions are really useless We therefore further simplify the example to null 0 1 lt stuff gt null 70 1 lt more stuff gt lt spare bit gt Problems with Names The 3GPP specifications will sometimes omit angle brackets around multi word names where we require them For example they will have lt one thing One Thing gt ratherthan lt one thing lt One Thing gt gt It seems like most of the time they will have the extra angle brackets there Another naming issue is that CSN 1 names are supposed to be case insensitive We really treat them as case sensitive however because we map the names to ASN 1 names which are case sensitive Sometimes you ll find capitalization differences lead to errors about missing types Subclassing The subclass operator has two forms The 3GPP specifications sometimes use the wrong operator for the operands they give The operator is used with a literal bit string while the operator is used with an integer User Defined Functions CSN 1 allows the use of a user defined function inside an exponent The generated code will need to invoke this user defined function The C function name will be taken to be lt typePrefix gt lt functionName gt where lt typePrefix gt is th
222. dir lt directory gt set output binary directory objdir lt directory gt set output object directory prjdir lt directory gt set the output project directory this automatically sets sane defaults for the library directory lib binary directory bin source directory src and object directory obj param lt name gt lt value gt create types from param types using given value pdu lt type gt designate lt type gt to be a Protocol Data Unit PDU lt type gt may be all to select all type definitions usepdu lt type gt specify a Protocol Data Unit PDU type for which sample reader writer programs and test code has to be generated print lt filename gt generate print functions prtfmt details bracetext format of output generated by print shortnames reduce the length of compiler generated names strict do strict checking of table constraint conformance syntaxcheck do syntax check only no code generation reader generate sample reader program trace add trace diag msgs to generated cod no UniqueNames resolve name clashes by generating unique names default on use noUniqueNames to disable warnings output compiler warning messages writer generate sample writer program C C options array use arrays for SEQUENCE OF SET OF types arraySize lt size gt specify the size of the array variable compare lt filename gt generate comparison functions copy lt filename gt generate copy functions cppNs l
223. dname gt Present as follows struct unsigned lt field namel gt 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 If a 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 is 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 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 Anew Type Assignment is created for a TypeField s type definition as follows _ lt ClassName gt _ lt FieldName gt lt Type gt Here ClassNa
224. e type xsd string gt lt xsd element name initial type xsd string gt lt xsd element name familyName type xsd string gt lt xsd all gt lt xsd complexType gt would result in the creation of the following C type definition typedef struct EXTERN Name Struct f OSUINT32 n OSUINT8 elem 3 _order const OSUTF8CHAR givenName const OSUTF8CHAR initial const OSUTF8CHAR familyName Name In this case the _order element is for the order element described earlier Normally the user does not need to deal with this item When the generated initialization is called for the type or C constructor the array will be set to indicate elements should be transmitted in the declared order If XML decoding is done the contents of the array will be adjusted to indicate the order the elements were received in xsd choice and xsd union The xsd choice type is converted to an ASN 1 CHOICE type ASNIC generates exactly the same code For example 105 XSD to C C Type Mappings lt xsd complexType name NamePart gt lt xsd choice gt lt xsd element name givenName type xsd string gt lt xsd element name initial type xsd string gt lt xsd element name familyName type xsd string gt lt xsd choice gt lt xsd complexType gt in this case the generated code is the same as for ASN 1 CHOICE define T_NamePart_givenName 1 define T_NamePart_initial define T_NamePart_f
225. e type prefix specified for the module in which the function is referenced and lt functionName gt is the name as it appears in the CSN 1 For example TS44018Msg_p Naturally you will ned to define and implement the user function You should name it as just described It should return an integer type and accept an integer argument of a type that is compatible with the argument that is passed to the function in the CSN 1 For example int TS44018Msg_p OSUINTS8 n 270 Compiling CSN 1 CSN 1 to ASN 1 Example In this section a sample CSN 1 file is presented along with the corresponding ASN 1 There is little to no commentary here as the chapter that defines the mappings really is the commentary The majority of the patterns that may be recognized are illustrated in this sample Example 18 5 CSN 1 Example ASNIMODULE UserGuide This is a definition where the right hand side is mapped to a component and the whole is therefore mapped into a SEQUENCE lt SingleComponent gt 0 1 lt fields lt fieldl bit 4 gt lt field2 bit 3 gt gt This example illustrates some of the effects of naming lt Naming gt lt ALL CAPS 1 bit 1 gt becomes all caps 1 lt PART Caps bit 1 gt becomes part Caps lt CamelCase bit 1 gt becomes camelCas Illustrate various patterns of alternation lt Alternations gt lt 1 bativor hobit i gt H gt lt particular gen
226. e code contained within the given file for what would have been generated for encoding the element The code in this case is not a complete function but rather a snippet to be inserted within a larger function The current include path is searched for the given filename This item is only supported for C 3GPP layer 3 code generation lt ctype gt chararray This is used to specify a specific C type be used in place of the default definition generated by ASNIC In the case of elements the only supported customization is for character string types which would normally be represented by a character pointer type char to be changed to use static character arrays This can only be done if the string type contains a size constraint lt end3GExtElem name element name gt lt Element name gt attribute This item is used to delimit a group of optional elements that start with an ext boolean element A common pattern in the specification of 3GPP IE s is to include an 27 Using the Compiler Name Values Description extension bit to signal the presence or absence of group of elements these normally comprise a single octet This is essentially an alternative way to specify an optional element group in ASN 1 This item is only supported for C 3GPP layer 3 code generation lt iei format tltvitlv IEI hex value This item is used to indicate an element is part of the non length length
227. e decode function at this point If not the user may call the rtXmlpMatchStartTag method to match the initial tag in the message with a known start tag The user can continue to do this until a match is found with one of the expected message types Note that the rtXmlpMarkLastEvent function must be called if the tag is to be reparsed to attempt another match operation A decode function can then be called to decode the message If the return status indicates success 0 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 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 include file generated by ASNIC main PersonnelRecord data OSCTXT ctxt OSBOOL trace TRUE verbose FALSE const char filename message xml int 2 Stat logic to read message into msgbuf This example uses a static context block step 1 initialize the context block stat rtXmlInitContext amp ctxt if stat 0 rtxErrPrint amp ctxt return stat
228. e enough to hold a a decoded value A typical case is an integer value that is too large to fit in the standard C integer type typically a 32 bit value on a given platform If this occurs it is usually necessary to use a configuration file setting to force the compiler to use a different data type for the item For example for integer the lt isBigInteger gt setting can be used to force use of a big integer type 24 RTERR_INVCHAR Invalid character This status code is returned when a character is encountered that is not valid for a given data type For example if an integer value is being decoded and a non numeric character is encountered this error will be raised 301 ASNIC Error Codes Error Code Error Name Description 25 26 RTERR_XMLSTATE RTERR_XMLPARSE XML state error This status code is returned when the XML parser XML parser error This status code in returned when the underlying XML parser application by default this is Expat returns an error code The parser error code or text is returned as a parameter in is not in the correct state to do a certain operation RTERR_SEQORDER Sequence order error This status code is returned when decoding an ASN 1 SEQUENCE or XSD xsd sequence construct It is raised if the elements were received in an order different than that specified the errInfo structure within the context structure RTERR_FILNOTFOU File not found Th
229. e 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 ASNI CType or one of its descendents The equivalent C and C type definitions for each of the various ASN 1 types follow 117 Generated C C Source Code Generated C Source Files By default the ASN1C 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 asn E_ lt type gt lt moduleName gt Dec c decode functions asn1D_ lt type 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
230. e 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 200 Generated Octet Encoding Rules OER Functions within the structure This memory is tracked within the context structure and is released when the context structure is freed The function result variable st at returns the status of the decode operation Status code 0 0 indicates the function was successful A negative value indicates decoding failed Return status values are defined in the asn1ErrCodes h and rtxErrCodes h header files The reason text and a stack trace can be displayed using the rtxErrPrint function described later in this document Procedure for Calling C Decode Functions This section describes the step by step procedure for calling a C OER decode function Unlike BER the user must know the ASN 1 type of an OER 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 The following are the basic steps in calling a compiler generated decode function 1 Prepare a context variable for decoding 2 Initialize the data structure to receive the decoded data 3 Call the appropriate compiler generated decode function to decode the message
231. e modelled as a 3G extended list This can only be applied to SEQUENCE OF productions It is used in 3G layer 3 messages when the extension of a repeating type is controlled by an extension bit that occurs either before or after the record If the pre eol attribute short for preceding end of list is specified it indicate a bit before the record signals whether another record follows The value 0 or 1 indicates which bit value signal end of list The post eol attribute is the same except that it indicates the control bit follows after the record This item is only supported for C 3GPP layer 3 code generation lt is3GMessage gt n a This item specifies that this production represents a 3G layer 3 message type as opposed to a 3G layer 3 25 Using the Compiler Name Values Description information element IE This item is only supported for C 3GPP layer 3 code generation lt isBigInteger gt n a This item 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 lt isOpenType gt n a This item is used to indicate that any element of this type will
232. e released when the either the context is freed or explicitly when the rtxMemFree or rtxMemReset function is called 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 rtInitContext 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 include file generated by ASNIC main 201 Generated Octet Encoding Rules OER Functions OSOCTET pMsgBuf int len stat OSCTXT ctxt PersonnelRecord employee const char filename message dat step 1 initialize context stat rtInitContext amp ctxt if stat 0 printf rtInitContext failed check license n rtErrPrint amp ctxt return stat step 2 read input file into a memory buffer stat rtxFileReadBinary amp ctxt filename amp pMsgBuf amp len if 0 stat stat rtxInitContextBuffer amp ctxt pMsgBuf len if 0 stat rtxErrPrint amp ctxt rtFreeContext amp ctxt return stat step 3 initialize the data variable asnlInit_PersonnelRecord amp employee step 4 call the decode function stat OERDec_PersonnelRecord amp ctxt amp employee if stat 0 process received data
233. e specification of XML input from a file memory buffer or another stream The function result variable status returns the status of the decode operation The return status will be zero if decoding is successful or a negative value if an error occurs Return status values are documented in the C C Common Functions Reference Manual and in the rtxErrCodes h include file Procedure for Using the C Control Class Decode Method The following are the steps are involved in decoding an XML message using the generated C class 1 Instantiate an XML decode buffer object OSXMLDecodeBuffer to describe the message to be decoded There are several choices of constructors that can be used including one that takes the name of a file which contains the XML message one the allows a memory buffer to be specified and one that allows an existing stream object to be used 2 Instantiate an ASN1T_ lt ProdName gt object to hold the decoded message data 3 Instantiate an ASN1C_ lt ProdName gt 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 4 Invoke the ASN1C_ lt ProdName gt object Decode or DecodeFrom method 232 Generated XML Functions 5 Check the return status The return value is a status value indicating whether decoding was successful or not Zero indicates success If
234. e to use as our basis When a CSN 1 string is mapped to a component the mapping procedure will have already assigned a CSN 1 name if there is one to be used as the basis When a CSN 1 string is mapped to an ASN 1 type we can attempt to locate a CSN 1 name as follows Divide the string into a determinant and remainder part If the remainder is labeled use the label name as the CSN 1 name Otherwise if the string itself is labeled use that name If neither of those cases applies then if the string is an exponential string it has an exponent the string is mapped to an ASN 1 SEQUENCE OF and the base of the string has a labeled remainder part if you split it into a determinant and remainder then use that label name in this case the ASN 1 identifier will have a list suffix as noted below If we now have a CSN 1 name we use the mapping of CSN 1 name to ASN 1 identifier to produce the ASN 1 identifier If the previous step called for it we append a list suffix to the result We now have our ASN 1 identifier Otherwise 255 Mapping CSN 1 to ASN 1 we assign an ASN 1 identifer directly If the invoking procedure is creating a SEQUENCE names are of the form component n If the invoking procedure is creating a CHOICE names are of the form choice n In either case n equals the number of components already added to the SEQUENCE or CHOICE plus 1 Note The mapping procedures this one included do not ensure that type or compo
235. e 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 ASN1DynBitStr OSUINT32 numbits const OSOCTET data ASN1IDynBitStr The ASNITDynBitStr type is defined in the asn1 CppTypes h header file as follows struct ASN1ITDynBitStr public ASN1DynBitStr ctors ASN1TDynBitStr numbits 0 ASN1TDynBitStr OSUINT32 _numbits OSOCTET _data 55 ASN 1 To C C Mappings ASN1TDynBitStr ASN1DynBitStr _bs ASN1ITDynBitStr 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 ASN 1 production lt name gt BIT STRING SIZE lt len gt Generated C code typedef struct OSUINT32 numbits OSOCTET data lt adjusted_len gt lt name gt If the strict size command line option is used the numbits component within this type definition may be of a different type OSUINTS8 or OSUINT16 or eliminated completely if the type is constrained to be a fixed size Generated C code typedef struct lt name gt OSUINT32 numbits OSOCTET data lt adjusted_len gt ctors ASN1T_ lt name gt ASNIT_ lt na
236. e 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 Using the Compiler Option Argument Description 3g13 None This option is used to generate code for encoding and decoding 3GPP Layer 3 messages Support is primarily provided for Non Access Stratum NAS message types as defined in 3GPP TS 24 007 24 008 and 24 301 LTE NAS As of this release only the C language is supported allow ambig tags None This option suppresses the check that is done for ambiguous tags within a SEQUENCE or SET type within a specification Special code is generated for the decoder that assigns values to ambiguous elements within a SET in much the same way as would be done if the elements were declared to be in a SEQUENCE This option used to be called noAmbigTag appInfo lt items gt This option only has meaning when generating an XML schema definitions XSD file using the xsd option It instructs the compiler to generate an XSD application information section lt appinfo gt for certain ASN 1 only items The items are specified as a comma delimited list Valid values for items are tags enum and ext lt items gt is an optional parameter If it is not specified it is assumed that application information should be produced for all three item classes ASN 1 tags ASN 1 enumerations and extended elements array none Th
237. e 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 134 Generated Encode Decode Function and Methods 3 If a match 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 i 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 If a 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 object definition and will fully decode all type fields and store pointers to the decoded type variables in the ASN1TObject decoded fields
238. eaeeeeesereseeeesenereeenes 144 Built in Compact Memory Management 0 00 cece cece cece eeceeece ence eeceeeseeeeaeeea essa sean ecu eeaeeeneeeeeees 146 Low Level Memory Management API eee cece cece cence ence eeeeeceeceeeeeeeeaecea esau eeaa sean eeae esas 146 C Memory Mangement csie meniere hoses dss sepa PNE EO SEE E dts edesedesssoesieeiocasesseoteadsedoans 147 Memory Security ssrin cat oieee Ee e Oe A ease Mei ee ees aoa 148 iv ASNIC Sale Memory COPY ssp sscasses eea a shay esos gs ny cou ahe EAA VEO ER aes oe EEA ESES ESPES 148 Zero ON BVOC seirer ete ise PANU alae Beets Sea sts be nt atgtbehl ls ode ate ory ab Say aa Re ate teal Be 148 9 Generated BER VFUNCHONS Jon csacsos sages done face sane baat dae e nawalh as Gu e See se OLA eee ease ores thas dove leur dur ebh Gage aaesaaube 150 Generated BER Encode Functions 20 00 00 ccc ccee cece cece cn cece cece cena eens E AE a EE AE E seen eeaeeeaes 150 Generated C Function Format and Calling Parameters 0 ccecccseeceeeeeeeeeceneeeeees 150 Generated C Encode Method Format and Calling Parameters eccceeeeeceeeceeece nese eeee eee 154 Generated BER Streaming Encode Functions 0 cceceee cece scence nce eceeeeeeeeeeeceeeeaeseu esau sean eeu eegs 158 Generated Streaming C Function Format and Calling Parameters o oo 158 Generated Streaming C Encode Method Format and Calling Parameters o oo 161 Generated BER Dec
239. eamFileAttach e rtxStreamSocketAttach e rtxStreamMemoryCreate e rtxStreamMemoryAttach 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 It is also possible to use a simplified form of these function calls to create a writer interface to a file memory or socket stream rtxStreamFileCreate Writer e rtxStreamMemoryCreate Writer rtxStreamSocketCreate Writer 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 rtxStreamClose function A program fragment that could be used to encode an employee record is as follows include employee h include file generated by ASNIC int main int stat OSCTXT ctxt Employee employee typedef generated by ASNIC const char filename message dat 159 Generated BER Functions Step 1 Initialize the context and stream if berStrmInitContext amp ctxt 0 initialization failed could be a license problem printf context initialization failed check license n return 1 Step 2 create a file stream object within the context stat rtxStreamFileCreateWriter amp ctxt f
240. ecode Functions Generated C Function Format and Calling Parameters The format of the name of each decode function generated is as follows MDERDec_ 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 follows status MDERDec_ lt name gt OSCTXT pctxt lt name gt pvalue In this definition lt name gt denotes the prefixed production name defined above The pct xt 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 rt InitContext run time function before use 205 Generated Medical Device Encoding Rules MDER Functions The pvalue argument is a pointer to a variable of the generated type that will receive the decoded data The function result variable status returns the status of t
241. ectidentifierMatch amp E Information Object Classes W EE Information objects GF t Information object sets H fe UsefulDefinitions Once a schema has been validated or compiled in ACGUI the ASN 1 Tree window provides an interactive view of the ASN 1 types defined in it At the top level of the tree the modules of the schema are shown Each of these modules can be expanded to reveal branches for the types values information objects etc defined in each of them Clicking on any node of the tree will show the relevant ASN 1 definition in a built in browser in the editor window 40 ASNI1C GUI Users Guide Error Log Window Error Log Clear Q 1 Validation was successful The Error Log window displays messages related to schema validation and compilation Whenever a schema is successfully validated or compiled the Error Log will report a success If an error occurs an error message will be displayed In many cases an error will be associated with a particular portion of the schema being compiled In these cases clicking on an error will open the schema editor to the location that the error occurred If more than one error is reported clicking the Next Error and Previous Error buttons in the toolbar will move the editor window to the part of the schema where the next or previous error occurred When the reported errors are no longer needed they can be cleared by clicking the Clear button in the Error Lo
242. ed for A class ASNIC_B public ASNIC_A These intermediate classes are also derived from the ASNICType 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 is a reference to a variable of the generated type The constructor takes two arguments an Asn MessageBufferlF 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 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 ASNI 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 causes a number of additional methods to b
243. edure for Using the Streaming 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 ASNIBERDecodeStream 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 ASN1C generated control class and to invoke and then to invoke that object 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 include rtbersrc ASNIBERDecodeStream h include rtxsrc OSRTFileInputStream h main ASNITAG tag int i len const char filename message dat OSBOOL trace TRUE Decode ASN1IBERDecodeStream in new OSRTFileInputStream filename if in getStatus 0 in printErroriInfo return 1 if in peekTagAndLen tag len 0 printf peekTagAndLen failed n in printErroriInfo return 1 Now switch on initial tag value to determine what type of message was received switch msgtag case TV_PersonnelRecord
244. eee EO E SE ste shees 251 L7 Mapping CSN Tto ASN erien see teagns hs Soest dowel thcth a r bee yy eeaiesd one tea cbs Sumalelegy Seamus pe tumest IE 253 TMtrOGUCHION iniaenoi E aE E tweed E E E E ed eaa ea cublies E N E Ni 253 CreneralsProcedure asczdeshsaserrves e a a a a e a a eed wage e EE 254 Mapping CSN 1 name to ASN 1 identifier 2 0 0 eee c cece cece ne ce ence eeeeeceeeeeeseaeeea esau eens eeae esas 254 Mapping CSN 1 name to ASN 1 typereference 2 0 0 0 lec ce cece cc ee ce eece ence eeeeeeceeeeaeeeaeeeaeeaa sean eeaes 255 ASN 1 Identifier Assignment 2 3 332 5sciccees ues eek neat nos eded raa des E A R aa OET E N E DNR 255 CSN1String Mapping Procedure esie emne e ae dba degen edeweg ceed sdods euudass cas ceaweetueatetadeentess 256 Alternation Mapping Procedure ionis a o ce cene E EE e a S EE ER esas 256 DISKE AATE aTe a LAE AAE EE S E EAS A E E A ENE AE E E A EE 260 Concatenation Mapping Procedure sosser in inn E E a E EE A E E E S 261 Exponential Mapping eare a e aa ae e R E N E E seek Sn ve S E Ne 263 Intersection Procedures siniseen ana EE E AEA VEAN EE EE AEA A na ae 264 Intersection Analysis Procedute sossen neson enre o E seas EE N E EEEE EENES e 264 Intersection Mapping Procedure no annoa aE E E E OE E A I A E 265 Patera Mapping senean e a E a a a tins aa E doar lant a a E E AaS 265 Re ference Mappih imion e E E T oddly E T E E a EE A N ERa Enay 266 Send Mappine enkaa e e E N a a E E E AE E EA sends deeds
245. eger 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 0o 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 This will cause the compiler to generate the following type declaration 54 ASN 1 To C C Mappings typedef const char SecurityKeyType The SecurityKeyType variable can now be populated with a hexadecimal string for encoding such as the following SecurityKeyType secKey 0xfd09874da875cc90240087cd12fd Note that in this definition the 0x 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 f
246. element3 would be expanded into the union structure as is shown The lt SelectorEnumType gt would be an enumerated type that is generated to represent each of the choices in the referenced information object set The union then contains an entry for each of the possible types as defined in the object set that can be used in the open type field Comments are used to list the fixed type fields corresponding to each open type field An example of the code that is generated from the S1AP sample ASN 1 snippet above is as follows typedef enum 89 ASN 1 To C C Mappings zj kal ES T_S1AP_PDU_Descriptions_S1AP_EL T_S1AP_PDU_Descriptions_S1AP_EL T_S1AP_PDU_Descriptions_S1AP_EL CEC SLAP_ELEMENTARY_PROCEDURE_TVALUE ENTARY_PROCEDURES_handoverPreparation ENTARY_PROCEDURES_handoverResourceAllocation ENTARY_PROCEDURES_pathSwitchRequest zj Ral ES zj a A ES zI typedef struct InitiatingMessage ProcedureCode procedureCode Criticality criticality k k information object selector Ef S1AP_ELEMI 7 NTARY_PROCEDURE_TVALUE t S1AP ELEMENTARY PROC E union procedureCode id HandoverPreparation criticality reject HandoverRequired handoverPreparation A DURE information objects procedureCode id HandoverResourceAllocation criticality reject xiy Ha
247. emF ree rtxMemHeapFreeAl1 Free all memory in context rtxMemFreePtr rtxMemHeapFreePtr 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 implement a custom memory management scheme This is done by implementing some or all of the C rt xMemHeap functions defined in the following interface note a default implementation is shown that replaces the ASN1C memory manager with direct calls to the standard C run time memory management functions include lt stdlib h gt include rtxMemory h Create a memory heap int rtxMemHeapCreate void ppvMemHeap 144 Memory Management in C C return 0 Allocate memory int rtxMemHeapAlloc void ppvMemHeap int nbytes return malloc nbytes Allocate and zero memory int rtxMemHeapAllocZ void ppvMemHeap int nbytes return calloc nbytes 1 Free memory pointer int rtxMemHeapFreePtr void ppvMemHeap void mem_p free mem_p Reallocate memory int rtxMemHeapRealloc void ppvMemHeap void mem_p int nbytes_ return realloc mem_p nbytes_ Free heap memory reset all heap variables void rtxMemHeapFreeAll void ppvMemHeap There is no analog in standard memory management Free heap memory reset all heap variables and free heap
248. ement This means MyType can either reference MyBaseElement or MyExtendedElement As per X 694 ASNIC generates a special type that acts as a container for all the different possible elements in the substitution group This is a choice type with the name lt BaseElement gt _group where lt BaseElement gt would be replaced with the name of the subsitution group head element MyBaseElement in this case The generated C type definitions for the above XSD definitions follow typedef const OSUTF8CHAR MyBaseElement typedef const OSUTF8CHAR MyExtendedElement define T_MyBaseElement_group_myBaseElement 1 define T_MyBaseElement_group_myExtendedElement 2 typedef struct EXTERN MyBaseElement_group int t union PR tos 1 MyBaseElement myBaseElement t 2 MyExtendedElement myExtendedElement MyBaseElement_group 113 XSD to C C Type Mappings typedef struct EXTERN MyType MyBaseElement_group myBaseElement MyType typedef MyType MyElement In this case if MyE lement or MyType is used it can be populated with either base element or extended element data 114 Chapter 6 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
249. ement with the name units bitslbytes gt length of type INTEGER that is the first element in a SEQUENCE This indicates special processing should be done on the element On encode any value populated in this field will be ignored and the actual length of the encoded data will be calculated and populated in this field after encoding is complete On decode this element is used to determine when end of message occurs The bitFieldLength attribute is used to specify the field size if it not an even octet 8 bits The units attribute specifies the units stored in the length field bits or bytes This item is only supported for C 3GPP layer 3 code generation lt is3GVarLenList n a This item specifies that this element will be modelled lengthElem name gt as a 3G variable length list This can only be applied to elements of type SEQUENCE OF It is used in 3G layer 3 messages when a length element is used to determine the number of items in the list The lengthElem attribute specifies the element within the structure that contains this count This item is only supported for C 3GPP layer 3 code generation 28 Using the Compiler Name Values Description lt isBigInteger gt lt isOpenType gt n a n a This item specifies that this element 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 u
250. ementation 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 expat sourceforge net 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 A diagram showing the components used in the XML decode process is as follows Step 1 Generate code C header file struct MySeq int a bool b char c hi C source file startElement characters endElement Step 2 Build Application XML document Populated data var ASNIC generated SAX handlers ASNIC generates code to implement the following methods defined in the SAX content handler interface startElement 220 Generated XML Functions charac
251. enerated OER Decode Functions OER encode decode functions are generated when the oer switch is specified on the command line For each ASN 1 production defined in the ASN 1 source file a C OER decode function is generated This function will parse the data contents from an OER encoded ASN 1 message and populate a variable of the corresponding type with the data Generated C Function Format and Calling Parameters The format of the name of each generated OER decode function is as follows OERDec_ 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 follows status OERDec_ lt name gt OSCTXT pctxt lt name gt pvalue In this definition lt name gt denotes the prefixed production name defined above The pct xt 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 somewher
252. enerated type The third 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 EXPL 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 ASNJ 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 OSCTXT pctxt lt ProdName gt value int asnlPD_ lt ProdName gt OSCTXT 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
253. ent they apply to C Standard Library Containers for SEQUNCE OF Type As noted above cpp11 can be used among other things to specify that std list should be used for SEQUENCE OF types where a linked list would otherwise be used while other C Standard library containers e g std vector can be specified by using a configuration file When a C STL class is used the generated C code will resemble the following typedef std list lt ASN1T_ lt ElementTypeName gt ASN1T_ lt SeqOfTypeName gt The contained type will always be a pointer type Generation of Temporary Types for SEQUENCE OF Elements As with other constructed types the lt type gt 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 production The format of this temporary type name is as follows 72 ASN 1 To C C Mappings 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 SE
254. ents 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 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 also make it possible to create an optimized print to string capability by maintaining a structure that keeps track of the current end of string position in the output buffer The generated print to string functions always must use the strlen run time function to find the end position an operation that becomes compute intensive in large string buffers that are constantly appended to 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 277 Additional Generated Functions 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
255. eo hase eieb ends laa ed te nade sd TEER 198 Generated C Function Format and Calling Parameters cccccecceec eee eece ence eecneeea seca sean scans 198 Populating Generated Structure Variables for Encoding 1 c1ccsecc usec nsec nece eect ence eeeeeeeeeeenees 198 Procedure for Calling C Encode Functions cccccecccvec ence cece nce n nce eccneeeeeceeeceeseeeseaeseaeeeaes 198 Generated OER Decode Functions esser iena cece cece cece cece cece ce eene cena cea EAO E E O EEES rS 200 Generated C Function Format and Calling Parameters scccsecceec eee ence teen eeeeeeca seca sean scans 200 Procedure for Calling C Decode Functions 0 cccccseceeecceecceece ee ceeeeeeeeaeeca ceca eeu ecaeeeneeenees 201 12 Generated Medical Device Encoding Rules MDER Functions 00 ceceeceeeeeececeeecereecereeesereeenenes 203 Generated MDER Encode Functions e cece cece cece e E E eeca cece eeae eeu E E I E SES 203 Generated C Function Format and Calling Parameters e ccc cece cece eeeceeece teen seen seca eenneeues 203 Procedure for Calling C Encode Functions 0 0 0 0 00 ccc ecceee cece cece ecc ne ceeeceeceeneeeeeeeeeeeeeeseaeeeaes 203 Encoding a Series of Messages Using the C Encode Functions cccseceeseeceeneeeeescenueeeenees 205 Generated MDER Decode Functions 20 0 0 ccc ner na cece ence ence E E eeea sean eeu R ROS 205 Generated C Function Format and Calling Parameters
256. equired to disambiguate elements in a SEQUENCE or SET ASN W DUPLICATE ASN W DUPLTAG The referenced type or value was previously defined The referenced tag was previously defined in a CHOICE or SET this happens when an contextual tag is provided more than once ASN E UNRECTYP The type described is not recognized by the compiler ASN E MULTDEF A choice tag has multiple definitions ASN E UNDEFVAL ASN E INVTYPNAM The referenced value is not defined or cannot be found Invalid type name This is a parsing failure all type names must begin with an uppercase letter ASN E UNDEFTAG The referenced type must be tagged in this context ASN E UNKNOWN Undocumented error occurred in routine A status value is provided with this error message to help locate the cause of the failure ASN I NOCASE ASN E IMPFILOPN A case statement for the named object was not generated The compiler was unable to open the named import file ASN E IMPFILPAR The compiler was unable to parse the named imported module ASN E IMPNOTFOU The named type was not found in the import module as specified in the IMPORT statement ASN E INVCNSTRNT ASN W INVOBJNAM Invalid constraint specification Invalid object name The object name must begin with a lowercase letter ASN E SETTOOBIG Set contains more than 32 elements 297 ASNIC Error Codes Error Code Error Descrip
257. er 3 Encode Functions 3GPP Layer 3 encode decode functions are generated when the 3g 3 switch is specified on the command line For each ASN 1 production defined in the ASN 1 source file a C 3GPP Layer 3 encode function is generated This function will convert a populated C variable of the given type into a 3GPP layer 3 encoded message C is not directly supported for 3GPP Layer 3 however it is possible to call the generated C functions from a C program Generated C Function Format and Calling Parameters The format of the name of each generated 3GPP layer 3 encode function is as follows x3GL3Enc_ 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 It is also possible to change the x3GL3 prefix at the beginning of the function name by using the lt protocol gt configuration setting For example an API was generated for the Non Access Stratum NAS protocol within the ASNIC package A protocol setting of NAS was used for this so all encode function names begin with NASEnc_ instead of x3GL3Enc_ The calling sequence for each encode function is as follow
258. eral 010 lt Naming gt lt pg determinant bit 3 gt exclude 010 lt something else bit 4 gt gt lt stereo choice 1 0O lt first bit 1 gt 1 lt second bit 2 gt gt lt stereo choice 2 00 01 lt first bit 1 gt 11 lt second bit 2 gt lt third 10 gt gt lt optional with presence bit 0 1 lt maybe bit 4 gt gt lt optional with presence bit and container determined null 0 1 lt possibly bit 3 gt gt lt optional container determined null lt questionable bit 2 gt gt i lt padding gt lt bit gt send 0 lt Length Constrained Content gt lt length bit 7 gt lt willy nilly bit 4 gt ff OS E BEEE a lt padding gt amp octet val length lt Concat gt lt el bit 1 gt 271 Compiling CSN 1 This nesting will get removed lt e2 bit 2 gt lt e3 bit 3 gt lt e4 bit 4 gt lt a pad bit lt bit gt send 0 gt lt some literal bits 0101 bit gt lt single bit lt single octet lt ref to a name octet gt Naming gt 001 gt 1 lt two bit value using more done bit bit 2 gt 0 1 lt two bit value using more done bit bit 2 gt 0 gt lt value bit lt list ending with container bit 3 gt lt named list lt list of 10 Truncated concatenation lt Truncated Concat gt lt el bit 1 gt 4 gt 10 gt This nesting wi
259. erated C C Source Code 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 asnID_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 asn PE_ and asn PD_ for encoder and decoder respectively XER function prototypes begin with asnIXE_ and asn1XD_ A sample section from a C header file for the same production is as follows RR KR KKK KK KR KI RR I I OR RK I OR OR KK EmployeeNumber ef i 7 RR KR KR KKK KK KK RK RR RI OR RK I OR RK define TV_EmployeeNumber TM_APPL TM_PRIM 2 typedef OSINT32 ASN1T_EmployeeNumber class EXTERN ASN1C_EmployeeNumber public ASN1CType protected ASN1T_EmployeeNumber amp msgData public ASN1C_EmployeeNumber ASN1T_EmployeeNumber amp data ASN1C_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 t EncodeTo ASN1MessageBufferIF amp msgBuf t DecodeFrom ASN1MessageBufferIF amp msgBuf EXTERN in ASN1T_ asnlE_EmployeeNumber
260. ere 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 transferring 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 sre directories on the target platform note if transferring 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 the installation to the build_lib subdirectory on the target platform note if transferring 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 a CC C compiler executable name 18 Using the Compiler b CCC C compiler executable name c 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
261. erpretation of the literal 2 When a component is created for this type it shall be given a DEFAULT of k However the component must be present in the encoding The DEFAULT is added due to the inner workings of our code generator 3 The encoding of this type is the literal bit string Reference Mapping This procedure only applies when invoked by another procedure 1 If the reference is to bit the string is mapped to the ASN 1 type INTEGER 0 1 2 Otherwise if the referenece is to octet the string is mapped to the ASN 1 type INTEGER 0 255 3 Otherwise if the reference refers to a string that is mapped to something other than an ASN 1 type or ASN 1 component then the reference is mapped the same as the string that is referenced e g to padding 4 Otherwise the reference is mapped to an ASN 1 DefinedType where the typereference is the result of using the CSN 1 name to ASN 1 type reference mapping on the referenced name Note that in the case where the mapping produces an DefinedType that type might not be defined in the CSN 1 module Our tool support is such that the type may be defined in ASN 1 using the same module name or it may be imported from another ASN 1 module where the definition may originate in either ASN 1 or CSN 1 Note that our tool issues a warning when a reference is made to a string that we mapped to a type which we assumed based on the presence of padding was to be byte aligned The reason for this
262. ers who have the source code version of the run time The only difference in this API with what is described above is that tracking of allocated memory is done through the context This makes it possible to provide an implementation of the rt xMemHeapF reeA11 function as described above This memory management scheme is slower than the default manager i e nibble based but has a smaller code footprint This form of memory management is enabled by defining the MEMCOMPACT C compile time setting This can be done by either adding D_MEMCOMPACT to the C compiler command line arguments or by uncommenting this item at the beginning of the rt xMemory h header file Uncomment this definition before building the C or C run time libraries to enable compact memory management This will have a smaller code footprint than the standard memory management however the performance may not be as good Ey define _MEMCOMPACT 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 Using different core functions may be necessary on some systems that do not have the standard C run time functions malloc free and realloc or when extra functionality is desired To replace the core functions use the rtxMemSetAllocFuncs runtime library call void
263. es 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 AGNU 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 124 Generated C C Source Code 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 project exists within the ASNIC installation directory tree The generation logic tries to determine the root directory of the installation by travers
264. es may be truncated in the encoding If the string inside the curly braces is a Concatenation any member of that Concatenation along with all subsequent 248 CSN 1 Described members may be absent Note that if any member is itself enclosed in curly braces that member is present or absent as a whole That is lt a gt lt b gt lt c gt lt d gt can match ab but not abc 4 OptionalString is the syntax for an optional string but we do not currently support this We have not encountered any use of this notation in 3GPP technical specifications CSN1String CSN1String SendExpression Alternation Intersection Exclusion Concatenation BASIC_NAME ExponentExpr BasicString ExponentExpr ACSN 1 string defines a set of acceptable bit strings Strings are combined using various operations These operations are given in order of precedence highest to lowest Table 16 1 CSN 1 Operations from highest to lowest precedence exponentiation an exponent is applied to indicate repetition concatenation exclusion disallowing certain strings that would otherwise be accepted alternation intersection error alternatives send specifying a particular string the encoder should send allowing decoders to accept other strings too The BASIC_NAME in the sixth alternative shall not be a multi word name Alternation Alternation CSN1String CSN1String CSN1String Sor
265. espace gt is namespace URI if not given no target namespace declaration is added useAsnlxXsd reference types in asnl xsd schema license options lickey lt key gt set license key value To use the compiler at a minimum an ASN 1 or XSD 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 asncode gt will compile all ASN 1 files in the current working directory It is also possible to provide a list of source files by adding all file specifications to a text file one per line and then providing the path to the text file prefixed with an character 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 T 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 lists all of the command line options and what they ar
266. esults to populate the data variables with the decoded data Note that for XML code generation xml command line option the SAX handler interface is not generated That is because XML decoders use a pull parser instead of SAX code to parse the XML input stream 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 endElement 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 129 Generated Encode Decode Function and Methods contents of various messages that are allowed in a particular exchange of messages The ASN1C compiler extracts the types in
267. etation depends on whether there was a length determinant or not If there was a length determinant with units in octets the encoder shall pad using the pad bit so that the length of the length constrained content is a multiple of 8 bits If the units were bits the encoder need not do any padding In both cases a decoder must be prepared to skip any padding bits If there is no length determinant we assume the encoding of the SEQUENCE should be padded to a mulitple of 8 bits 6 Otherwise if asnlobjects has a single member the Concatenation is mapped to that same item whether it is an ASN 1 type or ASN 1 component Exponential Mapping This procedure is invoked for a string having an exponent It is only invoked when called for by another procedure 1 If the exponent is constant and evaluates to 1 map the string as if the exponent were not present 2 Otherwise if the base is a reference to bit and the exponent is constant and less than or equal to 32 this procedure produces type INTEGER 0 k where k 2exponent 1 The encoding for this type encodes the integer in binary in exponent bits 3 Otherwise if the base is a reference to bit and the exponent is variable or greater than 32 this procedure produces type BIT STRING The size constraint clause below applies 4 Otherwise if the base is a reference to octet this procedure produces type OCTET STRING The size constraint clause below applies 5 Otherwise invoke the CSN
268. ex 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 rtxMemFree call The rtxtMemAlloc 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 OSCTXT structure is passed in addition to the number of bytes to allocate All allocated memory is tracked within the context structure so that when the rtxMemF ree 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 is 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 1 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 performi
269. example an attribute was expected Invalid number of occurrences This status code is returned by the decoder when an XML instance contains a number of occurrences of a repeating element that is outside the bounds minOccursmaxOccurs defined for the element in the XML schema RTERR_INVMSGBUF Invalid message buffer has been passed to decode or validate method This status code is returned by decode or validate method when the used message buffer instance has type different from OSMessageBufferIF XMLDecode RTERR_DECELEMFAIL Element decode failed This status code and parameters are added to the failure status by the decoder to allow the specific element on which a decode error was detected to be identified RTERR_DECATTRFAIL RTERR_STRMINUSE Attribute decode failed This status code and parameters are added to the failure status by the decoder to allow the specific attribute on which a decode error was detected to be identified Stream in use This status code is returned by stream functions when an attempt is made to initialize a stream or create a reader or writer when an existing stream is open in the context The existing stream must first be closed before initializaing a stream for a new operation RTERR_NULLPTR Null pointer This status code is returned when a null pointer is encountered in a place where it is expected that the pointer value is to be set RTERR_FAILED General failure Low level
270. examples The send operator has the lowest precedence of the operators this seems to be frequently overlooked A common pattern of use is this null 0 bit lt no string gt 1 lt stuff gt which is equivalent to null 0 bit lt no string gt 1 lt stuff gt This is clearly wrong the encoder strings are not all accepted by the decoder string Most likely what they really wanted was null 0 bit lt no string gt 1 lt stuff gt In the remainder of this discussion the examples will be corrected for operator precendence Next consider this example null 0 bit lt no string gt 1 lt stuff gt null 0 bit lt no string gt 1 lt more stuff gt lt spare bit gt 269 Compiling CSN 1 This pattern of usage is meant to allow interoperability between releases It occurs at the end of an information element that must be a multiple of 8 bits The context means that we must be able to add padding bits at the end but the above doesn t allow an encoder to encode padding in all cases for example no padding can be encoded if you choose to omit stuff Let s say we correct this as follows null 0 bit lt no string gt 1 lt stuff gt null 0 bit lt no string gt 1 lt more stuff gt lt spare bit gt Now we can always add the necessary pad bits but what about the bit lt no string gt constructions On deco
271. ext 211 Chapter 13 Generated XML Functions Overview X 693 specifies XER XML Encoding Rules There are three variants of XER given BASIC XER often just XER for short canonical XER and EXTENDED XER Into this mix Objective Systems has added its own encoding rules which we ll call OSys XER OSys XER is very similar to XER but has a few variations that are meant to produce XML documents more closely aligned with what you might get if you were using XML Schema to specify your abstract syntax Generally OSys XER produces fewer tags The differences between these two sets of encoding rules are discussed in more detail below ASNIC supports BASIC XER canonical XER and OSys XER It has for some time supported EXTENDED XER via direct compilation of XSD In version 6 5 0 we have begun to add direct support for EXTENDED XER by adding support for some of the XER encoding instructions Nonetheless EXTENDED XER is most fully support today via direct compilation of XSD By compiling XSD you can obtain behavior much the same as with OSys XER and more Prior to version 6 5 1 ASNIC generated two different styles of code and had two different runtime layers for the various XML encoding rules In support of XER basic and canonical there was the XER style of generated code and the XER runtime In support of OSys XER and extended XER via direct compilation of XSD there was what we called simply the XML style of generated code and the XML
272. ext function OSCTXT ctxt context variable 177 Generated BER Functions if berStrmInitContext amp ctxt 0 initialization failed could be a license problem printf context initialization failed check license n return 1 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 rtxStreamFileOpen e rtxStreamFileAttach e rtxStreamSocketAttach e rtxStreamMemoryCreate e rtxStreamMemoryAttach 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 simplified version of the Open functions are the CreateReader functions e rtxStreamFileCreateReader e rtxStreamMemoryCreateReader e rtxStreamSocketCreateReader After initializing the context and populating 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 librar
273. f 2010 Visual Studio or Visual C For example specifying 2012 2005 will generate a project that links against libraries in the _vs2005 directory Not specifying a year will cause the compiler to link against libraries compiled for Visual Studio 2010 A custom build rule is generated that deletes the generated source files and then invokes ASNIC to regenerate them when a rebuild is done Doing a clean operation will cause the generated source files to be deleted a subsequent build will regenerate them For Visual C 6 0 project files you can see this build rule by locating the first ASN 1 file under the Source Files for the project right clicking it choosing Settings and then choosing the Custom Build tab For Visual Studio 2005 2008 2010 and 2012 project files the procedure to see the custom rule is very similar to that for Visual C 6 0 except that you choose Properties when you right click on the first ASN 1 file and then click on Custom Build Step or Custom Build Tool on the left w32 None This option is used with makefile and or Visual Studio project generation to indicate the generated file is to be used on a Windows 32 bit system In the case of makefile generation this will cause a makefile to be generated that is compatible with the Visual Studio nmake utility w64 None This option is similar to the w32 option documented above except that it specifies a Windows 64 bit system warnings None Output inf
274. f 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 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 tdefine T_ lt name gt _ lt elementl nam define T_ lt name gt _ lt element2 nam Vv NO FR typedef struct int Ei union lt typel gt lt element1 name gt lt type2 gt lt element2 name gt u lt name gt 0r 74 ASN 1 To C C Mappings typedef struct lt tempNamel
275. f constraint is as follows ContainingBS BIT STRING CONTAINING INTEGER ASNIC will generate a type definition that references the type that is within the containing constraint In this case that would be INTEGER therefore the generated type definition would be as follows typedef OSINT32 ContainingBS The generated encoders and decoders would handle the extra packing and unpacking required to get this to and from a BIT STRING container This direct use of the containing type can be suppressed through the use of the noContaining command line argument In this case a normal BIT STRING type will be used and it will be the users responsibility to do the necessary packing and unpacking operations to encode and decode the variable correctly ASN1CBitStr 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 ASN1CBitStr 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 ASNIT 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 ASN1CBitStr class inline as follows 58 ASN 1 To C C
276. f this type of function from the S1AP definitions is as follows al void asnlSetTC_HandoverRequired_protocolIEs_element_HandoverRequiredIEs_id_MME_UE_S1AP OSCTXT pctxt HandoverRequired_protocolIEs_element pElem MME_UE_S1AP_ID value Generated C Classes and Methods This section discusses items that are generated idfferently for C for union table constraints Choice Selector TVALUE Type For C an enumerated type is generated for each of the options in a type field union These correspond to each of the items in the information object set associated with the union For example the TVALUE type generated for S1AP_ELEMENTARY_PROCEDURES is as follows typedef enum T_S1AP_PDU_Descriptions_S1AP_ELEMENTARY_PROCEDURES_UNDEF_ T_S1AP_PDU_Descriptions_S1AP_ELEMENTARY_PROCEDURES_handoverPreparation T_S1AP_PDU_Descriptions_S1AP_ELEMENTARY_PROCEDURES_handoverResourceAllocation T_S1AP_PDU_Descriptions_S1AP_ELEMENTARY_PROCEDURES_pathSwitchRequest 7 SLAP_ELEMENTARY_PROCEDURES_TVALUE The generated names include the name of the module object set and object in order to ensure that no name clashes occur between enumerations with common names For C this type is generated as a class with TVALUE as a public member inside class S1AP_ELEMENTARY PROCEDURES public enum TVALUE T_UNDEF_ T_handoverPreparation T_handoverResourceAllocation
277. 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 1 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 by the nibble allocation algorithm can be changed By default this value is set to 4K bytes The run time function
278. ffer 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 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 Using the Compiler Option Argument Description 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 Note An al
279. 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 lt asnlModuleName gt Test c where lt asnI ModuleName 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_ 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 test function is as follows 282 Additional Generated Functions lt typeName gt pvalue lt testFunc gt OSCTXT pctxt In this definition lt testFunc gt denotes the formatted function name defined above The pct xt argument is 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
280. functions are also generated for each type that contains table constraints These functions have the following prototypes BER DER int asnlETC_ lt ProdName gt OSCTXT pctxt lt ProdName gt pvalue int asnlDTC_ lt ProdName gt OSCTXT pctxt lt ProdName gt pvalue PER int asnlPETC_ lt ProdName gt OSCTXT pctxt lt ProdName gt pvalue 133 Generated Encode Decode Function and Methods int asnlPDTC_ lt ProdName gt OSCTXT 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 foundation 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
281. g window Project Settings The project settings window is where details such as encoding rules target language and code features to generate are modified 41 Output Function Generation Application Language Type c kone rc r cas cce C Java F Target Java 1 4 I Targ Additional Translations F Generate HTML files for input ASN 1 Generate equivalent XML schema Pretty print ASN 1 Encoding Rules Iv BER f CER F DER F PER F SON F XER E XML F MODER fF m Perform a lax syntax check Allow ambiguous tags ASNI1C GUI Users Guide The Output tab contains options for selecting a target language encoding rules output directory In order to compile a schema a target language must be selected under Application Language Type For C and Java more specific targets are available as well Additional Translations contains several options for generating transformed versions of the input schema such as HTML or pretty printed Encoding Rules allows for one or more encoding rule set to be selected for generated code Input Options affect how strict the compiler is when parsing the ASN 1 schema Enabling these options can cause unpredictable behavior in generated code but they may be useful under certain circumstances Depending on the target language selected additional options are shown C C Output Options Output code to c h filles based on module names
282. g 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 73 ASN 1 To C C Mappings Some SEQUENCE OF elements in constructed types are inlined In other words no temporary type is created instead either the OSRTDList reference for linked list or the array definition is inserted directly into the generated C structure This is particularly true when XSD files are being compiled 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 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 element name gt where lt name gt is the name of the ASN 1 production and lt element name gt is the name of the CHOICE alternative I
283. g is successful call xe_getp to fetch a pointer to the start of th ncoded message msgptr xe_getp amp ctxt else rtxErrPrint amp ctxt return msglen 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 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_getp Note that this is not the start of the allocated memory that is maintained within the context structure To free the memory either the rtxMemFree function may be used to free all memory held by the context or the xe_free function used to free the encode buffer only The following code fragment illustrates encoding using a dynamic buffer include employee h include file generated by ASNIC 152 Generated BER Functions main OSOCTET msgptr aint msgle
284. 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 lt include encoders names gt ASN 1 type names specified as an attribute list This item allows a list of ASN 1 types to be included in the generated code for which only encode functions will be generated lt include decoders names gt ASN 1 type names specified as an attribute list This item allows a list of ASN 1 types to be included in the generated code for which only decode functions will be generated lt include memfree names gt ASN 1 type names specified as an attribute list This item allows a list of ASN 1 types to be included in the generated code for which only memory free functions will be generated lt include importsFrom ASN 1 module name s This form of the include directive tells the compiler to only name gt specified as an attribute list include types and or values in the generated code that are imported by the given module s lt exclude types names ASN 1 type or values names This item allows a list of
285. gt typedef struct lt tempName2 gt typedef struct int ts union lt tempNamel gt lt elementl name gt lt tempName2 gt lt element2 name gt u lt name gt If the use enum types command line option is used an enumerated type is used instead of the define statements and integer t member variable as follows typedef struct enum T T_ lt name gt _ lt elementl name gt T_ lt name gt _ lt element2 name gt t union lt typel gt lt elementl name gt lt type2 gt lt element2 name gt u lt name gt If the static command line option or lt storage gt static lt storage gt configuration variable is set for the given production then pointers will not be used for the variable declarations Note 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 ASN1T_ 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 element 2 type gt respectively lt tempName1 gt and lt t empName2 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
286. h as consisting of function pointers The error event however is not part of this struct and must be defined separately 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 in C is as follows virtual void startElement const char name int index 0 virtual void endElement const char name int index 0 and in C typedef void rtxStartElement const char name int idx typedef void rtxEndElement const char name int idx 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 A5String NumericString PrintableString etc as well as for big integer values Note that this method is overloaded The second implementation is for 16 bit character strings These strings are represented as an array of unsigned short integers in ASNIC A
287. h 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 asn1ber asn per or asn1xer as well as the common run time functions library asnIrt 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 asnI ber_a lib asnIper_a lib or asnIxer_a lib for BER DER CER PER XER or XML 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 libasn1xml 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 lasn ber lasn1 per lasn1xer lasn1xml and or lasnIrt 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 asnilrt_a lib Static single threaded libraries These are built without MT multithreading asnlber_a lib and MD dynamic link libraries options These are not thread safe However asnlper_a lib they provide the smallest footp
288. haracter 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 file INTEGER and REAL value specifications cause define statements to be generated BOOLEAN Value 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 The INTEGER type causes a define statement to be generated in the header file of the form ASN1V_ 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 This mapping is defined as follows ASN 1 production lt name gt INTEGER lt value gt Generated code define ASN1V_ lt name gt lt value gt For example the following declaration ivalue INTEGER 5 will cause the following statement to be added to the generated
289. hat C s encoding is not empty if there are more bits to be decoded where C should appear If the encoding for C is empty C is absent e If C is absent the encoding of C consists of the determinant for the non type producing alternative When C is present the encoding consists of the determinant for the type producing alternative followed by the encoding for T C s type which will have been defined by the procedure that produced T f If C is absent and the encoder is permitted to and elects to use an empty encoding it is an error for an encoder to encode any bits within the same container i e you can t encode bits that the decoder might interpret as being an encoding for C 4 If the alternation matches the Optional component container determined pattern then the mapping produces an ASN 1 component C as follows a For this alternation pattern one of the alternatives would produce an ASN 1 type Let typeString be the remainder for that alternative which is the string that would produce the ASN 1 type b Invoke the CSN1String Mapping procedure for typeString This will produce an ASN 1 type T C s type shall be T C shall be an OPTIONAL component c The name of the component is derived from the CSN 1 but the CSN 1 does not always provide a name The calling procedure e g the Concatenation mapping procedure is ultimately responsible for assigning the name to the component This procedure merely assigns a CSN 1 name to the co
290. he common BER PER DER encode procedure A complete example showing how to assign an open type value in the legacy tables case is as follows Test DEFINITIONS BEGIN 135 Generated Encode Decode Function and Methods I ATTRIBUTE CLASS amp Type amp id OBJECT IDENTIFIER UNIQU WITH SYNTAX WITH SYNTAX amp Type ID amp id GI name ATTRIBUTE WITH SYNTAX VisibleString ID fe OR sal 3 oh name ATTRIBUTE WITH SYNTAX INTEGER ID fo Oe 2 oF of SupportedAttributes ATTRIBUTE name commonName Invoke SEQUENCE opcode ATTRIBUTE amp id SupportedAttributes argument ATTRIBUTE amp Type SupportedAttributes opcode END In the above example the Invoke 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 or 0 1 2 If the 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 SupportedAttri
291. he decode operation The return status will be greater than or equal to zero if decoding is successful or negative if an error occurs Return status values are defined in the asnitype h include file Procedure for Calling C Decode Functions This section describes the step by step procedure for calling a C MDER 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 OSCTXT 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 OSCIXT ctxt int stat stat rtInitContext amp ctxt if stat 0 rtxErrPrint amp ctxt rtFreeContext amp ctxt return stat The next step is to create a stream reader that will read from the given source In our example we read from a file but it is also possible to read data from a socket or other source as well 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 allocate
292. he general idea of how it is done Example 2 A Formatted Print Handler C As with the C version a C version of the sample is available in the c sample_per eventHandler directory A header file containing all function declaratios must be created In this example an initializePrintHandler AsnINamedCEventHandler printHandler const char varname function is also declared which will be used to populate the Asn NamedCEventHandler struct AsniNamedCEventHandler printHandler void initializePrintHandler AsnlNamedCEventHandler printHandler const char varname void finishPrint void indent void printStartElement const char name int index void printEndElement const char name int index 287 Event Handler Interface void printBoolValue void printIntValue OSINT32 OSBOOL value value A corresponding c file printHandler c in this case contains the definitions of these functions static int gs_IndentSpaces void initializePrintHandler AsnlNamedCEventHandler printHandler const char varname printHandler gt startElement amp printStartElement printHandler gt endElement amp printEndElement printHandler gt boolValue amp printBoolValue printHandler gt intValue amp printIntValue void printStartElement const char name int index indent printf name if index gt 0 printf
293. he name of the field without the leading amp lt TypeName gt would be replaced with the C type name for the ASN 1 Type 96 ASN 1 To C C Mappings 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 amp Type amp Parame amp id T CLASS terType OPTIONAL OBJECT IDENTIFIER UNIQU GI WITH SYNTAX amp Type ID amp id This would result in the following definition in the C source file ry class EXT protecte ASNIT ATTRI public virtu O virtu O OSBOO YE virtu O virtu O inlin rG 3 RN ATTRIBUT GI d ObjId id BUTE al int encodeBERType SCTXT pctxt ASN1TObject amp object 0 al int decodeBERType SCTXT pctxt ASN1TObject amp object 0 L isParameterTypePresent m ParameterTypePresent return TRUE else return FALSE al int encodeBERParameterType SCTXT pctxt ASN1ITObject amp object return 0 al int decodeBERParameterType SCTXT pctxt ASN1ITObject amp object return 0 e OSBOOL idEquals ASNITObjId pvalue turn 0 rtCmpTCOID amp id pvalue This assumes that only BER or DER was specified as the encoding ru
294. he 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 ISO IEC 8824 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 and ISO IEC 8825 1 standards e Packed Encoding Rules PER as published in the ITU T X 691 and ISO IEC 8825 2 standards Both aligned and unaligned variants are supported via a switch that is set at run time e XML Encoding Rules XER as published in the ITU T X 693 and ISO IEC 8825 3 standards e Medical Device Encoding Rules MDER as published in the ISO IEEE 11073 standards e Octet Encoding Rules OER as published in the NTCIP 1102 2004 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 decoders 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 As of release version 6 0 it is possible to com
295. he purpose of this procedure is to ensure that the Intersection matches a supported pattern and to identify aspects of the Intersection that will be used during the mapping procedure 1 The Intersection must have exactly two operands 264 Mapping CSN 1 to ASN 1 7 One of the operands must be a reference to bit or octet with a finite exponent This operand is the constraining operand it controls the length of the constrained operand in terms of the number of bits octets The other operand is the constrained operand The exponent on the constraining operand being finite will either be a fixed integer expression e g 4 or 5 4 or it will use a function passing a label name for the argument If a function is used the exponent must be reversible and the referenced label must be defined within the enclosing definition such that it will appear in the encoding prior to the constrained operand We call the referenced labeled string the length determinant for the constrained operand The definition of a reversible exponent see next clause has the effect of ensuring there will be a single referenced label An exponent is reversible if given the length of the constrained operand an encoder can uniquely determine the value of the label that is referenced by the exponent This precludes using a user defined function in the exponent or referring to more than one label Relaxing the requirement for exponent reve
296. her applications may use them for their oan purposes but this will ngg con gtendiong and modifications needed to maintain or improve the Direchory sarviog a ID sm OHJECT IDENTIFIER 13 ds ID n jimit ds 3 Banm onan a wm 13 categories of information object a module ID ds 1 n sericeElement ID i ds 2 applicationContest IO n ds 3 atiributetpe ID ds 4 atiributeSyntax IO ae 5 objectClass ID n ds 8 28 attributeset ds 7 29 algorithm I sm es ra a abaimactayntax ID ism ds 9 34 object am de 10 aa port Bice de 11 38 dsadperstional ttribute 1D ds 12 mateh nrgRule ID de 13 4 knowtedgeMatchingRule iO 1m d 14 E namerorm em d 153 a group ID p fds 5 37 ASNIC GUI Users Guide Editor ACSE L asn C InformationFramework asn UsefulDefinitions asn E 2 UsefulBefinitions joint iso tu ds 5 module l usefulBefinitions 0 3 3 DEFINITIONS 4 BEGIN gt 6 EXPORTS All 7 The types and values definec ed for use in the other ASN 1 module B withir n Jakes Director which will use them 9 Directory sen ut this will nat LO amp ntersio Ins and TI D OBJECT IDENTIFIER 12 13 ds ID joint iso tut ds 5 14 15 categories of information object 16 module ID ds 1 17 18 serviceElement ID ds 2 19 20 applicationContext ID ds 3 21 22 attributeType ID ds 4 23 24 attr
297. hin 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 13 Using the Compiler Option Argument Description 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 all keyword may be specified for lt typeName gt to indicate that all productions within an ASN 1 module should be treated as PDU types per None This option is used to generate encode decode functions that implement the Packed Encoding Rules PER as specified in the ASN 1 standards perindef None This option is used to generate encode decode functions that implement the Packed Encoding Rules PER as specified in the ASN 1 standards including support for indefinite fragmented lengths prtfmt bracetext details Sets the print format for generated print functions The details option 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 br
298. his option is used to generate code for strict validation of table constraints By default generated code will not check for value field constraints None This option causes strict interpretation of size constraints to be enabled This may result in the generation of more optimized code as unnecessary size variable holders are eliminated For example a declaration of OCTET STRING SIZE 10 will result in the generation of a 10 byte static array rather than a structure with a count field and array syntaxcheck None This option is used to do a syntax check of the ASN 1 source files only No code is generated table unions None This option is used to generate union structures for table constraints in C C instead of void pointers as is done when the tables option is used These are generally easier to use as they present all options in a user friendly way targetns lt namespace gt This option only has meaning when generating an XML schema definitions XSD file using the xsd option It allows specification of a target namespace lt namespace gt is a namespace URI if it is not provided no target namespace declaration is added to the generated XSD file 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
299. his 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 include employee h include file generated by ASNIC main 216 Generated XML Functions ea H OSOCTI msgbuf 4096 int msglen stat OSCTXT ctxt OSBOOL cxer FALSE OSBOOL aligned TR Employee employee canonical XER flag UE typedef generated by ASNIC Initialize context and set encode buffer pointer if rtInitContext amp ctxt 0 rtxErrPrint amp ctxt 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 0 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 Procedure for Using the C Control Class Encode Me
300. his structure the developer must test the flags to determine if the element was provided in the message or not The generated C structure will contain a constructor 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 is 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 67 ASN 1 To C C Mappings 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 specify default value selected If this is done a value is not encoded into the message On the decode side the developer must test for present bit not set If this is
301. hod 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 221 Generated XML Functions 1 Prepare a context variable for decoding 2 Open a stream 3 Call the appropriate compiler generated decode function to decode the message 4 Free the context after use of the decoded data is complete to free allocated memory structures Before a C XER decode function can be called the user must initialize a context variable This is a variable of type OSCTXT 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 rtxStreamInit function OSCTXT ctxt context variable if rtInitContext amp ctxt 0 initialization failed could be a license problem printf context initialization failed check license n return 1 rtxStreamInit 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 func
302. hould 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 lt 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 0 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 0 decoding successful data in employeeData 172 Generated BER Functions process received data else error processing 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 mployee 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 decode performance These include adjusting memory allocation parameters using compact code generation using decode
303. iable 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 lt name gt _data lt data gt 84 ASN 1 To C C Mappings A hexadecimal string would be the same except the ASN 1 constant would end in a H Character String Value A character string declaration would cause aC or C const char declaration to be generated ASN 1 production lt name gt lt string type gt lt value gt Generated code const char lt name gt lt value gt In this definition lt string type gt could be any of the standard 8 bit characters string types such as A5String PrintableString etc Note Code generation is not currently supported for value declarations of larger character string types such as BMPString Object Identifier Value Specification Object identifier values 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 ASNI1OBJID lt name gt lt value gt For example consider the following declaration oid OBJECT IDENTIFIER ccitt b 5 10 This would result in the following definit
304. ibuteSyntax ID ds 5 25 26 objectClass ID ds 6 27 268 attriputeset D st as 7 29 acute ID ds 8 30 31 abstractSyntax ID ds 9 33 object ID ds 10 34 port ID ds 11 35 dsaQperationalattribute ID 36 ds 12 37 38 matchingPule ID ds 13 39 40 knowledgeMatchingRule ID ds 14 4 42 nameForm ID ds 15 43 44 group ID ds 16 38 ASNI1C GUI Users Guide The central part of the ACGUI window is the schema editor From here schema files can be viewed and edited To begin editing an ASN 1 schema create a new file or open an existing file via the toolbar or menu The file will be added to the current project and shown in the editor The editor window is also used to display a schema browser for navigating a validated schema To display the browser after validating a schema click on an item in the ASN 1 Tree window The browser will display a hyperlinked version of the schema centered on the definition of the selected item Clicking the names of other defined types in the browser will cause their definitions to be shown By default documents are displayed in tabs in the editor Tabs Text and Browser at the bottom of the window are for schema editing and hyperlinked schema browsing respectively At the top of the Text tab each schema file currently being edited has a tab Alternatively ACGUI can display documents in separate subwindows To change this select Too
305. idual 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 0perationCode 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 message header Invoke SEQUENCE invokeID INTEGER opcode OPERAT
306. if you have not updated your PATH variable you will need to enter the full pathname asnlic You should observe the following display or something similar ASN1C Compiler Version 6 8 x Copyright c 1997 2015 Objective Systems Inc All Rights Reserved Usage asnlc lt filename gt lt options gt lt filename gt ASN 1 or XSD source filename s Multiple filenames may be specified and wildcards are allowed language options generate C code C generate C cod ctt 11 generate C code that uses C 11 features c generate C code java generate Java code cldc generate Java ME CLDC compatible 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 oer generate OER encode decode functions mder generate MDER encode decode functions per generate PER encode decode functions uper generate unaligned PER encode decode functions xer generate XER encode decode functions xml generate XML encode decode functions json generate JSON encode decode functions 3g13 generate 3GPP layer 3 encode decode functions basic options asnl lt file gt generate pretty printed ASN 1 source code asnstd lt std gt set standard to be used for parsing ASN 1 source file Possi
307. ilename if stat 0 rtxErrPrint amp ctxt return stat Step 3 Populate the structure to b ncoded mployee name 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 0 error processing rtxStreamClose amp ctxt In general streaming encoding is slower than memory buffer based encoding However in the case of streaming encoding it is not necessary to implement code to write or send the encoded data to an output device The streaming functions also use less memory because there is no need for a large destination memory buffer For this reason the final performance of the streaming functions may be the same or better than buffer oriented functions Encoding a Series of Messages Using the Streaming 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 streaming 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
308. ill 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 ASN1C 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 an element to be an open type by using the lt isOpen
309. in the table at the end of this section The specification of an individual production is done using the lt production gt lt production gt tag pair This tag pair can only be nested within a lt module gt 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 lt production name MyProd gt 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 is always used For example assume a lt t yoePrefix 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
310. ine 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 191 Generated PER Functions 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 follows status asnlPD_ lt name gt OSCTXT pctxt lt name gt pvalue In this definition lt name gt denotes the prefixed production name defined above The pct xt argument is used to hold a context pointer to keep track of decode parameters This is a basic handle variable that is used
311. ing 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 a static 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 An example of an Information Object Set definition that is derived from the ASN 1 ATTRIBUTE class above is as follows E SupportedAttributes ATTRIBUTE name commonName 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 ncodeType 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 1l ncodeType amp asnlE__commonName_Type SupportedAttributes 1 decodeType amp asnlD__commonName_Type SupportedAttributes 1 id numids 3 SupportedAttributes 1 id subid 0
312. ing presented here will use prose to describe how the ASN 1 types that are produced should be encoded so as to correspond to the CSN 1 from which they were derived General Procedure The general mapping procedure is to iterate over the Definitions in the DefinitionList and to map each Definition as follows 1 Let csnstr be the CSN1String of the Definition Invoke the CSN1String mapping procedure for csnstr 2 If the mapping of csnstr produces either an ASN 1 type or an ASN 1 component then an ASN 1 TypeAssignment TA is produced for this Definition The typereference for TA is obtained by invoking the procedure for mapping a CSN 1 name to a typereference The Type for TA is specified in the following clauses If the mapping of csnstr did not produce any ASN 1 then no ASN 1 is produced for this Definition 3 If an ASN 1 type T was produced this is the type for TA 4 Otherwise if an ASN 1 component C was produced the type for TA is a SEQUENCE S defined as follows a S shall consist of a single component namely C b If C was produced without a label name the component name shall be component 1 c Otherwise C was produced with a label name the component name shall be obtained by invoking the procedure for mapping a CSN 1 name to an ASN 1 identifier d The optionality and type for C will already have been specified by the procedure that produced C e The encoding for S is the encoding for C which will h
313. ing 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 Generated VC Project Files The vcproj option causes Microsoft Visual Studio project and workspace files to be generated that can be used to build the generated code The files are compatible with Visual Studio version 6 0 but higher versions of Visula Studio can convert these files to the newer formats This option can be used with the dll option that will generate project files to compile all generated code into a DLL and mt that will add multi threaded compilation options to generated projects Because there are several different versions of Visual Studio
314. ings 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 Generated C code with cpp11 typedef struct OSUINT32 n std array lt lt type gt lt len gt gt elem ASNIT_ lt name gt If the strict size command line option is used the n component within this type definition may be of a different type OSUINTS8 or OSUINT16 or eliminated completely if the type is constrained to be a fixed size List based SEQUENCE OF Type A doubly linked list header type OSRTDList is used for the type definition 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 OSRTDList lt name gt Generated C code typedef ASN1TSeqOfList ASN1T_ lt name gt The type definition of the OSRTDList structure can be found in the osSysTypes h header file The common run time utility functions beginning with the prefix rtxDList are available for initializing and a
315. instead of a plain C static array Its use requires the cpp 1 command line option The list 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 When cpp is specified on the command line you can also use the following storage options to select the use of C Standard Library container classes lt storage gt std list lt storage gt lt storage gt std vector lt storage gt lt storage gt std deque 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 T 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 ASN1TPDU OSUINT32 n lt type gt elem ASN1T_ lt name gt ASN1T_ lt name gt ASN1T_ 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 types or explicitly via the pdu command line option the ASNITPDU 70 ASN 1 To C C Mapp
316. int information on the error that was encountered printf decode error detected n rtErrPrint pCtxt printf n Skip element xd_NextElement pCtxt Return an OK status to indicate parsing can continue return 0 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 complicated 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 It should be noted that implementing an error handler in C does not involve a struct at all It is only necessary to implement a function with the appropriate signature specified above and to pass a pointer to it to the decode buffer So with a error handler function 290 Event Handler Interface static int myErrorHandler OSCTXT pctxt Brror handling code goes here the function is set in the decode context by calling rtSet BrrorHandler amp ctxt where ctxt is an
317. ion lt name gt denotes the prefixed production name defined above The pct xt 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 program The variable should be initialized using the rt InitContext run time library function see the C JSON Runtime 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 function result variable st at returns an error status code if encoding fails Return status values are defined in the asnltype h include file Procedure for Calling C Encode Functions This section describes the step by step procedure for calling a C JSON encode function Before any encode function can be called the user must first initialize an encoding context This is a variable of type OSCTXT 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 InitContext function as follows 234 Generated JavaScript Object Notation JSON Funct
318. ion 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_GetMsgPrtr 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 OSCTXT ctxt O SBOOL aligned TRUE Employee employee typedef generated by ASNIC GI moployee name givenName SMITH stat rtInitContext amp ctxt if stat 0 printf rtInitContext failed check license n rtxErrPrint amp ctxt return stat pu_setBuffer amp ctxt 0 0 aligned if stat asnlPE_Employee amp ctxt s amp employee 0 msgptr pe_GetMsgPtr amp ctxt amp msglen else 187 Generated PER Functions error processing It is also possible to encode directly to a stream interface To do this the call to pu_setBuffer above would be replaced with a call to create a stream writer within the context such as rtxStreamFileCreateWriter The call to the generated PER encode function would not change it will automatically know to use the stream interface instead of a memory buffer Procedure for Using the C Control Class Encode Method The procedure to encode a message using the C class interface is as follows l Instantiate an ASN 1 PER e
319. ion in the C or C source file ASNIOBJID oid Bar Ar Ol bp 20 4 3 To populate a variable in a generated structure with this value the rt Set OID 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 ASN1TObjId contains constructors and assignment operators that allow direct assignment of values in this form to the target variable Constructed Type Values ASNIC will generate code for following remaining value definitions only when their use is required in legacy table constraint validation code e SEQUENCE 85 ASN 1 To C C Mappings e SET e SEQUENCE OF e SET OF e 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 OSCTXT 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 initializa
320. ions OSCTXT ctxt if rtInitContext amp ctxt 0 initialization failed could be a license problem printf context initialization failed check license n return 1 After initializing the context and populating a variable of the structure to be encoded an encode function can be called to encode the message A complete example may be found in the employee sample program here edited for brevity stat rtInitContext amp ctxt stat rtxStreamFileCreateWriter amp ctxt filename if stat 0 printf Unable to create file stream n rtxErrPrint amp ctxt return stat rtxSetDiag amp ctxt verbose asnlInit_PersonnelRecord amp employee populate employee structure stat asnlJsonEnc_PersonnelRecord amp ctxt amp employee Encoding a Series of Messages Encoding a series of messages in JSON is similar to encoding a series of messages in any other set of encoding rules iterate through the input data using a loop using rt xMemReset to improve performance by reusing memory initialize context et c for 7 initialize populate message structure to b ncoded call MDEREnc_ lt messageType gt call rtxMemReset when finished encoding rtxMemReset pctxt Generated C Encoding Methods Generated C encoding methods use the control classes and the OSJSONEncodeBuffer and OSJSONOut put St ream cla
321. ired variety of library can be selected 51 ASNI1C GUI Users Guide Build Options T Generate a list of cs files in lt modulename gt mk T Generate a makefile Generate a Visual Studio Project mr V5 2013 WS 2012 VS 2010 VS 2008 WS 2005 Similarly for C a makefile or Visual Studio project can be created optionally including a mk file listing the files generated Build Options Generate a list of java files in lt modulename gt mk Generate an Ant build script T Generate a batch file or shell script Java can also provide a mk generated file list as well as Ant build script and a batch or shell script 52 Chapter 4 ASN 1 To C C Mappings Type Mappings 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 char ASN 1 production lt name gt BOOLEAN Generated C code typedef OSBOOL lt name gt Generated C code typedef OSBOOL ASN1T_ lt name gt For example if B PRIVATE 10 BOOLEAN was defined 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 ASN1T_ prefix on the C type INTEGER The ASN 1 INTEGER type is converted into o
322. irst alternative the BASIC_NAME is the referenced name while in the third alternative the EXTENDED_NAME is the referenced name 247 CSN 1 Described 8 The second alternative can also represent a reference This will be the case if the CSN1Stringisa BASIC_NAM The referenced name will normally correspond to the EXTENDED_NAME of a Definition However as will be discussed elsewhere when there is not a match we assume that the name will be resolved at the ASN 1 level The first and third alternatives both allow or require for the first a subclass expression A subclass expression can only be applied to references and therefore it is not allowed in the second alternative Gl an In that case however the BASIC_NAME must not be a multi word name If the CSN1String is not a BAS IC_NAME then the second alternative is simply labeling the given string GI The third alternative lets you reference any defined string not just ones whose name is a BASIC_NAMB as in the first and second alternatives You may optionally provide an exponent and or a subclass expression A label is not allowed in this alternative because if it were there would be a conflict between it and the second alternative since some inputs e g a b could be parsed as either an EXTENDED_NAME ora CSN1String an Exclusion in the case of a b When using the third alternative expone
323. is expecting a certain element to be present at the current position and instead something different is encountered An example is decoding a sequence container type in which the declared elements are expected to be in the given order If an element is encountered that is not the one expected this error is raised 4 RTERR_INVENUM Invalid enumerated identifier This status is returned when an enumerated value is being encoded or decoded and the given value is not in the set of values defined in the enumeration facet 5 RTERR_SETDUPL Duplicate element in set This status code is returned when decoding an ASN 1 SET or XSD xsd all construct It is raised if a given element defined in the content model group occurs multiple times in the instance being decoded 6 RTERR_SETMISRQ Missing required element in set This status code is returned when decoding an ASN 1 SET or XSD xsd all construct and all required elements in the content model 299 ASNIC Error Codes Error Code Error Name Description group are not found to be present in the instance being decoded 7 RTERR_NOTINSET Element not in set This status code is returned when encoding or decoding an ASN 1 SET or XSD xsd all construct When encoding it occurs when a value in the generated _order member variable is outside the range of indexes of items in the content model group It occurs on the decode side when an element is received that is
324. is option specifies that an array type will be used for SEQUENCE OF SET OF constructs arraySize lt size gt This option specifies the default size of static array variables This will be overridden by the value of a SIZE constraint on the given type if it exists asn 1 lt filename gt This option causes pretty printed ASN 1 to be generated to the given file name or to stdout if no filename was given Besides the obvious use of providing neatly formatted ASN 1 source code the option is also useful for producing ASN 1 source code from XML schema document XSD files as well as producing trimmed specifications when lt include gt or lt exclude gt configuration directives are used asnstd x208 This option selects the version of ASN 1 syntax to be x680 parsed x680 the default refers to modern ASN 1 as mixed 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 OBJECTTYPE macros The mixed option is used to specify a source file that contains modules with both X 208 and X 680 based syntax attrs lt items gt This option only has meaning when generating an XML schema definitions XSD file using the xsd option Using the Co
325. 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 95 ASN 1 To C C Mappings As an example consider the following ASN 1 class definition ATTRIBUTE CLASS amp Type amp id OBJECT IDENTIFIER UNIQU WITH SYNTAX amp Type ID amp id zai This would result in the following definition in the C source file typedef struct ATTRIBUTE int TypeSize int encodeType OSCTXT void ASN1TagType int decodeType OSCTXT void ASN1TagType int ASN1OBJID id C Code generation The C abstract class generated to model an ASN 1 CLASS contains member 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
326. is status code is returned if an attempt is made to open a file input stream for decoding and the given file does not exist 30 RTERR_READERR RTERR_WRITEERR Read error This status code if returned if a read IO error is encountered when reading from an input stream associated with a physical device such as a file or socket Write error This status code if returned if a write IO error is encountered when attempting to output data to an output stream associated with a physical device such as a file or socket 31 RTERR_INVBASE64 Invalid Base64 encoding This status code is returned when an error is detected in decoding base64 data 32 RTERR_INVSOCKET Invalid socket This status code is returned when an attempt is made to read or write from a scoket and the given socket handle is invalid This may be the result of not having established a proper connection before trying to use the socket handle variable 33 34 RTERR_INVATTR RTERR_REGEXP Invalid attribute This status code is returned by the decoder when an attribute is encountered in an XML instance that was not defined in the XML schema Invalid regular expression This status code is returned when a syntax error is detected in a regular expression value Details of the syntax error can be obtained by invoking rtxErrPrint to print the details of the error contained within the context variable 35 RTERR_PATMATCH Pattern match error
327. is that this would typically imply that the referenced type was not top level and the padding was probably not a case of simple byte alignment after all Send Mapping This procedure only applies when invoked by another procedure This mapping procedure imposes the following constraints on a send string 1 The right hand operand must be a single literal bit 0 1 L H or a reference to such a string 2 The left hand operand must recognize a single bit of any value or be a reference to such a string The send string is mapped to a pad bit The encoding is a single bit An encoder shall encode the literal bit specified by the right hand operand A decoder shall accept any bit value 266 Chapter 18 Compiling CSN 1 This chapter discusses the use of our tool for compiling CSN 1 We cover some basics using CSN 1 and ASN 1 in tandem and some tips related to common problems Basics The basics are simple Put your CSN 1 notation into a file using the csn1 extension Invoke the asnlc compiler using the 3g13 option and passing your csn1 file as input Note we currently support only a single CSN 1 module per input file Our compiler takes each CSN 1 file applies the CSN 1 to ASN 1 mapping rules see the previous chapter and internally generates the ASN 1 objects as belonging to the ASN 1 module that you identified in the CSN 1 file The compiler then generates code just as we would for the corresponding ASN 1 with adjustment
328. ist Error Error value ERROR shall reference an error value type shall reference an error type if no value is specified LinkedOperationNames OperationList empty OperationList Operation OperationList Operation Operation value OPERATION shall reference an op value type shall reference an op type if no 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 ARGUMENT SEQUENCE username IA5String password IA5String 293 ROSE and SNMP Macro Support vu ESULT SEQUENCE ticket OCTET STRING welcomeMessage IA5String ERRORS authenticationFailure insufficientResources 1 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 ASN1C 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 gener
329. it PDU By default any type defined in an ASN 1 source file that is not referenced by any other type is a 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 calling 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_ lt name gt public ASNI1CType protected ASN1T_ lt name gt amp msgData public ASN1C_ lt name gt ASN1T_ lt name gt amp data ASN1C_ lt name gt ASN1MessageBufferIF amp msgBuf ASN1T_ lt name gt 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 a The name of the generated class is ASN C_ lt name gt where lt name gt is the name of the production The only defined attribute is 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
330. it value naming is not required in CSN 1 That itself presents a challenge Next observe that this CSN 1 could correspond to either of the following components in ASN 1 and arguably other less obvious possibilities and nothing in the CSN 1 tells us which is intended value BOOLEAN value INTEGER 0 1 As another example you might think CSN 1 alternation maps directly to ASN 1 CHOICE But consider this example 0 1 lt foobar lt foo gt lt bar gt gt Here you have something called foobar that may or may not be present in the encoding depending on whether a one or zero bit preceedes it That sounds more like an optional component of a SEQUENCE than two alternatives in a CHOICE It also happens that sometimes the context affects how something is mapped This is why the mapping procedure presented here is algorithmic and does not specify how each CSN 1 operation concatenation alternation is mapped into ASN 1 The mapping process must also specify encoding rules If you map CSN 1 to ASN 1 that ASN 1 can t produce bit strings that are valid according to the CSN 1 unless you specify some encoding rules That s a challenge however because none of the standard ASN 1 encoding rules fit the bill and the only standardized notation for defining custom 253 Mapping CSN 1 to ASN 1 ASN 1 encoding rules ECN is extremely complicated and we believe insufficient for this task For this reason the mapp
331. it is possible to nest a SEQUENCE definition within another SEQUENCE definition as follows A SEQUENCE x SEQUENCE al INTEGER a2 BOOLEAN 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 internal types The names of these types are of the form lt name gt _ lt element namel gt _ lt elementname2 gt _ lt element nameN gt For example in the definition above two temporary types would be generated A_x and A_y A_yis generated because a static OCTET STRING maps to a C struct type The general form is as follows ASN 1 production lt name gt 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 lt elementl nam lt type2 gt lt element2 name gt v e Poe or typedef struct stenam typedef struct lt tempName2 gt 64 ASN 1 To C C Mappings typedef struct lt tempNamel gt lt element1l 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 element1
332. ith 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 if 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 include employee h include file generated by ASNIC main OSOCTET msgbuf 1024 ASNI1TAG msgtag int msglen status 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 0 handle error Now switch on initial tag value to determine what type of message was received switch msgtag case TV_PersonnelRecord compiler generated constant ASN1T_PersonnelRecord msgData ASN1C_PersonnelRecord employ decodeBuffer msgData if status employee Decode 0 decoding successful data in msgData process 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
333. l be inserted into the encoded data stream on encoding and skipped over on decoding Its purpose is the production of more compact and faster code for PER by bypassing run time calculations needed to encode or decode variable data This item is used to configure an element within a CHOICE in a 3GPP layer 3 message It specifies the value of another element within the container type which selects this element The element field specifies the name of the element within the container type and value specifies the value are O no length field or 2 This item is only supported for C 3GPP layer 3 code generation lt setvar name name value value gt n a This item is used within encode and decode functions to set a given variable within a generated structure to the given value Normally it is used in conjunction with the addarg configuration item to set a variable to value of an additional argument passed into a function This item is only supported for C 3GPP layer 3 code generation lt storage gt lt storage gt One of the following keywords dynamic static list array dynamicArray The definition 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 this element 29 Using the Compiler Name Values Description std list std vector Std deque Compiler Error Reporting Errors that c
334. l then validate it If the schema has errors the log at the bottom of the window will show them Otherwise it is safe to move on Since we ve already set up our project we can click the Compile button to generate code according to our project settings If all goes well the project window will show a list of generated files under Generated Items in the section for the selected language If there were any errors they will be shown in the log Project ay E 1 files testrecipe asn be ncaa Directories Configuration files Generated Items C C files 2 i MyModule c MyModuleDec c MyModuleEnc c MyModule h w C files Ben Java files i KSD files At this point project settings can be changed and schema files can be edited as needed Creating a Project Since there are a large number of options available in the code generation process ACGUI allows settings to be saved in project files for reuse Project files can be created opened and saved from the Project menu If no project file is explicitly used a dummy project will be implicitly created and can be saved to a file at a later time Project assets such as ASN 1 schemas and generated source files are visible in the Project window Project settings can be changed via the Project Settings window accessible by selecting Project gt Project Settings from the menubar 35 ASN1C GUI Users Guide Editing Schemas The central area
335. lRecord public ASNITPDU ASN1T_PersonnelRecord m uniPresent 0 m seqOfseqPresent 0 ASN1T_PersonnelRecord ASN1C_PersonnelRecord amp srcData ASN1T_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 ASN TPDU base class variable from which PDU data types are now derived The dynamic memory within the item will persist until the item is deleted Generated Test Functions The genTest option causes test functions to be generated These functions can be used to 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
336. lared as follows asnlPrtToStrm_ lt name gt OSCTXT pctxt const char name lt name gt pvalue The name and pvalue arguments are the same as they were in the print case The pctxt argument is 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 print 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 There are two possible print formats details and bracetext 278 Additional Generated Functions The details format prints a line by line display of every item in the generated structure For example the fol
337. lement within this type See the ASN1CTime ASN1CGeneralizedTime and ASN1CUTCTime subsections in the C C Run Time Library Reference Manual for details on all of the methods available in these classes EXTERNAL 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 UNIVERSAL 8 IMPLICIT SEQUENCE direct reference OBJECT IDENTIFIER OPTIONAL indirect reference 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 always be generated in the AsnlExternal hand AsnlExternal 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 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 Asn1External source files are generated EMBEDDED PDV The ASN 1 EMBEDDED PDV t
338. les type First notice that member variables have been generated for the fixed type fields in the definition These include the id field Information o bject classes derived from this definition are expected to populate these fields in their constructors 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 97 ASN 1 To C C Mappings 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 form lt fiel
339. lied 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 st at returns the completion status of the operation 0 0 means the success 158 Generated BER Functions Procedure for Calling Streaming C Encode Functions This section describes the step by step procedure for calling a streaming 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 OSCTXT This variable holds all of the working data used during 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 berStrmInitContext function OSCTXT ctxt if berStrmInitContext amp ctxt 0 initialization failed could be a license problem printf context initialization failed check license n return 1 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 rtxStreamFileOpen e rtxStr
340. line the generated code may use features of the C Standard Library such as std string for character strings and std list or another container class for SEQUENCE OF types There are a few considerations to keep in mind when using this option ASNIC generates code that manages memory using OSCTXT and rt xMem functions The design of the generated code and memory management is such that the C constructors and destructors generally don t need to be invoked 122 Generated C C Source Code For example dynamic memory is allocated using rt xMemAllocType instead of new and initialization can be done by assigning individual fields or else using a generated asnl1 Init function so that the constructor is never invoked The C Standard Library classes are more typical C classes and failing to invoke their constructor or destructor or invoking them more than once can lead to memory leaks or crashes This means that when you are using the cpp11 option you must take care that the C constructors and destructors for the generated classes are invoked exactly once Follow these rules to avoid problems e When you dynamically allocate an object use rt xMemA11loc to allocate the memory then use a placement new expression to invoke the constructor e C destructors don t have access to an OSCTXT for use in freeing memory Therefore before an object is destructed invoke the generated asn1Free function for that type to free any dyn
341. ll NOT get removed lt e2 bit 2 gt lt e3 bit 3 gt lt e4 bit 4 gt rg lt Things With Expone lt a 23 bit int b nts gt 22 it 23 gt lt a fixed length bit stri lt a var length bi ng bit 45 gt bit val a 23 bit int gt t string lt a fixed length octet str octet 4 gt lt a var len octet lt repeating optio lt five pad bits str oc lt bit gt se lt count bit encoding 0 lt fixed num of type Nami lt var num of type Naming tet val a 23 bit int gt nal component 0 1 lt opt comp bit 4 gt 5 gt nd 0 gt 5 1 gt ng 5 gt val a 23 bit int gt The resulting ASN 1 follows Our tool generates tags in the ASN 1 these have been removed to improve readability Example 18 6 The resulting ASN 1 UserGuide DEFINITIONS AUTOMATIC TAGS BEGIN Productions LHType ENUMERATED lbit 0 hbit 1 272 Compiling CSN 1 Naming SEQUENCE all caps 1 INTEGER 0 1 part Caps INTEGER 0 1 camelCase INTEGER 0 1 Alternations SEQUENCE l1 bit or h bit LHType pg determinant INTEGER 0 7 GI a particular general CHOIC naming Naming something else INTEGER 0 15 ae stereo choice 1 CHOICE first INTEGER 0 1 second INTEGER 0 3 pa stereo choice 2 CHOICE
342. ll of the other contents methods correspond to a single equivalent ASN 1 primitive type The C 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 OSCTXT pCtxt ASNICCB pCCB int stat 0 The C error handler function unlike the other events in C is not contained within a struct Its signature is as follows typedef int rtErrorHandler OSCTXT pctxt ASNICCB pCCB int stat In these definitions pCtxt and pctxt are pointers 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 index 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 In both C and C two things must be done to define event handlers 1 In C one or more new classes must be derived from the Asn NamedEventHandler and or the Asn1 ErrorHandler base classes All pure virtual methods must be implemented In C a function with an appropriate signature must be created for each function pointer in the struct the behavior of null function p
343. lling Parameters The format of the name of each generated decode function is as follows x3GL3Dec_ 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 It is also possible to change the x3GL3 prefix at the beginning of the function name by using the lt protocol gt configuration setting For example an API was generated for the Non Access Stratum NAS protocol within the ASNIC package A protocol setting of NAS was used for this so all decode function names begin with NASDec_ instead of x3GL3Dec_ The calling sequence for each decode function is as follows 242 Generated 3GPP Layer 3 3GL3 Functions status x3GL3Dec_ lt name gt OSCTXT pctxt lt name gt pvalue In this definition lt name gt denotes the prefixed production name defined above The pct xt 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 so
344. llows Application Layer Call specific function to decode Login ARGUMENT and process data A Encoded message pointer and length Decode ROSE header message structure Invoke Open type structure contains message pointer and length of encoded Login ARGUMENT A 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 ROSE Layer 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 295 ROSE and SNMP Macro Support applicationError in this case with the first letter set to uppercase The name of the value will
345. lowing 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 This is a more concise format that will omit optional fields that are not present in the decoded data An example of this is as follows Employee name givenName John initial P familyName Smith number 51 title Director As of ASNIC version 6 0 and higher bracetext is the default format used if prtfmt is not specified on the commandline Previous versions of ASNIC had details as the default setting Generated Compare Functions The genCompare option causes comparison functions to be generated These functions can be used to compare the contents of two generated type variables If an output file is not 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
346. ls gt Options from the menus In the General tab of the options window change Open files from In tabs to In MDI windows Click OK and restart ACGUI Now open files will be displayed as separate windows within the main ACGUI window This option is useful for viewing two files simultaneously for example Project Window Untitled El o ACSE L asr 1 files E n rela Configuration files Generated Items i C C files Java files XSD files The project window allows the user to interact with project assets Schema ASN 1 files Files containing the current project s ASN 1 schema definitions Include directories Directories containing auxiliary ASN 1 schema files The current project s schema may import definitions from modules defined in an included directory Configuration file An ASNIC compiler configuration file Generated Items A listing of the files generated by the compiler separated by target language 39 ASNI1C GUI Users Guide Clicking on a schema file or configuration file in the project window will open that file in the editor A right click context menu is also provided for schema files include directories and configuration file for adding or removing these assets from the project ASN 1 Tree Window H fz ACSE 1 J4 amp InformationFramework Gh Types GF Values i be id at aliasedEntryName fe id at objectClass i ee id mr distinguishedName 2 i be id mr obj
347. mat and Calling Parameters Generated C streaming decode functions are invoked through the C class interface by calling the generated DecodeFrom method The calling sequence for this method is as follows 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 ASN1DecodeStream class The function result variable st at returns the completion status Error status codes are negative Return status values are defined in the rtxErrCodes 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 181 Generated BER Functions 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 ASNI DecodeStream 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 Proc
348. 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 asn type h run time header file or in Appendix A of the C C Common Functions Reference Manual If encoding is 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 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 is 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 ASN1C main const OSOCTET msgptr OSOCTET msgbuf 1024 int msglen step 1 construct ASN1C C generated class this specifies a static encode message buffer ASN1BEREncodeBuffer encodeBuffer msgbuf sizeof msgbuf 155 Ge
349. me gt OSUINT32 _numbits const OSOCTET _data ASNIT_ lt name gt E lt adjusted_len gt lt len gt 1 8 1 If the strict size command line option is used the numbits component within this type definition may be of a different type OSUINTS8 or OSUINT16 or eliminated completely if the type is constrained to be a fixed size For example the following ASN 1 production BS PRIVATE 220 BIT STRING SIZI ea D N Would translate to the following C typedef typedef struct BS OSUINT32 numbits OSOCTET data 6 BS In this case six octets would be required to hold the 42 bits eight in the first five bytes and two in the last byte In the case of small sized strings less than or equal to 32 bits a built in type is used rather than generating a custom type This built in type is defined as follows typedef struct ASNIBitStr32 OSUINT32 numbits OSOCTET data 4 56 ASN 1 To C C Mappings ASN1BitStr32 The C variant ASN1TBitStr32 adds constructors for initialization and copying 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 If the strict size command line option is used the numbits component would be eliminated since the type is constrained to be a fixed size N
350. me is 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 is 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 98 ASN 1 To C C Mappings 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 Anew Value Assignment is created for a ValueField s default value definition as follows _ lt ClassName gt _ lt FieldName gt _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 the Class
351. ment should be added to either the encode or decode function only By default the argument is added to both the encode and decode function This item is only supported for C 3GPP layer 3 code generation lt aligned gt n a This item is used to specify that byte alignment is to be done after encoding or decoding an instance of the targeted type This item is only supported for C 3GPP layer 3 code generation 24 Using the Compiler Name Values Description lt cDecFuncName gt cDecFuncName gt lt lt cEncFuncName gt cEncFuncName gt lt lt C source file name lt C source file name This item is used to substitute the C source code contained within the given file for what would have been generated for the C decode function for the given type The current include path is searched for the given filename This item is only supported for C 3GPP layer 3 code generation This item is used to substitute the C source code contained within the given file for what would have been generated for the C encode function for the given type The current include path is searched for the given filename This item is only supported for C 3GPP layer 3 code generation lt ctype gt byte intl6 uintl6 int32 uint32 int64 string chararray This is used to specify a specific C integer or character string type be used in place of the default definition generated by ASNIC
352. met e None of the above patterns applied to the alternation e There are at least two non null alternatives e Each of the non null alternatives has a determinant e Each of the non null alternatives either would produce an ASN 1 type or else has a uniquely named determinant 3 If the alternation matches either of the Optional component with presence bit patterns then the mapping produces an ASN 1 component C as follows a For this alternation pattern one of the alternatives would produce an ASN 1 type Let typeString be the remainder for that alternative which is the string that would produce the ASN 1 type b Invoke the CSN1String Mapping procedure for typeString This will produce an ASN 1 type T C s type shall be T C shall be an OPTIONAL component c The name of the component is derived from the CSN 1 but the CSN 1 does not always provide a name The calling procedure e g the Concatenation mapping procedure is ultimately responsible for assigning the name to the component This procedure merely assigns a CSN 1 name to the component if there is one If typeString was labeled the CSN 1 name is that label name Otherwise if the alternation as a whole was labeled the CSN 1 name is that label name Otherwise the component does not have a CSN 1 name d The encoding for C may be empty if and only if the Optional component with presence bit and container determined pattern was matched In that case a decoder shall assume t
353. method that will create a new dynamically allocated copy of the referenced ASN JT_ data member variable e An assignment operator This is used to copy one instance of a control class to another one inline ASN1C_ lt name gt amp operator ASN1C_ lt name gt amp srcData srcData getCopy amp msgData return this For example inline ASN1C_PersonnelRecord operator ASN1C_PersonnelRecord amp srcData srcData getCopy amp msgData return this Finally the class declaration might look as follows class EXTERN ASN1C_PersonnelRecord public ASN1CType protected ASN1T_PersonnelRecord amp msgData public ASN1C_PersonnelRecord ASN1MessageBuffer amp msgBuf ASN1T_PersonnelRecord amp data ASN1C_PersonnelRecord ASN1C_PersonnelRecord original ASN1T_PersonnelRecord amp getCopy ASN1T_PersonnelRecord pDstData 0 ASN1T_PersonnelRecord newCopy inline ASN1C_PersonnelRecord operator ASN1C_PersonnelRecord amp srcData srcData getCopy amp msgData return this 281 Additional Generated Functions 3 The generated ASN JT lt name gt structure will also contain 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 ASN1T_Personne
354. mewhere 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 st at returns the status of the decode operation Status code 0 0 indicates the function was successful A negative value indicates decoding failed Return status values are defined in the asn1ErrCodes h and rtxErrCodes h header files The reason text and a stack trace can be displayed using the rtxErrPrint function described later in this document It is possible to add extra arguments to 3GPP Layer 3 decode functions through the use of the lt addarg gt configuration setting This is normally done to pass data from container type member variables into a decode function Procedure for Calling C Decode Functions This section describes the step by step procedure for calling a C 3GL3 decode function A Protocol Data Unit PDU function is normally defined that includes all of the message that make up a given protocol These are grouped together using an Information Object Set that sets up a relation between the protocol discriminator message type field combination and the associated message data type This PDU function is then called
355. more modules are involved and they contain productions with common names 20 Using the Compiler The following tables specify the list of attributes that can be 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 lt asn1config gt section Name Values Description lt events gt lt events gt lt includedir gt lt includedir gt defaultValue keyword lt Include directory gt This configuration item is for use with Event Handling as described in a later section in this document It is used to include a special event that is fired when a PER message is being parsed This event occurs at the location a value should be present in the message but is not and a default value has been specified in the ASN 1 file for the element In this case the normal event sequence startElement contents endElement is executed using the default value This configuration item is used to specify a directory that will be search for IMPORT files It is equivalent to the I command line option lt protocol gt lt protocol gt lt Protocol identifier gt Specifies a protocol identifier to be associated with the ASN 1 specification set For C C this specifies a prefix that will be used with generated encode and decode functions Currently this only applies to 3GPP Layer 3 functions
356. mpiler Option Argument Description It instructs the compiler to generate non native attributes for certain ASN 1 only items that cannot be expressed in XSD The items are specified as a comma delimited list Valid values for items are tags enum and ext lt items gt is an optional parameter If it is not specified it is assumed that application information should be produced for all three item classes ASN 1 tags ASN 1 enumerations and extended elements ber None This option is used to generate encode decode functions that implement the Basic Encoding Rules BER as specified in the X 690 ASN 1 standard bindir lt directory gt This option is used in conjunction with the genMake option to specify the name of the binary executable directory to be added to the makefile Linked executable programs will be output to this directory bitMacros None This option is used 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 runtime C 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 c or cpp None Generate C source code
357. mponent if there is one If typeString 258 Mapping CSN 1 to ASN 1 was labeled the CSN 1 name is that label name Otherwise if the alternation as a whole was labeled the CSN 1 name is that label name Otherwise the component does not have a CSN 1 name d The encoding for C may be empty A decoder shall assume that C s encoding is not empty if there are more bits to be decoded where C should appear If the encoding for C is empty C is absent e If C is absent the encoding of C is empty When C is present the encoding consists of the encoding for T C s type which will have been defined by the procedure that produced T After encoding C as absent it is an error for an encoder to encode any bits within the same container i e you can t encode bits that the decoder might interpret as being an encoding for C If the alternation matches the L H Alternative pattern then the mapping produces an ASN 1 type The type is an DefinedType with typerefence equal to LHType The encoding for this is the encoding of LHType If the alternation matches the Stereotypical choice pattern then the mapping is as follows a If the alternation includes one or more null alternatives the mapping produces an ASN 1 component C C shall be OPTIONAL C type shall be a CHOICE type constructed as in the case where the alternation has no null alternatives described in the following clauses If the alternation itself is labeled that name shall
358. msglen stat OSBOOL aligned TRU GI logic to read message into msgbuf step 1 instantiate a PER decode buffer object ASN1PERDecodeBuffer decodeBuffer msgbuf msglen aligned step 2 instantiate an ASN1T_ lt ProdName gt object ASN1T_PersonnelRecord msgData step 3 instantiate an ASN1C_ lt ProdName gt object ASN1C_PersonnelRecord employ decodeBuffer msgData step 4 decode the record stat employee Decode step 5 check the return status if stat 0 process received data else error processing decodeBuffer PrintErrorInfo step 6 free dynamic memory will be done automatically when both the decodeBuffer and employ objects go out of scope declaration in step 1 would be replaced with the following two statements OSRTFileInputStream istrm filename ASN1PERDecodeBuffer decodeBuffer istrm aligned 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 195 Generated PER Functions It would be much better to create all of the required objects outside of
359. n OSCTXT CLxXG Employee employee typedef generated by ASNIC if rtInitContext amp ctxt 0 initialization failed could be a license problem printf context initialization failed check license n return 1 xe_setp amp ctxt NULL 0 mployee name givenName SMITH msglen asnlE_Employee amp ctxt amp employee ASNIEXPL if msglen gt 0 msgptr xe_getp amp ctxt rtxMemFree 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 however 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 OSCTXT ctxt PersonnelRecord data Init context structure if stat rtInitContext amp ctxt 0
360. n C C static 21 Using the Compiler Name Values Description array You must specify cpp11 on the command line to use this option If one of std list std vector std deque then the corresponding C Standard Library container class will be used You must specify cpp11 on the command line to use one of these options Module Level These attributes can be applied at the module level by including them within a lt module gt section Name Values Description lt name gt lt name gt module name This attribute identifies the module to which this section applies Either this or the lt oid gt element attribute is required lt oid gt module OID identifier object This attribute provides for an alternate form of module identification for the case when module name is not unique For example a given ASN 1 module may have multiple versions A unique version of the module can be identified using the OID value lt codename gt lt codename gt C C Java or C name This item specifies an alternate name for the module to be used in generated code By default the module name is used in the form it appears in the ASN 1 specification with hyphens converted to underscores lt include types names values names gt ASN 1 type or value names are specified as an attribute list This item allows a list of ASN 1 types and or values to be included in the
361. n Object definition lt objectsetPrefix gt lt prefix text This is used to specify a prefix that will be applied to objectsetPrefix gt all generated 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 23 Using the Compiler Name Values Description 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 intl6 uintl6 int32 uint32 int64 string This is used to specify a specific C integer type be used for all unconstrained integer types By default ASNIC will use the int32 32 bit integer type for 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 gt lt namespace URI This is used to specify the target namespace for the given module 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
362. n also be added to a choice group In this case an ASN 1 SEQUENCE is formed consisting of the attribute elements and an embedded element choice for the choice group An example of this is as follows lt xsd complexType name NamePart gt lt xsd choice gt lt xsd element name givenName type xsd string gt lt xsd element name initial type xsd string gt lt xsd element name familyName type xsd string gt lt xsd choice gt lt xsd attribute name occupation type xsd string gt lt xsd complexType gt This results in the following C type definitions being generated 109 XSD to C C Type Mappings define T_NamePart_choice_givenName 1 define T_NamePart_choice_initial 2 define T_NamePart_choice_familyName 3 typedef struct EXTERN NamePart_choice int t union t 1 const OSUTF8CHAR givenName t 2 const OSUTF8CHAR initial t 3 const OSUTF8CHAR familyName u NamePart_choice typedef struct EXTERN NamePart struct unsigned occupationPresent 1 m const OSUTF8CHAR occupation NamePart_choice choice NamePart In this case occupation attribute declaration was added as before But the choice group became a separate embedded element called choice which the ASNIC compiler pulled out to create the NamePart_choice temporary type This type was then referenced by the choice element in the generated type definition for NamePart
363. n each iteration main OSOCTET msgbuf 1024 ASN1TAG msgtag int offset 0 msglen len OSCTXT CUKEs PersonnelRecord employee FILE fp Step 1 Initialize a context variable for decoding if rtInitContext amp ctxt 0 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 for offset lt msglen xd_setp amp ctxt msgbuf offset msglen offset amp msgtag amp len 168 Generated BER Functions Decode if tag TV_PersonnelRecord Call compiler generated decode function stat asnlD_PersonnelRecord amp ctxt amp employee ASN1EXPL 0 if stat 0 decoding successful data in employee else error handling return 1 else printf unexpected tag hx received n tag offset ctxt buffer byteIndex rtxMemReset amp ctxt 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 ASN1C_ lt prodName gt generated for the given p
364. n object set into a container type The container type holds a list of the IE fields The structure of an IE field type is similar to a message type the first element is used as an index element to the remaining elements That is followed by one or more fixed type or variable type elements In the case defined above only a single fixed type and variable type element is shown but there may be more An example of this pattern from the S1AP LTE specification follows HandoverRequired SEQUENCE protocollEs ProtocollIE Container HandoverRequiredIEs ProtocollIE Container SlAP PROTOCOL IES IEsSetParam SEQUENCE SIZE 0 maxProtocollIEs OF ProtocolIE Field IEsSetParam ProtocolIE Field SlAP PROTOCOL IES IEsSetParam SEQUENCE id S1AP PROTOCOL IES id IEsSetParam criticality S1AP PROTOCOL IES amp criticality IEsSetParam id value S1AP PROTOCOL IES amp Value IEsSetParam id In this case standard parameterized type instantiation is used to create a type definition for the protocolIEs element This results in a list type being generated List of HandoverRequired_protocollEs_element typedef OSRTDList HandoverRequired_protocollEs The type for the protocol IE list element is created in much the same way as the main message type was above typedef struct HandoverRequire
365. n the asnitype h include file Procedure for Calling C Decode Functions This section describes the step by step procedure for calling a C JSON 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 OSCTXT 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 OSCTXT ctxt int stat stat rtInitContext amp ctxt if stat 0 rtxErrPrint amp ctxt rtFreeContext amp ctxt return stat The next step is to create a reader that will read from the given source In our example we read from a file but it is also possible to read data from a socket or other source as well Alternatively a decode buffer may also be used 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 dynamic memory and stored pointers to objects in the C structure After processing on the C structure is complete the run time
366. n this definition lt name gt denotes the prefixed production name defined above The pct xt 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 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 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 215 Generated XML Functions 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 If it contains standard text this text will be used as the element name 2 If it is null a default element name will be applied Default names for all of the built in
367. n 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 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 initialization function is as follows asnlInit_ lt name gt 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 varia
368. nagement in many cases especially in shared libraries A minimum of four kilobytes is allocated for WSD every single time a DLL is loaded even if less space is required If 50 bytes were needed for example 4046 bytes would be wasted every time the DLL was loaded For this reason the use of WSD is highly discouraged In practice WSD are globally scoped variables declared outside of a function struct or class and static variables declared in functions WSD may be eliminated by modifying primitive types with const Complex types i e classes or structs with non trivial constructors will be marked as WSD whether marked const or not It is common in generated code to use lookup tables for some types e g ENUMERATED These tables are composed of simple types and marked as const to avoid being marked as WSD by Symbian compilers Extern Linkage Most common compilers support applying external linkage to an entire class but Symbian s does not Symbian also requires that both prototype and implementation be marked with the appropriate linkage When the symbian option is specified generated code is modified to accommodate these requirements The following specification will demonstrate the differences between code generated with Symbian and without Test DEFINITIONS BEGIN A NULL END The usual class definition for this specification looks like this class EXTERN ASNIC_A public ASN1CType protected
369. 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 OSCTXT pctxt lt name gt pvalue ASN1TagType tagging In this definition lt name gt denotes the prefixed production name defined above The pct xt 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 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 app
370. nation mapping is invoked and the particular general case applies the operand will actually be mapped to two ASN 1 components rather than just one a If the operand has an exponent determine whether the repetition is delimited using a more bit and done bit This is the case if the following apply e The operand s exponent is infinite e The exponents base string has a determinant call it more bit consisting of a single bit e The operand is immediately followed by a literal string consisting of a single bit call it done bit The negation of done bit is more bit In this case do the following i Discard the operand following this operand ii Invoke the Exponential mapping procedure on this operand iii If the Exponential mapping does not produce a type and the exponent s base has an empty remainder we recognize acase of an INTEGER with count bits encoding The operand maps to the ASN 1 type INTEGER 0 255 The encoding is as follows For a value v there are v bits equal to the more bit followed by a single done bit 261 Mapping CSN 1 to ASN 1 iv Otherwise the Exponential mapping shall have produced an ASN 1 type T which is a SEQUENCE OF R for some type R The operand maps to T The encoding of T shall be formed as follows this alters the encoding specified by the Exponential mapping For each R in T encode a more bit followed by the encoding for R Finally end the encoding by encoding a done bi
371. native is a null alternative e The other alternative produces an ASN 1 type d L H Alternative The alternation matches this pattern if there are exactly two alternatives each consisting of only a determinant with one determinant value being L and the other H e Particular General The alternation matches this pattern if the following conditions are met e None of the above patterns applied to the alternation e There are exactly two alternatives One of these must meet the requirements below for the particular alternative while the must meet the requirements below for the general alternative e The particular alternative has a determinant Call it the particular determinant e The general alternative does not have a determinant and would produce an ASN 1 type The general alternative begins with or is itself a bit string of a fixed length e g lt bit 4 gt Call this fixed length bit string the general determinant Note that the general determinant is not a determinant as that term is being used in this section 257 Mapping CSN 1 to ASN 1 it is not a fixed value but we can think of it as preceding the alternation and determining which alternative is encoded e The length of the particular determinant equals the length of the general determinat The general determinant excludes the value of the particular determinant f Stereotypical choice The alternation matches this pattern if the following conditions are
372. nce invoke the Reference Mapping procedure on it 7 Otherwise if the CSN1String is a Send expression invoke the Send mapping procedure for the string 8 If the string has a label name and the result of the above procedures is an ASN 1 type T rather than an ASN 1 component then the result of these procedures is an ASN 1 component C C is non optional C s type is T C s CSN 1 name is the label name The purpose of this rule is to preserve the label name from the CSN 1 in the ASN 1 Alternation Mapping Procedure Mapping an Alternation requires first evaluating the alternation so that we can determine what pattern it matches After the pattern is determined then we map the Alternation to ASN 1 The mapping procedure treats error alternatives identically to normal alternatives 1 Analyze each alternative of the alternation as follows a Determine whether the alternative would produce either an ASN 1 type or ASN 1 component This clause is not meant to invoke a mapping procedure for the alternative Currently we use the rule that any non literal string a string which matches more than one bit string would produce an ASN 1 type or ASN 1 component This rule has worked for us thus far It is for further study whether it is really an adequate rule 256 Mapping CSN 1 to ASN 1 b Determine whether the alternative consists of the empty string a determinant without a remainder a determinant with a remainder or a remainder only an
373. ncode if stat employee Encode 0 printf Encoding was successful n printf Hex dump of encoded record n ncodeBuffer hexDump printf Binary dump n encodeBuffer binDump employee Get start of message pointer and length msgptr encodeBuffer getMsgPtr len encodeBuffer getMsgLen else printf Encoding failed n encodeBuffer printErroriInfo exit 0 return 0 It is also possible to encode a PER message to a stream rather than a memory buffer To do this you would first declare a variable of one of the OSRT output stream classes This would then be associated with the encode buffer through the ASN1PERencode buffer declaration Everything after that would be similar to the memory buffer based program The preceding program fragment rewritten to do streaming output to a file would look like this include employee h include file generated by ASNIC main int stat OSBOOL aligned TRUE const char filename message_out per Create an instance of the compiler generated class This example write output to a file stream 190 Generated PER Functions OSRTFileOutputStream fostrm filename ASN1PEREncodeBuffer encodeBuffer fostrm aligned ASN1T_PersonnelRecord msgData ASN1C_PersonnelRecord employ encodeBuffer msgData Populate msgData within the class variable m
374. ncode buffer object ASN1PEREncodeBuffer 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 Instantiate an ASN1T_ lt ProdName gt object and populate it with data to be encoded Instantiate an ASN1C_ lt ProdName gt object to associate the message buffer with the data to be encoded Invoke the ASN1IC_ lt ProdName gt object Encode method Check the return status The return value is a status value indicating whether encoding was successful or not Zero 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 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 A program fragment that could
375. nd ASNIT_ lt Type gt control classes The format of the filenames of these files is as follows asnl lt suffix gt _ lt prodname gt cpp ASN1C_ lt prodname gt cpp ASN1T_ lt prodname gt cpp where lt suffix gt depends on the encoding rules and function type selected encode decode free etc and 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 production in the employee asn file asnlD_Name cpp asnlE_Name cpp ASN1T_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 ASNJC_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 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 with
376. nd remainder for an alternative 1 If the alternative is empty i e it consists of just the null terminal there is no determinant and the remainder is empty This alternative is called the null alternative 4 If the alternative is a Concatenation or a single literal the determinant is the longest string of literals that begins the alternative note the use of null in concatenation is superfluous and ignored If this string is empty the alternative does not have a determinant The rest of the alternative is the remainder If the alternative is a Reference that resolves to a single literal or a concatenation of literals those literals form the determinant The remainder is empty Otherwise the alternative does not have a determinant and the remainder part is the entire alternative A determinant could be written using exponentiation e g 10 2 instead of 1010 To keep things simple we do not support this 260 Mapping CSN 1 to ASN 1 Concatenation Mapping Procedure This section describes how to map a Concatenation It only applies as invoked by another mapping procedure A Concatenation is a truncated Concatenation if it is enclosed in curly braces and followed by the truncation operator e g lt a gt lt b gt 1 Nested concatenations are eliminated according to the following rule If concat outer is an unlabeled non truncated concatenation and concat inner is one of the operands of concat outer
377. ndoverRequest handoverResourceAllocation procedureCode id HandoverNotification criticality ignore HandoverNotify handoverNotification CEC u InitiatingMessage Note that the long names generated in the SLAP_ELEMENTARY_PROCEDURE_TVALUE type can be reduced by using the lt alias gt configuration element Generated C Type Definitions for Information Element IE Types In addition to message types another common pattern in 3GPP specifications is protocol information element IE types The general form of these types is a list of information elements as follows lt ProtocollEsType gt lt ProtocollE ContainerType gt lt ObjectSet gt lt ProtocollIE ContainerType gt lt Class gt lt ObjectSetParam gt SEQUENCE SIZE lt size gt OF lt ProtocolIE FieldType gt ObjectSetParam 90 ASN 1 To C C Mappings lt ProtocollE FieldType gt lt Class gt lt ObjectSetParam gt SEQUENCE 7 na lt elementl gt lt Class gt amp lt fixed type field gt ObjectSetParam lt element2 gt lt Class gt amp lt fixed type field gt ObjectSetParam element1 lt element3 gt lt Class gt amp lt Type field gt ObjectSetParam element1 There are a few different variations of this but the overall pattern is similar in all cases A parameterized type is used as a shorthand notation to pass an informatio
378. ne 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 different range values 53 ASN 1 To C C Mappings 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 OSINT16 short signed 16 bit int 0 65535 OSUINT16 unsigned short unsigned 16 bit int 2147483648 2147483647 OSINT32 int signed 32 bit intege
379. nent names are unique If unique names are not produced so that the ASN 1 is in error then the CSN 1 specification is considered to be in error as well for the purposes of the mapping To resolve this problem the CSN 1 must be adjusted CSN1String Mapping Procedure This procedure is only used when invoked by another procedure Angle brackets are a syntactic feature in CSN 1 We do not have a separate procedure for mapping a string in angle brackets If the angle brackets are used to make a reference the string is a reference and is mapped as such If the angle brackets are used to apply a label possibly in addition to being used to make a reference we map the string as though it were not labeled and then we take account of the label 1 If the CSN1String is an Alternation invoke the Alternation mapping procedure for the string 2 Otherwise if the CSN1String has an exponent invoke the Exponential mapping procedure on it 3 Otherwise if the CSN1String is a literal bit string a sequence of 1 or more literal bits then invoke the Literal mapping procedure for the string 4 Otherwise if the CSN1String is a Concatenation without an exponent and other than a simple concatenation of literal bits forming a literal bit string invoke the Concatenation mapping procedure for the string 5 Otherwise if the CSN1String is an Intersection invoke the Intersection Mapping procedure for the string 6 Otherwise if the CSN1String is a refere
380. nerated BER Functions ASN1T_PersonnelRecord msgData ASN1C_PersonnelRecord employ encodeBuffer msgData step 2 populate msgData structure with data to be encoded 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 code 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 OSOCTET msgptr int msglen construct encodeBuffer class with no arguments ASNIBEREncodeBuffer encodeBuffer ASN1T_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 156 Generated BER Functions 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
381. ng 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 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 especially if a large number of reallocations are required For this reason run time helper functions are provided 142 Generated Encode Decode Function and Methods 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
382. nibble allocation algorithm 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 which are very expensive in terms of performance The large blocks of memory are tracked through the ASN 1 context OSCTXT structure 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 rt xMemAlloc All memory can be released at once when a user is done with a structure containing dynamic memory items by calling rt xMemF ree 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 generated 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 rt xMem These are mapped to a set of similar functions that begin with the prefix rt xMemHeap A table showing this basic mapping is as follows Macro Function Description rtxMemAlloc rtxMemHeapAlloc Allocate memory rtxMemAllocZ rtxMemHeapAlloczZ Allocate and zero memory rtxMemRealloc rtxMemHeapRealloc Reallocate memory rtxM
383. not defined in the content model group 8 RTERR_SEQOVFLW Sequence overflow This status code is returned when decoding a repeating element ASN 1 SEQUENCE OF or XSD element with minmaxOccurs gt 1 and more instances of the element are received the content model group 9 RTERR_INVOPT Invalid option in choice This status code is returned when encoding or decoding an ASN 1 CHOICE or XSD xsd choice construct When encoding it occurs when a value in the generated t member variable is outside the range of indexes of items in the content model group It occurs on the decode side when an element is received that is not defined in the content model group 10 RTERR_NOMEM No dynamic memory available This status code is returned when a dynamic memory allocation request is made and an insufficient amount of memory is available to satisfy the request 11 RTERR_INVHEXS Invalid hexadecimal string This status code is returned when decoding a hexadecimal string value and a character is encountered in the string that is not in the valid hexadecimal character set 0 9A Fa f or whitespace 12 RTERR_ INVREAL Invalid real number value This status code is returned when decoding a numeric floating point value and an invalid character is received i e not numeric decimal point plus or minus sign or exponent character 13 RTERR_STROVFLW String overflow This status code is returned when a fixed sized field is being decoded a
384. ns 230 Procedure for Calling C Decode Functions cseccsece sec eece ence ee ce nese eeca ceca cena eeaeecaeeeneeenees 230 Generated C Decode Method Format and Calling Parameters o oo 232 Procedure for Using the C Control Class Decode Method n 232 14 Generated JavaScript Object Notation JSON Functions 20 00 00 ccc cece ee cece cece cece neceeeeeeeeeeeeeeeeaeeeaeeenes 234 Generated JSON Encode Function 2 2 cess sepsvhanes sietgee stoned oe dehdaensersudeoueyadersdueddongovedasw seus desaaeed dese 234 Generated C Function Format and Calling Parameters ccc cece cece ceeee eee ee cen eeneeeeeeeeneeees 234 Procedure for Calling C Encode Functions eccceeesee cece scence eeceeeceeeceeeeeeeeeeeeeeseeeseaeeenes 234 Encoding a Senes of Messages ors ootasin nE rae E E tenance des E EEE e aed vaya 235 Generated C Encoding Methods 3s cosh ieren oae a s RS adh beghee Seve tescaeeades 235 Encoding a Series of Messages using the C Control Class sssessesssesessrerisrrerrrrerrrreerreerese 236 Generated JSON Decode FUNCHONS sssri e seesedbopneaesste Seatishs wee cas peed E p senda th Seeseeb eet 236 Generated C Function Format and Calling Parameters 0 1ccccec cece eece ence eeceeecaeeen seen sean eeaes 236 Procedure for Calling C Decode Functions ce cee ceeec cece ence eeceeeeeeeca seca cena eens eeu eeneeeenees 237 Decoding a Series of Messages Using the C Decode Functions
385. nse n return i The next step is 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 start 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 This is illustrated in the following diagram Encode buffer size 1K Buffer start Start of Encode this way End of Buffer address 0x500 Message 0x100 0x200 In this example a 1K encode buffer is declared which happens to start at address 0x100 When the co
386. nted 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 In addition to this change in how open types are represented a large amount of supporting code is generated to support the table constraint validation process This additional code is described below Note that it is not necessary for the average user to understand this as it is not for use by users in accomplishing encoding and decoding of messages It is only described for completeness in order to know what that additional code is used for CLASS specification 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 structure 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 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
387. ntext 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 include employee h include file generated by ASNIC int main OSOCTET msgbuf 1024 msgptr 151 Generated BER Functions int msglen OSCTXT ctxt Employee employee typedef generated by ASNIC Step 1 Initialize the context and set the buffer pointer if rtInitContext amp ctxt 0 initialization failed could be a license problem printf context initialization failed check license n return 1 xe_setp amp ctxt msgbuf sizeof msgbuf Step 2 Populate the structure to b ncoded mployee name givenName 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 encoded message component if msglen gt 0 Step 5 If encodin
388. nts must use the parenthetical notation An attempt to use the notation will have the treated as part of the name use lt pig 4 gt not lt pig 4 gt The latter would be treated as a reference to the name pig 4 According to an unofficial source lt mylabel a b gt is supposed to be interpreted as lt mylabel lt a b gt gt However we report an error in this case and require you to use the extra brackets The reason for this is that lt maylabel a b gt is matched by the second alternative so that a b is taken to be a CSN1String But in order to avoid ambiguities involved in using multi word names outside of angle brackets we report an error whenever a multi word name is used fora CSN1St ring In order apply a label to an EXTENDED_NAME simply use extra angle brackets lt mylabel lt crazy name gt gt BasicString BasicString BraceExpr rte eS ees if aes ST eds AngleBracketString BraceExpr OptionalString not supported TruncatedString CSN1String TruncatedString CSN1String a Ae OptionalString LT CSNiString K l BasicString covers those strings which are self contained the literal bits null and expressions enclosed in some kind of brackets parentheses braces The braces ina BraceExpr have no real meaning except to set off part of a string and control operator precedence TruncatedString indicates that the string inside the curly brac
389. nversions are necessary for encoding and decoding 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 suppresses addition of an open extension element extElem in constructs that contain extensibility markers The purpose of the element is to collect any unknown items in a message If an application does not 12 Using the Compiler Option Argument Description 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 noxmlIns None This option suppresses the insertion of XML namespace entries in generated XML documents This includes xmlns attributes and prefixed names nouniquenames None This option suppresses the automatic generation of unique names to resolve name clashes in the generated code Name clashes can occur for example if two modules are being compiled that contain a production with the same name A unique name is generated by prepending the module name to one of the 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
390. o 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 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 Parser ASN 1 decode function follows The events are defined to be significant actions that occur during the parsing process We will define the following events tha
391. ocess each message A code fragment showing a way to do this is as follows include Employee h include file generated by ASNIC include rtbersrc ASNIBERDecodeStream h include rtxsrc OSRTFileInputStream h int main ASNITAG tag int i len const char filename message dat OSBOOL trace TRUE Decode ASN1BERDecodeStream in new OSRTFileInputStream filename if in getStatus 0 in printErroriInfo return 1 183 Generated BER Functions ASN1T_PersonnelRecord msgData ASN1C_PersonnelRecord employ msgData for 7G 4 if in peekTagAndLen tag len 0 printf peekTagAndLen failed n in printErroriInfo return 1 Now switch on initial tag value to determine what type of message was received switch msgtag case TV_PersonnelRecord compiler generated constant in gt gt employee if in getStatus 0 printf decode of PersonnelRecord failed n in printErroriInfo return 1 or employee DecodeFrom in case TV_ handle other known messages Need to reinitialize objects for next iteration mploy memFreeAll end of loop return 0 This is quite similar to the first example Note that we have pulled the ASN T_Employee and ASNIC_Employee object creation logic out of the switch statement and moved it above the loop These objects can now be
392. ocument 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 XML encode function is as follows lt namespace gt XmlEnc_ lt prefix gt lt prodName gt 225 Generated XML Functions where lt namespace gt is an optional C namespace prefix 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 lt namespace gt is set using the ASNIC namespace command line argument Note that this should not be confused with the notion of an XML namespace The calling sequence for each encode function is as follows status lt ns gt XmlEnc_ lt name gt OSCTXT pctxt lt name gt value const OSUTF8CHAR elemName const OSUTF8CHAR nsPrefix In this definition lt ns gt is short for lt namespace gt and lt name gt denotes the prefixed production name defined above The pct xt argument
393. ode 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 A program fragment that could be used to encode an employee record is as follows include 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 ASN1T_PersonnelRecord msgData msgData name givenName SMITH step 3 instantiate an instance of the ASN1C_ lt ProdName gt 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 0 printf encoded XML message n printf const char msgbuf printf n 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 218 Generated XML Functions el
394. ode 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 0 the message will have been encoded to the given stream Streaming 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 buffer for streaming 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 Streaming C Function Format and Calling Parameters The format of the name of each generated streaming encode function is as follows asnlBSE_ lt prefix gt lt prodName gt where lt prodName gt is the
395. ode Functions sienien e cece eee E O EE essa seca seas eeu eeaeeneeeeeeenes 164 Generated C Function Format and Calling Parameters cccccecceecc eee ence eeceeeceeeea seen sean eeaes 165 Generated C Decode Method Format and Calling Parameter o oo 169 BER Decode Performance Enhancement Techniques csseeceeececceeceueeeeeencenueeeeaeceeaeseeaneeeeees 173 Dynamic Memory Management ccc ceee cece see c nee E E SE E E esau sean eeges 173 Compact Code Generation se aea en igh wen ean tee a agi tev nen sy chet esata ter a EES 174 Decode Fast Copy sits E eieit hs Seedaie rela ede Se Sehegck a E Soiree ea Salton Dea eed a 174 Using Initialization Functions 0 cceeeceeeeeceeece cn eeceeececaeeceaeeeeeececaeseeuaeeeaeeeeaneeeeens 175 BER DER Deferred Decoding 0 0 32 eu a Benes Led aeed E O ek Se ace besa eead eneeasdbeesedos 175 Generated BER Streaming Decode Functions 0 cece cece cece cece cnee ce eeca cece cena cen eeneeeeeeeeeeeeeeeeeeaees 176 Generated Streaming C Function Format and Calling Parameters 00 ccceeeeeeeeee eee eeeeeeees 177 Generated Streaming C Decode Method Format and Calling Parameters 0 ceeeeee eee 181 10 Generated PER FUNCIONS sre nar Se ssyies Se brads beh ne E cee AES eau eal wand ede eae mea EE ERS 185 Generated PER Encode Functions siset ne get dce gonad opee ued dasa deedasnewhi ass adeussersteutdeg afetes 185 Generated C F
396. ode operation Status code 0 0 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 asnltype h include file The error text and a stack trace can be displayed using the rtxErrPrint function 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 OER Procedure for Calling C Encode Functions This section describes the step by step procedure for calling a C OER encode function This method must be used if C code generation was done 198 Generated Octet Encoding Rules OER Functions Before an OER encode function can be called the user must first initialize an encoding context block structure The context block is initialized by calling the rt nitContext function The user then has the option to do stream based or memory based encoding If stream based is to be done the user must call a rtxStreamCreateWriter function for the type of stream to which data will be written For example if the user wishes to write data to a file the rtvStreamFileCreateWriter function would be
397. ode to test bit gt define NamedBS_bitTen 10 define SET_BS3_bitTen bs lt code to set bit gt define CLEAR _BS3_bitTen bs lt code to clear bit gt define TEST_BS3_bitTen bs lt code to test bit gt 57 ASN 1 To C C Mappings Type definitions typedef struct ASN1IT_NamedBS OSUINT32 numbits OSOCTET data 2 NamedBS The named bit constants would be used to access the data array within the ASNIT_NameaBS type If bit macros were not generated the rtxSetBit function could be used to set the named bit bitOne with the following code NamedBS bs memset amp bs 0 sizeof bs rtxSetBit bs data 10 NamedBS_bitOne The statement to clear the bit using rtxClearBit would be as follows rtxClearBit bs data 10 NamedBS_bitOne Finally the bit could be tested using rtxTestBit with the following statement if rtxTestBit bs data 10 NamedBS_bitOne a Ditis 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 Contents Constraint It is possible to specify a contents constraint on a BIT STRING type using the CONTAINING keyword This indicates that the encoded contents of the specified type should be packed within the BIT STRING container An example of this type o
398. of failure errors are trapped and reported Finally the proper MDEREnc function is called to encode the data A pointer to the message content is retrieved using the rtxStreamMemoryGetBuffer function This pointer is used later to fill in the contents of the payload After encoding the payload the rest of the message content must be populated and encoded Initialize 2nd context structure stat rtInitContext amp ctxt2 Populate apdu with test data OSCRTLMEMSET amp aarq 0 sizeof AarqgApdu aarg assoc_version numbits 32 rtxSetBit aarq assoc_version data 32 AssociationVersion_assoc_versionl DataProto rtxMemAllocType amp ctxt2 DataProto DataProto gt data_proto_id data_proto_id_20601 DataProto gt data_proto_info numocts len DataProto gt data_proto_info data msgptr FOO IOS rtxDListAppend amp ctxt2 amp aarq data_proto_list pDataProto The msgptr variable is used here to fill in the contents of the dat a_proto_info structure The rest of the contents are initialized and then encoded apdu t T_ApduType_aarq apdu u aarg amp aarq Create memory output stream 209 Generated Medical Device Encoding Rules MDER Functions stat rtxStreamMemoryCreateWriter amp ctxt2 0 0 if stat lt 0 printf Create memory output stream failed n rtxErrPrint amp ctxt rtFreeContext amp ctxt Encode stat MDEREnc
399. of the ACGUI window is dedicated to editing ASN 1 schema definition files To create a new file click the New button in the toolbar or select File gt New Schema File in the menus To open an existing schema file either click the Open button in the toolbar or select File gt Open File from the menus In both cases the file will be added to the project and the editor will show it Clicking on an ASN 1 schema file name in the project window will also display that file in a tab in the editor At any point during editing the schema can be saved and checked for proper syntax by clicking the Validate button in the toolbar Compiling Once a project has been created and schemas added we re ready to compile This assumes that a target language has been selected in the project Click the Compile button or select Tools gt Compile from the menus If any files have unsaved changed we will be prompted to save them Once this is done the compiler will run generating source code and related files From here we can continue to make changes to the schema and to project settings and recompile as needed 36 ASNIC GUI Users Guide Interface Us ng joint iso u e ionsi0 3 DEFINITIONS i BEHN EXPOATS All The types and values defined in thes module are exported for use in the other ASHI modules co within the Directory Speciications and forthe use of other applications which will use them te a Directory senices Ot
400. of the intermediate 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 _n suffix is added where n is a sequential number to make the names unique 65 ASN 1 To C C Mappings It is possible to suppress the pulling out of nested types to form new types through the use of the lt inline gt configuration item This will not work in all cases however It is at times necessary to use the sizeof operator on an intermediate type to determine the size of a structure for memory allocations If a temporary type is not created it will not be possible to determine this size An error will be reported in this case 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 rewritten as the following set of productions X SEQUENCE al INTEGER a2 BOOLEAN Y OCTET STRING
401. ointers is undefined The error handler function if one is desired must also be defined 2 Objects of these classes or in C an instance of the Asn NamedCEventHandler struct must be created and registered prior to calling the generated decode method or function 285 Event Handler Interface The best way to illustrate this procedure is through examples We will first show a C and then a C version of 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 C 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 and newline The value will then be printed followed by another newline Finally a closing brace followed by another newline will terminate the printing of the element An indentation count will 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
402. oke type fields 4 Encode the Invoke type to produce the final message 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 Object 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
403. ommand line option is used a more specialized type of structure is generated In this case instead of a void pointer being used to hold an instance of a type containing data to be encoded all entries from the referenced Information Object Set are used in a union structure in much the same way as is done in a CHOICE construct If code is being generated from an XML schema file and the file contains an lt xsd any gt wildcard declaration a special type of any structure is inserted into the generated C C code This is the type OSXSDAny which is defined in the osSysTypes h header file This structure contains a union which contains alternatives for data in either binary or XML text form This makes it possible to transfer data in either binary form if working with binary encoding rules or XML form if working with XML Character String Types 8 bit character character string types are either represented using a character pointer const char or if cpp11 is specified on the command line std string In the case of const char the pointer is used to hold a null terminated C string for encoding decoding For encoding the string can either be static i e a string literal or address of a static buffer or dynamic The decoder allocates dynamic memory from within its context to hold the memory for the string This memory is released when the rt xMemF ree function is called The useful character string types in ASN 1 are as follows
404. on mapping Otherwise if this procedure was not invoked by the Concatenation mapping this procedure produces a SEQUENCE consisting of the same two components that would have been produced in the first case a We currently do not support the case where the particular determinant uses L or H bits b If the general determinant is not labeled and the general determinant s exclusion string is labeled copy the label from the exclusion string to the general determinant itself c Invoke the CSN1String mapping procedure for the general determinant This will produce the determinant type DT d Create an ASN 1 CHOICE type 259 Mapping CSN 1 to ASN 1 m Remove the particular determinant from the particular alternative The result is the new particular alternative If nothing remains let the particular type be the ASN 1 NULL type Otherwise something remains invoke the CSN 1String mapping procedure on what remains in order to produce the particular type Add a NamedType to the CHOICE type for the particular alternative The type shall be the particular type The identifier shall be determined according to the rules in ASN 1 Identifier Assignment Remove the general determinant from the general alternative The result is the new general alternative Invoke the CSN1String mapping procedure on what remains to produce the general type Add a NamedType to the CHOICE type for the general alternative The type shall be
405. onal the decode function can be called directly if the type of message is known if msgtag TV_PersonnelRecord Step 3 Call decode function note last two args should always be ASNIEXPL and 0 status asnlD_PersonnelRecord amp ctxt employee ASNI1EXPL 0 Step 4 Check return status if status 0 process received data in employee variable Remember to release dynamic memory when done rtxMemFree amp ctxt 166 Generated BER Functions else 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 main OSOCTET msgbuf 1024 ASN1TAG msgtag int msglen OSCTXT ctxt PersonnelRecord employee Step 1 Initialize a context variable for decoding if rtInitContext amp ctxt 0 initialization failed could be a license problem printf context initialization failed check license n return 1 for 77 logic to read message into msgbuf xd_setp amp ctxt msgbuf 0 amp msgtag amp msglen Step 2 Test message tag for type of message received note thi
406. ontrol 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 required 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 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 11 Using the Compiler Option Argument Description the compilation unit that is currently being generated is complete mder None This option is used to generate functions that implement the Medical Device Encoding Rules MDER as specified in the IEEE ISO 11073 standard mt None When used in conjunction with the genMake command line option the generated makefile uses multi threaded libraries nmake lt filename gt This option instructs the compiler to generate a Visual Studio compatible makefile It is equivalent to using the genMake w32 combination of command line options noContaining None This option suppresses the generation of inline code to support the CONTAINING keyword Instead a normal
407. 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 const char 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 asn1 Compare_Employee employee amp employee etc might be used 279 Additional Generated Functions The pvalue argument is used to pass a pointer to a variable of the item to the first item to be compared The pCmpValue 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 These arguments may be omitted by passing null 0 values if you only care
408. or 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 ASNI C 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 is 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 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 lt name gt BIT STRING Generated C code typedef ASN1DynBitStr lt name gt Generated C code typedef ASN1TDynBitStr ASN1T_ lt name gt In this case different base types are used for C and C The difference between th
409. or socket without intermediate copying into memory If the full amount of data is 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 is available or an I O error occurs for example the remote side closes the connection Generated Streaming C Function Format and Calling Parameters The format of the name of each streaming decode function generated is as follows asn1lBSD_ 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 follows status asnlBSD_ lt name gt OSCTXT pctxt lt name gt pvalue ASNiTagType tagging int length In this definition lt name gt denotes the prefixed production name defined above The pct xt 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 vari
410. ormation on compiler generated warnings xer None This option is used to generate encode decode functions that implement the XML Encoding Rules XER as specified in the X 693 ASN 1 standard The xsd option can be used in conjunction with this option to generate a schema describing the XML format xml None This option is used to generate encode decode 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 is used 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 16 Using the Compiler Option Argument Description if the filename argument is not provided There are two supported mappings from ASN 1 to XSD one corresponding to the xml option and one corresponding to the xer option The default is to follow the xml variant If the xer option is given then that variant is followed 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 wit
411. out this option 120 Generated C C Source Code 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 moduleName gt c cpp lt moduleName gt Enc c cpp lt moduleName gt Dec c cpp All code was generated in a single file with 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 and above In 5 6 and below the cfile option did not have any effect for files containing copy print compare etc functions For ASN1C 5 7 and above cfile causes everything to be output to one file unless specific filename parameters are specified with genPrint genCopy etc Once again to maintain the previous behavior the compat 5 6 option can be used Generated C files and the symbian Option ASNIC version 6 1 introduced the symbian option to generate code that targets the Symbian platform While an exhaustive discussion of the differences between Symbian C and standard C is impractical for this User s Guide the differences in generated code are relatively minimal Two principle areas of concern are writable static data WSD and extern linkage Writable Static Data Writable static data are per process data that exist throughout the lifetime of the process The use of WSD complicates memory ma
412. p rriective SYSTEMS INC ASNIC ASN 1 Compiler Version 6 8 C C Users Guide Reference Manual Objective Systems Inc version 6 8 July 2015 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 2015 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 ASN1C may be submitted via electronic mail to info obj sys com Table of Contents Le Overview OL ASNIC songs pea ni tsa pinaasles ous cadet ipttaseebacen dane tages pave hvacnt a E E E ss Da E T des 1 2 Using the Compiler sci s665 ss r niere i EEEE EAE cededa euch ieee ches Sask Stk os Sees ie eee de ashore 2 Running ASNIC from the Command line 2 0 0 0 cece cc eeceneceeece ences ceeeeaeeea seca eeaa esas eeaeeeneeeenees 2 Compiling and Linking Generated Code 0 0 0 0 eee cecc cece ence ence eeceeeceeeeaeeeaeeea sean eeue eeu eeneeeeeeees 17 Porting Run time Code to Other Platforms 20 0 0 cece cece cece cece cee ce eece cena eeae een Tp a aE ea 18 Compiler Configuration Fil sesse eseese este e rE eave covebevedevents EE O a 19 Compiler Error RepOrting sisse 255 cavscces cases cecngess
413. pe ASN1XERSAXHandler protected ASNIT_ lt name gt amp msgData additional control variables public ASN1C_ lt name gt ASNIT_ lt name gt amp data ASN1C_ lt name gt ASN1MessageBufferIF amp msgBuf ASN1T_ lt name gt amp data 128 Generated Encode Decode Function and Methods standard encode decode methods defined in ASN1CType base class int Encode int Decode stream encode decode methods int EncodeTo ASN1MessageBufferIF amp msgBuf int DecodeFrom ASN1iMessageBufferIF amp msgBuf SAX Content Handler Interface virtual void startElement 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 bi The main differences between the BER DER PER control class definition and this are 1 The class generated for XER inherits from the ASNIXERSAXHandler 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 ASN1C would then receive the parsed data via the SAX interface and use the r
414. pe is a 4 bit value and should be 0101 In practice subclass expressions are applied not only to references but also to exponentiated references as in the above example where it is applied to bit 4 2 The CSN1St ring in the first alternative must be a string of one or more literals 3 The second alternative specifies an integer value Obviously this requires knowing how many bits should be used to encode that integer value which means the reference with exponent if given must have a fixed length 252 Chapter 17 Mapping CSN 1 to ASN 1 Introduction In this chapter we discuss our mapping from CSN 1 to ASN 1 There is no standard procedure for this mapping what we present here is our own invention The purpose of this mapping is ultimately to be able to generate data binding code from the CSN 1 code that includes structures that mirror the data defined in the CSN 1 along with code for encoding those structures into a bit string according to the CSN 1 definition and decoding in the reverse direction For a description of CSN 1 along with the grammar we use to describe CSN 1 please refer to the previous chapter The purpose of this chapter is to help you understand how we generate code from CSN 1 by explaining the intermediate step that our compiler internally performs the CSN 1 to ASN 1 conversion This chapter is not required reading you might skip it for now and return to it if needed Note that you can see the
415. pe is referenced to allow any derivation of the type to be used in a message An example of this is as follows lt xsd complexType name MyType gt lt xsd sequence gt lt xsd element name ElementOne type xsd string gt lt xsd element name ElementTwo type xsd int gt lt xsd sequence gt lt xsd complexType gt lt xsd complexType name MyExtendedType gt lt xsd complexContent gt lt xsd extension base MyType gt lt xsd sequence gt lt xsd element name ElementThree type xsd string gt lt xsd element name ElementFour type xsd int gt lt xsd sequence gt lt xsd extension gt lt xsd complexContent gt lt xsd complexType gt The base type in this case is MyType and it is extended to contain two additional elements in MyExtendedType The resulting C type definitions for MyType MyExtendedType and the special derivations type are as follows typedef struct EXTERN MyType const OSUTF8CHAR elementOne OSINT32 elementTwo MyType typedef struct EXTERN MyExtendedType const OSUTF8CHAR elementOne OSINT32 elementTwo const OSUTF8CHAR elementThree OSINT32 elementFour MyExtendedtType define T_MyType_derivations_myType 1 define T_MyType_derivations_myExtendedType 2 typedef struct EXTERN MyType_derivations int t union 112 XSD to C C Type Mappings ete EA MyType myType PR BOS Dn BI MyExtendedType
416. pename to distinguish the data class from the control class the control class contains an ASN1C_ 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 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
417. perator to assign a string msgData name SMITH step 4 invoke lt lt operator or EncodeTo method out lt lt employee or employee EncodeTo out can be used here step 5 check status of the operation if out getStatus 0 printf Encoding failed Status i n out getStatus out printErroriInfo return 1 if trace printf Encoding was successful n Encoding a Series of Messages Using the Streaming C Control Class Interface Encoding a series of messages using the streaming 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 ASN1C include rtbersrc ASN1B Eal REncodeStream h include rtxsrc OSRTFileOutputStream h int main const OSOCTET msgptr OSOCTET msgbuf 1024 int msglen const char filename message dat 163 Generated BER Functions step 1 ASNIBER if out gets ou ES CUEN L step 2 EncodeStream out tatus t printErroriInfo construct stream object new OSRTFileOutputStream filename
418. pes instead of integers Generate fully qualified enumerated constants Support indefinite PER lengths Pad PER BIT STRING contained values In the case of C or C as the target language code modifications include several settings for adjusting how ASN 1 types are mapped to native C C types C Code Modifications For C modifications allow for manipulating the namespace into which code is generated 49 ASNI1C GUI Users Guide Java Code Modifications Specify package name Specify package prefix Similarly for Java the package name for generated code can be changed Build Options tab When a target language other than None is selected an additional Build Options tab contains language environment specific settings for generating makefiles and build scripts 50 ASNIC GUI Users Guide l Generate Makefiles Windows nmake GNU Generate Visual Studio Project VS 2013 V5 2012 ao oC VS 2010 v5 2008 WS 2005 WS 2003 V5 6 0 1998 Be ey cay Build Libraries C Generate static libraries C Generate shared libraries Generate multithreaded libraries Link applications using shared libraries For C and C a makefile can be generated in either Windows or GNU format For Windows a Visual Studio project can also be generated Under Build Libraries which will generate the build script to build a library rather than an executable the des
419. pile an XML schema definitions XSD file and generate encoders decoders that can generate XML in compliance with the schema as well as binary encoders encoders that implement the ASN 1 binary encoding rules ASNIC 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 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 ASNIC also 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 The compiler can also parse type syntax from common macro definitions such as the ROSE OPERATION and ERROR macros Chapter 2 Using the Compiler Running ASN1C from the Command line The ASNIC compiler distribution contains command line compiler executables as well as a graphical user interface GUD wizard 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 compiler was successfully installed enter asnic with no parameters as follows note
420. ponent is not returned only an OK status indicating encoding was successful A negative value indicates encoding failed Return status values are defined in the asnitype 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 185 Generated PER Functions 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 PER encode function This status value will be 0 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 f
421. possible by setting the buffer address argument to null and the buffer size argument to zero An encode function can then be called to encode the message If the return status indicates success 0 then the message will have been encoded in the given buffer or written to the given stream 3GL3 encoding starts from the beginning of the buffer and proceeds from low memory to high memory until the message is complete This differs from definite length BER where encoding was done from back to front Therefore the buffer start address is where the encoded 3GL3 message begins The length of the encoded message can be obtained by calling the rtxCtxtGetMsgLen run time function If dynamic encoding was specified i e a buffer start address and length were not given the rtxCtxtGetMsgPtr run time function 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 a 3G NAS Identity Request message is as follows include rt3gppsrc TS24008Msgs h include file generated by ASNIC main TS24008Msg_PDU pdu TS24008Msg_IdentityRequest idReq OSCTXT ctxt OSOCTET msgbuf 256 msgptr int i len stat const char filename message dat Initialize context structure stat rtInitContext amp ctxt if 0 stat printf rtInitContext failed status d n ret rtxErrPrint amp ctxt return ret
422. 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 lt namespace gt is set using the ASNIC namespace command line argument Note that this should not be confused with the notion of an XML namespace The calling sequence for each decode function is as follows status lt ns gt XmlDec_ lt name gt OSCTXT pctxt lt name gt pvalue In this definition lt name gt denotes the prefixed production name defined above The pct xt 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 returns the status of the decode operation Status code zero indicates the function was successful A negative value indicates
423. procedure to encode a message using the C class interface is as follows 1 Instantiate an XML encode buffer object OSXMLEncodeBuffer to describe the buffer into which the message will be encoded Constructors are available that allow a static message buffer to be specified The default constructor specifies use of a dynamic encode buffer 2 Instantiate an ASN1T_ lt type gt object and populate it with data to be encoded 3 Instantiate an ASN1IC_ lt type gt object to associate the message buffer with the data to be encoded 4 Invoke the ASN1C_ lt type gt object Encode or EncodeTo method 5 Check the return status The return value is a status value indicating whether encoding was successful or not Zero 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 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 XML 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 A program fragment that could be used to encode an employee record is
424. py was introduced in version 6 7 primarily in response to the need to pacify some static code analysis tools that flagged unchecked memory copies Formerly ASN1C generated code that used the OSCRTLMEMCPY macro to make calls to memcpy or by editing the rtxCommonDefs h file to a function of the user s choice ASNIC now generates code that calls OSCRTLSAFEMEMCPY which provides checks to ensure that the destination buffer is sufficiently large to hold the source content In this way ASNIC helps to prevent potential buffer overflows The runtime libraries also use this macro internally Zero on Free Users also have the option of zeroing memory whenever it is freed or reset using the memory heap functions In sensitive applications this can prevent exploits that depend on reading data from memory after it is freed by the calling application In order to activate zero on free users will need to set a flag in the runtime context heap 148 Memory Management in C C OSCTXT ctxt int heap_flag RT_MH_ZEROONFREE stat T ll stat rtInitContext amp ctxt if stat 0 rtxErrPrint amp ctxt return stat rtxMemHeapSetProperty amp ctxt pMemHeap OSRIMH_PROPID_SETFLAGS void amp heap_flag There are two caveats to zeroing memory on free First it is a slow operation and will noticeably degrade performance in most cases Second it will leave some metadata behind
425. r 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 int 64 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 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 ASNIC compiler allows an integer to be declared a big integer via a configuration file variable the lt isBigInt
426. rated EXTENDED XER code Working with the code generated for EXTENDED XER is the same as for XER except that you must be sure to have set the OSASN1XER context flag The generated PDU encoders and decoders should automatically set OSASN1XER for you but if you are not using these methods you should be sure to set the OSASN1XER flag yourself using rtxCtxtSetFlag For encoding and decoding you will work with the XML as opposed to the XER runtime This is actually true for BASIC XER also unless you are using the deprecated old style XER Finally there is a sample reader and writer program in c sample_xer employ xer and cpp sample_xer employ xer should you need to see an example 214 Generated XML Functions Generated XER Encode Functions Old Style Deprecated XER stands for XML Encoding Rules a form of XML specified in the X 693 standard for use with ASN 1 Note As noted in the Overiew the style of generated code that is discussed here is now deprecated To upgrade to the new style see the section below for some upgrade tips The old style XER encode functions can still be generated by specifying the xer compat 649 or lower switches on the command line This ability may be removed in some future version of ASN1C so you are encouraged to upgrade to the new style For each ASN 1 prouction defined in the ASN 1 source file a C XER encode function is generated This function will convert a pop
427. rated 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_ 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 print function is as follows asnlPrint_ lt name gt const char name lt name gt pvalue In this definition lt name gt denotes the prefixed production name defined above 276 Additional Genera
428. rates the helper methods NewElement and Append in the generated control class for a SEQUENCE OF 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 cop sample_ber employee writer cpp file for an example of how these methods are used In this program the following logic is used to populate one of the elements in the children list for encoding ASN1T_ChildInformation pChildInfo ASN1C__SeqOfChildInformation listHelper encodeBuffer msgData children pChildiInfo listHelper NewElement fill_Name amp pChildInfo gt name Ralph T Smith pChildInfo gt 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 ASNIC also generates helper methods in SEQUENCE SET and CHOICE control classes to assist in allocating and adding elements to inline SEQUENCE OF lists These methods are named new_ lt elem gt _element and append_to_ lt elem gt where lt elem gt would be replaced with the name of the elem
429. re Login ARGUMENT and encode Encoded message pointer and length Populate ROSE header message structure Invoke and encode Open type structure contains message pointer and length from previous step Vv Final encoded message On the decode side the process would be reversed with the message flowing up the stack ROSE Layer 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 294 ROSE and SNMP Macro Support 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 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 applicationspecific 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 fo
430. re a consistent size of an enumerated variable and to handle the case of unknown extension values If the use enum types use enumerated types command line option is selected the type generated for C is identical to what is generated for the C case documented above when this option is selected NULL The ASN 1 NULL type does not generate an associated C or C type definition 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 62 ASN 1 To C C Mappings typedef ASNIOBJID lt name gt Generated C code typedef ASN1ITObj Id ASNIT_ 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 and assignment operators that make setting the value a bit easier The ASNIOBJID 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 ASNIOBJID 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 ASNITO
431. resulting ASN 1 that is generated from CSN 1 by adding the asnl lt f ilename gt option to the compiler command line this tells the compiler to output the ASN 1 to a file The challenge in defining the mapping is that CSN 1 is a concrete syntax To a certain degree by naming labeling parts of the notation semantics are conveyed but the notation is still a concrete notation not an abstract notation like ASN 1 In order to generate data structures from CSN 1 in a way similar to what asnlc does for ASN 1 we need to recognize patterns in the CSN 1 and infer the semantics That s what our CSN 1 to ASN 1 mapping does Once we internally map the CSN 1 into ASN 1 we can generate code for it just as we do for ASN 1 On the surface the mapping procedure might seem simple but a semi formal description of the mapping is complex for a variety of reasons First there are multiple possible mappings so there are choices to be made Also not everything in the CSN 1 represents application data some bits are auxiliary they are purely a part of the encoding so some parts of the CSN 1 probably shouldn t be mapped into ASN 1 at all but yet must be accounted for somehow Just to illustrate consider the following simple example as a way to highlight the difference between CSN 1 being concrete and ASN 1 being abstract This CSN 1 calls for a single bit either a O or 1 in the encoding lt value bit gt First note that we have chosen to name the b
432. 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 184 Chapter 10 Generated PER Functions Generated PER Encode Functions PER encode decode functions are generated when the per perindef or uperswitch is specified 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 lt prefix gt is an optional prefix that can be set via a configuration file setting The configuration setting use
433. rint of the different libraries asnlxer_a lib asnlxml_a lib asnirt lib DLL libraries These are used to link against the DLL versions of the run time asnlber lib libraries asn rt dll etc asnlper lib asnlxer lib asnlxml lib asnirtmt_a lib Static multi threaded libraries These libraries were built with the MT option asnlbermt_a lib They should be used if your application contains threads and you wish to link asnlpermt_a lib with the static libraries The DLLs are also thread safe asnlxermt_a lib asnixmlmt a lib In Visual Studio 2005 and greater all libraries are multi threaded by default E so these libraries are not available for those versions asnlrtmd_a lib DLL ready multi threaded libraries These libraries were built with the MD asnlbermd_a lib option They allow linking additional object modules in with the ASNIC run asnlpermd_a lib time modules to produce larger DLLs asnlxermd_a lib asnlxmlimd_a lib 17 Using the Compiler 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 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
434. roduction 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 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 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 asn1type h include file 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 ASNIBERDecodeBuffer class has a standard method for parsing the initial tag length from a message to determine the 169 Generated BER Functions type of message received This call is used in conjunction w
435. ror Codes This appendix describes all of the status codes that may be returned during code generation and program execution in three sections The first contains errors that might arise when generating code from an input ASN 1 or XML schema Runtime error messages are divided into two sections the first for errors that are independent of the underlying encoding like socket read errors or end of buffer messages and the second for errors related specifically to ASN 1 encodings like invalid object identifiers or bad tag values The runtime error messages may be found in the runtime documentation as well Users may look at rtxsrc rtxErrCodes hand rtsrc asnll ErxrCodes h for up to date lists of what may be returned Code Generation Error Messages The following table describes error messages that ASN1C may report during the course of code generation not during runtime These include syntax errors import warnings type resolution failures and others There are several classes of status messages in this list errors ASN E messages warnings ASN W messages and informational notices ASN I messages Error Code ASN E NOTYPE Error Description No type was defined for the referenced element in a SEQUENCE or SET ASN E UNDEFTYPE The type referenced was not defined within the context of this module ASN E NOTAG The object must be tagged in this context This usually occurs when context specific tags are r
436. rrsrerrrrrsrrrersrrerrsrrsrrerrreresrrerrsreerreresrt 121 Generated C files and the symbian Option ss ssessssseessesrssrerrsrrsrreresrrrrsrrerrsrrerrsresrrreesrereereet 121 Writable Static Dafa o2 0 05 csis Gecasisieyegusts uecastaaeeecesta Secussteees poses unos bok ETETE AEE EE ES EE AEAEE SEE 121 Extern binkage roni aa E osasieie nrctieees natty sas Dea dba A a e E rete see T a Eas 121 Considerations When Using C Standard Library 0 0 0 0 ee cece cee ceeece teen seca seen eeaeeeneeeneeeneees 122 Generated Build Files eapon sss cose osses rE EEEE Ehra otepa seas cs sedsaees seovesud asp iacdastotinasacdsaesstessecatsaeSewsees 124 Generated Makefile seiren ae ers erne S e E EEEE ES E EESE E E EEE E ee EEA 124 Generated VC Project Files speserei iaa nip D e a E E E E E E EEE GE 125 7 Generated Encode Decode Function and Methods 2 0 0 0 cece cece cee cence teen cece cece eeeeeeae cea eeneeeneeeeeeeeees 126 Encode Decode Function Prototypes lt 02 s cc0cisscccesssectssspecssenss sores isvestencssecveegsseose sys suseandseevanessseees 126 Generated C Control Class Definition 2 0 0 0 cece cece eee cee ce eece ceca cece eeae eens eeneeneeeeeeeeeeeeeaees 127 BER DER ot PER Class Definition seisseen ii aa E nabag ges EEE ates 127 AER Class Definitio ss i a Wes S e ra e S E EEEE E eS E 128 Generated Methods vrss rsio Soo tossed based oE seco aeaa RTEA yP RAE E PEORES SEEPI EET a KINESER 129 Generated Information Object Table
437. rs configuration error 11 bit gt In this example the error alternative is a never ending bit string This is pretty useless for a decoder as it doesn t allow the decoder to recover and continue decoding the rest of the data You have two options in this case First you could entirely remove the error alternative This will cause the decoder to fail if that input would have been matched Second you could modify the error alternative to be simply the determinant the 11 In that case if the error alternative is found the decoder may or may not fail depending on the input but your code can report an error if the error alternative was matched The send Operator mom The send operator either send or is used in cases where a decoder should be able to accept various inputs but an encoder should send something particular It is commonly used in relation to padding such as Padding using L bits lt spare padding gt lt bit gt send L A single pad bit commonly used as lt spare bit gt lt spare bit gt lt bit gt send 0 We ve seen a few uses of the send operator in the 3GPP specifications that were likely not written as intended There are basically two issues 1 inattention to operator precedence and 2 mistakes in planning for extension compatibility These issues are illustrated in 3GPP 44 018 10 5 2 25c RR Packet Uplink Assignment We ll discuss each of these here with simplified
438. rsibility is for further study This requirement allows us to have the encoder set the value the length determinant based on the actual encoded length of the constrained operand It could be relaxed by requiring the user to supply a value for the length determinant and requiring the encoder to verify that the exponent evaluates to a value consistent with the actual encoded length Due to considerations related to the internal workings of our code generation tool we place an additional requirement on the use of length determinants The length determinant is required to immediately precede the Intersection in the encoding Therefore the mappings do not cover the contrary case which is left for further study It is considered an error if the Intersection does not satisfy the requirements specified in this procedure Intersection Mapping Procedure This procedure only applies when invoked by another procedure For an Intersection that is the operand of a Concatenation this procedure is only invoked if the Intersection does not have a length determinant This along with the requirement see the Analysis procedure that any length determinant immediately precede the Intersection means that this procedure is never invoked for an Intersection that has a length determinant This procedure will always produce a SEQUENCE type This was motivated by the internal working of our code generation tool relative to length constrained content It may not alway
439. ry 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 57 Cros Parent void fillParent Parent parent A aa B bb C cc logic to populate aa bb and cc parent gt a amp aa parent gt b amp bb 141 Generated Encode Decode Function and Methods parent gt c CCG 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 fil 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 i 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 compl
440. s status x3GL3Enc_ lt name gt OSCTXT pctxt lt name gt value In this definition lt name gt denotes the prefixed production name defined above The pct xt 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 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 st at returns the status of the encode operation Status code 0 0 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 asnltype h include file The error text and a stack trace can be displ
441. s e encoding named numbers as empty elements Enforcement of Encoding Instruction Restrictions ASNIC does not check that you are using encoding instructions properly Misapplication of encoding instructions has undefined results For example X 693 does not generally allow ATTRIBUTE to be applied to a sequence type there are a few cases where it can be such an application produces malformed XML In particular when applying ATTRIBUTE to a restricted character string type the type should be restricted to exclude the control characters listed in X 680 15 15 5 since these control characters are encoded as empty elements Another solution would be to use ATTRIBUTE and BASE64 together except that ASNIC does not currently support BASE64 for restricted character strings ASN1C will not enforce this rule but you will get malformed XML if you try to encode a string having control characters as an attribute e XSD Generation The xsd switch does not currently generate XSD that can be used to validate EXTENDED XER encodings Actually in the worst cases it is not possible to produce XSD that validates precisely the set of valid EXTENDED XER encodings the closest approximations would either fail to reject some invalid encodings or fail to accept some valid encodings This is a result of the encoder s options which can produce mixed content models and XML Schema s limited abilities to constrain mixed content models Working with gene
442. s be the most natural mapping l 2 3 5 Invoke the Intersection Analysis procedure on the Intersection Invoke the CSN1String mapping procedure on the constrained operand of the Intersection If the previous step produces an ASN 1 SEQUENCE type this procedure produces the same SEQUENCE type a If the SEQUENCE s encoding was specified as being padded to a byte boundary this is changed to being padded to the fixed length specified by the constraining operand using the same bits for padding Otherwise if the procedure produced some other ASN 1 type or an ASN 1 component that type or component is wrapped into a SEQUENCE type which will be the type produced by this procedure The name of the component added to the SEQUENCE will be derived from the ASN 1 type or ASN 1 component in the same way as is done when mapping a Concatenation Otherwise this Intersection is not supported Literal Mapping This procedure only applies when invoked by another procedure 265 Mapping CSN 1 to ASN 1 This procedure is used to map a literal bit string a sequence of one or more literal bits It will only be invoked when a literal string is not otherwise incorporated into the encoding For example it is not invoked to map the strings that act as alternative determinants in an Alternation 1 This mapping restricts the literal to being 32 bits or less The literal is mapped to the ASN 1 type INTEGER k where k is the integer int
443. s 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 memory free function is as follows asnlFree_ lt name gt OSCTXT 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 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 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 gene
444. s error is returned from within a list iterator when it is detected that the list was modified outside the control of the iterator 107 ASN_E_ ILLSTATE Illegal state for operation This error is returned in places where an operation is attempted but the object is not in a state that would allow the operation to be completed One example is in a list iterator class when an attempt is made to remove a node but the node does not exist 108 109 ASN_E_ NOTPDU ASN_E_UNDEFTYP This error is returned when a control class Encode or Decode method is called on a non PDU Only PDUs have implementations of these methods Element type could not be resolved at run time This error is returned when the run time parser module is used AsnIRTProd to decode a type at run time and the type of the element could not be resolved 110 ASN_E_INVPERENC Invalid PER encoding This occurs when a given element within an ASN 1 specification is configured to have an expected PER encoding and the decoded value does not match this encoding 305
445. s h include file The error text and a stack trace can be displayed using the rtvErrPrint function In addition to the XML encode function generated for types a different type of encode function is generated for Protocol Data Units PDU s These are types in an ASN 1 specification that are not referenced by any other types In an XML schema specification these are global elements that are not reference within any other types or global elements The format of the a PDU encode function is the same name format as above with the suffix _PDU This function does not contain the elemName and nsPrefix arguments these are built into the function as defined in the schema For this reason calling PDU functions is usually more convenient than calling the equivalent function for the referenced type Procedure for Calling C Encode Functions This section describes the step by step procedure for calling C XML encode functions This procedure is similar to that for the other encoding methods except that some of the functions used are specific to XML Before an XML encode function can be called the user must first initialize an encoding context block structure The context block is initialized by calling rtXmlInitContext to initialize a context block structure The user then must call the rtXmlSetEncBufPtr function to specify a message buffer to receive the encoded message Specification of a dynamic message buffer is possible by setting the buffer address arg
446. s in the encoders and decoders to meet the encoding and decoding rules specified as part of the mapping procedure Since the CSN 1 is compiled to ASN 1 internally you can use a config file in the usual way All you have to do is be careful to use the ASN 1 names in the config file rather than the CSN 1 names For example instead of My Favorite Type you would use the converted name My Favorite Type You may find it helpful to see the ASN 1 that resulted from the CSN 1 to ASN 1 mapping you can this by adding the asnl lt filename gt option to the compiler command line to tell the compiler to output the ASN 1 to a file Using CSN 1 and ASN 1 Together Our tool lets you use the CSN 1 and ASN 1 notations in tandem in a straightforward way A few simple example files should suffice to illustrate Example 18 1 main csn1 ASNIMODULE Main lt My Pdu gt lt Name gt lt Location gt lt FooBar gt lt Marker gt lt Marker gt lt ml bit 5 gt lt m2 bit 3 gt Example 18 2 main asn1 Main DEFINITIONS AUTOMATIC TAGS BEGIN IMPORTS Name Location FROM Common FooBar SEQUENCE foo INTEGER 0 3 bar BOOLEAN marker Marker END 267 Compiling CSN 1 Example 18 3 common csn1 ASNIMODULE Common lt Name gt lt octet 5 gt Example 18 4 common asn1 Common DEFINITIONS AUTOMATIC TAGS BEGIN Location ENUMERATED city 1 su
447. s 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 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 OSDynOctStr AsciiString typedef OSDynOctStr EBCDICString 76 ASN 1 To C C Mappings typedef struct String int t union Rit clin S7 AsciiString asciiString fae ee ego EBCDICString eBCDICString u 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
448. s is optional the decode function can be called directly if the type of message is known Now switch on initial tag value to determine what type of message was received switch msgtag case TV_PersonnelRecord compiler generated constant status asnilD_PersonnelRecord amp ctxt amp employee ASN1EXPL 0 if status 0 decoding successful data in employee 167 Generated BER Functions process received data else error processing break default handle unknown message type here switch Need to reinitialize objects for next iteration rtxMemReset amp ctxt The only changes were the addition of the for loop and the call to rtxMemReset 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 rtxMemFree 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 which the buffer already contains multiple messages encoded back to back it is necessary to advance the buffer pointer i
449. s specified by a size constraint and the item contains more characters or bytes then this amount It can occur when a run time function is called with a fixed sixed static buffer and whatever operation is being done causes the bounds of this buffer to be exceeded 14 RTERR_BADVALUE Bad value This status code is returned anywhere where an API is expecting a value to be within a certain range and it not within this range An example is the encoding or decoding date values when the month or day value is not within the legal range 1 12 for month and 1 to whatever the max days is for a given month 15 RTERR_TOODEEP Nesting level too deep This status code is returned when a preconfigured maximum nesting level for elements within a content model group is exceeded 300 ASNIC Error Codes Error Code Error Name Description 16 RTERR_CONSVIO Constraint violation This status code is returned when constraints defined the schema are violated These include XSD facets such as minmaxOccurs minmaxLength patterns etc Also ASN 1 value range size and permitted alphabet constraints 17 RTERR_ENDOFFILE Unexpected end of file error This status code is returned when an unexpected end of file condition is detected on decode It is similar to the ENDOFBUF error code described above except that in this case decoding is being done from a file stream instead of from a memory buffer 18 RTERR_INVUTF8 Invalid U
450. se printf Encoding failed n encodeBuffer printErroriInfo exit 0 msgptr and len now describe fully encoded messag Tips for Upgrading to the New Style The old XER runtime generally has corresponding methods in the XML runtime that you can use For example xerEncStartDocument can be replaced by rtXmlEncStartDocument XmlEnc_ lt Type gt _PDU methods will encode a type along with the start and end of the XML document These methods can be used to replace a sequence of calls to xerEncStartDocument asni XE_ lt Type gt and xerEncEndDocument When invoking an XmlEnc_ lt Type gt method you must pass the correct element name to encode the value within unlike asnl XER_ lt Type gt the xmlasnltypename is not automatically supplied for you You will want to pass null for the namespace argument since XER does not use XML namespaces Calls to rtInitContext should be replaced by calls to rtxmlInitContext If you are not using one of the XmlEnc_ lt Type gt methods you must use rtxCtxtSetFlag to set the OSASNIXER flag This signals the generated and runtime code that XER and not OSys XER rules apply xerSetEncBufPtr is replaced by rtXmlSetEncBufPtr The latter does not accept a canonical flag Use rtxCtxtSetFlag to set the OSXMLCIAN flag if you want to encode using canonical XER the OSASNIXER flag must still also be set xerGetMsgPtr is replaced by rtXmlGetEncBufPtr XERBYTECNT can be replaced by rtxCtxt
451. section describes how to perform two phase encoding and decoding using the MDER Run Time Library Examples are also provided in the distribution Two phase Encoding We demonstrate an example of two phase encoding using communication with an electrocardiogram This code is based on the ASN 1 specification provided in IEEE 11073 20601 2008 and submitted drafts for an application of this type Two phase encoding requires the use of multiple encoding contexts to encode both the header and payload They must therefore be declared with the rest of the pertinent variables ApduType apdu AarqApdu aarqd DataProto pDataProto PhdAssociationInformation phdAssocInfo OSCTXT GEXE CEE Zs OSOCTET msgptr int len const char filename message dat We first populate and encode the payload specific details will vary depending on the application Populate and encode PhdAssociationInformation OSCRTLMEMSET amp phdAssocInfo 0 sizeof phdAssocInfo phdAssocInfo protocol_version numbits 32 phdAssocInfo protocol_version data 0 0x40 phdAssocInfo encoding_rules numbits 16 rtxSetBit phdAssocInfo encoding_rules data 16 EncodingRules_mder phdAssocInfo nomenclature_version numbits 32 rtxSetBit phdAssocInfo nomenclature_version data 32 NomenclatureVersion_nom_versionl1 phdAssociInfo functional_units numbits 32 phdAssocInfo system_type numbits 32 rtxSetBit phdAsso
452. sed 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 This flag variable specifies that this element will be decoded as an open type i e skipped Refer to the section on deferred decoding for further information Note that this variable can only be used with BER CER or DER encoding rules lt length fixed size number gt This item is used to configure a length field in an OCTET STRING type for 3GPP layer 3 messages By default a length field is a single byte but there are occasions where the field width may be different This allows a fixed size encoded field width to be specified The most common values are 0 no length field or 2 This item is only supported for C 3GPP layer 3 code generation lt notUsed gt n a This flag variable specifies that this element will not be used at all in the generated code It can only be applied to optional elements within a SEQUENCE or SET or to elements within a CHOICE Its purpose is for production of more compact code by allowing users to configure out items that are of no interest to them lt perEncoding gt perEncoding gt lt lt selector element name value value gt hex data This variable allows a user to substitute a known binary PER encoding for the given element This encoding wil
453. sgData name givenName SMITH Encode if stat employee Encode 0 printf Encoding was successful n printf Hex dump of encoded record n ncodeBuffer hexDump printf Binary dump n encodeBuffer binDump employee else printf Encoding failed n encodeBuffer printErroriInfo exit 0 return 0 Note that the encodeBuffer hexDump and encodeBuffer binDump commands work despite the fact that the output has been written to a stream This is because a capture buffer is used when tracing is enabled to record all of the encoded information If memory is tight a user should ensure that trace output is turned off when using the stream 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 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 l
454. should be generated for this production This item is only supported for C 3GPP layer 3 code generation lt setvar name name value value gt This item is used within encode and decode functions to set a given variable within a generated structure to the given value Normally it is used in conjunction with the addarg configuration item to set a variable to value of an additional argument passed into a function This item is only supported for C 3GPP layer 3 code generation lt storage gt lt storage gt One of the following keywords dynamic static list array dynamicArray std list std vector Std deque The definition 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 26 Using the Compiler Name Values Description lt typePrefix gt lt typePrefix gt Element Level 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 ASN1T_ prefix This can be used to prevent name clashes if multiple modules are involved in a compilation and they all contain common names These attributes can be applied at the element level by including them within an lt element gt section func encodeldecode gt specified using attributes Name
455. sion Exclusion CSN1String CSN1String CSN1String exclude CSN1String The and exclude operators are equivalent The Exclusion matches any string that matches the left hand operand and does not match the right hand operand Intersection Intersection CSN1String amp CSN1String CSN1iString and CSN1String The amp and and operators are equivalent The Intersection matches any string that is matched by both operands Send Expression SendExpression CSN1String CSN1String CSN1String send CSN1String The and send operators are equivalent The left hand operand represents the string that should be matched by a decoder The right hand operand represents the string that should be sent by an encoder Naturally the right hand operand should provide a value that can be accepted by the left hand operand Subclass Expressions Subclass CSN1String nis INTEGER SubclassOpt empty Subclass 251 CSN 1 Described 1 A subclass expression is meant to be applied to a reference as a way of further restricting the referenced string 3GPP 24 007 does not discuss subclassing this comment is based on non official resources This makes it a way of specifying that a particular value should be present in the encoding and that this string is one of those strings matched by the given reference For example lt message_type bit 4 0101 gt is a way of saying message_ty
456. 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 expat sourceforge net All of the necessary include files and binary libraries are included with the 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 Porting Run time Code to Other Platforms The run time source version of the compiler includes 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 th
457. sses to accomplish encodings as in the following code snippet 235 Generated JavaScript Object Notation JSON Functions OSJSONEncodeBuffer encodeBuffer 0 0 ncodeBuffer setDiag verbose ASN1T_PersonnelRecord msgData ASN1C_PersonnelRecord employ encodeBuffer msgData Populate structure of generated type here Encode if stat employee Encode 0 if trace printf Encoding was successful n printf s n const char encodeBuffer getMsgPtr The generated control class ASNLC_PersonnelRecord contains methods for encoding Encode It unites the message data held in ASN1T_PersonnelRecord and the encoding buffer OSTSONEncodeBuf fer to encode the JSON message Encoding a Series of Messages using the C Control Class Encoding a series of messages is virtually identical in the C case as it is with C for 7 logic for populating the data type stat employee Encode if stat 0 encoding was successful else error handling encodeBuffer init The major difference in this case is that the init method is called at the end of the loop rather than the C runtime function rtxMemReset The init method serves the same purpose Generated JSON Decode Functions Generated C Function Format and Calling Parameters The format of the name of each decode function generated is as follows 236 Generate
458. 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 lt filename gt 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 a new file will be started with an _1 appended for example lt moduleName gt Enc_1l 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
459. structure if it was allocated void rtxMemHeapRelease void ppvMemHeap There is no analog in standard memory management In most cases it is only necessary to implement the following functions e rtxMemHeapAlloc e rtxMemHeapAllocZ e rtxMemHeapFreePtr e rtxMemHeapRealloc There is no analog in standard memory management for ASNIC s rtxMemFree macro i e the rtxMemHeapF reeA11 function The user is responsible for freeing all items in a generated ASNIC structure individually if standard memory management is used The rtxMemHeapCreate and rtxMemHeapRelease 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 rtxMemHeapCreate 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 OSCTXT structure The rtxMemHeapRelease 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 145 Memory Management in C C Built in Compact Memory Management A built in version of the simple memory management API described above i e with direct calls to malloc free etc is available for us
460. such as the context structure and tag type parameters 161 Generated BER Functions 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 ASNIEncodeStream class The function result variable st at returns the completion status Error status codes are negative Return status values are defined in the rtxErrCodes 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 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 ASNI EncodeStream 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 Streaming C Control Class Encode Method The procedure to encode a message directly to an output s
461. t If the Exponential mapping procedure did not produce an ASN 1 type it is an error b If the operand has an exponent and the repetition is not delimited using a more bit and done bit do the following i Invoke the Exponential mapping procedure on the operand ii If the exponent is infinite then one of the following cases must apply or else it is an error A The Exponential mapping produced an ASN 1 type and no operands follow this operand This is a case of container delimited repetition The requirement that there be no subsequent operand is due to the fact that nothing can be encoded following a container delimited repetition B The Exponential mapping recognized the operand as padding iii As long as the previous clause does not indicate an error this operand is mapped to the result of invoking the Exponential mapping c Otherwise invoke the CSN1String mapping procedure on the operand d If the CSN1String mapping procedure recognized a single pad bit then the operand is mapped to the ASN 1 type INTEGER 0 1 When the ASN 1 component is created for this operand it shall have a DEFAULT value corresponding to the value of the pad bit e It is an error if any operand except for the last is mapped to padding This is because padding is a repetition whose length is determined by the container boundary thus nothing is permitted to follow it Let asnlobjects be the set of ASN 1 types and ASN 1 components that the operands
462. t concern themselves with idiosyncrasies like byte alignment or length markers Short pseudo code is shown below As in the encoding example rt xMemReset is used at the end of the loop to avoid allocating new memory for dynamic data structures This helps to improve performance initialize context et c for 7 initialize data structure call MDERDec_ lt name gt function perform operations on decoded structure reset memory stat rtxMemReset amp ctxt More details may be found in the sample programs included in the ASN1C software development kit Two Phase Messaging MDER is specified using ITU T X 208 which uses a two phase method for encoding and decoding ANY DEFINED BY types These types are used to allow flexibility in message transmission by specifying a hole in a message to be filled in by a type specified by an object identifier 207 Generated Medical Device Encoding Rules MDER Functions Let us assume for sake of example that we wish to transmit a message that has a generic header and a payload defined by some object identifier We must first encode the payload and attach it to the message Then we can encode the whole message and transmit it Because this takes two steps we call this two phase encoding The inverse holds for decoding The whole message is first decoded The payload may then be identified and decoded according to its specific type This
463. t have no ASN 1 definitions That means that if you create an ASN 1 file to do nothing more than define imports you will need to define at least one type such as Dummy NULL Tips on Working with CSN 1 This section contains various tips on working with CSN 1 Error Alternatives As discussed in the mapping procedures we treat error alternatives the same as regular alternatives It is up to the user to recognize that the error alternative was matched However the 3GPP specifications often specify error alternatives in ways that don t seem useful Let s consider some examples 1 lt Ignore bit lt no string gt gt In this example a send construction is being used in the error alternative This seems pointless because presumably an encoder would not encode an error alternative and therefore would not encode whatever the send construction 268 Compiling CSN 1 specifies for the encoding Remove the send construction in such cases In the rest of the examples we ll omit the send construction Next observe the meaning of this alternation a one bit is accepted and a zero bit is an error In this case you could just as well replace the alternation with the good alternative A decoder will fail on bad input If however you want to be able to tell that decoding failed for this reason you can replace the alternation with bit and write your code to report an appropriate error if the bit is zero lt PDCH pai
464. t namespace gt dynamicArray nerated cod EQUENCE add a C namespace to g use dynamic arrays for S C only OF SET OF types Using the Compiler linkedList use linked lists for SEQUENCE OF SET OF types hfile lt filename gt C or C header h filename default is lt ASN 1 Module Name gt h cfile lt filename gt C or C source c or cpp filename default is lt ASN 1 Module Name gt c genBitMacros generate named bit set clear test macros genFree generate memory free functions for all types hdrGuardPfx lt pfx gt add prefix to header guard defines in h files maxcfiles generate separate file for each function maxlines lt num gt set limit of number of lines per source file default value is 50000 noBitStr32 do not use BitStr32 type for small bit strings noEnumConvert do not generate conversion functions for enumerated items BER CER DER PER only noInit do not generate initialization functions oh lt directory gt set output directory for header files perIndef add support for PER indefinite fragmented lengths perPadBitStrings pad bit strings that contain other types to octet boundary prtToStrm lt filename gt generate print to stream functions hexStrFmt lt hexAsciiDump formattedHexDump hexstring gt change the output format for hexadecimal strings from the default hexAsciiDump
465. t structure and the tag type parameters 154 Generated BER Functions 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 ASN1C_ 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 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 ASN1T_ lt name gt type and populate it with the data to be encoded 2 Create an ASNIBEREncodeBuffer object 3 Create a variable of the generated ASN1C_ 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 ASN1C_ lt type gt class takes a message buffer object argument This makes it possible to specify a static encode message buffer when the class variable is 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
466. t 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 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 284 Event Handler Interface In C 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 CppEvtHndlr h header file In C the first 3 event types are contained within a struct Asn NamedCEventHandler defined in asnI CEvtHndlr
467. tatus decodeBuffer ParseTagLen msgtag msglen if status 0 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 0 decoding successful data in employeeData process received data else 171 Generated BER Functions error processing break default handle unknown message type her switch Need to reinitialize objects for next iteration if isLastIteration employee memFreeAll end of loop This is quite similar to the first example Note that we have pulled the ASN T_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 BER messages encoded back to back then it is necessary to modify the buffer pointer in each iteration The getByteIndex method s
468. ted Functions 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 asn1Print_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 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 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 const char name lt name gt
469. ternaitve option for C C is table unions which generates union structures for table constraints These are generally easier to work with then the legacy void pointer approach used in this option 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 module from the ASN 1 source file hdrGuardPrefix lt prefix gt This option allows the specification of a prefix that will be used in the generated defines that are added to header files to make sure they are only included once hexStrFmt hexAsciiDump formattedHexDump hexstring Setting the hex string format allows users to change how OCTET STRINGs and uninterpreted open types are printed The default behavior is to output a formatted dump with hex and printable ASCII characters side by side this is the hexAsciiDump option formattedHexDump removes the ASCII component and hexstring removes a
470. ters 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 asn1lXD_ 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 follows status asnlXD_ lt name gt OSCTXT pctxt lt name gt pvalue In this definition lt name gt denotes the prefixed production name defined above The pct xt argument is used to hold a context pointer to keep track of decode parameters This is a basic handle variable that is
471. th a table constraint within a SEQUENCE container is as follows lt Type gt SEQUENCE lt element gt lt Class gt amp lt type field gt lt ObjectSet gt index element If tables is not specified on the command line a standard open type structure is used to hold the element value typedef struct lt Type gt ASN1OpenType lt element gt The ASN1OpenType built in type holds the element data in encoded form The only validation that is done on the element is to verify that it is a well formed tag length value TLV structure if BER encoding is used or a valid length prefixed structure for PER If the tables command line option is selected the code generated is different In this case ASN1OpenType above is replaced with ASN1Object or ASN1TOb ject for C This is defined in asnlt ype h as follows typedef struct generic table constraint value holder ASN10penTyp ncoded void decoded OSINT32 index table index 94 ASN 1 To C C Mappings ASN1Ob ject 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 a 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 represe
472. the t value in the structure to the selected information object field and then populate the type field This is very similar to populating a CHOICE construct The comments in the elements show what the value of the key element s must be if that alternative is selected The open type field at the end extElem1 is added because the object set is extensible and it therefore may contain a value that is currently not included in the set Legacy Table Form Code Generation In the legacy form of table constraint code generation the following structure would be generated for the Invoke type above typedef struct EXTERN Invoke OSINT32 invokeID 132 Generated Encode Decode Function and Methods _OPERATION_operationCode opcode ASN1O0bject argument This is almost identical to the type generated in the simple case The difference is the ASN1 Object type or ASNI TObject for C that is used instead of ASNI OpenType This type is defined in the asn type h run time header file as follows typedef struct ASN1Object ASN10penTyp 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 of this type is as follows 1 Populate a variable of the type to be used as the argument to the invoke type 2 Plug the address of this variable into the decoded void pointer in the structure above 3 Populate the remaining Inv
473. the C Control Class Encode Method n 217 Tips for Upgrading to the New Style cece cc cece ece iee EEE E EEE EESE esau sean ES 219 Generated XER Decode Functions Old Style Deprecated 20 0 0 cece cece cece cece eeneeneeeneeennees 219 Procedure for Using the C Interface ccccccc cece ence a c cence ance E E T E sean eeags 221 Generated C Function Format and Calling Parameters 1 1 0 0 ccccsecceec eee ceeceeeceeeceeeea ceca eenneeaes 221 Procedure for Calling C Decode Functions cccccsec sec c ence eece ee ceeeceeecaeeea cena eeaeecueceaneenees 221 Procedur e for Using the C Interface vrspern pete gos eotene snob eeatis ESE ESINE pR Apae 223 Procedure for Interfacing with Other C and C X ML Parser Libraries o oo 224 Tips for Upgrading to the N w Stylesin ineeie aae ee a a a e E es S 225 Generated XML Encode Function Sisseneri ee asn i ceca e p E E O S E E aR 225 Generated C Function Format and Calling Parameters c0ccceccsece nec eeceeeceeeceeeea seca sean scans 225 Procedure for Calling C Encode Functions 0 cccccsccceec cece nece nce e cence ence eeeeeeseeeeeeeseeseuesenes 226 Generated C Encode Method Format and Calling Parameters o oo 227 Procedure for Using the C Control Class Encode Method o 228 Generated XML Decode F nctions oyen senn edsr oree EE a EEE NENE RE EOE ENER E ENES 229 Generated C Function Format and Calling Parameters cccccec cece eee eeceeeceeecaeeea teen cena sca
474. the C interface This is because the control class hides all of the details of managing the context and releasing dynamic memory The 170 Generated BER Functions 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 is 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 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 ASN1T and ASNIC objects ASNIBERDecodeBuffer decodeBuffer msgbuf len ASN1T_PersonnelRecord employeeData ASN1C_PersonnelRecord employ decodeBuffer employeeData for Cpe A logic to read message into msgbuf s
475. 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 OSRTDList and have the name extElem1 This is a linked list of open type fields Each entry in the list is of type ASN1 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 extElem1 element These elements will be treated as optional elements whether they were declared that way or not The reason is because a 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 exten
476. the course of code generation typically this is raised during test code generation ASN E INVXMLATTR This indicates that the specified attribute type must be a simple type ASN E INTERNAL This indicates that internal structures used for generating code are inconsistent ASN E NOPDU This indicates that a PDU type was not found for generating a reader or writer program General Runtime Error Messages The following table contains runtime status codes that may occur during program execution These failures do not arise from ASN 1 specific features such as an invalid PER encoding for example but buffer overflows invalid socket options or closed streams Error Code Error Name Description 0 RT_OK Normal completion status 2 RT_OK_FRAG Message fragment return status This is returned when a part of a message is successfully decoded The application should continue to invoke the decode function until a zero status is returned 1 RTERR_BUFOVFLW Encode buffer overflow This status code is returned when encoding into a static buffer and there is no space left for the item currently being encoded 2 RTERR_ENDOFBUF Unexpected end of buffer This status code is returned when decoding and the decoder expects more data to be available but instead runs into the end of the decode buffer 3 RTERR_IDNOTFOU Expected identifier not found This status is returned when the decoder
477. 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 Q main GI OSOCTI int OSBOOL msgl i step 1 ASNIPERDecodeBuffer decodeBuffer aligned fil includ generated by msgbuf 1024 en stat TRUI GI nstantiate a PER decode buffer object step 2 i ASN1T_Person step 3 i msgbuf msglen nstantiate an ASNIT_ lt ProdName gt object nelRecord msgData nstantiate an ASN1C_ lt ProdName gt object ASN1C_Person loop to c EO Cpe et logic nelRecord employ decodeBuffer msgData ontinuously decode records to read message into msgbuf stat step 5 If stat proces else err decode step 6 mploy memF r Decod check the return status s received data or processing Buffer PrintErroriInfo O free dynamic memory All mploy If rea to the decodeBuf O ding unaligned data it is necessary to do next octet boundary before decoding the n ASN1C aligned a byte align operation to mov fer byteAlign xt messag 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
478. 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 specific 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 calling rtInitContext to initialize a context block structure 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 0 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 T
479. therwise if none of the above clauses applied it is an error g If the above clauses specified a type for T this procedure produces the type SEQUENCE OF T The size constraint clause below applies 6 If the above procedures produced a type and noted that the size constraint clause applied then the exponent shall be evaluated to determine whether a size constraint should be added to the type This is done as follows a If the exponent is a constant integer k then the size constraint SIZE k shall be added The encoding shall consist of k bits k octets or k encodings of type T depending on whether the type was a BIT STRING OCTET STRING or SEQUENCE OF T b Otherwise if the exponent is infinite or non reversible no size constraint is added The encoding shall consist simply of the bits octets or encodings of type T based on the value depending on whether the type was a BIT STRING OCTET STRING or SEQUENCE OF T Unless the calling procedure specifies otherwise the encoding is delimited by its container It is an error for an encoder to encode anything following this type within the same container A decoder will recognize the end of the encoding when it finds the end of the container c Otherwise we evaluate the exponent The exponent uses the val function to refer to a single labeled string or else it would be non reversible or a constant integer Call the reference string RefString RefString shall have already been mapped
480. this document is not from any official source Also it is a simplified version of the grammar as used by our parser e g the rules presented here do not reflect operator precedence A note on the grammar syntax it is basically bison grammar syntax with a shorthand for repetition x means zero or more x x means one or more x x means 0 or 1 x Definitions multi word name A name which contains spaces CSN 1 Lexical Items Literals There are 5 literals 0 1 L H and null Not surprisingly 0 represents a 0 bit and 1 represents a 1 bit The null terminal not surprisingly matches the empty string Then we have L and H The bit value of an L or H depends on the position within the encoding Take the bit pattern 0x2B 0010 1011 and repeat it infinitely many times Line up your entire encoding with this pattern The value of L at a given position in the encoding is the value of the bit at the corresponding position in the pattern The value of H is the opposite of the value of L So for example given an encoding of 0010 1011 which matches the pattern exactly you have the encoding for LLLL LLLL Given an encoding of 1101 0100 the negation of the pattern you have the encoding for HHHH HHHH 0111 1110 is the encoding for LHLH LHLH All of these examples assume that the encoding given is at the beginning of the entire encoding In order to determine the value for an L or H bit you
481. thod The procedure to encode a message using the C class interface is as follows 1 Instantiate an ASN 1 XER encode buffer object ASNIXEREncodeBuffer 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 ASN1T_ lt type gt object and populate it with data to be encoded 3 Instantiate an ASN1IC_ lt type gt object to associate the message buffer with the data to be encoded 4 Invoke the ASN1C_ lt type gt object Encode method 217 Generated XML Functions 5 Check the return status The return value is a status value indicating whether encoding was successful or not Zero 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 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 XER Enc
482. tialization failed could be a license problem rtxErrPrint amp ctxt return stat Step 2 Populate the structure to b ncoded pdata rtxMemAllocType amp ctxt ApduType asnlInit_ApduType pdata pdata gt t T_ApduType_rlrq pdata gt u rlrq rtxMemAllocTypeZ amp ctxt RlrqApdu pdata gt u rlrq gt reason normal Step 3 Call the generated encode function Eal stat MDI REnc_ApduType amp ctxt pdata Step 4 Check the return status if stat lt 0 rtxErrPrint amp ctxt return stat 204 Generated Medical Device Encoding Rules MDER Functions stat rtFreeContext amp ctxt if stat 0 printf Error freeing context n return stat return 0 Encoding a Series of Messages Using the C Encode Functions Encoding a series of messages in MDER is very similar to encoding a series of messages in any other set of encoding rules Performance can be improved by calling rt xMemReset to avoid allocating new memory for dynamic message structures as in the code below initialize context et c for 7 initialize populate message structure to b ncoded call MDEREnc_ lt messageType gt call rtxMemReset when finished encoding rtxMemReset pctxt More details may be found in the sample programs included in the ASNIC software development kit Generated MDER D
483. tion ASN E DUPLCASE ASN E AMBIGUOUS This tag was used in a previous switch case statement This indicates a general ambiguity in the specification such as multiple embedded extensible elements ASN E VALTYPMIS This indicates the value specified does not match the type it is associated with ASN E RANGERR This indicates the value is not within defined range for its associated type ASN E VALPARSE ASN E INVRANGE This indicates a general failure to parse a value definition It would be raised for example if a floating point number was used as part of a SIZE constraint This indicates an invalid range specification for example when the lower bound is greater than the upper bound ASN E IMPORTMOD This indicates that the specified import module object was not found ASN E NOTSUPP This indicates that the requested functionality is not supported by the compiler Most often the error is raised when generating test code for complex value definitions ASN E IDNOTFOU ASN E NOFIELD This indicates the compiler was unable to look up the specified identifier This indicates that the specified field could not be found in the named class ASN E DUPLNAME This indicates the specified name is already defined ASN W UNNAMED This warning is raised when specifications use unnamed fields These fields not allowed in X 680 but ASNIC supports them for purposes of backwards compatibility with
484. tion function must be called explicitly SEQUENCE or SET Value Specification The mapping of an ASN 1 SEQUENCE or SET value 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 name VisibleString 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 initialization function would be as follows 86 ASN 1 To C C Mappings value id 12 value name abc SEQUENCE OF SET OF Value The mapping of an ASN 1 SEQUENCE OF or SET OF value declaration to a global C or C value declaration is as follows ASN 1 production lt name gt lt SeqOfType gt lt value gt Generated code lt SegqOfType 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 SeqOfType value Code generated in the value initialization function would be as follows
485. tions e rtxStreamFileOpen e rtxStreamFileAttach e rtxStreamSocketAttach e rtxStreamMemoryCreate e rtxStreamMemoryAttach 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 0 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 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 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 include employee h include file generated by ASNIC main int stat OSCEXT CET PersonnelRecord employee 222 Generated XML Functions ASN1ConstCharPtr filename message xml Step 1 Init context structure if rtInitContext amp ctxt 0 return 1 rtxStreamInit amp ctxt Step 2 Open a stream stat rtxStreamFileOpen amp ctxt filename OSRTSTRMF_
486. tions in ASN 1 is limited This section relates to our support for XER encoding instructions If some features you need are not supported you might consider using direct compilation of XSD How to Generate Code for EXTENDED XER If your ASN 1 contains XER encoding instructions ASNIC will automatically generate code for EXTENDED XER instead of BASIC XER This is true whether you use xer or xm1 on the command line If however any unsupported encoding instructions are found ASNIC will ignore all XER encoding instructions since it would not be capable of supporting EXTENDED XER for that specification 213 Generated XML Functions Supported Instructions and Brief Summary ASNIC supports these instructions ATTRIBUTE and BASE64 Very brief summaries of the effects of these instructions follow e ATTRIBUTE This instruction causes a component of a sequence to be encoded as an XML attribute e BASE64 This instruction causes octet strings to be encoded in a base64 representation rather than a hexadecimal one Limitations The following are limitations related to EXTENDED XER e For BASE64 ASNIC only supports BASE64 on octet strings Using BASE64 with octet stings having contents constraints open types or restricted character strings is not supported e For encoder s options ASN1C decoders do not support the following encoder s options allowed by EXTENDED XER e encoding named bits as empty element
487. 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 st at returns the status of the decode operation Status code 0 0 indicates the function was successful A negative value indicates decoding failed Return status values are defined in the asn1type 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 status 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 passe
488. tream using the C class interface is as follows 1 Create an OSRTOutputStream object for the type of output stream Choices are OSRTFile OutputStream for a file OSRTMemory OutputStream for a memory buffer or OSRTSocketOutputStream for an IP socket connection 2 Create an ASNIBEREncodeStream object using the stream object created in 1 as an argument 3 Create a variable of the ASN T_ lt name gt type and populate it with the data to be encoded 4 Create a variable of the generated ASNIC_ lt name gt class specifying the item created in 2 as an argument to the constructor 5 Invoke the EncodeTo method or lt lt operator 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 include rtbersrc ASN1IBEREncodeStream h include rtxsrc OSRTFileOutputStream h Eal main int msglen const char filename message dat step 1 construct output stream object 162 Generated BER Functions ASNI1BEREncodeStream out new OSRTFileOutputStream filename if out getStatus 0 out printErroriInfo return 1 step 2 construct ASN1C C generated class ASN1T_PersonnelRecord msgData ASN1C_PersonnelRecord employ msgData step 3 populate msgData structure with data to be encoded note this uses the generated assignment o
489. ucted types In some cases simplifications are done to make the generated code easier to work with The following are mappings for specific XSD complex types xsd sequence The XSD sequence type is normally mapped to an ASN 1 SEQUENCE type The following items describe special processing that may occur when processing a sequence definition If the resulting SEQUENCE type contains only a single repeating element it is converted into a SEQUENCE OF type This can occur if either the sequence declaration has a maxOccurs attribute with a value greater than one or if the single element inside has a similar maxOccurs attribute If the sequence contains an element that has a minOccurs 0 attribute declaration the element is mapped to be an OPTIONAL element in the resulting ASN 1 SEQUENCE assignment If the sequence contains a repeating element denoted by having a maxOccurs attribute with a value greater than one then a SEQUENCE OF type for this element is used in the ASN 1 SEQUENCE for the element If attributes are defined within the complex type container containing the sequence group attributes are defined these attribute declarations are added to the resulting ASN 1 as element declarations as per the X 694 standard In XML encodings these appear as attributes in the markup in binary encodings they are elements Example lt xsd complexType name Name gt lt xsd sequence gt lt xsd element name givenName type xs
490. ues are defined in the asnltype h include file Procedure for Calling C Encode Functions This section describes the step by step procedure for calling a C MDER encode function 203 Generated Medical Device Encoding Rules MDER Functions Before any encode function can be called the user must first initialize an encoding context This is a variable of type OSCTXT 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 InitContext function as follows OSCTXT ctxt if rtInitContext amp ctxt 0 initialization failed could be a license problem printf context initialization failed check license n return 1 After initializing the context and populating a variable of the structure to be encoded an encode function can be called to encode the message A program fragment that could be used to encode a simple release request PDU is as follows Eal include IEI E 11073 20601 ASN1 h include file generated by ASNIC int main void ApduType pdata typedef generated by ASNIC OSCTXT CUxXt OSOCTET msgptr int stat Step 1 Initialize the context and set the buffer pointer stat rtInitContext amp ctxt if stat 0 ini
491. ulated C variable of the given type into an XER encoded ASN 1 message i e an XML 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 Note that you may use the xsd switch when generating XER encoders and decoders with xer The XML schema produced from the ASN 1 specification using the xsd switch can be used to validate the XML messages generated using the XER encode functions Similarly an XML instance can be validated using the generated XML schema prior to decoding Generated C Function Format and Calling Parameters The format of the name of each generated XER encode function is as follows asn1lXE_ 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 status asnlXE_ lt name gt OSCTXT pctxt lt name gt value const char elemName const char attributes I
492. ument to null and the buffer size argument to zero An encode function can then be called to encode the message If the return status indicates success then the message will have been encoded in the given buffer XML 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 226 Generated XML Functions back to front Therefore the buffer start address is where the encoded XML message begins If a dynamic message buffer was used the start address of the encoded message can be obtained by calling the rtXmlEncGetMsgPtr function Since the encoded XML message is nothing more than a null terminated string in a memory buffer the standard C library function strlen can be used to obtain the length A program fragment that could be used to encode an employee record is as follows include employee h include file generated by ASNIC int main int argc char argv PersonnelRecord employee OSCTXT CUxt OSOCTET msgbuf 4096 int stat Initialize context and set encode buffer pointer stat rtXmlInitContext amp ctxt if 0 stat printf context initialization failed n rtxErrPrint amp ctxt return stat rtXmlSetEncBufPtr amp ctxt msgbuf sizeof msgbuf Populate variable with data to be encoded mployee name givenName John Encode data stat
493. unction 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 a PER encode function can be called the user must first initialize an encoding context block structure The context block is initialized by calling the rtInitContext to initialize the block The user then must call pu_setBuffer 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 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 0 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 i 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 encode
494. unction Format and Calling Parameters 0 c0ccsecc usec ence ence ence neces ceneeaeeeaeeaaes 185 Generated C Encode Method Format and Calling Parameter o oo 185 Populating Generated Structure Variables for Encoding 1 1 0 2 cccccec cece ence nee ece ne eeneccueeeecennees 186 Procedure for Calling C Encode Functions 1 ccseccsecenecc ence eeceeeceeecaeeea seca eeae eens ceueceeeennees 186 Procedure for Using the C Control Class Encode Method n 188 Encoding a Series of PER Messages using the C Interface ccccccecceeceeecneeceeeca teen tenn eeaes 191 Generated PER Decode BUnctionss 2 s st ciees Uo eeces tase ta E insted at od en diets ad Me ee dss esac eee eee NS 191 Generated C Function Format and Calling Parameters 1 ccccseceveccneccnecc ence eeceeeceeeseeeeaeeeaes 192 Generated C Decode Method Format and Calling Parameter o oo 192 Procedure for Calling C Decode Functions 1 ccccceee cece neccneccnnce ence eeceeeceeeeaeecaesea sean sean eeaes 192 Procedure for Using the C Control Class Decode Method n on 194 Decoding a Series of Messages Using the C Control Class Interface occon 195 Performance Considerations Dynamic Memory Management 0 c0cc cece cece nsec neee een eeneeees 197 11 Generated Octet Encoding Rules OER Functions cceceeceecneceeeceeeeeceeeeecereecereeenereeeseneeaneneees 198 Generated OER Encode Functions sei n a o sendy tar N te eee
495. 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 rtxStreamInit 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 within the structure This memory is tracked within the context structure and is released when the context structure is freed The function result variable st at returns the status of the decode operation Status code zero indicates the function was successful A negative value indicates decoding failed Return status values are defined in the rtxErrCodes h include file The reason text and a stack trace can be displayed using the rtxErrPrint 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 met
496. 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 I 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 The special REAL values lt NOT A NUMBER gt lt PLUS INFINITY gt and lt MINUS INFINITY gt are represented as NaN INF and INF respectively GeneralizedTime and UTCTime values are transformed into the XSD representation for dateTime YYYY MMDDTHH MM SS SSSS Zl I HH MM when encoded to XML When an XML document is decoded the time format is transformed into the ASN 1 format EXTENDED XER EXTENDED XER specified in X 693 allows you to vary the XML encoding of ASN 1 by using XER encoding instructions ASN1C supports EXTENDED XER in two different ways by compiling XSD and by compiling ASN 1 with XER encoding instructions Support for XER encoding instruc
497. volved 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 unions 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 Open types with relational constraints result in the generation of C union structures that enumerate all of allowed fields as defined by the constraint This form is selected by using the table unions command line option 3 Legacy table form this is similar to 2 in that all information object related items result in the generation of additional code In this case however instead of a union structure being generated for open types with relational constraints a void pointer is used to hold an object in decoded form This form is selected using the tables command line option To better understand the support in this area the indiv
498. x check Allow ambiguous tags C C Output Options Output code to c h files based on module names C Output all code to a single c h file Output each generated function to its own source file Max lines per file ASNI1C GUI Users Guide In the first tab Output under Application Language Type select C Below that under Encoding Rules select BER Finally choose an output directory for the generated files Once the settings are correct click Save These settings can be changed at any time by selecting Project gt Project Settings from the menus Next we ll create a new schema file for our project Click the New button in the toolbar or select File gt New Schema File from the menus A new file Untitled will be added to the project window under Schema ASN 1 files and its contents will be shown in the editor 33 ASNIC GUI Users Guide Text Browser Now we need to write our schema between the DEFINITIONS BEGIN and END statements in the file Enter something like MySequence SEQUENCE 34 ASNI1C GUI Users Guide ingredient PrintableString count INTEGER units PrintableString When you are satisfied with the schema you ve created click the Validate button to make sure there are no errors Since the new schema file hasn t been saved yet ACGUI will ask if it should be Save the new file and ACGUI wil
499. xsd anyAttribute An xsd anyAttribute declaration is the attribute equivalent to the xsd any wildcard element declaration described earlier The main difference is that a single xsd anyAttribute declaration indicates that any number of undeclared attributes may occur whereas xsd any without a maxOccurs facet indicates that only a single wildcard element may occur at that position X 694 models xsd anyAttribute as a SEQUENCE OF UTFSString in ASN 1 Each string in the sequence is expected to be ina name value format The generated C type for this is simply a linked list of character strings For example lt xsd complexType name MyType gt lt xsd anyAttribute processContents lax gt lt xsd complexType gt results in the following C type typedef struct EXTERN MyType List of const OSUTF8CHAR OSRTDList attr MyType To populate a variable of this type for encoding one would add name value strings to the list for each attribute For example MyType myVar rtxDListInit amp myVar attr rtxDListAppend amp ctxt amp myVar attr OSUTF8 attrl valuel 110 XSD to C C Type Mappings rtxDListAppend amp ctxt amp myVar attr OSUTF8 attr2 value2 and so on xsd simpleContent The xsd simpleContent type is used to either extend or restrict an existing simple type definition In the case of extension the common use is to add attributes to a simple type AS
500. y function rtxMemFree should be called to free the allocated memory After stream processing is complete the stream is closed by invoking the rtxStreamClose function A program fragment that could be used to decode an employee record is as follows include employee h include file generated by ASNIC include rtxsrc rtxStreamFile h main ASNITAG msgtag int msglen OSCTXT ctxt PersonnelRecord employee const char filename message dat Step 1 Initialize a context variable for decoding 178 Generated BER Functions if berStrmInitContext amp ctxt 0 initialization failed could be a license problem printf context initialization failed check license n return 1 Step 2 Open the input stream to read data stat rtxStreamFileCreateReader amp ctxt filename if stat 0 rtxErrPrint amp ctxt return stat 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 if stat berDecStrmPeekTagAndLen amp ctxt amp tag amp len 0 rtxErrPrint amp ctxt return stat if msgtag TV_PersonnelRecord Step 4 Call decode function note last two args should always be ASNIEXPL and 0 status asn1lBSD_PersonnelRecord amp ctxt amp employee ASNI1EXPL 0
501. y will be tracked in the context 243 Generated 3GPP Layer 3 3GL3 Functions structure so the programmer does not need to worry about freeing it It will be released when the either the context is freed or explicitly when the rtxMemFree or rtxMemReset function is called 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 rtInitContext or dynamic created using rtNewContext The function to free the context is rtF reeContext A program fragment that could be used to decode a 3G NAS PDU is as follows include rt3gppsrc TS24008Msgs h include file generated by ASNIC main TS24008Msg_PDU data OSCTXT Gtxty OSOCTET msgbuf const char filename message dat int stat OSSIZE len step 1 initialize context stat rtInitContext amp ctxt if stat 0 printf rtInitContext failed check license n rtErrPrint amp ctxt return stat step 2 read input file into a memory buffer stat rtxFileReadBinary amp ctxt filename amp pMsgBuf amp len if 0 stat stat rtxInitContextBuffer amp ctxt pMsgBuf len if 0 stat rtxErrPrint amp ctxt rtFreeContext amp ctxt return stat step 3 set protocol version number rtxCtxtSetProtocolVersion amp ctxt 8 step 4 call the decode fun
502. ype xsd token use required gt lt xsd restriction gt lt xsd simpleContent gt lt xsd complexType gt This applies a restriction to the SizeType that was previously derived In this case the generated C type is as follows typedef struct EXTERN SmallSizeType const OSUTF8CHAR system_ OSINT32 base SmallSizeType In this case the type definition is almost identical to the original Si zeType The only exception is that the bit mask field for optional elements is removed a consequence of the use required attribute that was added to the 111 XSD to C C Type Mappings systemattribute declaration The handling of the minInclusive andmaxInclusive attributes is handled inside the generated encode and decode function in the form of constraint checks xsd complexContent The xsd complexContent type is used to extend or restrict complex types in different ways It is similar to deriving types from base types in higher level programming languages such as C or Java A common usage pattern in the case of extension is to add additional elements to an existing sequence or choice group In this case a new type is formed that contains all elements those declared in the base definition and those in the derived type Also generated is a new type with the name lt baseType gt _derivations which is a choice of all of the different derivations of the base type This is used wherever the complex content base ty
503. ype 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 EmbeddedPDV UNIVERSAL 11 IMPLICIT SEQUENCE identification CHOICE syntaxes SEQUENCE abstract OBJECT IDENTIFIER transfer OBJECT IDENTIFIER a T T Er syntax OBJECT IDENTIFIER presentation context id INTEGER context negotiation SEQUENCE presentation context id INTEGER 80 ASN 1 To C C Mappings transfer syntax OBJECT IDENTIFIER r 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 AsnlEmbeddedPDV h and AsnlEmbeddedPDV 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 NOTE It is recommended that if a specification contains multiple ASN 1 source files that reference EMBEDDEDPDYV all of these source files be compiled with a single ASNIC call in order to ensure that only a singled copy of the AsnlEm

Generated C Function Format and Calling Parameters

Contents

Download Pdf Manuals

Related Search

Related Contents