Context Management Functions

Context initialization functions handle the allocation, initialization, and destruction of context variables (variables of type OSCTXT). More...


Classes
struct	OSRTErrLocn
	Run-time error location structure. More...
struct	OSRTErrInfo
	Run-time error information structure. More...
struct	OSRTBuffer
	Run-time message buffer structure. More...
struct	OSRTBufSave
	Structure to save the current message buffer state. More...
struct	OSCTXT
	Run-time context structure. More...
Defines
#define	rtxCtxtGetMsgPtr(pctxt) (pctxt)->buffer.data
	This macro returns the start address of an encoded message.
#define	rtxCtxtGetMsgLen(pctxt) (pctxt)->buffer.byteIndex
	This macro returns the length of an encoded message.
#define	rtxCtxtTestFlag(pctxt, mask) ((pctxt->flags & mask) != 0)
	This macro tests if the given bit flag is set in the context.
#define	rtxByteAlign(pctxt)
	This macro will byte-align the context buffer.
Functions
EXTERNRT int	rtxInitContextUsingKey (OSCTXT pctxt, const OSOCTET key, size_t keylen)
	This function initializes a context using a run-time key.
EXTERNRT int	rtxInitContext (OSCTXT *pctxt)
	This function initializes an OSCTXT block.
EXTERNRT int	rtxInitContextExt (OSCTXT *pctxt, OSMallocFunc malloc_func, OSReallocFunc realloc_func, OSFreeFunc free_func)
	This function initializes an OSCTXT block.
EXTERNRT int	rtxInitThreadContext (OSCTXT pctxt, const OSCTXT pSrcCtxt)
	This function initializes a context for use in a thread.
EXTERNRT int	rtxInitContextBuffer (OSCTXT pctxt, OSOCTET bufaddr, size_t bufsiz)
	This function assigns a message buffer to a context block.
EXTERNRT int	rtxCtxtSetBufPtr (OSCTXT pctxt, OSOCTET bufaddr, size_t bufsiz)
	This function is used to set the internal buffer pointer for in-memory encoding or decoding.
EXTERNRT size_t	rtxCtxtGetIOByteCount (OSCTXT *pctxt)
	This function returns the count of bytes either written to a stream or memory buffer.
EXTERNRT int	rtxCheckContext (OSCTXT *pctxt)
	This function verifies that the given context structure is initialized and ready for use.
EXTERNRT void	rtxFreeContext (OSCTXT *pctxt)
	This function frees all dynamic memory associated with a context.
EXTERNRT void	rtxCtxtSetFlag (OSCTXT *pctxt, OSUINT32 mask)
	This function is used to set a processing flag within the context structure.
EXTERNRT void	rtxCtxtClearFlag (OSCTXT *pctxt, OSUINT32 mask)
	This function is used to clear a processing flag within the context structure.
EXTERNRT int	rtxCtxtPushElemName (OSCTXT pctxt, const OSUTF8CHAR elemName)
	This function is used to push an element name onto the context element name stack.
EXTERNRT const OSUTF8CHAR *	rtxCtxtPopElemName (OSCTXT *pctxt)
	This function pops the last element name from the context stack.

Detailed Description

Context initialization functions handle the allocation, initialization, and destruction of context variables (variables of type OSCTXT).

These variables hold all of the working data used during the process of encoding or decoding a message. The context provides thread safe operation by isolating what would otherwise be global variables within this structure. The context variable is passed from function to function as a message is encoded or decoded and maintains state information on the encoding or decoding process.

Define Documentation

#define rtxCtxtGetMsgLen ( pctxt ) (pctxt)->buffer.byteIndex

This macro returns the length of an encoded message.

It will only work for in-memory encoding, not for encode to stream.

Note that this macro will not work with ASN.1 BER in-memory encoding. In this case, the BER-specific version of the function must be used.

Parameters:

pctxt

Pointer to a context structure.

Definition at line 377 of file rtxContext.h.

#define rtxCtxtGetMsgPtr ( pctxt ) (pctxt)->buffer.data

This macro returns the start address of an encoded message.

If a static buffer was used, this is simply the start address of the buffer. If dynamic encoding was done, this will return the start address of the dynamic buffer allocated by the encoder.

Note that this macro will not work with ASN.1 BER in-memory encoding. In this case, the BER-specific version of the function must be used.

Parameters:

pctxt

Pointer to a context structure.

Definition at line 366 of file rtxContext.h.

#define rtxCtxtTestFlag	(	pctxt,
		mask		)	((pctxt->flags & mask) != 0)

This macro tests if the given bit flag is set in the context.

Parameters:

	pctxt	- A pointer to a context structure.
	mask	- Bit flag to be tested

Definition at line 442 of file rtxContext.h.

Function Documentation

EXTERNRT int rtxCheckContext ( OSCTXT * pctxt )

This function verifies that the given context structure is initialized and ready for use.

Parameters:

pctxt

Pointer to a context structure.

Returns:

Completion status of operation:

0 = success,
RTERR_NOTINIT status code if not initialized

EXTERNRT void rtxCtxtClearFlag	(	OSCTXT *	pctxt,
		OSUINT32	mask
	)

This function is used to clear a processing flag within the context structure.

Parameters:

	pctxt	- A pointer to a context structure.
	mask	- Mask containing bit(s) to be cleared.

