PER C Utility Functions
[PER Runtime Library Functions.]

Defines
#define	pd_setp(pctxt, bufaddr, bufsiz, aligned)   pu_setBuffer(pctxt, bufaddr, bufsiz, aligned)
#define	pe_setp(pctxt, bufaddr, bufsiz, aligned)   pu_setBuffer(pctxt, bufaddr, bufsiz, aligned)
#define	pe_resetp(pctxt)   rtxResetContext(pctxt)
#define	pd_resetp(pctxt)   rtxResetContext(pctxt)
Functions
int	pu_addSizeConstraint (OSCTXT *pctxt, const Asn1SizeCnst *pSize)
OSBOOL	pu_alignCharStr (OSCTXT *pctxt, OSUINT32 len, OSUINT32 nbits, Asn1SizeCnst *pSize)
OSUINT32	pu_bitcnt (OSUINT32 value)
Asn1SizeCnst *	pu_checkSize (Asn1SizeCnst *pSizeList, OSUINT32 value, OSBOOL *pExtendable)
int	pu_checkSizeExt (Asn1SizeCnst *pSizeCnst, OSUINT32 value, OSBOOL *pExtendable, Asn1SizeValueRange *pSizeRange, OSBOOL *pExtSize)
void	pu_freeContext (OSCTXT *pctxt)
size_t	pu_getMaskAndIndex (size_t bitOffset, unsigned char *pMask)
size_t	pu_getMsgLen (OSCTXT *pctxt)
size_t	pu_getMsgLenBits (OSCTXT *pctxt)
void	pu_hexdump (OSCTXT *pctxt)
int	pu_setBuffer (OSCTXT *pctxt, OSOCTET *bufaddr, size_t bufsiz, OSBOOL aligned)
int	pu_initContext (OSCTXT *pctxt, OSOCTET *bufaddr, OSUINT32 bufsiz, OSBOOL aligned)
int	pu_initContextBuffer (OSCTXT *pTarget, OSCTXT *pSource)
const char *	pu_getFullName (OSCTXT *pctxt, const char *suffix)
void	pu_init16BitCharSet (Asn116BitCharSet *pCharSet, OSUNICHAR first, OSUNICHAR last, OSUINT32 abits, OSUINT32 ubits)
void	pu_insLenField (OSCTXT *pctxt)
OSBOOL	pu_isFixedSize (const Asn1SizeCnst *pSizeList)
OSCTXT *	pu_newContext (OSOCTET *bufaddr, OSUINT32 bufsiz, OSBOOL aligned)
PERField *	pu_newField (OSCTXT *pctxt, const char *nameSuffix)
void	pu_initFieldList (OSCTXT *pctxt, OSINT16 bitOffset)
void	pu_initRtxDiagBitFieldList (OSCTXT *pctxt, OSINT16 bitOffset)
void	pu_popName (OSCTXT *pctxt)
void	pu_pushElemName (OSCTXT *pctxt, int idx)
void	pu_pushName (OSCTXT *pctxt, const char *name)
void	pu_setCharSet (Asn1CharSet *pCharSet, const char *permSet)
void	pu_set16BitCharSet (OSCTXT *pctxt, Asn116BitCharSet *pCharSet, Asn116BitCharSet *pAlphabet)
void	pu_set16BitCharSetFromRange (Asn116BitCharSet *pCharSet, OSUINT16 firstChar, OSUINT16 lastChar)
void	pu_setFldBitCount (OSCTXT *pctxt)
void	pu_setFldBitOffset (OSCTXT *pctxt)
void	pu_setFldListFromCtxt (OSCTXT *pctxt, OSCTXT *srcctxt)
void	pu_setOpenTypeFldList (OSCTXT *pctxt, OSRTSList *plist)
void	pu_setRtxDiagOpenTypeFldList (OSRTDiagBitFieldList *pMainBFList, OSRTDiagBitFieldList *pOpenTypeBFList)
OSBOOL	pu_setTrace (OSCTXT *pCtxt, OSBOOL value)
void	pu_setAligned (OSCTXT *pctxt, OSBOOL value)
void	pu_deleteFieldList (OSCTXT *pctxt)
void	pu_bindump (OSCTXT *pctxt, const char *varname)
void	pu_dumpField (OSCTXT *pctxt, PERField *pField, const char *varname, size_t nextBitOffset, BinDumpBuffer *pbuf)
void	pu_init32BitCharSet (Asn132BitCharSet *pCharSet, OS32BITCHAR first, OS32BITCHAR last, OSUINT32 abits, OSUINT32 ubits)
void	pu_set32BitCharSet (OSCTXT *pctxt, Asn132BitCharSet *pCharSet, Asn132BitCharSet *pAlphabet)
void	pu_set32BitCharSetFromRange (Asn132BitCharSet *pCharSet, OSUINT32 firstChar, OSUINT32 lastChar)
int	pu_GetLibVersion (OSVOIDARG)
const char *	pu_GetLibInfo (OSVOIDARG)

