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

Functions
int	xerSetEncBufPtr (OSCTXT pCtxt, OSOCTET bufaddr, size_t bufsiz, OSBOOL canonical)
int	xerEncAscCharStr (OSCTXT pctxt, const char value, const char *elemName)
int	xerEncBase64Str (OSCTXT pctxt, OSUINT32 nocts, const OSOCTET data, const char *elemName)
int	xerEncBigInt (OSCTXT pctxt, const char value, const char *elemName)
int	xerEncBitStr (OSCTXT pctxt, OSUINT32 nbits, const OSOCTET data, const char *elemName, ASN1StrType outputType)
int	xerEncBoolValue (OSCTXT *pctxt, OSBOOL value)
int	xerEncBool (OSCTXT pctxt, OSBOOL value, const char elemName)
int	xerEncEndDocument (OSCTXT *pctxt)
int	xerEncEndElement (OSCTXT pctxt, const char elemName)
int	xerEncIndent (OSCTXT *pctxt)
int	xerEncInt (OSCTXT pctxt, OSINT32 value, const char elemName)
int	xerEncInt64 (OSCTXT pctxt, OSINT64 value, const char elemName)
int	xerEncNewLine (OSCTXT *pctxt)
int	xerEncObjId (OSCTXT pctxt, const ASN1OBJID pvalue, const char *elemName)
int	xerEncObjId64 (OSCTXT pctxt, const ASN1OID64 pvalue, const char *elemName)
int	xerEncRelativeOID (OSCTXT pctxt, const ASN1OBJID pvalue, const char *elemName)
int	xerEncOctStr (OSCTXT pctxt, OSUINT32 nocts, const OSOCTET data, const char *elemName)
int	xerEncReal (OSCTXT pctxt, OSREAL value, const char elemName)
int	xerEncReal10 (OSCTXT pctxt, const OSUTF8CHAR value, const char *elemName)
int	xerEncStartDocument (OSCTXT *pctxt)
int	xerEncStartElement (OSCTXT pctxt, const char elemName, const char *attributes)
int	xerEncEmptyElement (OSCTXT pctxt, const char elemName, const char *attributes)
int	xerEncNamedValue (OSCTXT pctxt, const char value, const char elemName, const char attributes)
int	xerEncUInt (OSCTXT pctxt, OSUINT32 value, const char elemName)
int	xerEncUInt64 (OSCTXT pctxt, OSUINT64 value, const char elemName)
int	xerEncBMPStr (OSCTXT pctxt, const ASN1BMPString value, const char *elemName)
int	xerEncUnivStr (OSCTXT pctxt, const ASN1UniversalString value, const char *elemName)
int	xerEncUniCharData (OSCTXT pctxt, const OSUNICHAR value, OSUINT32 nchars)
int	xerEncUniCharStr (OSCTXT pctxt, OSUNICHAR value, const char *elemName)
int	xerEncOpenType (OSCTXT pctxt, OSUINT32 nocts, const OSOCTET data, const char *elemName)
int	xerEncNull (OSCTXT pctxt, const char elemName)
int	xerEncXmlCharData (OSCTXT pctxt, const XMLCHAR pvalue, int length)

Detailed Description

The XER low-level encode functions handle the XER encoding of primitive ASN.1 data types. Calls to these functions are assembled in the C source code generated by the ASN1C complier to accomplish the encoding of complex ASN.1 structures. These functions are also directly callable from within a user's application program if the need to accomplish a low level encoding function exists.

The procedure to call a low-level encode function is the same as the procedure to call a complier generated encode function described above. The rtInitContext and xerSetEncBufPtr functions must first be called to initialize a context and set a pointer to a buffer into which the variable is to be encoded. A static encode buffer is spcified by specifying a pointer to a buffer and buffer size. Setting the buffer address to NULL and buffer size to 0 specifies a dynamic buffer. The encode function is then invoked. The result of the encoding will start at the beginning of the specified buffer, or, if a dynamic buffer was used, it can be obtained by calling xerGetMsgPtr. The length of the encoded component is obtained by calling xerGetMsgLen.

Function Documentation

int xerEncAscCharStr	(	OSCTXT *	pctxt,
		const char *	value,
		const char *	elemName
	)

