Home > Support > Documentation

EXI runtime library functions.


Files

file  osrtexi.h
 EXI low-level C context and structure definitions.

Classes

struct  OSEXICtxtInfo
struct  OSEXIHeader
struct  OSEXIStateEvent
 This structure holds state/event information. More...
struct  OSEXIAutomaton
 This structure defines a finite state automata for EXI grammars. More...
struct  OSEXIAtmState
 This structure defines state information from an automaton that must be preserved at each stack level. More...

Defines

#define OSEXINULLINDEX   OSUINT32_MAX
#define OSEXI_PRESERVE_DTD   0x80000000
#define OSEXI_PRESERVE_PIS   0x40000000
#define OSEXI_PRESERVE_COMMENTS   0x20000000
#define OSEXI_PRESERVE_PREFIXES   0x10000000
#define OSEXI_PRESERVE_LEXICAL   0x08000000
#define OSEXI_FRAGMENT   0x04000000
#define OSEXI_COMPRESSED   0x02000000
#define OSEXI_ALIGNED   0x01000000
#define OSEXI_PRECOMPRESSED   0x00800000
#define OSEXI_SCHEMA   0x00400000
#define EXICTXT(pctxt)   ((OSEXICtxtInfo*)((pctxt)->pEXIInfo))
#define rtEXISetBufPtr(pctxt, bufaddr, bufsiz)   rtxCtxtSetBufPtr (pctxt, bufaddr, bufsiz)
 This function is used to set the internal buffer within the run-time library context.
#define rtEXIGetMsgPtr(pctxt)   (pctxt)->buffer.data
 This macro returns the start address of the encoded EXI message.
#define rtEXIGetMsgLen(pctxt)   (pctxt)->buffer.byteIndex
 This macro returns the length of the encoded XML message.
#define rtEXISetOption(pctxt, option)   EXICTXT(pctxt)->options |= option;
 This macro is used to set a bit flag in the EXI options bit mask.
#define rtEXIClearOption(pctxt, option)   EXICTXT(pctxt)->options &= ~option;
 This macro is used to clear a bit flag in the EXI options bit mask.
#define rtEXITestOption(pctxt, option)   ((EXICTXT(pctxt)->options & option) != 0)
 This macro tests if the given option is set in the EXI context.

Typedefs

typedef OSINT16 OSEXIState
typedef int(* OSEXIAtmAddTransFunc )(OSCTXT *pctxt, OSEXIAutomaton *pAutomaton, OSEXIState fromState, OSEXIState toState, const OSEXIEvent *pEvent, const OSEXIEventCode *pEventCode)
 Add transition function definition.

Enumerations

enum  OSEXIAtmType

Functions

EXTERNEXI int rtEXIInitContext (OSCTXT *pctxt)
 This function initializes a context variable for EXI encoding or decoding.
EXTERNEXI int rtEXIInitCtxtAppInfo (OSCTXT *pctxt)
 This function initializes the EXI application info section of the given context.
EXTERNEXI void rtEXIEnableBitFieldTrace (OSCTXT *pctxt)
 This function turns on bit field tracing and initializes the bit field trace list.
EXTERNEXI void rtEXIAutomatonInit (OSCTXT *pctxt, OSEXIAutomaton *pAutomaton, const OSXMLFullQName *pElemName, OSEXIState numStates)
 This function initializes the automaton to its default state.
EXTERNEXI OSEXIAutomaton * rtEXINewAutomaton (OSCTXT *pctxt, const OSXMLFullQName *pElemName, OSEXIState numStates)
 This function allocates memory for a new automaton structure and initializes the structure.
EXTERNEXI OSEXIAutomaton * rtEXIAutomatonCopy (OSCTXT *pctxt, OSEXIAutomaton *pAutomaton)
 This function copies an automaton structure.
EXTERNEXI void rtEXIAutomatonFreeMem (OSCTXT *pctxt, OSEXIAutomaton *pAutomaton, OSBOOL dynamic)
 This function frees all memory within an Automaton structure.
EXTERNEXI OSEXIAutomaton * rtEXIAutomatonAddTransition (OSCTXT *pctxt, OSEXIAutomaton *pAutomaton, OSEXIState fromState, OSEXIState toState, const OSEXIEventCode *pEventCode)
 This function adds a transition between two states.
