Objective Systems, Inc.  
Home
About ASN.1
Products
Free Software
Open Source
Documents
Services
Resources
Resellers
Customers
Careers
About Us
Contact Us
 

Google
Objective Systems, Inc.
Main Page | Modules | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members

XER C Decode Functions.
[XER Runtime Library Functions.]

Detailed Description

XER runtime library decode functions handle the decoding of the primitive ASN.1 data types and length variables. Calls to these functions are assembled in the C source code generated by the ASN1C complier to decode complex ASN.1 structures. These functions are also directly callable from within a user's application program if the need to decode a primitive data item exists.


Functions

int xerDecBMPStr (ASN1CTXT *pctxt, ASN1BMPString *outdata)
int xerDecBase64Str (ASN1CTXT *pctxt, ASN1OCTET *pvalue, ASN1UINT *pnocts, ASN1INT bufsize)
int xerDecBigInt (ASN1CTXT *pctxt, char **ppvalue, int radix)
int xerDecBitStr (ASN1CTXT *pctxt, ASN1OCTET *pvalue, ASN1UINT *pnbits, ASN1INT bufsize)
int xerDecBitStrMemBuf (ASN1MemBuf *pMemBuf, ASN1Const XMLCHAR *inpdata, int length, ASN1BOOL skipWhitespaces)
int xerDecBool (ASN1CTXT *pctxt, ASN1BOOL *pvalue)
int xerDecCopyBitStr (ASN1CTXT *pctxt, ASN1OCTET *pvalue, ASN1UINT *pnbits, ASN1INT bufsize, int lastBitOffset)
int xerDecCopyDynBitStr (ASN1CTXT *pctxt, ASN1DynBitStr *pvalue, int lastBitOffset)
int xerDecCopyDynOctStr (ASN1CTXT *pctxt, ASN1DynOctStr *pvalue, int lastBitOffset)
int xerDecCopyOctStr (ASN1CTXT *pctxt, ASN1OCTET *pvalue, ASN1UINT *pnocts, ASN1INT bufsize, int lastBitOffset)
int xerDecDynAscCharStr (ASN1CTXT *pctxt, ASN1ConstCharPtr *outdata)
int xerDecDynBase64Str (ASN1CTXT *pctxt, ASN1DynOctStr *pvalue)
int xerDecDynBitStr (ASN1CTXT *pctxt, ASN1DynBitStr *pvalue)
int xerDecDynOctStr (ASN1CTXT *pctxt, ASN1DynOctStr *pvalue)
int xerDecDynUTF8Str (ASN1CTXT *pctxt, ASN1UTF8String *outdata)
int xerDecInt (ASN1CTXT *pctxt, ASN1INT *pvalue)
int xerDecInt8 (ASN1CTXT *pctxt, ASN1INT8 *pvalue)
int xerDecInt16 (ASN1CTXT *pctxt, ASN1SINT *pvalue)
int xerDecInt64 (ASN1CTXT *pctxt, ASN1INT64 *pvalue)
int xerDecObjId (ASN1CTXT *pctxt, ASN1OBJID *pvalue)
int xerDecObjId64 (ASN1CTXT *pctxt, ASN1OID64 *pvalue)
int xerDecOctStr (ASN1CTXT *pctxt, ASN1OCTET *pvalue, ASN1UINT *pnocts, ASN1INT bufsize)
int xerDecOctStrMemBuf (ASN1MemBuf *pMemBuf, ASN1Const XMLCHAR *inpdata, int length, ASN1BOOL skipWhitespaces)
int xerDecOpenType (ASN1CTXT *pctxt, ASN1OpenType *pvalue)
int xerDecReal (ASN1CTXT *pctxt, ASN1REAL *pvalue)
int xerDecRelativeOID (ASN1CTXT *pctxt, ASN1OBJID *pvalue)
int xerDecUInt (ASN1CTXT *pctxt, ASN1UINT *pvalue)
int xerDecUInt8 (ASN1CTXT *pctxt, ASN1UINT8 *pvalue)
int xerDecUInt16 (ASN1CTXT *pctxt, ASN1USINT *pvalue)
int xerDecUInt64 (ASN1CTXT *pctxt, ASN1UINT64 *pvalue)
int xerDecUnivStr (ASN1CTXT *pctxt, ASN1UniversalString *outdata)
int xerSetDecBufPtr (ASN1CTXT *pCtxt, ASN1ConstOctetPtr bufaddr, size_t bufsiz)