This function encodes a variable one of the ASN.1 character string types that are based on 8-bit character sets. This includes IA5Sring, VisibleString, PrintableString, and UTF8String, and NumericString.

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.
	value	A pointer to a null-terminated C character string to be encoded.
	elemName	This argument specifies the name of the element that is wrapped around the encoded value. If an empty string is passed (""), no element tag is added to the encoded value.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncBase64Str	(	OSCTXT *	pctxt,
		OSUINT32	nocts,
		const OSOCTET *	data,
		const char *	elemName
	)

This function encodes a variable of the ASN.1 OCTET STRING type using Base64 encoding.

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.
	nocts	The number of octets (bytes) within the OCTET STRING to be encoded.
	data	A pointer to an OCTET STRING containing the octet data to be encoded.
	elemName	This argument specifies the name of the element that is wrapped around the encoded value. If the name is null, the default name for this type is (<OCTET_STRING>) is added. If an empty string is passed (""), no element tag is added to the encoded value.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncBigInt	(	OSCTXT *	pctxt,
		const char *	value,
		const char *	elemName
	)

This function encodes 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.

Items of this type are stored in character string constant variables. They can be represented as decimal strings (with no prefixes), as hexadecimal strings starting with a "0x" prefix, as octal strings starting with a "0o" prefix or as binary strings starting with a "0b" prefix. Other radixes are currently not supported.

Parameters:

	pctxt	Pointer to context block structure.
	value	A pointer to a character string containing the value to be encoded.
	elemName	This argument specifies the name of the element that is wrapped around the encoded value. If the name is null, the default name for this type (<INTEGER>) is added. If an empty string is passed (""), no element tag is added to the encoded value.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncBitStr	(	OSCTXT *	pctxt,
		OSUINT32	nbits,
		const OSOCTET *	data,
		const char *	elemName,
		ASN1StrType	outputType
	)

This function encodes a variable of the ASN.1 BIT STRING 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.
	nbits	The number of bits within the bit string to be encoded.
	data	A pointer to an OCTET string containing the bit data to be encoded. This string contains bytes having the actual bit settings as they are to be encoded in the message.
	elemName	This argument specifies the name of the element that is wrapped around the encoded value. If the name is null, the default name for this type (<BIT_STRING>) is added. If an empty string is passed (""), no element tag is added to the encoded value.
	outputType	An enumerated type whose value is set to either 'ASN1BIN' (for binary format) or 'ASN1HEX' (for hexadecimal format).

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncBMPStr	(	OSCTXT *	pctxt,
		const ASN1BMPString *	value,
		const char *	elemName
	)

This function encodes a variable of the BMPString ASN.1 character string 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.
	value	A pointer to a structure representing a 16-bit character string to encoded. This structure contains a character count element and a pointer to an array of 16-bit character elements represented as 16-bit short integers.
	elemName	A pointer to a name of an element.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncBool	(	OSCTXT *	pctxt,
		OSBOOL	value,
		const char *	elemName
	)

This function encodes a variable of the ASN.1 BOOLEAN 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.
	value	A BOOLEAN value to be encoded. A BOOLEAN is defined as a single octet whose value is 0 for False and any other value for TRUE.
	elemName	This argument specifies the name of the element that is wrapped around the encoded value. If the name is null, the default name for this type (<BOOLEAN>) is added. If an empty string is passed (""), no element tag is added to the encoded value.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncEmptyElement	(	OSCTXT *	pctxt,
		const char *	elemName,
		const char *	attributes
	)

This function encodes an empty element, such as <element/>.

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.
	elemName	A pointer to the name of the element.
	attributes	A pointer to the attributes of the element.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncEndDocument ( OSCTXT * pctxt )

This function should be called at the end of the document's encoding.

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.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncEndElement	(	OSCTXT *	pctxt,
		const char *	elemName
	)

This function encodes the ending tag of the XML element, such as </element>.

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.
	elemName	A pointer to the name of the element.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncIndent ( OSCTXT * pctxt )

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.

int xerEncInt	(	OSCTXT *	pctxt,
		OSINT32	value,
		const char *	elemName
	)

This function encodes a variable of the ASN.1 INTEGER 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.
	value	An INTEGER value to be encoded. The OSINT32 type is set to the C type 'int' in the asn1type.h file. This is assumed to represent a 32-bit integer value.
	elemName	This argument specifies the name of the element that is wrapped around the encoded value. If the name is null, the default name for this type (<INTEGER>) is added. If an empty string is passed (""), no element tag is added to the encoded value.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncInt64	(	OSCTXT *	pctxt,
		OSINT64	value,
		const char *	elemName
	)