---

Detailed Description

The PER utility functions are common routines used by both the PER encode and decode functions.

---

Function Documentation

int pu_addSizeConstraint	(	OSCTXT *	pctxt,
		const Asn1SizeCnst *	pSize
	)

This function is used to add size to a context variable.

Parameters:

	pctxt	A pointer to a context structure. The referenced size constraint is added to this structure for use by a subsequent encode or decode function.
	pSize	A pointer to the size constraint to add the context variable.

Returns:

Completion status of operation:

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

void pu_bindump	(	OSCTXT *	pctxt,
		const char *	varname
	)

This function provides a detailed binary dump of the contents of the buffer currently specified in the given context. The list of fields dumped by this function was previously built up within the context using calls pu_newField, pu_pushName, and pu_popName. These calls are built into both compiler-generated and low-level PER encode/decode functions to trace the actual bit encoding of a given construct.

Parameters:

	pctxt	A pointer to a context structure. The contents of the encode or decode buffer that was specified in the call to pu_initContext or pu_newContext is dumped.
	varname	The name of the top-level variable name of the structure being dumped.

Referenced by ASN1PERMessageBuffer::binDump().

int pu_checkSizeExt	(	Asn1SizeCnst *	pSizeCnst,
		OSUINT32	value,
		OSBOOL *	pExtendable,
		Asn1SizeValueRange *	pSizeRange,
		OSBOOL *	pExtSize
	)

This function checks if the given value falls within the root or extension part of the given size constraint.

Parameters:

	pSizeCnst	A pointer to a size constraint structure.
	value	The value to be checked.
	pExtendable	Pointer to boolean indicating if size constraint is extensible.
	pSizeRange	Size range which value falls within.
	pExtSize	Indicates if the size range is an extension range.

Returns:

Status of the operation. 0 = success or RTERR_CONSVIO if size if not within the constraint bounds.

void pu_freeContext

(

OSCTXT *

pctxt

)

This function releases all dynamicmemeory associated with a context. This function should be called even if the referenced context variable is not dynamic. The reason is because it frees memory allocated within the context as well as the context structure (it will only try to free the context structure if it detects that it was previously allocated using the pu_newContext function).

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.

const char* pu_GetLibInfo

(

OSVOIDARG

)

Returns information string describing the library. The string contains name of library, its version and flags used for building the library.

Returns:

Information string

int pu_GetLibVersion

(

OSVOIDARG

)

Returns numeric version of run-time library. The format of version is as follows: MmP, where: M - major version number; m - minor version number; p - patch release number. For example, the value 581 means the version 5.81.

Returns:

Version of run-time library in numeric format.

size_t pu_getMsgLen

(

OSCTXT *

pctxt

)

This function will return the number of bytes in a PER message. This function is called after a complier generated encode function is called to get the byte count of the encoded 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.

See also:

pu_getMsgLenBits

Returns:

Length (in bytes) of encoded message content.

Referenced by ASN1PERMessageBuffer::getMsgLen().

size_t pu_getMsgLenBits

(

OSCTXT *

pctxt

)

This function will return the number of bits in a PER message. This function is called after a complier generated encode function is called to get the bit count of the encoded 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.

See also:

pu_getMsgLen

Returns:

Length (in bits) of encoded message content.

void pu_hexdump

(

OSCTXT *

pctxt

)

This function provides a standard hesadecimal dump of the contents of the buffer currently specified in the given context.

Parameters:

pctxt

Pointer to a context structure. The contents of the encode or decode buffer that was specified in the call to pu_initContext or pu_newContext is dumped.

