BER/PER C Utility Functions
[BER Runtime Library Functions.]

Defines
#define	xu_addTagErrParm berErrAddTagParm
#define	xu_hex_dump(msg, numoct, hdr) rtxHexDump(msg,numoct)
Functions
int	berDefToIndefLen (OSCTXT pSrcCtxt, OSCTXT pDstCtxt)
int	berIndefToDefLen (OSCTXT pSrcCtxt, OSCTXT pDstCtxt)
OSBOOL	berErrAddTagParm (OSCTXT *pctxt, ASN1TAG tag)
int	berErrUnexpTag (OSCTXT *pctxt, ASN1TAG exptag)
int	berGetLibVersion (OSVOIDARG)
const char *	berGetLibInfo (OSVOIDARG)
int	berParseTagLen (const OSOCTET buffer, size_t bufidx, size_t bufsiz, ASN1TAG ptag, size_t *plen)
const char *	berTagToString (ASN1TAG tag, char *buffer, size_t bufsiz)
const char *	berTagToDynStr (OSCTXT *pctxt, ASN1TAG tag)
int	berValidateIso8601DateStr (OSCTXT pctxt, const char *ppvalue)
int	berValidateIso8601DurationStr (OSCTXT pctxt, const char *ppvalue)
int	berValidateIso8601TimeStr (OSCTXT pctxt, const char *ppvalue)
int	xu_verify_len (OSOCTET *msg_p)
void *	xu_parse_mmbuf (OSOCTET *buf_p2, int buflen_p, OSOCTET *start_p, int bufsiz)
void	xu_alloc_array (OSCTXT pctxt, ASN1SeqOf seqOf_p, int recSize, int recCount)
void	xu_octscpy_s (OSUINT32 nocts_p, OSOCTET data_p, char *cstr, char zterm)
void	xu_octscpy_ss (ASN1OctStr octStr_p, char cstring, char zterm)
void	xu_octscpy_d (OSCTXT pctxt, OSUINT32 nocts_p, const OSOCTET *data_p2, char cstring, char zterm)
void	xu_octscpy_ds (OSCTXT pctxt, ASN1DynOctStr octStr_p, char *cstring, char zterm)
void	xu_octmcpy_s (ASN1OctStr octStr_p, void data_p, int datalen)
void	xu_octmcpy_d (OSCTXT pctxt, ASN1DynOctStr octStr_p, void *data_p, int datalen)
char *	xu_fetchstr (int numocts, char *data)
int	xu_hexstrcpy (char data, char hstring)
int	xu_binstrcpy (char data, char bstring)
int	xu_dump (const OSOCTET msgptr, ASN1DumpCbFunc cb, void cbArg_p)
int	xu_fdump (FILE file_p, const OSOCTET msgptr)
int	xu_dump2 (OSCTXT pctxt, const OSOCTET msgptr)
void	xu_fmt_tag (ASN1TAG tag_p, char class_p, char form_p, char id_code)
char *	xu_fmt_tag2 (ASN1TAG tag_p, char bufp)
char *	xu_fmt_contents (OSCTXT pctxt, int len, int count)
int	xu_fread (FILE fp, OSOCTET bufp, int bufsiz)
void	xu_SaveBufferState (OSCTXT pCtxt, OSRTBufSave pSavedInfo)
void	xu_RestoreBufferState (OSCTXT pCtxt, OSRTBufSave pSavedInfo)
int	berReadMsgFromSocket (OSCTXT pctxt, OSRTSOCKET socket, OSOCTET buffer, int bufsiz, OSOCTET *ppDestBuffer, int pMessageSize)

Detailed Description

BER/DER utility functions are provided for memory management, formatting output of ASN.1 messages, and error reporting. In many cases, these functions are closely coupled with the rt (runtime) series of common functions. The common functions provide common functionality shared between the BER/DER, PER, and XER runtime libraries. In many cases, these functions simply provide wrappers to the rt functions to maintain compatibility with existing versions of the ASN1C compiler.

Define Documentation

#define xu_hex_dump	(	msg,
		numoct,
		hdr	)	rtxHexDump(msg,numoct)

This function dumps binary data in raw hexadecimal and character text formats. It can be used only to examine runtime library encode/decode functions input or output data. This function outputs data only to the standard output device.

This function is considered depreciated and is only being maintained to provide backward compatibility with older versions of ASN1C.

Parameters:

	msg	A pointer to the start of the block of memory to be dumped.
	numoct	The number of octets (bytes) to be dumped.
	hdr	A Boolean variable indicating whether or not a head line should be dumped as the first line of the display.

Function Documentation

int berDefToIndefLen	(	OSCTXT *	pSrcCtxt,
		OSCTXT *	pDstCtxt
	)

This function converts BER encoded message with definite form of length to BER encoded message with indefinite form of length.