This function encodes a 64-bit variable of the ASN.1 INTEGER 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.
	value	A 64-bit INTEGER value to be encoded. The OSINT64 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). This is assumed to represent a 64-bit integer value.
	elemName	This argument specifies the name of the element that is wrapped around the encoded value. If the name is null, the default name for this type (<INTEGER>) is added. If an empty string is passed (""), no element tag is added to the encoded value.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncNamedValue	(	OSCTXT *	pctxt,
		const char *	value,
		const char *	elemName,
		const char *	attributes
	)

This function encodes a named value, for example an enumerated value, such as <element><value/></element>.

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.
	value	A pointer to a value string
	elemName	A pointer to the name of the element.
	attributes	A pointer to the attributes of the element.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncNewLine ( OSCTXT * pctxt )

This function inserts a new line symbol int the XML document.

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.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncNull	(	OSCTXT *	pctxt,
		const char *	elemName
	)

This function encodes an ASN.1 NULL placeholder. In XER the NULL value is represented as an empty element, such as <null/>.

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.
	elemName	This argument specifies the name of the element that is wrapped around the encoded value. If a null or empty string is passes (""), no element tag is added to the encoded value.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncObjId	(	OSCTXT *	pctxt,
		const ASN1OBJID *	pvalue,
		const char *	elemName
	)

This function encodes a variable of the ASN.1 OBJECT IDENTIFIER 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.
	pvalue	A pointer to an object identifier structure. This structure contains an integer to hold the number of subidentifers in the object and an array to hold the subidentifier values.
	elemName	This argument specifies the name of the element that is wrapped around the encoded value. If the name is null, the default name for this type (<OBJECT_IDENTIFIER>) is added. If an empty string is passed (""), no element tag is added to the encoded value.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncObjId64	(	OSCTXT *	pctxt,
		const ASN1OID64 *	pvalue,
		const char *	elemName
	)

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

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 64-bit object identifier structure. This structure contains an integer to hold the number of subidentifers in the object and an array of 64-bit unsigned integers to hold the subidentifier values.
	elemName	This argument specifies the name of the element that is wrapped around the encoded value. If the name is null, the default name for this type (<OBJECT_IDENTIFIER>) is added. If an empty string is passed (""), no element tag is added to the encoded value.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncOctStr	(	OSCTXT *	pctxt,
		OSUINT32	nocts,
		const OSOCTET *	data,
		const char *	elemName
	)

This function encodes a variable of the ASN.1 OCTET STRING 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.
	nocts	The number of octets (bytes) within the OCTET STRING to be encoded.
	data	A pointer to an OCTET STRING containing the octet data to be encoded.
	elemName	This argument specifies the name of the element that is wrapped around the encoded value. If the name is null, the default name for this type (<OCTET_STRING>) is added. If an empty string is passed (""), no element tag is added to the encoded value.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncOpenType	(	OSCTXT *	pctxt,
		OSUINT32	nocts,
		const OSOCTET *	data,
		const char *	elemName
	)

This function encodes a variable of the old (pre-1994) ASN.1 ANY type or other elements defined in the later standards to be Open Types (for example, a variable type declaration in a CLASS construct as defined n X.681). A variable of this is considered to be a previously encoded ASN.1 message component.

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.
	nocts	The number of octets (bytes) within the OCTET STRING to be encoded.
	data	A pointer to an OCTET STRING containing an encoded ASN.1 message component.
	elemName	This argument specifies the name of the element that is wrapped around the encoded value. If the name is null, the default name for this type (<REAL>) is added. If an empty string is passed (""), no element tag is added to the encoded value.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncReal	(	OSCTXT *	pctxt,
		OSREAL	value,
		const char *	elemName
	)

This function encodes a variable of the REAL data type. This function provides support for the plus-infinity and the minus-infinity special real values. Use the rtxGetPlusInfinity or rtxGetMinusInfinity functions to get these special values.

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.
	value	A value to be encoded. Special real values plus and minus infinity are encoded by using the rtxGetPlusInfinity and rtxGetMinusInfinity functions to set the real value to be encoded.
	elemName	A pointer to the name of the element.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncReal10	(	OSCTXT *	pctxt,
		const OSUTF8CHAR *	value,
		const char *	elemName
	)

This function encodes a variable of the REAL base 10 data type. This function provides support for the plus-infinity and the minus-infinity special real values. Use the rtxGetPlusInfinity or rtxGetMinusInfinity functions to get these special values.

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.
	value	A value to be encoded.
	elemName	A pointer to the name of the element.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncRelativeOID	(	OSCTXT *	pctxt,
		const ASN1OBJID *	pvalue,
		const char *	elemName
	)

