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 EXICTXT(pctxt)   ((OSEXICtxtInfo*)((pctxt)->pEXIInfo))
#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

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 int rtEXISetBufPtr (OSCTXT *pctxt, OSOCTET *bufaddr, size_t bufsiz)
 This function is used to set the internal buffer within the run-time library context.
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 OSEXIAutomaton * rtEXIAutomatonAddTransition (OSCTXT *pctxt, OSEXIAutomaton *pAutomaton, OSEXIState fromState, OSEXIState toState, const OSEXIEventCode *pEventCode)
 This function adds a transition between two states.
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, int(*addTransFunc)(OSCTXT *pctxt, OSEXIAutomaton *pAutomaton, OSEXIState fromState, OSEXIState toState, const OSEXIEvent *pEvent, const OSEXIEventCode *pEventCode))
 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.

C EXI Runtime Library Functions

The C run-time EXI library contains functions used to encode/decode XML data in EXI format. These functions are identified by their rtEXI prefixes.

The categories of functions provided are as follows:

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 216 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 189 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 182 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 202 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 232 of file osrtexi.h.

Function Documentation

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 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 OSEXIAutomaton* rtEXIGetDocAutomaton (  OSCTXT *  pctxt,
int(*)(OSCTXT *pctxt, OSEXIAutomaton *pAutomaton, OSEXIState fromState, OSEXIState toState, const OSEXIEvent *pEvent, const OSEXIEventCode *pEventCode)  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.
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.

EXTERNEXI int rtEXISetBufPtr (  OSCTXT *  pctxt,
OSOCTET *  bufaddr,
size_t  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).