Function Documentation

int xerDecBase64Str (  ASN1CTXT *  pctxt,
ASN1OCTET *  pvalue,
ASN1UINT *  pnocts,
ASN1INT  bufsize
) 
 

This function will decode a variable of teh ASN.1 OCTET STRING type into a static memory structure. The octet string must be Base64 encoded. This function call is used to decode a sized octet string production.

Parameters:
pctxt A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls.
pvalue A pointer to a variable to receive the decoded bit string. This is assumed to be a static array large enough to hold the number of octets specified in the bufsize input parameter.
pnocts A pointer to an integer value to receive the decoded number of octets.
bufsize A integer variable containing the size (in octets) of the sized ASN.1 octet string. An error will occur if the number of octets in the decoded string is larger than this value.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecBigInt (  ASN1CTXT *  pctxt,
char **  ppvalue,
int  radix
) 
 

This function will decode a variable of the ASN.1 INTEGER type. In this case, the integer is assumed to be of a larger size than can fit in a C or C++ long type (normally 32 or 64 bits). For example, parameters used to calculate security values are typically larger than these sizes.

These variables are stored in character string constant variables. Depending on specified radix, they could be represented as binary, octal, decimal or hexadecimal strings starting with appropriate prefix. If it is necessary to convert to another radix, then use rtBigIntSetStr or rtBigIntToString functions.

Parameters:
pctxt Pointer to context block structure.
ppvalue Pointer to a character pointer variable to receive the decoded unsigned value. Dynamic memory is allocated for the variable using the rtMemAlloc function. The decoded variable is represented as a string starting with appropriate prefix.
radix The expected radix of the decoded value. The only radices 2, 8, 10 and 16 are supported.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecBitStr (  ASN1CTXT *  pctxt,
ASN1OCTET *  pvalue,
ASN1UINT *  pnbits,
ASN1INT  bufsize
) 
 

This function will decode a variable of the ASN.1 BIT STRING type into a static memory structure. This function call is generated by ASN1C to decode a sized bit production.

Parameters:
pctxt A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls.
pvalue A pointer to a variable to receive the decoded bit string. This is assumed to be a static array large enough to hold the number of octets specified in the bufsize input parameter.
pnbits A pointer to an integer value to receive the decoded number of bits.
bufsize An integer variable containing the size (in octets) of the sized ASN.1 bit string. An error will occur if the number of octets in the decoded string is larger than this value.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecBitStrMemBuf (  ASN1MemBuf *  pMemBuf,
ASN1Const XMLCHAR *  inpdata,
int  length,
ASN1BOOL  skipWhitespaces
) 
 

This function decodes a variable of the ASN.1 BIT STRING type to a memory buffer. The decoded data will be put into the memory buffer starting from the current position and bit offset. After all data is decoded the bit string may be fetched out by call to xerDecCopyBitStr or xerDecCopyDynBitStr functions.

Usually, this function is used in the 'characters' SAX handler.

Parameters:
pMemBuf Pointer to the destination memory buffer.
inpdata Pointer to a source string to be decoded.
length Length of the source string (in characters).
skipWhitespaces Indicates, could whitespaces be ignored or they are illegal.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecBMPStr (  ASN1CTXT *  pctxt,
ASN1BMPString *  outdata
) 
 

This function will decode a variable ASN.1 16-bit character BMPString type. This function will allocate dynamic memory to store the decoded result.

Parameters:
pctxt A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls.
outdata A pointer to a structure variable to receive the decoded string. The string is stored as an array of short integer characters. The memory is allocated for the string by the rtMemAlloc function.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecBool (  ASN1CTXT *  pctxt,
ASN1BOOL *  pvalue
) 
 

This function decodes a variable of the ASN.1 BOOLEAN type.

Parameters:
pctxt Pointer to context block structure.
pvalue Pointer to a variable to receive the decoded BOOLEAN value.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecCopyBitStr (  ASN1CTXT *  pctxt,
ASN1OCTET *  pvalue,
ASN1UINT *  pnbits,
ASN1INT  bufsize,
int  lastBitOffset
) 
 

