® September 2015 for release 10 CONFIDENTIAL to OSS Nokalva, Inc. Copyright  2015 OSS Nokalva, Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means electronic, mechanical, photocopying, recording or otherwise, without the prior permission of OSS Nokalva, Inc. Every distributed copy of the OSS® ASN.1 Tools for C is associated with a specific license and related unique license number. That license determines, among other things, what functions of the OSS® ASN.1 Tools for C are available to you. Credits and Trademarks OSS and OSS Nokalva are registered trademarks of OSS Nokalva, Inc. All other trademarks are used for reference purposes only and are owned by their respective owners. Readers' comments may be addressed to [email protected]. OSS Nokalva, Inc., may use or distribute whatever information you supply in any way it believes appropriate without incurring any obligation to you. ii CONFIDENTIAL to OSS Nokalva, Inc. PREFACE About This Manual This document serves as the reference manual for the OSS ASN.1/C Runtime API. OSS Nokalva, Inc., developed the OSS ASN.1 Tools for converting message definitions from ASN.1 to C, and for encoding, decoding and in general working with such messages. The OSS ASN.1 Tools implement the ASN.1 language as described by the following standards: ITU-T Recommendation X.680 (2008) | ISO/IEC 8824-1:2008 Information technology - Abstract Syntax Notation One (ASN.1): Specification of basic notation ITU-T Recommendation X.681 (2008) | ISO/IEC 8824-2:2008 Information technology - Abstract Syntax Notation One (ASN.1): Information object specification ITU-T Recommendation X.682 (2008) | ISO/IEC 8824-3:2008 Information technology - Abstract Syntax Notation One (ASN.1): Constraint specification ITU-T Recommendation X.683 (2008) | ISO/IEC 8824-4:2008 Information technology - Abstract Syntax Notation One (ASN.1): Parameterization of ASN.1 specifications ITU-T Recommendation X.690 (2008) | ISO/IEC 8825-1:2008 Information technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER) ITU-T Recommendation X.691 (2008) | ISO/IEC 8825-2:2008 Information technology - ASN.1 encoding rules: Specification of Packed Encoding Rules (PER) ITU-T Recommendation X.693 | ISO/IEC 8825-4: 2008 Information technology - ASN.1 encoding rules: XML Encoding Rules (XER) ITU-T Recommendation X.694 | ISO/IEC 8825-5: 2008 Information technology - ASN.1 encoding rules: Mapping W3C XML schema definitions into ASN.1 ITU-T Recommendation X.696 | ISO/IEC 8825-7: 2014 Information technology - ASN.1 encoding rules: Specification of Octet Encoding Rules (OER) CCITT Recommendation X.208 (1988) 1 Specification of Abstract Syntax Notation One (ASN.1) ISO/IEC 8824:1990 Information technology - Open Systems Interconnection - Specification of Abstract Syntax Notation One (ASN.1) 1 In the few places where X.208 (1988) and ISO/IEC 8824:1990 are contradictory, the OSS® ASN.1 Tools implements ISO/IEC 8824:1990. iii CONFIDENTIAL to OSS Nokalva, Inc. CCITT Recommendation X.209 (1988) Specification of Basic Encoding Rules for Abstract Syntax Notation One (ASN.1) ISO/IEC 8825:1990 Information technology - Open Systems Interconnection - Specification of Basic Encoding Rules for Abstract Syntax Notation One (ASN.1) Related Documents and Manuals For general information on ASN.1 and the OSS® ASN.1 Tools, see our website at (http://www.oss.com). For information on how to install the OSS ASN.1 Tools, and for customized examples on how to use the toolkit on each supported platform, refer to the OSS ASN.1 Tools for C Getting Started Manual. For more information about the OSS ASN.1 compiler which translates ASN.1 specifications into C data structures, refer to the OSS ASN.1 Compiler for C Reference Manual. For details about ASN.1 Studio, introduced in version 9.0, refer to the ASN.1 Studio® Reference Manual. For more information about the functions available in the OSS Interpretive ASN.1 API, refer to the OSS ASN.1 Tools for C IAAPI Reference Manual. For details about the error messages issued by the OSS ASN.1 Compiler, refer to the OSS ASN.1 Tools Compiler Error Reference Manual. For details about the error messages issued by the OSS ASN.1 Runtime functions, refer to the OSS ASN.1 Tools Runtime Error Reference Manual. To learn about using the OSS OSAK Memory Manager, refer to Using the OSS OSAK Memory Manager. iv CONFIDENTIAL to OSS Nokalva, Inc. Table of Contents ABOUT THIS MANUAL .......................................................................................................................................... III 1 INTRODUCTION TO THE OSS API ..........................................................................................................15 1.1 GENERAL OVERVIEW OF THE ENCODER / DECODER ..............................................................................15 1.1.1 Configuring the encoder / decoder using built-in flags ....................................................................16 1.2 LINKING YOUR APPLICATION WITH THE OSS API .................................................................................16 1.3 COMMON CHARACTERISTICS AMONG OSS API FUNCTIONS .................................................................17 1.4 CALLING THE OSS API FUNCTIONS ......................................................................................................17 2 FUNCTION INDEX (QUICK LOOK-UP TABLES) ..................................................................................18 2.1 COMPREHENSIVE LOOK-UP TABLE (INDEX TO ALL OSS API FUNCTIONS) ............................................18 2.2 CORE-ESSENTIAL FUNCTIONS LOOK-UP TABLE .....................................................................................26 2.3 USEFUL NON-ESSENTIAL FUNCTIONS LOOK-UP TABLE .........................................................................27 2.4 ADVANCED-USER FUNCTIONS LOOK-UP TABLE .....................................................................................27 2.5 SPECIALIZED-TASK FUNCTIONS LOOK-UP TABLE ..................................................................................29 2.6 XML-RELATED FUNCTIONS ..................................................................................................................32 2.7 COMPRESSION AND DECOMPRESSION FUNCTIONS ................................................................................34 2.8 COMPILE-AND-GO-LIBRARY FUNCTIONS .............................................................................................34 3 FUNCTIONS REFERENCE .........................................................................................................................35 3.1 DECLARING FUNCTION PROTOTYPES, FUNCTION DEFINITIONS, AND FUNCTION POINTERS ..................35 3.2 CORE-ESSENTIAL FUNCTIONS ...............................................................................................................37 3.2.1 ossDecode() ......................................................................................................................................37 3.2.2 ossEncode() ......................................................................................................................................39 3.2.3 ossFreeBuf() .....................................................................................................................................41 3.2.4 ossFreePDU() ...................................................................................................................................42 3.2.5 ossinit() / ossUinit() / ossWinit() .......................................................................................................44 3.2.6 ossterm() / ossUterm() / ossWterm() ................................................................................................46 3.3 USEFUL NON-ESSENTIAL FUNCTIONS ....................................................................................................47 3.3.1 ossCloseTraceFile() ..........................................................................................................................47 3.3.2 ossConvertData() .............................................................................................................................48 3.3.3 ossDescribeReturnCode() .................................................................................................................50 3.3.4 ossGetDebugFlags() .........................................................................................................................51 3.3.5 ossGetDecodingFlags() ....................................................................................................................52 3.3.6 ossGetEncodingFlags() ....................................................................................................................53 3.3.7 ossGetEncodingRules() ....................................................................................................................54 3.3.8 ossGetErrMsg() ................................................................................................................................55 3.3.9 ossGetFlags() ...................................................................................................................................56 3.3.10 ossOpenTraceFile() ..........................................................................................................................57 3.3.11 ossOpenTraceWindow() ....................................................................................................................58 3.3.12 ossPrint() ..........................................................................................................................................59 3.3.13 ossPrintHex() ....................................................................................................................................60 3.3.14 ossPrintOctetAsASCII() ....................................................................................................................61 3.3.15 ossPrintOctetAsBCDString () ...........................................................................................................62 3.3.16 ossPrintOctetAsIPAddress()..............................................................................................................62 3.3.17 ossPrintOctetAsTBCDString () .........................................................................................................63 3.3.18 ossPrintPDU() ..................................................................................................................................63 3.3.19 ossPrintPDUToBuffer() ....................................................................................................................65 3.3.20 ossPrintPER() / ossPrintXPER() ......................................................................................................66 3.3.21 ossSetDebugFlags() ..........................................................................................................................70 v CONFIDENTIAL to OSS Nokalva, Inc. 3.3.22 ossSetDecodingFlags() .....................................................................................................................73 3.3.23 ossSetEncodingFlags() .....................................................................................................................79 3.3.24 ossSetEncodingRules() .....................................................................................................................83 3.3.25 ossSetFlags() ....................................................................................................................................84 3.3.26 ossTest() ............................................................................................................................................87 3.3.27 ossTestPD() .......................................................................................................................................89 3.4 ADVANCED-USER FUNCTIONS ...............................................................................................................89 3.4.1 ossCleanMemoryHandle() ................................................................................................................89 3.4.2 ossCloseDecoderInputFile() .............................................................................................................90 3.4.3 ossCloseEncoderOutputFile() ..........................................................................................................91 3.4.4 ossCreateMemoryHandle() ...............................................................................................................91 3.4.5 ossDeleteMemoryHandle() ...............................................................................................................93 3.4.6 ossDetermineEncodingLength() .......................................................................................................94 3.4.7 ossDetermineMessageLength() ........................................................................................................95 3.4.8 ossDetermineNumberOfPadBits() ....................................................................................................95 3.4.9 ossDeterminePDUBufferLength () ...................................................................................................96 3.4.10 ossFreeMemory() ..............................................................................................................................97 3.4.11 ossGetActiveMemoryHandle() ..........................................................................................................98 3.4.12 ossGetBuffer() ...................................................................................................................................99 3.4.13 ossGetBytesReadByDecoder() ........................................................................................................100 3.4.14 ossGetDecodingLength() ................................................................................................................101 3.4.15 ossGetInitializedMemory() .............................................................................................................102 3.4.16 ossGetMemory() .............................................................................................................................102 3.4.17 ossGetMemoryHandleStat() ...........................................................................................................103 3.4.18 ossGetMinFileSize() .......................................................................................................................105 3.4.19 ossGetObj() .....................................................................................................................................106 3.4.20 ossGetUserMallocFreeRealloc() ....................................................................................................106 3.4.21 ossLoadMemoryManager() ............................................................................................................107 3.4.22 ossMarkObj() ..................................................................................................................................109 3.4.23 ossOpenDecoderInputFile() ........................................................................................................... 111 3.4.24 ossOpenEncoderOutputFile() ......................................................................................................... 112 3.4.25 ossSetActiveMemoryHandle() ........................................................................................................ 114 3.4.26 ossSetBuffer().................................................................................................................................. 115 3.4.27 ossSetDecodingLength() ................................................................................................................. 116 3.4.28 ossSetMinFileSize() ........................................................................................................................ 117 3.4.29 ossSetTimeout() ............................................................................................................................... 118 3.4.30 ossSetUserMallocFreeRealloc() ..................................................................................................... 119 3.4.31 ossSkipPadBytes() ..........................................................................................................................120 3.4.32 ossTestObj() ....................................................................................................................................121 3.4.33 ossUnmarkObj() .............................................................................................................................122 3.5 SPECIALIZED-TASK FUNCTIONS ..........................................................................................................124 3.5.1 ossAddInfoObject() .........................................................................................................................124 3.5.2 ossAsnValToEncodedOid() .............................................................................................................125 3.5.3 ossAsnValToEncodedRelOid() ........................................................................................................126 3.5.4 ossCallerIsDecoder()......................................................................................................................128 3.5.5 ossCalTimeToGenTimeString() .......................................................................................................129 3.5.6 ossCalTimeToGenTimeStruct() .......................................................................................................131 3.5.7 ossCalTimeToUTCTimeString() ......................................................................................................132 3.5.8 ossCalTimeToUTCTimeStruct() ......................................................................................................134 3.5.9 ossCheckConstraints() ....................................................................................................................134 3.5.10 ossCmpValue() ................................................................................................................................136 3.5.11 ossConvertBCDStringToOctet() .....................................................................................................137 3.5.12 ossConvertOctetToBCDString() .....................................................................................................138 3.5.13 ossConvertOctetToTBCDString() ...................................................................................................139 vi CONFIDENTIAL to OSS Nokalva, Inc. 3.5.14 ossConvertTBCDStringToOctet() ...................................................................................................141 3.5.15 ossCpyValue() .................................................................................................................................142 3.5.16 ossDotValToEncodedOid() .............................................................................................................143 3.5.17 ossDotValToEncodedRelOid() ........................................................................................................144 3.5.18 ossDupWorld() ................................................................................................................................146 3.5.19 ossDurationEndPointIntervalToString().........................................................................................147 3.5.20 ossDurationEndPointRecIntervalToString() ...................................................................................149 3.5.21 ossDurationIntervalToString() ........................................................................................................150 3.5.22 ossDurationRecIntervalToString() ..................................................................................................151 3.5.23 ossGenTimeStringToCalTime() .......................................................................................................153 3.5.24 ossGenTimeStructToCalTime() .......................................................................................................153 3.5.25 ossUTCTimeStringToCalTime() ......................................................................................................154 3.5.26 ossUTCTimeStructToCalTime() ......................................................................................................155 3.5.27 ossEncodedOidToAsnVal() .............................................................................................................156 3.5.28 ossEncodedRelOidToAsnVal() ........................................................................................................157 3.5.29 ossEncodedOidToDotVal() .............................................................................................................159 3.5.30 ossEncodedRelOidToDotVal() ........................................................................................................160 3.5.31 ossGeneralizedTimeToInts() or ossGeneralizedTimeToShorts() .....................................................161 3.5.32 ossGetCompatibilityFlags()............................................................................................................163 3.5.33 ossGetConstructedNestingLimit() ..................................................................................................164 3.5.34 ossGetExtensionAddition() .............................................................................................................165 3.5.35 ossGetInfoObject() .........................................................................................................................165 3.5.36 ossGetInfoObjectSet() .....................................................................................................................167 3.5.37 ossGetOssGlobalSize() ...................................................................................................................168 3.5.38 ossGetPrintIndent() ........................................................................................................................169 3.5.39 ossGetRuntimeVersion() .................................................................................................................169 3.5.40 ossGetSeqSetNestingLimit() ...........................................................................................................170 3.5.41 ossGetTimeKind() ...........................................................................................................................171 3.5.42 ossGetUserFieldCpyCmp() ............................................................................................................172 3.5.43 ossGetUserPrint() ...........................................................................................................................174 3.5.44 ossGetUserVprint() .........................................................................................................................174 3.5.45 ossInitSync() ...................................................................................................................................175 3.5.46 ossIntsToGeneralizedTime() ...........................................................................................................176 3.5.47 ossIntsToUTCTime() .......................................................................................................................177 3.5.48 ossPartialDecode() .........................................................................................................................178 3.5.49 ossRemoveInfoObject() ...................................................................................................................180 3.5.50 ossSetCompatibilityFlags() ............................................................................................................182 3.5.51 ossSetConstructedNestingLimit() ...................................................................................................186 3.5.52 ossSetPrintIndent() .........................................................................................................................186 3.5.53 ossSetRuntimeVersion() ..................................................................................................................187 3.5.54 ossSetSeqSetNestingLimit() ............................................................................................................188 3.5.55 ossSetTemporaryBuffer() ................................................................................................................189 3.5.56 ossSetUserFieldCpyCmp() .............................................................................................................190 3.5.57 ossSetUserPrint() ...........................................................................................................................191 3.5.58 ossSetUserStack() ...........................................................................................................................192 3.5.59 ossSetUserVprint() .........................................................................................................................194 3.5.60 ossStartPointDurationIntervalToString() .......................................................................................194 3.5.61 ossStartPointDurationRecIntervalToString() .................................................................................196 3.5.62 ossStartPointEndPointIntervalToString() .......................................................................................197 3.5.63 ossStartPointEndPointRecIntervalToString() .................................................................................198 3.5.64 ossStringToDurationEndPointInterval() .........................................................................................200 3.5.65 ossStringToDurationEndPointRecInterval() ...................................................................................200 3.5.66 ossStringToDurationInterval() ........................................................................................................201 3.5.67 ossStringToDurationRecInterval() ..................................................................................................201 vii CONFIDENTIAL to OSS Nokalva, Inc. 3.5.68 ossStringToStartPointDurationInterval() .......................................................................................202 3.5.69 ossStringToStartPointDurationRecInterval() .................................................................................203 3.5.70 ossStringToStartPointEndPointInterval () ......................................................................................203 3.5.71 ossStringToStartPointEndPointRecInterval() .................................................................................204 3.5.72 ossStringToTimePoint () .................................................................................................................204 3.5.73 ossTermSync() .................................................................................................................................205 3.5.74 ossTimePointToString() ..................................................................................................................206 3.5.75 ossUTCTimeToInts() or ossUTCTimeToShorts() ............................................................................207 3.5.76 ossVprintWin() ................................................................................................................................208 3.6 XML-RELATED FUNCTIONS ................................................................................................................210 3.6.1 ossBinary2XML() ...........................................................................................................................210 3.6.2 ossDateToInts() ............................................................................................................................... 211 3.6.3 ossDateTimeToInts() .......................................................................................................................212 3.6.4 ossDurationToInts() ........................................................................................................................214 3.6.5 ossGDayToInts() .............................................................................................................................216 3.6.6 ossGetNamespacePrefix() ...............................................................................................................217 3.6.7 ossGetXMLEncodingRules() ..........................................................................................................218 3.6.8 ossGMonthDayToInts() ...................................................................................................................219 3.6.9 ossGMonthToInts() .........................................................................................................................220 3.6.10 ossGYearToInts() ............................................................................................................................221 3.6.11 ossGYearMonthToInts() ..................................................................................................................223 3.6.12 ossIdentifyPDUByEXERName() .....................................................................................................224 3.6.13 ossIntsToDate() ...............................................................................................................................225 3.6.14 ossIntsToDateTime() .......................................................................................................................226 3.6.15 ossIntsToDuration() ........................................................................................................................227 3.6.16 ossIntsToGDay() .............................................................................................................................229 3.6.17 ossIntsToGMonth() .........................................................................................................................230 3.6.18 ossIntsToGMonthDay() ...................................................................................................................231 3.6.19 ossIntsToGYear() ............................................................................................................................233 3.6.20 ossIntsToGYearMonth() ..................................................................................................................234 3.6.21 ossIntsToTime() ...............................................................................................................................235 3.6.22 ossPrintXML() ................................................................................................................................237 3.6.23 ossSetNamespacePrefix() ...............................................................................................................237 3.6.24 ossSetXmlDTD() .............................................................................................................................239 3.6.25 ossSetXMLEncodingRules() ...........................................................................................................240 3.6.26 ossSetXmlStylesheet() .....................................................................................................................241 3.6.27 ossTimeToInts() ...............................................................................................................................242 3.6.28 ossXML2Binary() ...........................................................................................................................243 3.7 ENCODING COMPRESSION ROUTINES ..................................................................................................245 3.7.1 ossCompress() ................................................................................................................................246 3.7.2 ossGetCompressDecompressFunctions() .......................................................................................249 3.7.3 ossGetCompressDecompressInfo() .................................................................................................249 3.7.4 ossGetCompSizeEstimator() ...........................................................................................................250 3.7.5 ossSetCompressDecompressFunctions() ........................................................................................250 3.7.6 ossSetCompressDecompressInfo() ..................................................................................................251 3.7.7 ossSetCompSizeEstimator() ............................................................................................................252 3.7.8 ossSkipCompressionPrefix () ..........................................................................................................253 3.7.9 ossUnCompress() ............................................................................................................................254 3.8 OSS COMPILE-AND-GO LIBRARY FUNCTIONS ...................................................................................255 3.8.1 ossCreateControlTable() .................................................................................................................255 3.8.2 ossGetAsn1CompilerHandle() ........................................................................................................257 3.8.3 ossDeleteAsn1CompilerHandle() ...................................................................................................258 3.8.4 ossDeleteControlTable() .................................................................................................................258 4 OSS API INTERNAL VARIABLES AND DATA STRUCTURES ...........................................................260 viii CONFIDENTIAL to OSS Nokalva, Inc. 4.1 OBJECTSETENTRY ..............................................................................................................................260 4.2 OPENTYPE ..........................................................................................................................................260 4.3 OPENTYPEEXTENDED .........................................................................................................................262 4.4 OSSBUF ...............................................................................................................................................263 4.5 OSSBUFEXTENDED .............................................................................................................................263 4.6 OSSDURATION .....................................................................................................................................264 4.7 OSSENCODEDOID ..............................................................................................................................265 4.8 OSSGLOBAL ........................................................................................................................................265 4.9 _OSSSETGLOBALUSERVAR .................................................................................................................267 4.10 OSSTIMEPOINT ....................................................................................................................................268 4.11 OSSTIMEKIND .....................................................................................................................................269 5 OSS API FUNCTION LIBRARY FILES ...................................................................................................270 5.1 STATIC LIBRARIES (FOR MICROSOFT VISUAL C++) ............................................................................270 5.1.1 Space-optimized encoder/decoder ..................................................................................................270 5.1.2 Time-optimized encoder/decoder ....................................................................................................271 5.1.3 Lean encoder/decoder (available separately) ................................................................................271 5.2 STATIC LIBRARIES (FOR CODEGEAR C++ BUILDER) ..........................................................................272 5.2.1 Space-optimized encoder/decoder ..................................................................................................272 5.2.2 Time-optimized encoder/decoder ....................................................................................................272 5.2.3 Lean encoder/decoder (available separately) ................................................................................272 5.3 DYNAMIC LIBRARIES ..........................................................................................................................274 5.3.1 Using the OSS dynamic linking libraries (DLLs) ...........................................................................274 5.3.1.1 Dynamically linking with the space-optimized encoder/decoder ................................................................................ 274 5.3.1.2 Dynamically linking with the time-optimized encoder/decoder ................................................................................. 274 5.3.1.3 Dynamically linking with the Lean encoder/decoder .................................................................................................. 274 5.3.2 The OSS Dynamic library files .......................................................................................................274 5.3.3 Creating an import library for use with the Borland C++ compiler .............................................275 6 THE OSS MEMORY MANAGEMENT ....................................................................................................277 6.1 OSS MEMORY MANAGERS ..................................................................................................................277 6.1.1 General overview ............................................................................................................................277 6.1.1.1 Memory management I/O variables ............................................................................................................................ 278 6.1.1.2 Allocating and deallocating memory for PDUs .......................................................................................................... 278 6.1.2 Rationale for using memory managers other than the default one .................................................279 6.1.3 Switching between the various memory managers .........................................................................279 6.1.3.1 Overwriting OSS's default memory manager DLL ..................................................................................................... 279 6.1.3.2 Explicitly choosing a memory manager at run-time ................................................................................................... 279 6.1.3.3 Replacing OSS's memory manager DLL with your own ............................................................................................ 280 6.1.3.4 Replacing the default memory manager in the static libraries .................................................................................... 280 6.1.4 Using the memory managers ..........................................................................................................281 6.1.4.1 Using the default memory manager ............................................................................................................................ 281 6.1.4.2 Using the file memory manager .................................................................................................................................. 283 6.1.4.3 Using the socket memory manager ............................................................................................................................. 290 6.1.4.4 Using a user-defined memory manager ...................................................................................................................... 291 6.2 MEMORY HANDLE API .......................................................................................................................294 6.2.1 General overview ............................................................................................................................294 6.2.2 Function details ..............................................................................................................................295 6.2.3 Use cases ........................................................................................................................................297 6.2.3.1 Reuse of memory when some OSS API function is being run in a loop ..................................................................... 297 6.2.3.2 Working simultaneously with several messages ......................................................................................................... 297 6.2.3.3 Manual modification of the decoded message ............................................................................................................ 298 6.2.3.4 Cleanup when total amount of allocated memory is too big ....................................................................................... 298 7 PARTIAL DECODING ................................................................................................................................301 8 TECHNOLOGY INTEGRATION - COMPRESSION/DECOMPRESSION ........................................303 8.1 COMPRESSION/DECOMPRESSION OF ENCODED DATA USING ......................................................303 ZLIB ix CONFIDENTIAL to OSS Nokalva, Inc. 8.2 COMPRESSION/DECOMPRESSION OF ENCODED DATA USING CUSTOMIZED CODECS ...........................306 8.3 STANDALONE COMPRESSION/DECOMPRESSION OF ENCODED DATA ...................................................310 9 RESTRICTIONS ..........................................................................................................................................314 9.1 NOTES ABOUT DEFAULT VALUES ......................................................................................................314 9.2 LIMITATIONS OF THE DER ENCODER/DECODER ..................................................................................314 9.3 LIMITATIONS OF THE PER ENCODER/DECODER ..................................................................................314 9.4 LIMITATIONS IMPOSED WHEN USING THE LEAN ENCODER/DECODER (LED) ......................................315 9.5 LIMITATIONS IMPOSED WHEN USING THE TIME-OPTIMIZED ENCODER/DECODER (TOED) .................316 9.6 LIMITATIONS IMPOSED WHEN USING XER ..........................................................................................317 9.7 LIMITATIONS IMPOSED WHEN USING E-XER ......................................................................................317 9.8 LIMITATIONS IMPOSED WHEN USING OER/C-OER .............................................................................318 9.9 LIMITATION IMPOSED WHEN USING OSSPRINTPDU() AND NULL CHARACTERS ................................318 9.10 LIMITATIONS IMPOSED WHEN HANDLING CHARACTER STRINGS .........................................................318 9.11 LIMITATIONS IMPOSED WHEN USING THE ENCODING COMPRESSION FUNCTIONALITY .......................318 9.12 LIMITATIONS OF THE CONSTRAINT CHECKER ......................................................................................319 10 EXAMPLES ..............................................................................................................................................320 10.1 A COMPLETE SIMPLE EXAMPLE ...........................................................................................................320 10.2 A MORE COMPLEX EXAMPLE...............................................................................................................323 10.3 ENCODING AND DECODING OPEN TYPES .............................................................................................336 10.3.1 Encoding/decoding with the AUTOMATIC_ENCDEC flag set .......................................................336 10.3.2 Encoding/decoding without the AUTOMATIC_ENCDEC flag set ..................................................336 10.4 ENCODING/DECODING TYPES MARKED WITH THE OSS.OBJHANDLE/OSS.NOCOPY DIRECTIVE ..341 10.5 USING THE SOCKET MEMORY MANAGER.............................................................................................345 10.6 USING INFORMATION OBJECTS ............................................................................................................351 11 FREQUENTLY ASKED QUESTIONS ......................................................................................................362 11.1 ENCODER-RELATED QUESTIONS .........................................................................................................362 11.1.1 How do I encode a message? .........................................................................................................362 11.1.2 Does the encoder allocate memory for its output buffer automatically, or does the application developer have to do this manually? ..............................................................................................................362 11.1.3 How do I pre-allocate an output buffer for the encoder? ...............................................................363 11.1.4 After the encoder returns successfully, what do the length and value fields of the OssBuf structure contain? ...........................................................................................................................................363 11.1.5 How do I free up the encoder's output buffer? ...............................................................................363 11.1.6 How do I change between the various encoding rules? .................................................................364 11.1.7 Is there an OSS API function that can print BER/DER/PER/UPER/OER/ C-OER encodings in hexadecimal format? ......................................................................................................................................365 11.1.8 PER bit encoding are hard to understand. Do you have a function that can print a PER encoding in an easy-to-understand labeled human-readable format? how about a function that can parse a PER encoding into a generic data structure? .........................................................................................................365 11.1.9 How do I instruct the encoder that I want to use the definite length form of encoding when using BER? 365 11.1.10 How do I instruct the encoder that I want to use the indefinite length form of encoding when using BER? 366 11.1.11 Is it possible to customize generated XER encoding? ....................................................................366 11.2 DECODER-RELATED QUESTIONS .........................................................................................................367 11.2.1 How do I decode a message? .........................................................................................................367 11.2.2 For the decoder's output, do I have to pass the address of a pointer declared to reference the compiler-generated type intended for decoding or can it be the address of a void pointer?.......................367 11.2.3 How does the decoder know which compiler-generated structure to fill upon decoding an encoded message? 367 x CONFIDENTIAL to OSS Nokalva, Inc.