EXTERNRT size_t rtxCtxtGetIOByteCount ( OSCTXT * pctxt )

This function returns the count of bytes either written to a stream or memory buffer.

Parameters:

pctxt

Pointer to a context structure.

Returns:: I/O byte count.

EXTERNRT const OSUTF8CHAR* rtxCtxtPopElemName ( OSCTXT * pctxt )

This function pops the last element name from the context stack.

Parameters:

pctxt

Pointer to a context structure.

Returns:: Element name popped from stack or NULL if stack is empty.

EXTERNRT int rtxCtxtPushElemName	(	OSCTXT *	pctxt,
		const OSUTF8CHAR *	elemName
	)

This function is used to push an element name onto the context element name stack.

Parameters:

	pctxt	Pointer to a context structure.
	elemName	Name of element to be pushed on stack. Note that a copy of the name is not made, the pointer to the name that is passed is stored.

Returns:

Completion status of operation:

0 = success,
RTERR_NOMEM if mem alloc for name fails.

EXTERNRT int rtxCtxtSetBufPtr	(	OSCTXT *	pctxt,
		OSOCTET *	bufaddr,
		size_t	bufsiz
	)

This function is used to set the internal buffer pointer for in-memory encoding or decoding.

It must be called after the context variable is initialized before any other compiler generated or run-time library encode function.

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.
	bufaddr	A pointer to a memory buffer to use to encode a message or that holds a message to be decoded. The buffer should be declared as an array of unsigned characters (OCTETs). This parameter can be set to NULL to specify dynamic encoding (i.e., the encode functions will dynamically allocate a buffer to hold the encoded message).
	bufsiz	The length of the memory buffer in bytes. Should be set to zero if NULL was specified for bufaddr (i.e. dynamic encoding was selected).

EXTERNRT void rtxCtxtSetFlag	(	OSCTXT *	pctxt,
		OSUINT32	mask
	)

This function is used to set a processing flag within the context structure.

Parameters:

	pctxt	- A pointer to a context structure.
	mask	- Mask containing bit(s) to be set.

EXTERNRT void rtxFreeContext ( OSCTXT * pctxt )

This function frees all dynamic memory associated with a context.

This includes all memory allocated using the rtxMem functions using the given context parameter.

Parameters:

pctxt

Pointer to a context structure.

EXTERNRT int rtxInitContext ( OSCTXT * pctxt )

This function initializes an OSCTXT block.

It sets all key working parameters to their correct initial state values. It is required that this function be invoked before using a context variable.

Parameters:

pctxt

Pointer to the context structure variable to be initialized.

Returns:

Completion status of operation:

0 = success,
negative return value is error.

EXTERNRT int rtxInitContextBuffer	(	OSCTXT *	pctxt,
		OSOCTET *	bufaddr,
		size_t	bufsiz
	)

This function assigns a message buffer to a context block.

The block should have been previously initialized by rtxInitContext.

Parameters:

	pctxt	The pointer to the context structure variable to be initialized.
	bufaddr	For encoding, the address of a memory buffer to receive the encoded message. If this address is NULL (0), encoding to a dynamic buffer will be done. For decoding, the address of a buffer that contains the message data to be decoded.
	bufsiz	The size of the memory buffer. For encoding, this argument may be set to zero to indicate a dynamic memory buffer should be used.

Returns:

Completion status of operation:

0 = success,
negative return value is error.

EXTERNRT int rtxInitContextExt	(	OSCTXT *	pctxt,
		OSMallocFunc	malloc_func,
		OSReallocFunc	realloc_func,
		OSFreeFunc	free_func
	)

This function initializes an OSCTXT block.

It sets all key working parameters to their correct initial state values. It is required that this function be invoked before using a context variable.

Parameters:

	pctxt	Pointer to the context structure variable to be initialized.
	malloc_func	Pointer to the memory allocation function.
	realloc_func	Pointer to the memory reallocation function.
	free_func	Pointer to the memory deallocation function.

Returns:

Completion status of operation:

0 = success,
negative return value is error.

EXTERNRT int rtxInitContextUsingKey	(	OSCTXT *	pctxt,
		const OSOCTET *	key,
		size_t	keylen
	)

This function initializes a context using a run-time key.

This form is required for evaluation and limited distribution software. The compiler will generate a macro for rtxInitContext in the rtkey.h file that will invoke this function with the generated run-time key.

Parameters:

	pctxt	The pointer to the context structure variable to be initialized.
	key	Key data generated by ASN1C compiler.
	keylen	Key data field length.

Returns:

Completion status of operation:

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

EXTERNRT int rtxInitThreadContext	(	OSCTXT *	pctxt,
		const OSCTXT *	pSrcCtxt
	)

This function initializes a context for use in a thread.

It is the same as rtxInitContext except that it copies the pointer to constant data from the given source context into the newly initialized thread context. It is assumed that the source context has been initialized and the custom generated global initialization function has been called. The main purpose of this function is to prevent multiple copies of global static data from being created within different threads.

Parameters:

	pctxt	Pointer to the context structure variable to be initialized.
	pSrcCtxt	Pointer to source context which has been fully initialized including a pointer to global constant data initialized via a call to a generated 'Init_<project>_Global' function.

Returns:

Completion status of operation:

0 = success,
negative return value is error.

Context Management Functions

Classes

Defines

Functions

Detailed Description

Define Documentation

Function Documentation