Home > Support > Documentation

PER C Utility Functions
[PER Runtime Library Functions.]

Detailed Description

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


Defines

#define pd_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, Asn1SizeCnst *pSize)
OSBOOL pu_alignCharStr (OSCTXT *pctxt, OSUINT32 len, OSUINT32 nbits, Asn1SizeCnst *pSize)
int pu_checkSizeConstraint (OSCTXT *pctxt, int size)
OSUINT32 pu_bitcnt (OSUINT32 value)
Asn1SizeCnst * pu_checkSize (Asn1SizeCnst *pSizeList, OSUINT32 value, OSBOOL *pExtendable)
void pu_freeContext (OSCTXT *pctxt)
int pu_getBitOffset (OSCTXT *pctxt)
size_t pu_getMaskAndIndex (size_t bitOffset, unsigned char *pMask)
size_t pu_getMsgLen (OSCTXT *pctxt)
void pu_hexdump (OSCTXT *pctxt)
int pu_setBuffer (OSCTXT *pctxt, OSOCTET *bufaddr, size_t bufsiz, OSBOOL aligned)
int pe_setp (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)
Asn1SizeCnst * pu_getSizeConstraint (OSCTXT *pctxt, OSBOOL extbit)
void pu_init16BitCharSet (Asn116BitCharSet *pCharSet, OSUNICHAR first, OSUNICHAR last, OSUINT32 abits, OSUINT32 ubits)
void pu_insLenField (OSCTXT *pctxt)
OSBOOL pu_isExtendableSize (Asn1SizeCnst *pSizeList)
OSBOOL pu_isFixedSize (Asn1SizeCnst *pSizeList)
OSCTXT * pu_newContext (OSOCTET *bufaddr, OSUINT32 bufsiz, OSBOOL aligned)
PERField * pu_newField (OSCTXT *pctxt, const char *nameSuffix)
void pu_popName (OSCTXT *pctxt)
void pu_pushElemName (OSCTXT *pctxt, int index)
void pu_pushName (OSCTXT *pctxt, const char *name)
void pu_setBitOffset (OSCTXT *pctxt, int bitOffset)
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)
OSBOOL pu_setTrace (OSCTXT *pCtxt, OSBOOL value)
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 ()
const char * pu_GetLibInfo ()

Function Documentation

int pu_addSizeConstraint (  OSCTXT *  pctxt,
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.

OSUINT32 pu_bitcnt (  OSUINT32  value  ) 
 

Parameters:
value Value to be encoded.

int pu_checkSizeConstraint (  OSCTXT *  pctxt,
int  size
) 
 

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.
size The size constraint to add the context variable.

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.

int pu_getBitOffset (  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.

const char* pu_GetLibInfo (   ) 
 

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 (   ) 
 

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 bits in a encoded 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.
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.

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_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_isExtendableSize (  Asn1SizeCnst *  pSizeList  ) 
 

Parameters:
pSizeList A pointer to the size of the Linked List.

OSBOOL pu_isFixedSize (  Asn1SizeCnst *  pSizeList  ) 
 

Parameters:
pSizeList A pointer to the size of the Linked List.

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.

void pu_popName (  OSCTXT *  pctxt  ) 
 

Parameters:
pctxt A pointer to a context structure.

void pu_pushElemName (  OSCTXT *  pctxt,
int  index
) 
 

Pushs an element on the stack.

Parameters:
pctxt A pointer to a context structure.
index The location to insert the element.

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

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.

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.

void pu_setFldBitCount (  OSCTXT *  pctxt  ) 
 

Parameters:
pctxt A pointer to a context structure.

void pu_setFldBitOffset (  OSCTXT *  pctxt  ) 
 

Parameters:
pctxt A pointer to a context structure.

OSBOOL pu_setTrace (  OSCTXT *  pCtxt,
OSBOOL  value
) 
 

Parameters:
pCtxt A pointer to a context structure.
value The BOOLEAN value to be encoded.