13
XML Parser for C

This chapter describes the following sections:

Parser APIs
W3C SAX APIs
W3C DOM APIs
Namespace APIs
See Also:

Oracle9i XML Developer's Kits Guide - XDK

Parser APIs

This C implementation of the XML processor (or parser) follows the W3C XML specification (rev REC-xml-19980210) and implements the required behavior of an XML processor in terms of how it must read XML data and the information it must provide to the application.

Calling Sequence

Parsing a single document:

xmlinit, xmlparsexxx, xmlterm

Parsing multiple documents, but only the latest document's data needs to be available:

xmlinit, xmlparsexxx, xmlclean, xmlparsexxx, xmlclean ... xmlterm

Parsing multiple documents, all document data must be available:

xmlinit, xmlparsexxx, xmlparsexxx ... xmlterm

Memory

Memory callback functions may be used if you wish to use your own memory allocation. If they are used, both functions should be specified.

The memory allocated for parameters passed to the SAX callbacks or for nodes and data stored with the DOM parse tree will not be freed until one of the following is done:

xmlclean() is called.
xmlterm() is called.

Thread Safety

If threads are forked off somewhere in the midst of the init-parse-terminate sequence of calls, you will get unpredictable behavior and results.

Data Types

Table 13-1 Summary of Data Types for Parser APIs

Data Type	Syntax	Description
boolean	typedef int boolean;	Boolean value, TRUE or FALSE.
oratext	typedef unsigned char oratext;	String pointer used for all data encodings, cast as needed; for UTF-16, to (ub2 *)
string	typedef unsigned char String;	String pointer (C/C++)
ub4	typedef unsigned int ub4;	32-bit (or larger) unsigned integer
uword	typedef unsigned int uword;	Native unsigned integer
xmlacctype	XMLACCESS_UNK /An access method was specified an a URL, but it was unknown to the XML parser/ XMLACCESS_FILE /Filesystem I/O/ XMLACCESS_HTTP /HyperText Transport Protocol; the Web)/ XMLACCESS_FTP /File Transfer Protocol / XMLACCESS_GOPHER /Gopher/ XMLACCESS_ORADB /Direct Oracle database access/ XMLACCESS_STREAM /User-defined stream/	An enumeration of the possible access methods used to retrieve an XML document XML access type, like HTTP, FTP, File, and so on. See the `xmlaccess()` function for more details.
xmlctx	typedef struct xmlctx xmlctx;	Top-level XML context; the contents of xmlctx are private and must not be accessed by users.
xmlmemcb	struct xmlmemcb { void (alloc)(void ctx, size_t size); void (free)(void ctx, void ptr); }; typedef struct xmlmemcb xmlmemcb;	Memory callback structure (optional). This is the memory callback structure. Allocations do not need to be initialized; works like `malloc`, not `calloc`.
xmlnode	typedef struct xmlnode xmlnode;	Note: The contents of xmlnode are private and must not be accessed by users.
xmlntype	ELEMENT_NODE = 1 /* element / ATTRIBUTE_NODE= 2 / attribute / TEXT_NODE = 3 / char data not escaped by CDATA / CDATA_SECTION_NODE= 4 / char data escaped by CDATA / ENTITY_REFERENCE_NODE = 5 / entity reference / ENTITY_NODE = 6 / entity / PROCESSING_INSTRUCTION_NODE = 7 / processing instruction / COMMENT_NODE= 8 / comment / DOCUMENT_NODE = 9 / document / DOCUMENT_TYPE_NODE= 10 / DTD / DOCUMENT_FRAGMENT_NODE= 11 / document fragment / NOTATION_NODE = 12 / notation */	Node type enumeration Parse tree node types, see `getNodeType()`. Names and values match DOM specification.
xmlsaxc	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 (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); sword (xmlDecl)(void ctx, const oratext version, boolean encoding); / Following fields are reserved for future use./ void (empty1)(); void (empty2)(); void (empty3)(); void (*empty4)(); }; typedef struct xmlsaxcb xmlsaxcb;	SAX callback structure (SAX only)

Functions and Methods of Parser APIs

Table 13-2 Summary of Functions and Methods of Parser APIs