This function encodes a variable of the ASN.1 RELATIVE-OID 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.
	pvalue	A pointer to an object identifier structure. This structure contains an integer to hold the number of subidentifers in the object and an array to hold the subidentifier values.
	elemName	This argument specifies the name of the element that is wrapped around the encoded value. If the name is null, the default name for this type (<RELATIVE_OID>) is added. If an empty string is passed (""), no element tag is added to the encoded value.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncStartDocument ( OSCTXT * pctxt )

This function encodes the starting record of the XML document (such as the <?xml version = "1.0" encoding = "UTF-8"?>). This function should be called prior to encoding any other fields in the document. After all elements in the document are encoded, xerEncEndDocument should be called.

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.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncStartElement	(	OSCTXT *	pctxt,
		const char *	elemName,
		const char *	attributes
	)

This function encodes the string tag of the XML element, such as <element>. After the element's data is encoded, the xerEncEndElement function should be called.

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.
	elemName	A pointer to the name of the element.
	attributes	A pointer to the attributes of the element.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncUInt	(	OSCTXT *	pctxt,
		OSUINT32	value,
		const char *	elemName
	)

This function encodes an unsigned variable of the ASN.1 INTEGER 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.e.
	value	An unsigned INTEGER value to be encoded. The ASNU1INT type is set to the C type 'unsigned int' in the asn1type.h file. This is assumed to represent a 32-bit integer value.
	elemName	This argument specifies the name of the element that is wrapped around the encoded value. If the name is null, the default name for this type (<INTEGER>) is added. If an empty string is passed (""), no element tag is added to the encoded value.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncUInt64	(	OSCTXT *	pctxt,
		OSUINT64	value,
		const char *	elemName
	)

This function encodes an unsigned 64-bit variable of the ASN.1 INTEGER 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.
	value	An unsigned 64-bit INTEGER value to be encoded. The OSUINT64 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). This is assumed to represent an unsigned 64-bit integer value.
	elemName	This argument specifies the name of the element that is wrapped around the encoded value. If the name is null, the default name for this type (<INTEGER>) is added. If an empty string is passed (""), no element tag is added to the encoded value.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncUniCharData	(	OSCTXT *	pctxt,
		const OSUNICHAR *	value,
		OSUINT32	nchars
	)

This function encodes a variable of the ASN.1 character string types that are based on 16-bit character sets and are represented as null-terminated Unicode string. This includes IA5String, VisibleString, PrintableString, NumericString, and BMPString.

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.
	value	A pointer to a null-terminated 16-bit string to be encoded.
	nchars	The number of characters to be encoded.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncUniCharStr	(	OSCTXT *	pctxt,
		OSUNICHAR *	value,
		const char *	elemName
	)

This function encodes a variable one of the ASN.1 character string types that are based on 16-bit character sets and are represented as null-terminated Unicode strings. This includes IA5String, VisibleString, PrintableString, NumericString, Adn BMPString.

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.
	value	A pointer to a null-terminated 16-bit character string to be encoded.
	elemName	This argument specifies the name of the element that is wrapped around the encoded value. If an empty string is passed (""), no element tag is added to the encoded value.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerEncUnivStr	(	OSCTXT *	pctxt,
		const ASN1UniversalString *	value,
		const char *	elemName
	)

This function encodes a variable of the ASN.1 Universal character string. This differs from the encode routines for the character strings previously described in that the Universal string type is based o te 32-bit characters. A 32-bit character string is modeled using an array of unsigned integers.

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.
	value	A pointer to a structure representing a 16-bit character string to encoded. This structure contains a character count element and a pointer to an array of 32-bit character elements represented as 32-bit short integers.
	elemName	A pointer to a name of an element.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

int xerSetEncBufPtr	(	OSCTXT *	pCtxt,
		OSOCTET *	bufaddr,
		size_t	bufsiz,
		OSBOOL	canonical
	)

This function is used to set the internal buffer within the runtime library encode module. It must be called prior to calling any other generated or runtime library encode 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.
	canonical	TRUE, if canonical XML encoding rules (CXER) should be used. Otherwise FALSE.

Returns:

Completion status of operation:

0 (0) = success,
negative return value is error.

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

Functions

Detailed Description

Function Documentation

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