14
XSLT Processor for C

The XSL language processor is used to read XML documents and transform them into other XML documents with different styles. The C implementation of the XSL processor follows the XSL Transformations standard (version 1.0, November 16, 1999) and implements the required behavior of an XSL processor as specified in the XSLT specification.

This chapter describes the following sections:

Data Structures and Types of XSLT APIs
See Also:

Oracle9i XML Developer's Kits Guide - XDK

Data Structures and Types of XSLT APIs

Data Structures

Table 14-1 Summary of Data Types

Data Type	Definition	Description
oratext	typedef unsigned char oratext;	String pointer used for all data encodings, cast as needed; for UTF-16, to `(ub *).`
ub4	typedef unsigned int ub4;	32-bit, or larger, unsigned integer.
uword	typedef unsigned int uword;	Native unsigned integer.
xmlctx	typedef struct xmlctx xmlctx;	Top-level XML context.
xmlnode	typedef struct xmlnode xmlnode;	Document node.
xmlsaxcb	struct xmlsaxcb { sword (startDocument)(void ctx); sword (endDocument)(void ctx); sword (startElement)(void ctx, const oratext name, const struct xmlattrs attrs); sword (endElement)(void ctx, const oratext name); sword (characters)(void ctx, const oratext ch, size_t len); sword (ignorableWhitespace) (void ctx, const oratext ch, size_t len); sword (processingInstruction) (void ctx, const oratext target, const oratext data); sword (notationDecl)(void ctx, const oratext name, const oratext publicId, const oratext systemId); sword (unparsedEntityDecl) (void ctx, const oratext name, const oratext publicId, const oratext systemId, const oratext notationName); sword (nsStartElement)(void ctx, const oratext qname, const oratext local, const oratext namespace, const struct xmlattrs attrs); sword (comment)(void ctx, const oratext data); sword (elementDecl)(void ctx, const oratext name, const oratext content); sword (attributeDecl)(void ctx, const oratext elem, const oratext attr, const oratext body); /* The following 5 fields are reserved for future use. / void (empty1)(); void (empty2)(); void (empty3)(); void (empty4)(); void (empty5)(); }; typedef struct xmlsaxcb xmlsaxcb;	SAX callback structure; SAX only.
xmlstream	struct xmlstream; typedef struct xmlstream xmlstream; #define XMLSTREAM_OPENF(func) uword func(xmlstream stream, ub4 rsvd) #define XMLSTREAM_WRITEF(func) uword func(xmlstream stream, ub4 rsvd) #define XMLSTREAM_CLOSEF(func) uword func(xmlstream stream, ub4 rsvd) struct xmlstream { XMLSTREAM_OPENF((open)); XMLSTREAM_WRITEF((write)); XMLSTREAM_CLOSEF((close)); /* User can associate any data to lpxstream structure using this member so that he can access that inside the callbacks which will always have xmlstream as the firstargument. / void userdata; };	Stream-based output.
xpnset	typedef struct xpnset xpnset;	XPath node set.
xpnsetele	typedef struct xpnsetele xpnsetele;	XPath node set element.
xpobj	typedef struct xpobj xpobj;	XPath object.
xpobjtyp	typedef enum xpobjtyp ( XPOBJTYP_BOOL, /* boolean / XPOBJTYP_NUM, / number / XPOBJTYP_STR, / string / XPOBJTYP_NSET, / node set / XPOBJTYP_RTFRAG / restult tree fragment */ } xpobjtyp;	XPath object type.
xslctx	typedef struct xslctx xslctx;	Top-level XSL context.
xsloutputmethod	typedef enum { XSLMETHOD_UNKNOWN = 0, XSLMETHOD_TEXT, XSLMETHOD_HTML, } xsloutputmethod;	Output method for XSL processing.

Functions of XSLT API

Table 14-2 Summary of XSLT Functions