This function copies the decoded BIT STRING from the memory buffer. This function call is generated by ASN1C to decode a sized bit string production.

Parameters:
pctxt Pointer to context block structure. Its buffer should be set to point to the decoded data.
pvalue Pointer to a buffer to receive the decoded data.
pnbits Pointer to an integer value to receive the decoded number of bits.
bufsize An integer variable containing the size (in octets) of the sized ASN.1 bit string. An error will occur if the number of octets in the decoded string is larger than this value.
lastBitOffset A number of actual bits in the last octet.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecCopyDynBitStr (  ASN1CTXT *  pctxt,
ASN1DynBitStr *  pvalue,
int  lastBitOffset
) 
 

This function copies the decoded BIT STRING from the memory buffer. This function will allocate dynamic memory to store the decoded result.

Parameters:
pctxt Pointer to context block structure. Its buffer should be set to point to the decoded data.
pvalue Pointer to a dynamic bit string structure to receive the decoded bit string. Dynamic memory is allocated to hold the string using the rtMemAlloc function.
lastBitOffset A number of actual bits in the last octet.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecCopyDynOctStr (  ASN1CTXT *  pctxt,
ASN1DynOctStr *  pvalue,
int  lastBitOffset
) 
 

This function copies the decoded OCTET STRING from the memory buffer. This function will allocate dynamic memory to store the decoded result.

Parameters:
pctxt Pointer to context block structure. Its buffer should be set to point to the decoded data.
pvalue Pointer to a dynamic octet string structure to receive the decoded octet string. Dynamic memory is allocated to hold the string using the rtMemAlloc function.
lastBitOffset A number of actual bits in the last octet.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecCopyOctStr (  ASN1CTXT *  pctxt,
ASN1OCTET *  pvalue,
ASN1UINT *  pnocts,
ASN1INT  bufsize,
int  lastBitOffset
) 
 

This function copies the decoded OCTET STRING from the memory buffer. This function call is generated by ASN1C to decode a sized octet string production.

Parameters:
pctxt Pointer to context block structure. Its buffer should be set to point to the decoded data.
pvalue Pointer to a variable to receive the decoded bit string. This is assumed to be a static array large enough to hold the number of octets specified in the 'bufsize' input parameter.
pnocts Pointer to an integer value to receive the decoded number of octets.
bufsize An integer variable containing the size (in octets) of the sized ASN.1 octet string. An error will occur if the number of octets in the decoded string is larger than this value.
lastBitOffset A number of actual bits in the last octet.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecDynAscCharStr (  ASN1CTXT *  pctxt,
ASN1ConstCharPtr *  outdata
) 
 

This function will decode a variable of one of the ASN.1 8-bit character string types. These types include IA5String, VisibleString, PrintableString, and NumericString. This function will allocate dynamic memory to store the result.

Parameters:
pctxt A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls.
outdata A pointer to a character string pointer variable to receive the decoded string. The string as stored as a standard null-terminated C string. Memory is allocated for the string by the rtMemAlloc function.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecDynBase64Str (  ASN1CTXT *  pctxt,
ASN1DynOctStr *  pvalue
) 
 

This function will decode a variable of the ASN.1 OCTET STRING type. The octet string must be Base64 encoded. This function will allocate dynamic memory to store the decoded result.

Parameters:
pctxt A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls.
pvalue A pointer to a dynamic octet string structure to receive the decoded octet string. Dynamic memory is allocated to hold the string using the rtMemAlloc function.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecDynBitStr (  ASN1CTXT *  pctxt,
ASN1DynBitStr *  pvalue
) 
 

This function will decode a variable of the ASN.1 BIT STRING type. This function will allocate dynamic memory to store the decoded result.

Parameters:
pctxt A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls.
pvalue A pointer to a dynamic bit string structure to receive the decoded bit string. Dynamic memory is allocated to hold the string using the rtMemAlloc function.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecDynOctStr (  ASN1CTXT *  pctxt,
ASN1DynOctStr *  pvalue
) 
 

This function will decode a variable of the ASN.1 OCTET STRING type. This function will allocate dynamic memory to store the decoded result.

Parameters:
pctxt A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls.
pvalue A pointer to a dynamic bit string structure to receive the decoded bit string. Dynamic memory is allocated to hold the string using the rtMemAlloc function.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecDynUTF8Str (  ASN1CTXT *  pctxt,
ASN1UTF8String *  outdata
) 
 