Referenced by ASN1PERMessageBuffer::hexDump().

int pu_initContext	(	OSCTXT *	pctxt,
		OSOCTET *	bufaddr,
		OSUINT32	bufsiz,
		OSBOOL	aligned
	)

This function is used to initialize a pre-allocated OSCTXT structure. This can be an OSCTXT variable declared on the stack or a pointer to an OSCTXT structure that was previously allocated. This function sets all internal variables within the structure to their initial 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.
	bufaddr	For encoding, this is the address of a buffer to receive the encoded PER message (note: this is optional, if specified to NULL a dynamic buffer will be allocated). For decoding, this is that address of the buffer that contains the PER message to be decoded.
	bufsiz	For encoding, this is the size of the encoded buffer (note: this is optional, if the bufaddr arguement is specified to NULL, then dynamic encoding is in effect and the buffer size is indefinite). For decoding, this is the length (in octets) of the PER message to be decoded.
	aligned	A Boolean value specifying whether aligned or unaligned encoding should be performed.

Returns:

Completion status of operation:

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

int pu_initContextBuffer	(	OSCTXT *	pTarget,
		OSCTXT *	pSource
	)

This function is used to initialize the buffer of an OSCTXT structure with buffer data from a second context structure. This function copies the buffer information from the source context buffer to the destination structure. The non-buffer related fields in the context remain untouched.

Parameters:

	pTarget	A pointer to the target context structure. Buffer information within this structure is updated with data from the source context.
	pSource	A pointer to the source context structure. Buffer information from the source context structure is copied to the target structure.

Returns:

Completion status of operation:

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

void pu_initFieldList	(	OSCTXT *	pctxt,
		OSINT16	bitOffset
	)

This function initializes a new bit field list for diagnostics tracing. It is now deprecated and has been replaced by function pu_initRtxDiagBitFieldList which works with the common context bit tracing list structure rather than the ASN.1 PER-specific list.

Parameters:

	pctxt	A pointer to a context structure.
	bitOffset	Current bit offset.

void pu_initRtxDiagBitFieldList	(	OSCTXT *	pctxt,
		OSINT16	bitOffset
	)

This function initializes a new bit field list for diagnostics tracing. It is used in code to encode or decode table-constrained open type data to break down the patterns within the containers.

Parameters:

	pctxt	A pointer to a context structure.
	bitOffset	Current bit offset.

void pu_insLenField