Function / Method	Description
freeElements()	Frees an allocated list of element nodes.
getEncoding()	Returns document's encoding.
isSingleChar()	Determines if document data is single or multibyte.
isStandalone()	Determines if document is standalone.
isUnicode()	Determines if document data is Unicode.
saveString()	Allocates memory and saves the `NULL`-terminated single or multibyte string in the XML string pool.
saveString2()	Allocates memory and saves the `NULL`-terminated Unicode string in the XML string pool.
printBuffer()	Prints representation of XML tree into buffer.
printSize()	Returns size of printed representation of XML tree.
printStream()	Writes a printed representation of an XML tree to file stream.
setDocOrder()	Sets the document order for each node in the current document.
xmlaccess()	Sets the I/O callback functions for the given access method.
xmlclean()	Frees any memory used during the previous parse.
xmlinit()	Initializes XML parser.
xmlinitenc()	Initializes XML parser specifying DOM data encoding.
xmlLocation()	Returns current location while parsing.
xmlparse()	Parses a URI.
xmlparsebuf()	Parses a buffer.
xmlparsedtd()	Parses an external DTD.
xmlparsefile()	Parses a file.
xmlparsestream()	Parses a user-defined stream.
xmlterm()	Shuts down XML parser.
xmlwhere()	Returns error location information.

freeElements()

Description

Frees an allocated list of element nodes. Used primarily to free the lists created by getElementsByTagName().

Syntax

void freeElements( xmlctx *ctx,
                   xmlnodes *list);

Parameter	IN / OUT	Description
ctx	(IN)	XML context.
list	(IN)	List of nodes to free

getEncoding()

Description

This function returns the IANA/Mime name of the DOM/SAX data encoding, such as "ASCII", "ISO-8859-1", "UTF-8", "UTF-16", and so on. See also the isSingleChar() function, which can be used to determine if the data is single or multibyte, and the isUnicode() function, which determines if the data is Unicode (UTF-16). The data encoding is specified by the user at initiation time.

Syntax