This function will decode a variable of UTF8String ASN.1 type. Generally, the SAX parser converts all UTF8 format strings to 16-bit Unicode format automatically. This function converts the Unicode string back to UTF8 format. This function will allocate dynamic memory to store the decoded result.

Parameters:
pctxt A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls.
outdata A pointer to a character string pointer variable to receive the decoded string. The string as stored as a UTF8 null-terminated string. Memory is allocated for the string by the rtMemAlloc function.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecInt (  ASN1CTXT *  pctxt,
ASN1INT *  pvalue
) 
 

This function decodes a variable of the ASN.1 INTEGER type.

Parameters:
pctxt Pointer to context block structure.
pvalue Pointer to a variable to receive the decoded integer value.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecInt16 (  ASN1CTXT *  pctxt,
ASN1SINT *  pvalue
) 
 

This function decodes a 16-bit variable of the ASN.1 INTEGER type.

Parameters:
pctxt Pointer to context block structure.
pvalue Pointer to a 16-bit variable to receive the decoded integer value.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecInt64 (  ASN1CTXT *  pctxt,
ASN1INT64 *  pvalue
) 
 

This function decodes a 64-bit variable of the ASN.1 INTEGER type.

Parameters:
pctxt Pointer to context block structure.
pvalue Pointer to a 64-bit variable to receive the decoded integer value. The ASN1INT64 type is set to the C type '__int64', 'long long' or 'long' in the asn1type.h file (depends on the used platform and the compiler).
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecInt8 (  ASN1CTXT *  pctxt,
ASN1INT8 *  pvalue
) 
 

This function decodes an 8-bit variable of the ASN.1 INTEGER type.

Parameters:
pctxt Pointer to context block structure.
pvalue Pointer to an 8-bit variable to receive the decoded integer value.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecObjId (  ASN1CTXT *  pctxt,
ASN1OBJID *  pvalue
) 
 

This function decodes a value of the ASN.1 OBJECT IDENTIFIER type.

Parameters:
pctxt Pointer to context block structure.
pvalue Pointer to value to receive decoded result. The ASN1OBJID structure contains an integer to hold the number of subidentifiers and an array to hold the subidentifier values.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecObjId64 (  ASN1CTXT *  pctxt,
ASN1OID64 *  pvalue
) 
 

This function decodes a value of the ASN.1 OBJECT IDENTIFIER type using 64-bit subidentifiers.

Parameters:
pctxt Pointer to context block structure.
pvalue Pointer to value to receive decoded result. The ASN1OID64 structure contains an integer to hold the number of subidentifiers and an array of 64-bit unsigned integers to hold the subidentifier values.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecOctStr (  ASN1CTXT *  pctxt,
ASN1OCTET *  pvalue,
ASN1UINT *  pnocts,
ASN1INT  bufsize
) 
 

This function will decode a variable of the ASN.1 OCTET STRING type into a static memory structure. This function call is generated by ASN1C to decode a sized octet string production.

Parameters:
pctxt A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls.
pvalue A pointer to a variable to receive the decoded bit string. This is assumed to be a static array large enough to hold the number of octets specified in the bufsize input parameter.
pnocts Pointer to an integer value to receive the number of octets.
bufsize An integer variable containing the size (in octets) of the sized ASN.1 octet string. An error will occur if the number of octets in the decoded string is larger than this value.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecOctStrMemBuf (  ASN1MemBuf *  pMemBuf,
ASN1Const XMLCHAR *  inpdata,
int  length,
ASN1BOOL  skipWhitespaces
) 
 

This function decodes a variable of the ASN.1 OCTET STRING type to a memory buffer. The decoded data will be put into the memory buffer starting from the current position and bit offset. After all data is decoded the octet string may be fetched out by call to xerDecCopyOctStr or xerDecCopyDynOctStr functions.

Usually, this function is used in the 'characters' SAX handler.

Parameters:
pMemBuf Pointer to the destination memory buffer.
inpdata Pointer to a source string to be decoded.
length Length of the source string (in characters).
skipWhitespaces Indicates, could whitespaces be ignored or they are illegal.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecOpenType (  ASN1CTXT *  pctxt,
ASN1OpenType *  pvalue
) 
 