Parameters:

	pSrcCtxt	A pointer to a source OSCTXT structure.
	pDstCtxt	A pointer to a destination OSCTXT structure.

Returns:: Status of the conversion operation. Possible values are 0 if conversion is successful or one of the negative status codes.

OSBOOL berErrAddTagParm	(	OSCTXT *	pctxt,
		ASN1TAG	tag
	)

This function adds a tag parameter to the context error structure.

Parameters:

	pctxt	Pointer to a context structure.
	tag	The tag to add.

Returns:: Pointer to the text string (buffer).

int berErrUnexpTag	(	OSCTXT *	pctxt,
		ASN1TAG	exptag
	)

This function logs a BER unexpected tag error (IDNOTFOU) by adding the expected and parsed tag to the error context and returning the error status.

Parameters:

	pctxt	Pointer to a context structure.
	exptag	Expected tag.

Returns:: RTERR_IDNOTFOU status code.

const char* berGetLibInfo ( OSVOIDARG )

This function returns a string that describes the features of the BER runtime library. Different release kits will return different strings. An example would be "ASN1BER v6.1.1, opt, compact, limited."

int berGetLibVersion ( OSVOIDARG )

This function returns an integer representation of the BER library version.

int berIndefToDefLen	(	OSCTXT *	pSrcCtxt,
		OSCTXT *	pDstCtxt
	)

This function converts BER encoded message with indefinite form of length to BER encoded message with definite form of length.

Parameters:

	pSrcCtxt	A pointer to a source OSCTXT structure.
	pDstCtxt	A pointer to a destination OSCTXT structure.

Returns:: Status of the conversion operation. Possible values are 0 if conversion is successful or one of the negative status codes.

int berParseTagLen	(	const OSOCTET *	buffer,
		size_t	bufidx,
		size_t	bufsiz,
		ASN1TAG *	ptag,
		size_t *	plen
	)

This function parses a tag and length value starting at the given buffer pointer location. This is assumed to be pointing at the beginning of a TLV. It is similar to xd_tag_len, except it does not require an initialized context to work. This makes it a better alternative in terms of performance when it is only necessary to get tag and length info without having to do full decoding.

Parameters:

	buffer	Pointer to buffer containing BER-encoded data to parse.
	bufidx	Index within buffer that parsing is to begin. It is expected that buffer[bufidx] is pointing at the start of a TLV (tag-length-value).
	bufsiz	Size of the BER-encoded message.
	ptag	Pointer to tag variable to receive parsed tag value.
	plen	Pointer to length variable to receive parsed length.

Returns:: Pointer to the text string (buffer).

int berReadMsgFromSocket	(	OSCTXT *	pctxt,
		OSRTSOCKET	socket,
		OSOCTET *	buffer,
		int	bufsiz,
		OSOCTET **	ppDestBuffer,
		int *	pMessageSize
	)

This routine reads the BER message into the given buffer. The TLV can be of indefinite length. If buffer is NULL, dynamic buffer will be allocated and returned as ppDestBuffer. Length of the message will be returned in pMessageSize.

Parameters:

	pctxt	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.
	socket	The socket to read from. It should be already connected TCP socket.
	buffer	The static buffer to receive the parsed data. Can be NULL.
	bufsiz	The size of the buffer to receive the parsed data. Should be 0, if `buffer` is NULL.
	ppDestBuffer	The pointer to receive the destination buffer pointer. If `buffer` is static, this parameter can be NULL.
	pMessageSize	The pointer to integer to receive the size of read message.

Returns:

Completion status of operation:

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

const char* berTagToDynStr	(	OSCTXT *	pctxt,
		ASN1TAG	tag
	)

This function converts an internal binary ASN.1 tag to a string in standard ASN.1 syntax form. This version creates a dynamic string by allocating memory using the rtxMemAlloc function. This memory will be release when context memory is freed.

Parameters:

	pctxt	Pointer to a context structure.
	tag	The tag to convert.

Returns:: Pointer to dynamic text string.

const char* berTagToString	(	ASN1TAG	tag,
		char *	buffer,
		size_t	bufsiz
	)

This function converts an internal binary ASN.1 tag to a string in standard ASN.1 syntax form.

Parameters:

	tag	The tag to convert.
	buffer	Text buffer into which the string will be written.
	bufsiz	Size of the text buffer.

Returns:: Pointer to the text string (buffer).

int berValidateIso8601DateStr	(	OSCTXT *	pctxt,
		const char **	ppvalue
	)

This function will validate that an ASN.1 ISO 8601 Date character string is in a proper format. This method is used for both buffer and stream encoding.

Parameters:

	pctxt	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.
	ppvalue	A pointer to a null-terminated C character string to be validated. Note the string will be modified.

Returns:: Status of the validation attempt. A negative status value will be returned if validation is not successful.

