16 Package XSLTVM for XML C APIs

Package XSLTVM implements the XSL Transformation (XSLT) language for XML C APIs, as specified in W3C Recommendation 16 November 1999. For convenience, we grouped XSLTVM methods into two interface types.

XSLTC Interface of XSLTVM for XML C APIs

The following table summarizes the methods available through the XSLTC interface of XSLTVM for XML C APIs.

Table 16-1 Summary of XSLTC XSLTVM Methods for XML C Implementation

Function Summary

XmlXvmCompileBuffer()

Compile an XSLT stylesheet from buffer into bytecode.

XmlXvmCompileDom()

Compile an XSLT stylesheet from DOM into bytecode.

XmlXvmCompileFile()

Compile an XSLT stylesheet from file into bytecode.

XmlXvmCompileURI()

Compile XSLT stylesheet from URI into byte code.

XmlXvmCompileXPath()

Compile an XPath expression.

XmlXvmCreateComp()

Create an XSLT compiler.

XmlXvmDestroyComp()

Destroy an XSLT compiler object.

XmlXvmGetBytecodeLength()

Returns the bytecode length.

XmlXvmCompileBuffer()

Compile an XSLT stylesheet from buffer into bytecode. Compiler flags could be one or more of the following:

  • XMLXVM_DEBUG forces compiler to include debug information into the bytecode

  • XMLXVM_STRIPSPACE is equivalent to <xsl:strip-space elements="*"/>.

The generated bytecode resides in a compiler buffer which is freed when next stylesheet is compiled or when compiler object is deleted. Hence, if the bytecode is to be reused it should be copied into another location.

XmlXvmCompileDom()

Compile an XSLT stylesheet from DOM into bytecode. Compiler flags could be one or more of the following:

  • XMLXVM_DEBUG forces compiler to include debug information into the bytecode

  • XMLXVM_STRIPSPACE is equivalent to <xsl:strip-space elements="*"/>.

The generated bytecode resides in a compiler buffer which is freed when next stylesheet is compiled or when compiler object is deleted. Hence, if the bytecode is to be reused it should be copied into another location.

Syntax

ub2 *XmlXvmCompileDom(
   xmlxvmcomp *comp,
   xmldocnode *root,
   xmlxvmflag flags,
   xmlerr *error);
Parameter In/Out Description
comp
IN

compiler object

rooot
IN

root element of the stylesheet DOM

flags
IN

flags for the current compilation

error
OUT

returned error code

Returns

(ub2 *) bytecode or NULL on error

XmlXvmCompileFile()

Compile XSLT stylesheet from file into bytecode. Compiler flags could be one or more of the following:

  • XMLXVM_DEBUG forces compiler to include debug information into the bytecode

  • XMLXVM_STRIPSPACE is equivalent to <xsl:strip-space elements="*"/>.

The generated bytecode resides in a compiler buffer which is freed when next stylesheet is compiled or when compiler object is deleted. Hence, if the bytecode is to be reused it should be copied into another location.

Syntax

ub2 *XmlXvmCompileFile(
   xmlxvmcomp *comp, 
   oratext *path,
   oratext *baseURI,
   xmlxvmflag flags,
   xmlerr *error);
Parameter In/Out Description
comp
IN

compiler object

path
IN

path of XSL stylesheet file

baseuri
IN

base URI of the document

flags
IN

flags for the current compilation

error
OUT

returned error code

Returns

(ub2 *) bytecode or NULL on error

XmlXvmCompileURI()

Compile XSLT stylesheet from URI into bytecode. Compiler flags could be one or more of the following:

  • XMLXVM_DEBUG forces compiler to include debug information into the bytecode

  • XMLXVM_STRIPSPACE is equivalent to <xsl:strip-space elements="*"/>.

The generated bytecode resides in a compiler buffer which is freed when next stylesheet is compiled or when compiler object is deleted. Hence, if the bytecode is to be reused it should be copied into another location.