(

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.

OSBOOL pu_isFixedSize

(

const Asn1SizeCnst *

pSizeList

)

This function determines if a size constraint is fixed (i.e allows only one value such as SIZE (2))

Parameters:

pSizeList

A pointer to a size constraint structure.

Returns:

TRUE if size constraint is fixed.

OSCTXT* pu_newContext	(	OSOCTET *	bufaddr,
		OSUINT32	bufsiz,
		OSBOOL	aligned
	)

This function is similar to the pu_initContext function in that it initializes a context variable. The difference is that this function allocates a new structure and then initializes it. It is equivalent to calling malloc to allocate a context structure and then calling pu_initContext to initialize it.

Parameters:

	bufaddr	For encoding, this is the address of a buffer to receive the encoded PER message (note: this is optional, if specified as NULL a dynamic buffer will be allocated). For decoding, this is that address of the buffer that contains the PER message to be decoded.
	bufsiz	For encoding, this is the size of the encoded buffer (note: this is optional, if the bufaddr argument is specified to NULL, then dynamic encoding is in effect and the buffer size is indefinite). For decoding, this is the length (in octets) of the PER message to be decoded.
	aligned	A Boolean value specifying whether aligned or unaligned encoding should be performed.

Returns:

A pointer to OSCTXT structure to receive the allocated structure. NULL is returned if any error occurs in allocating or initializing the context.

PERField* pu_newField	(	OSCTXT *	pctxt,
		const char *	nameSuffix
	)

This function creates a new bit field in a diagnostics bit trace field list. It is now deprecated and has been replaced by the common function rtxDiagNewBitField.

Parameters:

	pctxt	A pointer to a context structure.
	nameSuffix	Suffix to be append to current element name.

void pu_popName

(

OSCTXT *

pctxt

)

Pop an element name from the diagnostics bit trace stack. This function is now deprecated and has been replaced with the common function rtxCtxtPopElemName which is used maintain a name stack for other purposes as well (for example, error reporting).

Parameters:

pctxt

A pointer to a context structure.

void pu_pushElemName	(	OSCTXT *	pctxt,
		int	idx
	)

Push an array element on the diagnostics bit trace stack. This function is now deprecated and has been replaced with the common function rtxCtxtPushArrayElemName which is used maintain a name stack for other purposes as well (for example, error reporting).

Parameters:

	pctxt	A pointer to a context structure.
	idx	The location to insert the element.

void pu_pushName	(	OSCTXT *	pctxt,
		const char *	name
	)

Push an element on the diagnostics bit trace stack. This function is now deprecated and has been replaced with the common function rtxCtxtPushElemName which is used maintain a name stack for other purposes as well (for example, error reporting).

Parameters:

	pctxt	A pointer to a context structure.
	name	A pointer to the element to add to the stack.

void pu_set16BitCharSet	(	OSCTXT *	pctxt,
		Asn116BitCharSet *	pCharSet,
		Asn116BitCharSet *	pAlphabet
	)

This function sets a permitted alphabet character set for 16-bit character strings. This is the resulting set of character when the character associated with a 16-bit string type is merged with a permitted alphabet constraint.

Parameters:

	pctxt	Pointer to a context structure.
	pCharSet	Pointer to a character set structure describing the character set currently associated with the character string type. The resulting character set structure after being merged with the permSet parameter.
	pAlphabet	Pointer to a structure describing the 16-bit permitted alphabet.

void pu_set16BitCharSetFromRange	(	Asn116BitCharSet *	pCharSet,
		OSUINT16	firstChar,
		OSUINT16	lastChar
	)

Parameters:

	pCharSet	Pointer to a character set structure describing the character set currently associated with the character string type. The resulting character set structure after being merged with the permSet parameter.
	firstChar	The first character in the range.
	lastChar	The last character in the range.

void pu_set32BitCharSet	(	OSCTXT *	pctxt,
		Asn132BitCharSet *	pCharSet,
		Asn132BitCharSet *	pAlphabet
	)

This function sets a permitted alphabet character set for 32-bit character strings. This is the resulting set of character when the character associated with a 16-bit string type is merged with a permitted alphabet constraint.

Parameters:

	pctxt	Pointer to a context structure.
	pCharSet	Pointer to a character set structure describing the character set currently associated with the character string type. The resulting character set structure after being merged with the permSet parameter.
	pAlphabet	Pointer to a structure describing the 32-bit permitted alphabet.

void pu_set32BitCharSetFromRange	(	Asn132BitCharSet *	pCharSet,
		OSUINT32	firstChar,
		OSUINT32	lastChar
	)

Parameters:

	pCharSet	Pointer to a character set structure describing the character set currently associated with the character string type. The resulting character set structure after being merged with the permSet parameter.
	firstChar	The first character in the range.
	lastChar	The last character in the range.

int pu_setBuffer	(	OSCTXT *	pctxt,
		OSOCTET *	bufaddr,
		size_t	bufsiz,
		OSBOOL	aligned
	)

This function is used to set the buffer pointer for PER encoding or decoding. For encoding, the buffer would either be a static byte array in memory to receive the encoded message or, if bufaddr was set to NULL, would indicate encoding is to be done to a dynamic buffer. For decoding, a buffer in memory would be specified which contains the message to be decoded.

Parameters:

	pctxt	Pointer to a context structure.
	bufaddr	Address of memory buffer. For encoding, this may be set to NULL to indicate a dynamic buffer is to be used.
	bufsiz	Size, in byte, of static memory buffer.
	aligned	Indicate if aligned (true) or unaligned (false) PER should be used for encoding or decoding.

void pu_setCharSet	(	Asn1CharSet *	pCharSet,
		const char *	permSet
	)

This function sets a permitted alphabet character set. This is the resulting set of characters when the character associated with a standard character string type is merged with a permitted alphabet constraint.

Parameters:

	pCharSet	A pointer to a character set structure describing the character set currently associated with the character string type. The resulting character set structure after being merged with the permSet parameter.
	permSet	A null-terminated string of permitted characters.