oratext *getEncoding( xmlctx *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	The XML parser context.

isSingleChar()

Description

Returns a flag which specifies whether data encoding to this context is singlebyte characters (like ASCII, ISO-8859, EBCDIC, and others), or multibyte characters (like UTF-8 or Unicode). See getEncoding(), which returns the name of the data encoding.

Syntax

boolean isSingleChar( xmlctx *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	The XML parser context

isStandalone()

Description

Returns value of document's standalone flag. This function returns the boolean value of the document's standalone flag, as specified in the XML declaration.

Syntax

boolean isStandalone( xmlctx *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	The XML parser context

isUnicode()

Description

Returns the Unicode (UCS2) encoding flag. Similar to a isSingleChar().

Syntax

boolean isUnicode(xmlctx *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	The XML parser context

saveString()

Description

Allocates memory and saves the NULL-terminated single or multibyte string in the XML string pool. Strings saved this way cannot be freed individually since they are stored head-to-tail in a single pool, for maximum compactness. The memory is reused only when the entire pool is freed, after an xmlclean() or xmlterm() calls. Use saveString2() for saving Unicode strings.

Syntax

oratext *saveString( xmlctx *ctx,
                     oratext *str);

Parameter	IN / OUT	Description
xtx	(IN)	LPX context
str	(IN)	Pointer to a single or multibyte string.

saveString2()

Description

Allocates memory and saves the NULL-terminated Unicode string in the XML string pool. Note that a Unicode string is terminated with TWO NULL bytes, not just one! Strings saved this way cannot be freed individually since they are stored head-to-tail in a single pool, for maximum compactness. The memory is reused only when the entire pool is freed, after an xmlclean() or xmlterm() calls. Use saveString() for saving single or multibyte strings.

Syntax

ub2 *saveString2( xmlctx *ctx,
                  ub2 *ustr);

Parameter	IN / OUT	Description
xtx	(IN)	LPX context
ustr	(IN)	Pointer to a unicode string

printBuffer()

Description

Creates a printed representation of an XML tree rooted at the given node, and puts it into a destination buffer. Indentation is controlled by level and step: step is the number of spaces to indent each new level, and level is the starting level; 0 for top- level.

Syntax

void printBuffer( oratext *buffer,
                  size_t bufsiz,
                  xmlnode *node,
                  uword step,
                  uword level);

Parameter	IN / OUT	Description
buffer	(IN)	destination buffer where output is placed
bufsiz	(IN)	size of destination buffer
node	(IN)	root node of XML tree to print
step	(IN)	number of spaces to indent each new level
level	(IN)	starting level of indentation

printSize()

Description

Returns the size of the printed representation of an XML tree, rooted at the given node. Indentation is controlled by level and step as for printBuffer: step is the number of spaces to indent each new level, and level is the starting level; 0 for top-level. This function is used to pre-compute the size of the buffer needed for printBuffer().

Syntax

size_t printSize( xmlnode *node, 
                  uword step,
                  uword level);

Parameter	IN / OUT	Description
node	(IN)	root node of XML tree to print
step	(IN)	number of spaces to indent each new level
level	(IN)	starting level of indentation

printStream()

Description

Writes a printed representation of an XML tree (rooted at the given node) to a stdio stream (FILE*). This function is exactly like printBuffer except output is to a stream instead of into a buffer. Indentation is controlled by level and step: step is the number of spaces to indent each new level, and level is the starting level (0 for top-level).

Syntax

void printStream( FILE *stream,
                  xmlnode *node,
                  uword step,
                  uword level);

Parameter	IN / OUT	Description
stream	(IN)	output stream to write to
node	(IN)	root node of XML tree to print
step	(IN)	number of spaces to indent each new level
level	(IN)	starting level of indentation

setDocOrder()

Description

Sets the document order for each node in the current document. Must be called once on the final document before XSLT processing can occur. Note this is called automatically by the XSLT processor, so ordinarily the user need not make this call.

Syntax

ub4 setDocOrder(xmlctx *ctx, ub4 start_id);

Parameter	IN / OUT	Description
ctx	(IN)	XML context
start_id	((N)	Initial id number to assign

xmlaccess()

Description

Sets the I/O callback functions for the given access method.

Syntax

uword xmlaccess( xmlctx *ctx,
                 xmlacctype access,
                 XML_OPENF((*openf)),
                 XML_CLOSEF((*closef)),
                 XML_READF((*readf)));

Parameter	IN / OUT	Description
ctx	(IN)	The XML context
access	(IN)	Access method enum, XMLACCESS_xxx
openf	(IN)	Open-input callback function
closef	(IN)	Close-input callback function
readf	(IN)	Read-input callback function

Comments

Sets the I/O callback functions for the given access method. Most methods have built-in callback functions, so do not have to be provided by the user. The notable exception is XMLACCESS_STREAM, where the user must set the stream callback functions themselves.

The three callback functions are invoked to open, close, and read from the input source. The functions should have been declared using the function prototype macros XML_OPENF, XML_CLOSEF and XML_READF.

XML_OPENF is the open function, called once to open the input source. It should set 
its persistent handle in the xmlihdl union, which has two choices, a generic 
pointer (void *), and an integer (as unix file or socket handle). This function 
must return XMLERR_OK on success.

Parameter	IN / OUT	Description
ctx	(IN)	XML context.
ih	(OUT)	The opened handle is placed here.
length	(OUT)	Total length of input data in bytes, if known (0 if not known).
parts	(IN)	URL broken down into components; opaque pointer.
path	(IN)	Full URL to be opened.

XML_CLOSEF is the close function; it closes an open source and frees resources.

Parameter	IN / OUT	Description
ctx	(IN)	XML context.
ih	(IN)	The opened handle.

XML_READF is the reader function; it reads data from an open source into a buffer, and returns the number of bytes read:

If <= 0, an EOI condition is indicated.

If > 0, then the EOI flag determines if this is the final data.

On EOI, the matching close function will be called automatically.

Parameter	IN / OUT	Description
ctx	(IN)	XML context.
dest	(OUT)	Destination buffer to read data into.
destsize	(IN)	Size of dest buffer.
eoi	(OUT)	Hit End of Information?
ih	(IN)	Input handle union from which to read.
nraw	(OUT)	Number of bytes read.
path	(IN)	URL of source provided for use in error messages.

xmlclean()

Description

Recycles memory within the XML parser, but does not free it to the system; only xmlterm() finally releases all memory back to the system. If xmlclean() is not called between parses, then the data used by the previous documents remains allocated, and pointers to it are valid. Thus, the data for multiple documents can be accessible simultaneously, although only the current document can be manipulated with DOM.

If only access to only one document's data at a time within a single context is desired, than clear() should be called before each new parse.

Syntax

void xmlclean( xmlctx *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	The XML parser context

xmlinit()

Description

Initializes the XML parser. It must be called before any parsing can take place.

The C version of this call returns the XML context on success, and sets the user's err argument on error. As usual, a zero error code means success, nonzero indicates a problem.
This function should only be called once before starting the processing of one or more XML files. xmlterm() should be called after all processing of XML files has completed.
For C, all arguments may be NULL except for err. For C++, all arguments have default values and may be omitted if not needed.
By default, the data encoding is UTF-8. If documents are singlebyte, encoding should be set accordingly for better performance.
Messages are printed to stderr unless msghdlr is given.
By default, a DOM tree is built. For SAX mode, the saxcb callbacks should be set. Note that any of the SAX callback functions may be set to NULL if not needed.
The memory callback memcb may be used for user-defined memory allocation. Both alloc() and free() functions must be specified.
The parameters msgctx, saxcbctx, and memcbctx can be used to define and pass information to user-defined callback routines for the message handler, SAX functions, or memory functions, respectively. They should be set to NULL if user-defined callback functions do not need any additional information passed in to them.
The lang parameter determines the language of error messages; the default is "American."
Returns the XML context on success; sets the user's err argument on error. A zero error code means success, nonzero indicates a problem.

Syntax

xmlctx *xmlinit( uword *err,
                 const oratext *incoding,
                 XML_MSGHDLRF((*msghdlr)),
                 void *msgctx,
                 const xmlsaxcb *saxcb,
                 void *saxcbctx, 
                 const xmlmemcb *memcb,
                 void *memcbctx,
                 const oratext *lang);

Parameter	IN / OUT	Description
err	(OUT)	Numeric error code, on failure.
incoding	(IN)	Default input encoding.
msghdlr	(IN)	Error message handler function.
msgctx	(IN)	User's context for the error message handler.
saxcb	(IN)	SAX callback structure, filled with function pointers.
saxcbctx	(IN)	User's context for SAX callbacks.
memcb	(IN)	Memory function callback structure.
memcbctx	(IN)	User's context for the memory function callbacks.
lang	(IN)	Language for error messages.

Error Code	Description
XMLERR_BAD_ENCODING	An encoding was not known. Use IANA/Mine names for encodings, and make sure Globalization Support data is present.
XMLERR_INVALID_LANG	The language specified for error messages was not known.
XMLERR_INVALID_MEMCB	A memory callback structure (memcb) was specified, but it did not have alloc and free function pointers.
XMLERR_LEH_INIT	The LEH (catch/throw) package could not be initialized. An internal error, contact support.
XMLERR_NLS_INIT	The National Language Service package could not be initialized. Perhaps an installation or configuration problem.

xmlinitenc()

Description

Initializes the XML parser, specifying DOM data encoding. It must be called before any parsing can take place. Same as SAX xmlinit(), but allows data encoding to be specified.

Syntax

xmlctx *xmlinitenc( uword *err,
                    const oratext *incoding, 
                    const oratext *outcoding,
                    XML_MSGHDLRF((*msghdlr)),
                    void *msgctx,
                    const xmlsaxcb *saxcb,
                    void *saxcbctx, 
                    const xmlmemcb *memcb,
                    void *memcbctx,
                    const oratext *lang);

Parameter	IN / OUT	Description
err	(OUT)	Numeric error code, on failure.
incoding	(IN)	Default input encoding.
outcoding	(IN)	Output (DIM/SAX data) character set encoding.
msghdlr	(IN)	Error message handler function.
msgctx	(IN)	User's context for the error message handler.
saxcb	(IN)	SAX callback structure, filled with function pointers.
saxcbctx	(IN)	User's context for SAX callbacks.
memcb	(IN)	Memory function callback structure.
memcbctx	(IN)	User's context for the memory function callbacks.
lang	(IN)	Language for error messages.

Error Code	Description
XMLERR_BAD_ENCODING	An encoding was not known. Use IANA/Mine names for encodings, and make sure Globalization Support data is present.
XMLERR_INVALID_LANG	The language specified for error messages was not known.
XMLERR_INVALID_MEMCB	A memory callback structure (memcb) was specified, but it did not have alloc and free function pointers.
XMLERR_LEH_INIT	The LEH (catch/throw) package could not be initialized. An internal error, contact support.
XMLERR_NLS_INIT	The National Language Service package could not be initialized. Perhaps an installation or configuration problem.

Parameter	IN / OUT	Description

xmlLocation()

Description

Returns current source location while parsing. This function may be called at any time. However, a 0 will be returned for both path and line if the call is not made during parsing.

Syntax

uword xmlLocation( xmlctx *ctx,
                   ub4 *line,
                   oratext **path);

Parameter	IN / OUT	Description
ctx	(IN)	The XML parser context
line	(OUT)	Current line number
path	(OUT)	Current source path/URL

xmlparse()

Description

Invokes the XML parser on an input document that is specified by a URI. The parser must have been initialized successfully with a call to xmlinit() or xmlinitenc() first. Parser options are specified as flag bits OR'd together into the flags mask.

The default input encoding may be specified as incoding, which overrides the incoding given to xmlinit(). If the input's encoding cannot be determined automatically, based on BOM, XMLDecl, and others, then it is assumed to be incoding. IANA/Mime encoding names should be used, "UTF-8", "ASCII", others.

Syntax

uword xmlparse( xmlctx *ctx,
                const oratext *uri,
                const oratext *incoding,
                ub4 flags);

Parameter	IN / OUT	Description
ctx	(IN/OUT)	The XML parser context
uri	(IN)	URI of XML document
incoding	(IN)	Default input encoding
flags	(IN)	Mask of parser option flag bits

Parser Flag Option	Description
XML_DTD_ONLY	Parses an external subset. This is the same as calling `xmlparsedtd()`; it parses an external subset (DTD) instead of a complete XML document. Used primarily by the Class Generator so that it may generate classes from a DTD without need of a complete document.
XML_FLAG_DISCARD_WHITESPACE	Discards extraneous whitespace (end-of-line, and so on); default behavior is to report whitespace and indicate which whitespace can be ignored. This option will discard all whitespace between an end-element tag and the following start-element tag.
XML_FLAG_STOP_ON_WARNING	Stops validation on warnings. Validation problems are considered warnings (non-fatal) unless this flag is set. If set, validation will stop after the first warning.
XML_FLAG_VALIDATE	Turns validation on; default behavior is to only check for well-formedness.
XML_FORCE_INCODING	Forces input documents to be interpreted in the encoding "incoding". The default input encoding may be specified as incoding, which overrides the incoding given to xmlinit. If the input's encoding cannot be determined automatically, based on BOM, XMLDecl, and others, then it is assumed to be incoding. IANA/Mime encoding names should be used, "UTF-8", "ASCII", and so on. If `XML_FLAG_FORCE_INCODING` is set, the document will be interpreted as "incoding" regardless.
XML_WARN_DUPLICATE_ENTITY	Causes a warning to be emitted if a duplicate entity declaration is found. A duplicate entity declaration is usually silently ignored. When set, this flag causes a warning to be emitted instead.

xmlparsebuf()

Description

Invokes the XML parser on a buffer. The parser must have been initialized successfully with a call to xmlinit() or xmlinitenc() first. Parser options are specified as flag bits OR'd together into the flags mask.

Syntax

uword xmlparsebuf( xmlctx *ctx,
                   const oratext *buffer,
                   size_t len,
                   const oratext *incoding,
                   ub4 flags);

Parameter	IN / OUT	Description
ctx	(IN/OUT)	The XML parser context
buffer	(IN)	Input buffer name
len	(IN)	Length of the buffer
incoding	(IN)	Default input encoding
flags	(IN)	Mask of parser option flag bits

Parser Flag Option	Description
XML_DTD_ONLY	Parses an external subset. This is the same as calling `xmlparsedtd()`; it parses an external subset (DTD) instead of a complete XML document. Used primarily by the Class Generator so that it may generate classes from a DTD without need of a complete document.
XML_FLAG_DISCARD_WHITESPACE	Discards extraneous whitespace (end-of-line, and so on); default behavior is to report whitespace and indicate which whitespace can be ignored. This option will discard all whitespace between an end-element tag and the following start-element tag.
XML_FLAG_STOP_ON_WARNING	Stops validation on warnings. Validation problems are considered warnings (non-fatal) unless this flag is set. If set, validation will stop after the first warning.
XML_FLAG_VALIDATE	Turns validation on; default behavior is to only check for well-formedness.
XML_FORCE_INCODING	Forces input documents to be interpreted in the encoding "incoding". The default input encoding may be specified as incoding, which overrides the incoding given to xmlinit. If the input's encoding cannot be determined automatically, based on BOM, XMLDecl, and others, then it is assumed to be incoding. IANA/Mime encoding names should be used, "UTF-8", "ASCII", and so on. If `XML_FLAG_FORCE_INCODING` is set, the document will be interpreted as "incoding" regardless.
XML_WARN_DUPLICATE_ENTITY	Causes a warning to be emitted if a duplicate entity declaration is found. A duplicate entity declaration is usually silently ignored. When set, this flag causes a warning to be emitted instead.

xmlparsedtd()

Description

Invokes the XML parser on an external DTD file, not a complete document. It is used mainly by the Class Generator to create classes from a DTD without requiring a complete document. The parser must have been initialized successfully with a call to xmlinit() or xmlinitenc() first. Parser options are specified as flag bits OR'd together into the flags mask.

Syntax

uword xmlparsedtd( xmlctx *ctx,
                   const oratext *filename,
                   oratext *name,
                   const oratext *incoding,
                   ub4 flags);

Parameter	IN / OUT	Description
ctx	(IN/OUT)	The XML parser context
filename	(IN)	File name of the external subset
name	(IN)	Name of the DTD
incoding	(IN)	Default input encoding
flags	(IN)	Mask of parser option flag bits

Parser Flag Option	Description
XML_DTD_ONLY	Parses an external subset. This is the same as calling xmlparsedtd; it parses an external subset (DTD) instead of a complete XML document. Used primarily by the Class Generator so that it may generate classes from a DTD without need of a complete document.
XML_FLAG_DISCARD_WHITESPACE	Discards extraneous whitespace (end-of-line, and so on); default behavior is to report whitespace and indicate which whitespace can be ignored. This option will discard all whitespace between an end-element tag and the following start-element tag.
XML_FLAG_STOP_ON_WARNING	Stops validation on warnings. Validation problems are considered warnings (non-fatal) unless this flag is set. If set, validation will stop after the first warning.
XML_FLAG_VALIDATE	Turns validation on; default behavior is to only check for well-formedness.
XML_FORCE_INCODING	Forces input documents to be interpreted in the encoding "incoding". The default input encoding may be specified as incoding, which overrides the incoding given to xmlinit. If the input's encoding cannot be determined automatically, based on BOM, XMLDecl,and others, then it is assumed to be incoding. IANA/Mime encoding names should be used, "UTF-8", "ASCII", and so on. If `XML_FLAG_FORCE_INCODING` is set, the document will be interpreted as "incoding" regardless.
XML_WARN_DUPLICATE_ENTITY	Causes a warning to be emitted if a duplicate entity declaration is found. A duplicate entity declaration is usually silently ignored. When set, this flag causes a warning to be emitted instead.

xmlparsefile()

Description

Invokes the XML parser on a document in the file system. The parser must have been initialized successfully with a call to xmlinit() or xmlinitenc() first. Parser options are specified as flag bits OR'd together into the flags mask.

Syntax

uword xmlparsefile( xmlctx *ctx,
                    const oratext *path,
                    const oratext *incoding,
                    ub4 flags);

Parameter	IN / OUT	Description
ctx	(IN/OUT)	The XML parser context
path	(IN)	Filesystem path of the document
incoding	(IN)	Default input encoding
flags	(IN)	Mask of parser option flag bits

Parser Flag Option	Description
XML_DTD_ONLY	Parses an external subset. This is the same as calling xmlparsedtd; it parses an external subset (DTD) instead of a complete XML document. Used primarily by the Class Generator so that it may generate classes from a DTD without need of a complete document.
XML_FLAG_DISCARD_WHITESPACE	Discards extraneous whitespace (end-of-line, and so on); default behavior is to report whitespace and indicate which whitespace can be ignored. This option will discard all whitespace between an end-element tag and the following start-element tag.
XML_FLAG_STOP_ON_WARNING	Stops validation on warnings. Validation problems are considered warnings (non-fatal) unless this flag is set. If set, validation will stop after the first warning.
XML_FLAG_VALIDATE	Turns validation on; default behavior is to only check for well-formedness.

13 XML Parser for C

Parser APIs

Calling Sequence

Memory

Thread Safety

Data Types

Table 13-1 Summary of Data Types for Parser APIs

Functions and Methods of Parser APIs

Table 13-2 Summary of Functions and Methods of Parser APIs

freeElements()

Description

Syntax

getEncoding()

Description

Syntax

isSingleChar()

Description

Syntax

isStandalone()

Description

Syntax

isUnicode()

Description

Syntax

saveString()

Description

Syntax

saveString2()

Description

Syntax

printBuffer()

Description

Syntax

printSize()

Description

Syntax

printStream()

Description

Syntax

setDocOrder()

Description

Syntax

xmlaccess()

Description

Syntax

Comments

xmlclean()

Description

Syntax

xmlinit()

Description

Syntax

xmlinitenc()

Description

Syntax

xmlLocation()

Description

Syntax

xmlparse()

Description

Syntax

xmlparsebuf()

Description

Syntax

xmlparsedtd()

Description

Syntax

xmlparsefile()

Description

Syntax

13
XML Parser for C