Syntax

ub2 *XmlXvmCompileURI(
   xmlxvmcomp *comp, 
   oratext *uri, 
   xmlxvmflag flags, 
   xmlerr *error);
Parameter In/Out Description
comp
IN

compiler object

uri
IN

URI of the file that contains the XSL stylesheet

flags
IN

flags for the current compilation

error
OUT

returned error code

Returns

(ub2 *) bytecode or NULL on error

XmlXvmCompileXPath()

Compiles an XPath expression. The optional pfxmap is used to map namespace prefixes to URIs in the XPath expression. It is an array of prefix, URI values, ending in NULL, and so on.

Syntax

ub2 *XmlXvmCompileXPath(
   xmlxvmcomp *comp, 
   oratext *xpath,
   oratext **pfxmap,
   xmlerr *error);
Parameter In/Out Description
comp
IN

compiler object

xpath
IN

XPath expression

pfxmap
IN

array of prefix-URI mappings

error
OUT

returned error code

Returns

(ub2 *) XPath expression bytecode or NULL on error

XmlXvmCreateComp()

Create an XSLT compiler object. The XSLT compiler is used to compile XSLT stylesheets into bytecode.

Syntax

xmlxvmcomp *XmlXvmCreateComp(
   xmlctx *xctx);
Parameter In/Out Description
xctx
IN

XML context

Returns

(xmlxvmcomp *) XSLT compiler object, or NULL on error

XmlXvmDestroyComp()

Destroys an XSLT compiler object

Syntax

void XmlXvmDestroyComp(
   xmlxvmcomp *comp);
Parameter In/Out Description
comp
IN

XSLT compiler object

See Also:

XmlXvmCreateComp()

XmlXvmGetBytecodeLength()

The bytecode length is needed when the bytecode is to be copied or when it is set into XSLTVM.

Syntax

ub4 XmlXvmGetBytecodeLength(
   ub2 *bytecode,
   xmlerr *error);
Parameter In/Out Description
bytecode
IN

bytecode buffer

error
OUT

returned error code

Returns

(ub4) The bytecode length in bytes.

XSLTVM Interface of XSLTVM for XML C APIs

The following table summarizes the methods available through the XSLTVM interface of XSLTVM for XML C APIs.

Table 16-2 Summary of XSLTVM XSLTVM Methods for XML C Implementation

Function Summary

XMLXVM_DEBUG_F()

XMLXSLTVM debug function.

XmlXvmCreate()

Create an XSLT virtual machine.

XmlXvmDestroy()

Destroys an XSLT virtual machine.

XmlXvmEvaluateXPath()

Evaluate already-compiled XPath expression.

XmlXvmGetObjectBoolean()

Get boolean value of XPath object.

XmlXvmGetObjectNSetNode()

Get node from nodeset type XPathobject.

XmlXvmGetObjectNSetNum()

Get number of nodes in nodeset type XPathobject.

XmlXvmGetObjectNumber()

Get number from XPath object.

XmlXvmGetObjectString()

Get string from XPath object.

XmlXvmGetObjectType()

Get XPath object type.

XmlXvmGetOutputDom()

Returns the output DOM.

XmlXvmResetParams()

Resets the stylesheet top level text parameters.

XmlXvmSetBaseURI()

Sets the base URI for the XLTVM.

XmlXvmSetBytecodeBuffer()

Set the compiled bytecode.

XmlXvmSetBytecodeFile()

Set the compiled byte code from file.

XmlXvmSetBytecodeURI()

Set the compiled bytecode.

XmlXvmSetDebugFunc()

Set a callback function for debugging.

XmlXvmSetOutputDom()

Sets the XSLTVM to output document node.

XmlXvmSetOutputEncoding()

Sets the encoding for the XSLTVM output.

XmlXvmSetOutputSax()

Sets XSLTVM to output SAX.

