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, OSSIZE 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_insLenField (OSCTXT *pctxt)
OSBOOL pu_isFixedSize (const Asn1SizeCnst *pSizeList)
OSCTXT * pu_newContext (OSOCTET *bufaddr, OSUINT32 bufsiz, OSBOOL aligned)
PERFieldpu_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)
int 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)
int 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,
OSSIZE  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.
int 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.
Returns:
Status value of zero if successful, or a negative value if failure.
void pu_set16BitCharSetFromRange ( Asn116BitCharSet *  pCharSet,
OSUINT16  firstChar,
OSUINT16  lastChar 
)

This function sets a permitted alphabet character set for 16-bit character strings from a sequential range of characters (for example, 'A'..'Z').

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_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.
Returns:
Status value of zero if successful, or a negative value if failure.
void pu_set32BitCharSetFromRange ( Asn132BitCharSet *  pCharSet,
OSUINT32  firstChar,
OSUINT32  lastChar 
)

This function sets a permitted alphabet character set for 32-bit character strings from a sequential range of characters (for example, 'A'..'Z').

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.