EXTERNEXI int rtEXIAtmAddUndeclaredItems (OSCTXT *pctxt, OSEXIAutomaton *pAutomaton, OSEXIState fromState, OSEXIState toState, OSEXIEventCode *pEventCode, size_t numDeclAttrs, const OSXMLFullQName *declAttrs, OSEXIAtmAddTransFunc addTransFunc)
 This function adds all undeclared items (end element, start tag, and content) to an element automaton in schema-informed mode.
EXTERNEXI int rtEXIAtmAddUndeclaredStartTagItems (OSCTXT *pctxt, OSEXIAutomaton *pAutomaton, OSEXIState fromState, OSEXIState toState, OSEXIEventCode *pEventCode, size_t numDeclAttrs, const OSXMLFullQName *declAttrs, OSEXIAtmAddTransFunc addTransFunc)
 This function adds undeclared start tag items to an element automaton in schema-informed mode.
EXTERNEXI int rtEXIAtmAddUndeclaredContentItems (OSCTXT *pctxt, OSEXIAutomaton *pAutomaton, OSEXIState fromState, OSEXIState toState, OSEXIEventCode *pEventCode, OSEXIAtmAddTransFunc addTransFunc)
 This function adds undeclared content items to an element automaton in schema-informed mode.
EXTERNEXI OSEXIAutomaton * rtEXIAutomatonInitCopy (OSCTXT *pctxt, OSEXIAutomaton *pDestAtm, OSEXIAutomaton *pSrcAtm)
 This function initializes an automaton structure using the data from an existing automaton.
EXTERNEXI int rtEXIAutomatonPush (OSCTXT *pctxt, OSEXIAutomaton *pAutomaton)
 This function pushes an automaton onto the context stack.
EXTERNEXI OSEXIAutomaton * rtEXIAutomatonPop (OSCTXT *pctxt)
 This function pops an automaton from the context stack.
EXTERNEXI OSEXIEventCodeGroup * rtEXIAtmGetCurrentEventCodeGroup (OSEXIAutomaton *pAutomaton)
 This function returns a pointer to the event code group corresponding to the current state.
EXTERNEXI OSEXIAutomaton * rtEXIGetDocAutomaton (OSCTXT *pctxt, size_t numGblElems, const OSXMLFullQName *gblElems, OSEXIAtmAddTransFunc addTransFunc)
 This functions returns an automaton that accepts the built-in document grammar.
EXTERNEXI OSEXIAutomaton * rtEXIGetElemAutomaton (OSCTXT *pctxt, OSXMLFullQName *pqname, int(*addTransFunc)(OSCTXT *pctxt, OSEXIAutomaton *pAutomaton, OSEXIState fromState, OSEXIState toState, const OSEXIEvent *pEvent, const OSEXIEventCode *pEventCode))
 This function returns an automaton that accepts the built-in element grammar.

Define Documentation

#define rtEXIClearOption (  pctxt,
option   )     EXICTXT(pctxt)->options &= ~option;
 

This macro is used to clear a bit flag in the EXI options bit mask.

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.
option Option bit mask value as defined earlier in this header file (for example, OSEXI_PRESERVE_DTD).

Definition at line 252 of file osrtexi.h.

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

This macro returns the length of the encoded XML message.

Parameters:
pctxt Pointer to a context structure.

Definition at line 225 of file osrtexi.h.

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

This macro returns the start address of the encoded EXI 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.

Parameters:
pctxt Pointer to a context structure.

Definition at line 218 of file osrtexi.h.

#define rtEXISetBufPtr (  pctxt,
bufaddr,
bufsiz   )     rtxCtxtSetBufPtr (pctxt, bufaddr, bufsiz)
 

This function is used to set the internal buffer within the run-time library context.

It must be called after the context variable is initialized by the rtEXIInitContext function and 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. 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).

Definition at line 207 of file osrtexi.h.

#define rtEXISetOption (  pctxt,
option   )     EXICTXT(pctxt)->options |= option;
 

This macro is used to set a bit flag in the EXI options bit mask.

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.
option Option bit mask value as defined earlier in this header file (for example, OSEXI_PRESERVE_DTD).

Definition at line 238 of file osrtexi.h.

#define rtEXITestOption (  pctxt,
option   )     ((EXICTXT(pctxt)->options & option) != 0)
 

This macro tests if the given option is set in the EXI context.

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.
option Option bit mask value as defined earlier in this header file (for example, OSEXI_PRESERVE_DTD).
Returns:
True if set, false if not.