XmlXvmSetOutputStream()

Set the XSLTVM output to a user-defined stream.

XmlXvmSetTextParam()

Set the stylesheet top-level text parameter.

XmlXvmTransformBuffer()

Run compiled XSLT stylesheet on XML document in memory.

XmlXvmTransformDom()

Run compiled XSLT stylesheet on XML document as DOM.

XmlXvmTransformFile()

Run compiled XSLT stylesheet on XML document in file.

XmlXvmTransformURI()

Run compiled XSLT stylesheet on XML document from URI.

XMLXVM_DEBUG_F()

Debug callback function for XSLT VM.

Syntax

#define XMLXVM_DEBUG_F(func, line, file, obj, n)
void func(
   ub2 line,
   oratext *file,
   xvmobj *obj,
   ub4 n)
Parameter In/Out Description
line
IN

source stylesheet line number

file
IN

stylesheet filename

obj
IN

current VM object

n
IN

index of current node

XmlXvmCreate()

Create an XSLT virtual machine. Zero or more of the following XSLTVM properties could be set by using this API:

  • "VMStack", size sets the size[Kbyte] of the main VM stack; default size is 4K.

  • "NodeStack", size sets the size[Kbyte] of the node-stack; default size is 16K.

  • "StringStack", size sets the size[Kbyte] of the string-stack; default size is 64K.

If the stack size is not specified the default size is used. The explicit stack size setting is needed when XSLTVM terminates with "Stack Overflow" message or when smaller memory footprints are required.

Syntax

xmlxvm *XmlXvmCreate(
   xmlctx *xctx, 
   list);
Parameter In/Out Description
xctx
IN

XML context

list
IN

NULL-terminated list of properties to set; can be empty

Returns

(xmlxvm *) XSLT virtual machine object, or NULL on error

See Also:

XmlXvmDestroy()

XmlXvmDestroy()

Destroys an XSLT virtual machine

Syntax

void XmlXvmDestroy(
   xmlxvm *vm);
Parameter In/Out Description
vm
IN

VM object

See Also:

XmlXvmCreate()

XmlXvmEvaluateXPath()

Evaluate already-compiled XPath expression

Syntax

xvmobj *XmlXvmEvaluateXPath(
   xmlxvm *vm, 
   ub2 *bytecode, 
   ub4 ctxpos,
   ub4 ctxsize,
   xmlnode *ctxnode);
Parameter In/Out Description
vm
IN

XSLTVM object

bytecode
IN

XPath expression bytecode

ctxpos
IN

current context position

ctxsize
IN

current context size

ctxnode
IN

current context node

Returns

(xvmobj *) XPath object

XmlXvmGetObjectBoolean()

Get boolean value of XPath object

Syntax

boolean XmlXvmGetObjectBoolean(
   xvmobj *obj);
Parameter In/Out Description
obj
IN

object

Returns

XmlXvmGetObjectNSetNode()

Get node from nodeset-type XPath object

Syntax

xmlnode *XmlXvmGetObjectNSetNode(
   xvmobj *obj,
   ub4 i);
Parameter In/Out Description
obj
IN

object

i
IN

node index in nodeset

Returns

XmlXvmGetObjectNSetNum()

Get number of nodes in nodeset-type XPath object

Syntax

ub4 XmlXvmGetObjectNSetNum(
   xvmobj *obj);
Parameter In/Out Description
obj
IN

object

Returns

XmlXvmGetObjectNumber()

Get number from XPath object.

Syntax

double XmlXvmGetObjectNumber(
   xvmobj *obj);
Parameter In/Out Description
obj
IN

object

Returns

XmlXvmGetObjectString()

Get string from XPath object.

Syntax

oratext *XmlXvmGetObjectString(
   xvmobj *obj);
Parameter In/Out Description
obj
IN

object

Returns

XmlXvmGetObjectType()

Get XPath object type

Syntax