Function	Description
xslprocess()	Processes an XSL Stylesheet with an XML document source.
xslprocessex()	Processes an XSL Stylesheet with an XML document source.
xslprocessxml()	Processes an XSL Stylesheet with an XML document source.
xslprocessdocfrag()	Processes an XSL Stylesheet with an XML document source.
xslinit()	Creates and initializes an XSL context.
xslgetbaseuri()	Retrieves baseURI associated with XSL context.
xslgetoutputdomctx()	Retrieves output DOM associated with the XSL context.
xslgetoutputsax()	Retrieves SAX object associated with the XSL context.
xslgetoutputstream()	Retrieves output stream associated with the XSL context.
xslgetresultdocfrag()	Retrieves resultant doc fragment associated with the XSL context.
xslgetxslctx()	Retrieves XML context for XML stylesheet associated with XSL context.
xslsettextparam()	Sets a toplevel parameter (variable).
xslgettextparam()	Returns a top level parameter(variable) value.
xslsetoutputdomctx()	Sets XML context to store processing result (as DOM).
xslsetoutputencoding()	Sets XSLT output encoding.
xslsetoutputmethod()	Sets XSLT output method.
xslsetoutputsax()	Sets the SAX based events to be generated for the output.
xslsetoutputsaxctx()	Sets the SAX based events to be generated for the output.
xslsetoutputstream()	Sets the stream object specifying callbacks to generate the text stream based output.
xslresetallparams()	Resets all the top level parameters added.
xslterm()	Terminates an XSLT context object.

Table 14-3 Summary of XPath Functions

Function	Description
xpmakexpathctx()	Creates an XPath context.
xpfreexpathctx()	Parses an XPath expression.
xpparsexpathexpr()	Evaluates an XPath expression.
xpevalxpathexpr()	Retrieves values of evaluated xpath expression result.
xpgetxpobjtyp()	Retrieves values of evaluated xpath expression result.
xpgetbooleanval()	Retrieves values of evaluated xpath expression result.
xpgetnumval()	Retrieves values of evaluated xpath expression result.
xpgetstrval()	Retrieves values of evaluated xpath expression result.
xpgetnsetval()	Retrieves values of evaluated xpath expression result.
xpgetrtfragval()	Retrieves values of evaluated xpath expression result.
xpgetfirstnsetelem()	Retrieves values of evaluated xpath expression result.
xpgetnextnsetelem()	Retrieves values of evaluated xpath expression result.
xpgetnsetelemnode()	Retrieves values of evaluated xpath expression result.

xslprocess()

Description

Processes an XSL Stylesheet with an XML document source. Returns LPXERR_OK on success, otherwise LPXERR_FAIL.

Syntax

uword xslprocess( xmlctx *docctx,
                    xmlctx *xslctx,
                    xmlctx *resctx,
                    xmlnode **result);

Argument	IN / OUT	Description
docctx	(IN/OUT)	The XML document context.
xslctx	(IN)	The XSL stylesheet context.
resctx	(IN)	The result document fragment context.
result	(IN/OUT)	The result document fragment code.

xslprocessex()

Description

Processes an XSL Stylesheet with an XML document source. User can specify a list of toplevel parameters to be set before parsing begins. Returns LPXERR_OK on success, otherwise LPXERR_FAIL.

Syntax

uword xslprocessex( xmlctx *docctx,
                      xmlctx *sctx,
                      xmlctx *resctx,
                      size-t nparams,
                      oratext *params[],
                      oratext *vals[],
                      oratext *baseuri,
                      xmlnode **result);

Argument	IN / OUT	Description
docctx	(IN/OUT)	The XML document context
sctx	(IN)	The XSL stylesheet context
resctx	(IN)	The result document fragment context
nparams	(IN)	Number of (params, vals) pairs to be passed
params	(IN)	Array of name of pars (must be nparams in count)
vals	(IN)	Array of value of pars (must be nparams in count)
baseuri	(IN)	String giving the base uri for style sheet
result	(IN/OUT)	The result document fragment code

xslprocessxml()

Description

Processes an XSL Stylesheet with an XML document source. Returns LPXERR_OK on success, otherwise LPXERR_FAIL.

This XSLT API are supposed to be used after the user:

has created the XSLT processing context using xslinit(),
has set the base URI using xslinit(),
has set all the top level parameters using xslsettextparam(),
has selected an output method using xslsetoutput()

The function will process the given XML file (specified by docctx) according to the XSL stylesheet, parameters, and output method. This call returns one of the following depending on the output scheme that the user selected:

Stream based output: The output text has been redirected using the stream callbacks.
SAX based output: User should already have all the SAX events sent by XSLT.
DOM based output: User can make a call to the xslgetresultdocgrag() function to access the final Document Fragment created in context of the resctx() set by a call to xslsetoutputdomctx().

Syntax

uword xslprocessxml( xslctx *xslSSctx,
                        xmlctx *docctx,
                        boolean normalize,
                        ub4 resvd);

Argument	IN / OUT	Description
xslSSctx	(IN)	The XSL processing context
docctx	(IN/OUT)	The XML document context
normalize	(IN)	If `TRUE`, normalize the input DOM tree
resvd		Reserved; should be set to `NULL`

xslprocessdocfrag()

Description

Processes an XSL Stylesheet with an XML document source. Returns LPXERR_OK on success, otherwise LPXERR_FAIL.

This XSLT API are supposed to be used after the user:

has created the XSLT processing context using xslinit(),
has set the base URI using xslinit(),
has set all the top level parameters using xslsettextparam(),
has selected an output method using xslsetoutput()

Stream based output: The output text has been redirected using the stream callbacks.
SAX based output: User should already have all the SAX events sent by XSLT.
DOM based output: User can make a call to the xslgetresultdocgrag() function to access the final Document Fragment created in context of the resctx() set by a call to xslsetoutputdomctx().

Syntax

uword xslprocessxmldocfrag( xslctx *xslSSctx,
                                xmlctx *docctx,
                                xmlnode *docFrag,
                                boolean normalize,
                                ub4 resvd);

Argument	IN / OUT	Description
xslSSctx	(IN)	The XSL processing context.
docctx	(IN/OUT)	The XML document context.
docFrag	(IN)	The input document gragment node.
normalize	(IN)	If `TRUE`, normalize the input DOM tree.
resvd		Reserved; should be set to `NULL`

xslinit()

Description

Creates and initializes an XSL context. Returns the pointer to the XSL context object if successful; otherwise NULL.

Syntax

xslctx* xslinit ( uword *err,
                    xmlctx *xslctx,
                    const oratext *baseURI,
                    ub4 resvd);

Argument	IN / OUT	Description
err	(OUT)	`LPXERR_OK` on success, otherwise error code.
xslctx	(IN)	The XSL context for the input stylesheet.
baseURI	(IN)	The base URI for processing `include` and `import` statements.
resvd		Reserved for future use; should be set to `NULL.`

xslgetbaseuri()

Description

Retrieves baseURI associated with XSL context. Returns the pointer to the base URI if successful; otherwise NULL.

Syntax

const oratext* xslgetbaseuri ( xslctx *xslSSctx);

Argument	IN / OUT	Description
xslSSctx	(IN)	The XSL processing context to be queried.

xslgetoutputdomctx()

Description

Retrieves output DOM associated with the XSL context. Returns the pointer to the output DOM context object if successful; otherwise NULL.

Syntax

xmlctx* xslgetoutputdomctx( xslctx *xslSSctx);

Argument	IN / OUT	Description
xslSSctx	(IN)	The XSL processing context to be queried

xslgetoutputsax()

Description

Retrieves SAX object associated with the XSL context. Returns the pointer to the output SAX object if successful; otherwise NULL.

Syntax

xmlsaxcb* xslgetoutputsax( xslctx *xslSSctx);

Argument	IN / OUT	Description
xslSSctx	(IN)	The XSL processing context to be queried

xslgetoutputstream()

Description

Retrieves output stream associated with the XSL context. Returns the pointer to the output stream object if successful; otherwise NULL.

Syntax

xmlstream* xslgetoutputstream( xslctx *xslSSctx);

Argument	IN / OUT	Description
xslSSctx	(IN)	The XSL processing context to be queried.

xslgetresultdocfrag()

