Home > Support > Documentation

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  OSRTErrInfoList
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...
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 OSRTERRSTKSIZ   8
#define OSRTMAXERRPRM   5
#define OSDIAG   0x80000000
#define OSTRACE   0x40000000
#define OSDISSTRM   0x20000000
#define OSSAVEBUF   0x10000000
#define OSNOSTRMBACKOFF   0x8000000
#define OSRT_GET_FIRST_ERROR_INFO(pctxt)
#define OSRT_GET_LAST_ERROR_INFO(pctxt)
#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.

Typedefs

typedef OSUINT32 OSRTFLAGS
typedef int(* OSFreeCtxtAppInfoPtr )(OSCTXT *pctxt)
typedef int(* OSResetCtxtAppInfoPtr )(OSCTXT *pctxt)

Functions

EXTERNRT int rtxInitContext (OSCTXT *pctxt)
 This function initializes an OSCTXT block.
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 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.

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.

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 287 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 277 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 343 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 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.