xmlxvmobjtype XmlXvmGetObjectType(
   xvmobj *obj);
Parameter In/Out Description
obj
IN

object

Returns

XmlXvmGetOutputDom()

Returns the root node of the result DOM tree (if any). XmlXvmSetOutputDom has to be used before transformation to set the VM to output a DOM tree (the default VM output is a stream).

Syntax

xmlfragnode *XmlXvmGetOutputDom(
   xmlxvm *vm);
Parameter In/Out Description
vm
IN

VM object

Returns

(xmlfragnode *) output DOM, or NULL in a case of SAX or Stream output.

XmlXvmResetParams()

Resets the stylesheet top-level parameters with their default values.

Syntax

void XmlXvmResetParams(
   xmlxvm *vm);
Parameter In/Out Description
vm
IN

VM object

XmlXvmSetBaseURI()

Sets the base URI for the XSLTVM. The baseuri is used by VM to the compose the path XML documents to be loaded for transformation using document or XmlXvmTransformFile.

Syntax

xmlerr XmlXvmSetBaseURI(
   xmlxvm *vm, 
   oratext *baseuri);
Parameter In/Out Description
vm
IN

VM object

baseuri
IN

VM base URI for reading and writing documents

Returns

(xmlerr) error code.

XmlXvmSetBytecodeBuffer()

Set the compiled bytecode from buffer. Any previously set bytecode is replaced. An XML transformation can't be performed if the stylesheet bytecode is not set. The VM doesn't copy the bytecode into internal buffer, hence the it shouldn't be freed before VM finishes using it.

Syntax

xmlerr XmlXvmSetBytecodeBuffer(
   xmlxvm *vm, 
   ub2 *buffer, 
   size_t buflen);
Parameter In/Out Description
vm
IN

XSLT VM context

buffer
IN

user's buffer

buflen
IN

size of buffer, in bytes

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

XmlXvmSetBytecodeFile()

Set the compiled bytecode from file. Any previously set bytecode is replaced. An XML transformation can't be performed if the stylesheet bytecode is not set.

Syntax

xmlerr XmlXvmSetBytecodeFile(
   xmlxvm *vm,
   oratext *path);
Parameter In/Out Description
vm
IN

XSLT VM context

path
IN

path of bytecode file

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

XmlXvmSetBytecodeURI()

Set the compiled bytecode from URI. Any previously set bytecode is replaced. An XML transformation can't be performed if the stylesheet bytecode is not set.

Syntax

xmlerr XmlXvmSetBytecodeURI(
   xmlxvm *vm,
   oratext *uri);
Parameter In/Out Description
vm
IN

XSLT VM context

uri
IN

path of bytecode file

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

XmlXvmSetDebugFunc()

The user callback function is invoked by VM every time the execution reaches a new line in the XSLT stylesheet. The VM passes to the user the stylesheet file name, the line number, the current context nodes-set and the current node index in the node-set. IMPORTANT - the stylesheet has to be compiled with flag XMLXVM_DEBUG.

Syntax

#define XMLXVM_DEBUG_FUNC(func)
void func (ub2 line, oratext *filename, xvmobj *obj, ub4 n)
xmlerr XmlXvmSetDebugFunc(
   xmlxvm *vm,
   XMLXVM_DEBUG_FUNC(debugcallback));
Parameter In/Out Description
vm
IN

XSLT VM context

func
IN

callback function

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

XmlXvmSetOutputDom()

Sets the XSLTVM to output DOM. If xmldocnode==NULL, then the result DOM tree belongs to the VM object and is deleted when a new transformation is performed or when the VM object is deleted. If the result DOM tree is to be used for longer period of time then an xmldocnode has to be created and set to the VM object.

Syntax

xmlerr XmlXvmSetOutputDom(
   xmlxvm *vm,
   xmldocnode *doc);
Parameter In/Out Description
vm
IN

VM object

doc
IN

empty document

Returns