Definition at line 268 of file osrtexi.h.

Function Documentation

EXTERNEXI int rtEXIAtmAddUndeclaredContentItems (  OSCTXT *  pctxt,
OSEXIAutomaton *  pAutomaton,
OSEXIState  fromState,
OSEXIState  toState,
OSEXIEventCode *  pEventCode,
OSEXIAtmAddTransFunc  addTransFunc
) 
 

This function adds undeclared content items to an element automaton in schema-informed mode.

Parameters:
pctxt Pointer to context block structure.
pAutomaton Pointer to automaton structure.
fromState The origin state for this transition.
toState The destination state for this transition.
pEventCode Pointer to event code structure that contains the current state of assigned events in the grammar.
Returns:
Status of operation: 0 if successful; otherwise, a negative return code.

EXTERNEXI int rtEXIAtmAddUndeclaredItems (  OSCTXT *  pctxt,
OSEXIAutomaton *  pAutomaton,
OSEXIState  fromState,
OSEXIState  toState,
OSEXIEventCode *  pEventCode,
size_t  numDeclAttrs,
const OSXMLFullQName *  declAttrs,
OSEXIAtmAddTransFunc  addTransFunc
) 
 

This function adds all undeclared items (end element, start tag, and content) to an element automaton in schema-informed mode.

Parameters:
pctxt Pointer to context block structure.
pAutomaton Pointer to automaton structure.
fromState The origin state for this transition.
toState The destination state for this transition.
pEventCode Pointer to event code structure that contains the current state of assigned events in the grammar.
numDeclAttrs Number of items in declAttrs array.
declAttrs Array of declared attribute QNames. These are attributes that were declared in the schema but which are not valid within the current context.
Returns:
Status of operation: 0 if successful; otherwise, a negative return code.

EXTERNEXI int rtEXIAtmAddUndeclaredStartTagItems (  OSCTXT *  pctxt,
OSEXIAutomaton *  pAutomaton,
OSEXIState  fromState,
OSEXIState  toState,
OSEXIEventCode *  pEventCode,
size_t  numDeclAttrs,
const OSXMLFullQName *  declAttrs,
OSEXIAtmAddTransFunc  addTransFunc
) 
 

This function adds undeclared start tag items to an element automaton in schema-informed mode.

Parameters:
pctxt Pointer to context block structure.
pAutomaton Pointer to automaton structure.
fromState The origin state for this transition.
toState The destination state for this transition.
pEventCode Pointer to event code structure that contains the current state of assigned events in the grammar.
numDeclAttrs Number of items in declAttrs array.
declAttrs Array of declared attribute QNames. These are attributes that were declared in the schema but which are not valid within the current context.
Returns:
Status of operation: 0 if successful; otherwise, a negative return code.

EXTERNEXI OSEXIEventCodeGroup* rtEXIAtmGetCurrentEventCodeGroup (  OSEXIAutomaton *  pAutomaton  ) 
 

This function returns a pointer to the event code group corresponding to the current state.

Parameters:
pAutomaton Pointer to automaton structure.
Returns:
Pointer to event group group.

EXTERNEXI OSEXIAutomaton* rtEXIAutomatonAddTransition (  OSCTXT *  pctxt,
OSEXIAutomaton *  pAutomaton,
OSEXIState  fromState,
OSEXIState  toState,
const OSEXIEventCode *  pEventCode
) 
 

This function adds a transition between two states.

The transition is defined by a pair of states, and event and event code.

Parameters:
pctxt Pointer to context block structure.
pAutomaton Pointer to automaton structure.
fromState The origin state for this transition.
toState The destination state for this transition.
pEventCode The event code returned after the transition.

EXTERNEXI OSEXIAutomaton* rtEXIAutomatonCopy (  OSCTXT *  pctxt,
OSEXIAutomaton *  pAutomaton
) 
 

This function copies an automaton structure.

If the structure is closed, a shallow copy is done; otherwise, a deep copy.

Parameters:
pctxt Pointer to context block structure.
pAutomaton Pointer to automaton structure to copy.
Returns:
Copied automaton structure.

EXTERNEXI void rtEXIAutomatonFreeMem (  OSCTXT *  pctxt,
OSEXIAutomaton *  pAutomaton,
OSBOOL  dynamic
) 
 

This function frees all memory within an Automaton structure.