int berValidateIso8601DurationStr	(	OSCTXT *	pctxt,
		const char **	ppvalue
	)

This function will validate that an ASN.1 ISO 8601 Duration character string is in a proper format. This method is used for both buffer and stream encoding.

Parameters:

	pctxt	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.
	ppvalue	A pointer to a null-terminated C character string to be validated. Note the string will be modified.

Returns:: Status of the validation attempt. A negative status value will be returned if validation is not successful.

int berValidateIso8601TimeStr	(	OSCTXT *	pctxt,
		const char **	ppvalue
	)

This function will validate that an ASN.1 ISO 8601 Time character string is in a proper format. This method is used for both buffer and stream encoding.

Parameters:

	pctxt	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.
	ppvalue	A pointer to a null-terminated C character string to be validated. Note the string will be modified.

Returns:: Status of the validation attempt. A negative status value will be returned if validation is not successful.

void xu_alloc_array	(	OSCTXT *	pctxt,
		ASN1SeqOf *	seqOf_p,
		int	recSize,
		int	recCount
	)

This function will allocate space for a given count of fixed size elements.

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.
	seqOf_p	A pointer to a generic sequence of structure variables to receive the returned memory. This structure contains a record count and a data pointer element. The record count is populated with the recCount passed into the function. The data pointer is set to the value that is returned from the memory allocation function.
	recSize	The number of bytes in one record in the array.
	recCount	The number of records to allocate. A pointer to a generic sequence of structure variable to receive the returned memory. This structure contains a record count and data pointer element. The record count is populated with the recCount passed into the function. The data pointer is set to the value that is returned from the memory allocation function.

int xu_dump	(	const OSOCTET *	msgptr,
		ASN1DumpCbFunc	cb,
		void *	cbArg_p
	)

This function dumps an encoded ASN.1 message to the standard output device or to another interface in a formatted display. The display includes, for each message component, message tag (class, form, and ID code) and data (in hexadecimal and character text formats).

This function is invoked for each line of text formatted from the given message. The formatted line is passed on the text_p argument. The cbArg_p argument allows a user to defined callback argument to be passed to the callback function. This argument is specified in the call to xu_dump.

Use of the callback function is optional. If dump to standard output (stdout) is desired, the argument should be specified as NULL (note: the macro XU_DUMP in rtxsrc/rtxCommon.h can be used for this purpose).

Parameters:

	*msgptr	A pointer to an encoded ASN.1 message.
	cb	Callback function that gets invoked for each line of formatted output. For a dump to standard output (stdout), this parameter can be specified as NULL.
	cbArg_p	Callback function argument will be passed to the callback function.

Returns:: Status of the dump operation. Possible values are 0 if decoding is successful or one of the negative status codes.

Referenced by ASN1BERMessageBuffer::binDump().

int xu_dump2	(	OSCTXT *	pctxt,
		const OSOCTET *	msgptr
	)

This function dumps an encoded ASN.1 message to the standard output device or to another interface in a formatted display. The display includes, for each message component, message tag (class, form, and ID code) and data (in hexadecimal and character text formats).

This function is invoked for each line of text formatted from the given message. If a print stream has been registered using the rtxSetPrintStream or rtxSetGlobalPrintStream functions, the output of xu_dump2 will be sent to the stream instead of standard output.

Parameters:

	*pctxt	A pointer to an OSCTXT structure.
	*msgptr	A pointer to an encoded ASN.1 message.

Returns:: Status of the dump operation. Possible values are 0 if decoding is successful or one of the negative status codes.

See also:: rtxSetPrintStream; rtxSetGlobalPrintStream

int xu_fdump	(	FILE *	file_p,
		const OSOCTET *	msgptr
	)

This function dumps an encoded ASN.1 message to a text file. The display includes, for each message component, message tag (class, form, and ID code), length, and data (in hexadecimal and character text formats).

Parameters:

	*file_p	A text file pointer.
	*msgptr	A pointer to an encoded ASN.1 message buffer.

Returns:: Status of the dump operation. Possible values are 0 if decoding is successful or one of the negative status codes.

void xu_RestoreBufferState	(	OSCTXT *	pCtxt,
		OSRTBufSave *	pSavedInfo
	)

This function is used to restore the current buffer state from previously saved info.

Parameters:

	pCtxt	- A pointer to a context structure.
	pSavedInfo	- A pointer to a structure holding the saved info.

void xu_SaveBufferState	(	OSCTXT *	pCtxt,
		OSRTBufSave *	pSavedInfo
	)

This function is used to save the current buffer state.

Parameters:

	pCtxt	- A pointer to a context structure.
	pSavedInfo	- A pointer to a structure to hold the saved info.

BER/PER C Utility Functions [BER Runtime Library Functions.]

Defines

Functions

Detailed Description

Define Documentation

Function Documentation

BER/PER C Utility Functions
[BER Runtime Library Functions.]