Description

Retrieves resultant doc fragment associated with the XSL context. Returns the pointer to the document fragment node if successful; otherwise NULL.

Syntax

xmlnode*  xslgetresultdocfrag( xslctx *xslSSctx);

Argument	IN / OUT	Description
xslSSctx	(IN)	The XSL processing context to be queried.

xslgetxslctx()

Description

Retrieves XML context for XML stylesheet associated with XSL context. Returns the pointer to the XML context object of the XSL stylesheet if successful; otherwise NULL.

Syntax

xmlctx* xslgetxslctx( xslctx *xslSSctx);

Argument	IN / OUT	Description
xslSSctx	(IN)	The XSL processing context to be queried

xslsettextparam()

Description

Sets a toplevel parameter (variable). Returns LPXERR_OK on success, otherwise LPXERR_FAIL.

Syntax

uword xslsettextparam ( xslctx *xslSSctx,
                          const oratext *param_name,
                          const oratext *param_value);

Argument	IN / OUT	Description
xslSSctx	(IN)	The XSL processing context to be queried.
param_name	(IN)	The name of parameter (variable) whose value is to be set.
param_value	(IN)	The parameter value.

xslgettextparam()

Description

Returns a top level parameter(variable) value. Returns the pointer to the variable/parameter value if successful, otherwise NULL.

Syntax

const oratext *xslgettextparam( xslctx *xslSSctx,
                                  const oratext *param_name);

Argument	IN / OUT	Description
xslSSctx	(IN)	The XSL processing context.
param_name	(IN)	The name of parameter (variable) whose value is to be retrieved.

xslsetoutputdomctx()

Description

Sets XML context to store processing result (as DOM). Returns LPXERR_OK on success, otherwise LPXERR_FAIL.

A call to xslsetoutputdomctx() overrides any previous output method set using any previous calls to xslsetoutputdomctx() , xslsetoutputstream () or xslsetoutputsax(). Any subsequent processing of the XML input will be stored in form of a Document Fragment in the xmlctx specified by resctx.

xslgetoutputdomctx() can be used to retrieve the presently set resctx. If no DOM context is set or a call to xslsetoutputdomctx() has been overridden by a

subsequent call to xslsetoutputstream() or xslsetoutputsax(), then xslgetoutputdomctx() will return a NULL context indicating that the present output mode is not a DOM output mode.

Syntax

uword xslsetoutputdomctx( xslctx *xslSSctx,
                            xmlctx *resctx);

Argument	IN / OUT	Description
xslSSctx	(IN)	The XSL processing context
resctx	(IN)	The XML context object in which the output document fragment will be stored. This pointer must remain valid throughout, since this context is used to generate the processing event during subsequent processing of XML trees.

xslsetoutputencoding()

Description

Sets XSLT output encoding. Returns LPXERR_OK on success, otherwise LPXERR_FAIL. Overrides the XSL Stylesheet settings.

This call is used to set an output method equivalent to XSL processing directive xsl:output encoding ="...". If the XSL stylesheet contains one or more similar statements, then this function will override the effect of any previously present statements in XSL stylesheet.

Syntax

uword xslsetoutputencoding( xslctx *xslSSctx,
                              oratext* outcoding);

Argument	IN / OUT	Description
xslSSctx	(IN)	The XSL processing context
outcoding	(IN)	Encoding name for the output encoding

xslsetoutputmethod()

Description

Sets XSLT output method. Returns LPXERR_OK on success, otherwise LPXERR_FAIL. Overrides the XSL Stylesheet settings.

This call is used to set an output method equivalent to XSL processing directive xsl:output method = "text/xml/html". If the XSL stylesheet contains one or more similar statements, then this function will override the effect of any previously present statements in XSL stylesheet.

Syntax

uword xslsetoutputmethod( xslctx *xslSSctx,
                            xsloutputmethod method,
                            ub4 resvd);

Argument	IN / OUT	Description
xslSSctx	(IN)	The XSL processing context
method	(IN)	Output method to be selected
resvd		Reserved for future; must set to `NULL`

xslsetoutputsax()