This function will decode an ASN.1 open type. This used to be the ASN.1 ANY type, but now is used in a variety of applications requiring an encoding that can be interpreted by a decoder without prior knowledge of the type of the variable.

Parameters:
pctxt A pointer to a context block structure. This provides a storage area for the function to store all working variables that must be maintained between function calls.
pvalue A pointer to a structure variable to receive the decoded string. The string as stored as an array of unsigned integer characters. Memory is allocated for the string by the rtMemAlloc function.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecReal (  ASN1CTXT *  pctxt,
ASN1REAL *  pvalue
) 
 

This function will decode a variable of the ASN.1 32-bit character UniversalString type. This includes the UniversalString type.

Parameters:
pctxt A pointer to a context block structure. This provides a storage area for the function to store all working variables that must be maintained between function calls.
pvalue A pointer to a structure variable to receive the decoded string. The string as stored as an array of unsigned integer characters. Memory is allocated for the string by the rtMemAlloc function.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecRelativeOID (  ASN1CTXT *  pctxt,
ASN1OBJID *  pvalue
) 
 

This function decodes a value of the ASN.1 RELATIVE-OID type.

Parameters:
pctxt Pointer to context block structure.
pvalue Pointer to value to receive decoded result. The ASN1OBJID structure contains an integer to hold the number of subidentifiers and an array to hold the subidentifier values.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecUInt (  ASN1CTXT *  pctxt,
ASN1UINT *  pvalue
) 
 

This function decodes a variable of the unsigned variant of ASN.1 INTEGER type.

Parameters:
pctxt Pointer to context block structure.
pvalue Pointer to a variable to receive the decoded unsigned integer value.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecUInt16 (  ASN1CTXT *  pctxt,
ASN1USINT *  pvalue
) 
 

This function decodes a 16-bit variable of the unsigned variant of ASN.1 INTEGER type.

Parameters:
pctxt Pointer to context block structure.
pvalue Pointer to a 16-bit variable to receive the decoded unsigned integer value.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecUInt64 (  ASN1CTXT *  pctxt,
ASN1UINT64 *  pvalue
) 
 

This function decodes a 64-bit variable of the unsigned variant of ASN.1 INTEGER type.

Parameters:
pctxt Pointer to context block structure.
pvalue Pointer to a 64-bit variable to receive the decoded unsigned integer value. The ASN1UINT64 type is set to the C type 'unsigned __int64', 'unsigned long long' or 'unsigned long' in the asn1type.h file (depends on the used platform and the compiler).
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecUInt8 (  ASN1CTXT *  pctxt,
ASN1UINT8 *  pvalue
) 
 

This function decodes an 8-bit variable of the unsigned variant of ASN.1 INTEGER type.

Parameters:
pctxt Pointer to context block structure.
pvalue Pointer to an 8-bit variable to receive the decoded unsigned integer value.
Returns:
Completion status of operation:
  • 0 (ASN_OK) = success,
  • negative return value is error.

int xerDecUnivStr (  ASN1CTXT *  pctxt,
ASN1UniversalString *  outdata
) 
 

This function will decode a variable an ASN.1 32-bit character UniversalString type. This includes the UniversalString type.

Parameters:
pctxt A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls.
outdata A pointer to a structure variable to receive the decoded string. The string as stored as an array of unsigned integer characters. Memory is allocated for the string by the rtMemAlloc function.

int xerSetDecBufPtr (  ASN1CTXT *  pCtxt,
ASN1ConstOctetPtr  bufaddr,
size_t  bufsiz
) 
 

This function is used to set the internal decode buffer pointer within the runtime library decode module. It must be called prior to calling any other complier generated or runtime library decode functions.

Parameters:
pCtxt A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls.
bufaddr A pointer to a memory buffer containing the ASN.1 message. The pointer must point at the first byte in the message.
bufsiz The size of the message that was read. This is used to set an internal message size to check for field length errors. If this size is not known, a zero value can be passed to cause these checks to be bypassed.

Copyright © 1997-2005 Objective Systems,Inc.
All Rights Reserved.
This document may be distributed in any form, electronic
or otherwise, provided that it is distributed in its entirety
and that the copyright and this notice are included.
This file was last modified on 8 Sep 2005.
ASN1C XER Runtime, ASN1C v5.8x