(xmlerr) error code

XmlXvmSetOutputEncoding()

Sets the encoding for the XSLTVM stream output. If the input (data) encoding is different from the one set by this APIs then encoding conversion is performed. This APIs overrides the encoding set in the XSLT stylesheet (if any).

Syntax

xmlerr XmlXvmSetOutputEncoding(
   xmlxvm *vm, 
   oratext *encoding);
Parameter In/Out Description
vm
IN

VM object

encoding
IN

output encoding

Returns

(xmlerr) error code.

XmlXvmSetOutputSax()

Set XSLTVM to output SAX. If the SAX callback interface object is provided the VM outputs the result document in a form of SAX events using the user specified callback functions.

Syntax

xmlerr XmlXvmSetOutputSax(
   xmlxvm *vm,
   xmlsaxcb *saxcb, 
   void *saxctx);
Parameter In/Out Description
vm
IN

VM object

saxcb
IN

SAX callback object

saxctx
IN

SAX context

Returns

(xmlerr) error code

XmlXvmSetOutputStream()

Set the XSLTVM output to a user-defined stream. The default XSLTVM output is a stream. This APIs overrides the default stream with user specified APIs for writing.

Syntax

xmlerr XmlXvmSetOutputStream(
   xmlxvm *vm,
   xmlostream *ostream);
Parameter In/Out Description
vm
IN

VM object

ostream
IN

stream object

Returns

(xmlerr) error code.

XmlXvmSetTextParam()

Set the stylesheet top-level text parameter. The parameter value set in the XSLT stylesheet is overwritten. Since the top-level parameters are reset with stylesheet values after each transformation, this APIs has to be called again.

Syntax

xmlerr XmlXvmSetTextParam(
   xmlxvm *vm,
   oratext *name,
   oratext *value);
Parameter In/Out Description
vm
IN

VM object

name
IN

name of top-level parameter

value
IN

value of top-level parameter

Returns

(xmlerr) error code, XMLERR_SUCC [0] on success.

XmlXvmTransformBuffer()

Run compiled XSLT stylesheet on XML document in memory. The compiled XSLT stylesheet (bytecode) should be set using XmlXvmSetBytecodeXXX prior to this call.

Syntax

xmlerr XmlXvmTransformBuffer(
   xmlxvm *vm,
   oratext *buffer,
   ub4 length,
   oratext *baseURI);
Parameter In/Out Description
vm
IN

VM object

buffer
IN

NULL-terminated buffer that contains the XML document

length
IN

length of the XML document

baseURI
IN

base URI of XML document

Returns

XmlXvmTransformDom()

Run compiled XSLT stylesheet on XML document as DOM. The compiled XSLT stylesheet (bytecode) should be set using XmlXvmSetBytecodeXXX prior to this call.

Syntax

xmlerr XmlXvmTransformDom(
   xmlxvm *vm,
   xmldocnode *root);
Parameter In/Out Description
vm
IN

VM object

root
IN

root element of XML document's DOM

Returns

XmlXvmTransformFile()

Run compiled XSLT stylesheet on XML document in file. The compiled XSLT stylesheet (bytecode) should be set using XmlXvmSetBytecodeXXX prior to this call.

Syntax

xmlerr XmlXvmTransformFile(
   xmlxvm *vm,
   oratext *path,
   oratext *baseURI);
Parameter In/Out Description
vm
IN

VM object

path
IN

path of XML document to transform

baseURI
IN

base URI of XML document

Returns

XmlXvmTransformURI()

Run compiled XSLT stylesheet on XML document from URI. The compiled XSLT stylesheet (bytecode) should be set using XmlXvmSetBytecodeXXX prior to this call.

Syntax

xmlerr XmlXvmTransformURI(
   xmlxvm *vm, 
   oratext *uri);
Parameter In/Out Description
vm
IN

VM object

uri
IN

URI of XML document to transform

Returns