Parameters:
pctxt Pointer to a context structure.
pAutomaton Pointer to object in which memory will be freed.
dynamic Boolean indicating if pAutomaton is dynamic. If true, the memory for pAutomaton is freed.

EXTERNEXI void rtEXIAutomatonInit (  OSCTXT *  pctxt,
OSEXIAutomaton *  pAutomaton,
const OSXMLFullQName *  pElemName,
OSEXIState  numStates
) 
 

This function initializes the automaton to its default state.

Parameters:
pctxt Pointer to context block structure.
pAutomaton Pointer to automaton structure to initialize.
pElemName Pointer to element QName.
numStates Number of states (if known) or zero.

EXTERNEXI OSEXIAutomaton* rtEXIAutomatonInitCopy (  OSCTXT *  pctxt,
OSEXIAutomaton *  pDestAtm,
OSEXIAutomaton *  pSrcAtm
) 
 

This function initializes an automaton structure using the data from an existing automaton.

Parameters:
pctxt Pointer to context block structure.
pDestAtm Pointer to destination (target) automaton structure.
pSrcAtm Pointer to source automaton structure.
Returns:
Copied (destination) automaton structure.

EXTERNEXI OSEXIAutomaton* rtEXIAutomatonPop (  OSCTXT *  pctxt  ) 
 

This function pops an automaton from the context stack.

Parameters:
pctxt Pointer to context block structure.
Returns:
Last automaton pushed on stack or NULL if stack empty or error.

EXTERNEXI int rtEXIAutomatonPush (  OSCTXT *  pctxt,
OSEXIAutomaton *  pAutomaton
) 
 

This function pushes an automaton onto the context stack.

Parameters:
pctxt Pointer to context block structure.
pAutomaton Automaton to be pushed onto stack.
Returns:
Status of operation: 0 = success, negative = error.

EXTERNEXI void rtEXIEnableBitFieldTrace (  OSCTXT *  pctxt  ) 
 

This function turns on bit field tracing and initializes the bit field trace list.

Parameters:
pctxt Pointer to OSCTXT structure

EXTERNEXI OSEXIAutomaton* rtEXIGetDocAutomaton (  OSCTXT *  pctxt,
size_t  numGblElems,
const OSXMLFullQName *  gblElems,
OSEXIAtmAddTransFunc  addTransFunc
) 
 

This functions returns an automaton that accepts the built-in document grammar.

This grammar is not extensible, so all the event codes created are immutable.

Parameters:
pctxt Pointer to context block structure.
numGblElems Number of global elements.
gblElems Array of global element objects.
addTransFunc Pointer to function to add a transition.
Returns:
Pointer to document automaton.

EXTERNEXI OSEXIAutomaton* rtEXIGetElemAutomaton (  OSCTXT *  pctxt,
OSXMLFullQName *  pqname,
int(*)(OSCTXT *pctxt, OSEXIAutomaton *pAutomaton, OSEXIState fromState, OSEXIState toState, const OSEXIEvent *pEvent, const OSEXIEventCode *pEventCode)  addTransFunc
) 
 

This function returns an automaton that accepts the built-in element grammar.

The elementName is associated with the automaton.

Parameters:
pctxt Pointer to context block structure.
pqname Pointer to element QName.
addTransFunc Pointer to function to add a transition.
Returns:
Pointer to element automaton.

EXTERNEXI int rtEXIInitContext (  OSCTXT *  pctxt  ) 
 

This function initializes a context variable for EXI encoding or decoding.

Parameters:
pctxt Pointer to OSCTXT structure
Returns:
Completion status of operation:
  • 0 = success,
  • negative return value is error.

EXTERNEXI int rtEXIInitCtxtAppInfo (  OSCTXT *  pctxt  ) 
 

This function initializes the EXI application info section of the given context.

Parameters:
pctxt Pointer to OSCTXT structure
Returns:
Completion status of operation:
  • 0 = success,
  • negative return value is error.

EXTERNEXI OSEXIAutomaton* rtEXINewAutomaton (  OSCTXT *  pctxt,
const OSXMLFullQName *  pElemName,
OSEXIState  numStates
) 
 

This function allocates memory for a new automaton structure and initializes the structure.

Parameters:
pctxt Pointer to context block structure.
pElemName Pointer to element QName.
numStates Number of states (if known) or zero.
Returns:
Allocated automaton structure or NULL if no dynamic memory available.