Description

Sets the SAX based events to be generated for the output. Returns LPXERR_OK on success, otherwise LPXERR_FAIL.

The user can make a call to xslsetoutputsazctx() to set the SAX context to be used by the SAX callbacks. If none is set, NULL will be passed to the SAX callbacks as SAX context. Note: just setting the callbacks is sufficient to invoke the SAX callbacks.

Syntax

uword xslsetoutputsax( xslctx *xslSSctx,
                        xmlsaxcb *s);

Argument	IN / OUT	Description
xslSSctx	(IN)	The XSL processing context
s	(IN)	The SAX callbacks to be used to generate the SAX events

xslsetoutputsaxctx()

Description

Sets the SAX based events to be generated for the output. Returns LPXERR_OK on success, otherwise LPXERR_FAIL.

Syntax

uword xslsetoutputsaxctx( xslctx *xslSSctx,
                            void *saxctx);

Argument	IN / OUT	Description
xslSSctx	(IN)	The XSL processing context
saxctx	(IN)	the SAX context

xslsetoutputstream()

Description

Sets the stream object specifying callbacks to generate the text stream based output. Returns LPXERR_OK on success, otherwise LPXERR_FAIL.

Syntax

uword xslsetoutputstream( xslctx *xslSSctx,
                            xmlstream *stream);

Argument	IN / OUT	Description
stream	(IN)	The stream structure giving the callbacks to be used.
xslSSctx	(IN)	The XSL processing context

xslresetallparams()

Description

Resets all the top level parameters added. Returns LPXERR_OK on success, otherwise LPXERR_FAIL.

Syntax

uword xslresetallparams( xslctx *xslSSctx);

Argument	IN / OUT	Description
xslSSctx	(IN)	The XSL processing context

xslterm()

Description

Terminates an XSLT context object. Returns LPXERR_OK on success, otherwise LPXERR_FAIL.

Syntax

uword xslterm( xslctx *xslSSctx);

Argument	IN / OUT	Description
xslSSctx	(IN)	The XSL processing context.

xpmakexpathctx()

Description

Creates an XPath context. Returns an XPath context object; this call never fails.

Syntax

xpctx *xpmakexpathctx( xmlctx *ctx,
                          xmlnode *xslnode,
                          xmlnode* xml_node,
                          oratext* baseURI,
                          size-t nctxels,
                          xmlnode ** ctxnodes);

Argument	IN / OUT	Description
sctx	(IN)	XSL context; could be `NULL.`
xslnode	(IN)	The XSL nodeused for namespace expansion; could be `NULL.`
xml_node	(IN)	The context node; set to `NULL` for parsing.
baseURI	(IN)	The base URI for parsing.
nctxels	(IN)	The number of nodes in the current node set.
ctxnodes	(IN)	The current node set.

xpfreexpathctx()

Description

Frees an XPath context.

Syntax

void xpfreexpathctx( xpctx *xctx);

Argument	IN / OUT	Description
xctx	(IN)	The XPath context to be freed.

xpparsexpathexpr()

Description

Parses an XPath expression. Returns the expression tree on success; otherwise, NULL.

Syntax

xpexpr *xpparsexpathexpr( xpctx *xctx,
                            oratext *expr,
                            sword *err);

Argument	IN / OUT	Description
xctx	(IN/OUT)	The XPath context
expr	(IN)	The expression in the form of a string
err	(OUT)	The error code

xpevalxpathexpr()

Description

Evaluates an XPath expression. Returns the result object on success; otherwise, NULL. The type of the result object, obtained using xpgetxpobjtyp(), is one of the following:

XPOBJTYP_BOOL
XPOBJTYP_NUM
XPOBJTYP_STR
XPOBJTYP_NSET
XPOBJTYP_RTFRAG

Syntax

xpobj *xpevalxpathexpr( xpctx *xctx,
                          xpexpr *exprtree,
                          sword *err);

Argument	IN / OUT	Description
xctx	(IN/OUT)	The XPath context
exprtree	(IN)	The expression in the form of a tree
err	(OUT)	The error code