Low-Level Parser API

The high-level XML parser API is sufficient for many needs. However, there are some cases where using the low-level API is appropriate:

The XML Services callback-based API is somewhat more complex to use, but provides much more flexibility than the high-level API.

Conceptually, the low-level API is simple. You first define a set of callback functions that are invoked as the parsing process proceeds. As the parser encounters each XML structure, your functions are called, giving you an opportunity to handle the data however you wish.

Parser Callbacks

In order to use the low-level parser, you must implement three of the five callbacks described in this section--CFXMLParserCreateXMLStructureCallBack , CFXMLParserAddChildCallBack , and CFXMLParserEndXMLStructureCallBack . The other callbacks are optional.

The CFXMLParserCreateXMLStructureCallBack function is called when the parser encounters a new XML structure. It passes a pointer to a CFXMLNode. If the function returns NULL , the parser skips the structure.

The CFXMLParserAddChildCallBack function is called when the parser encounters a child structure. It notifies you of the parent-child relationship and passes the data you returned from CFXMLParserCreateXMLStructureCallBack for both the parent and child.

The CFXMLParserEndXMLStructureCallBack function is called when the parser exits an XML structure reported by CFXMLParserCreateXMLStructureCallBack . It passes the data you returned from CFXMLParserCreateXMLStructureCallBack .

The CFXMLParserResolveExternalEntityCallBack function is called when the parser encounters an XML external entity reference. It passes the publicID and systemID data for the entity. It is up to you to load the data if you wish and return it as a CFData. Not currently supported.

The CFXMLParserHandleErrorCallBack is called when the parser encounters an error condition. It passes an error code indicating the nature of the error. From within your error handler, you can use the function CFXMLParserCopyErrorDescription to get a CFString describing the error condition. You can also use the functions CFXMLParserGetLineNumber and CFXMLParserGetLocation to learn the exact location of the error within the XML document.

At any point during the parsing you can use the function CFXMLParserGetStatusCode to find out what the parser is doing. You can also call CFXMLParserAbort to signal an error.

Parser Option Flags

There are various options you can use to configure the parser's behavior. An option flag of 0 , or kCFXMLParserNoOptions , leaves the XML as "intact" as possible. In other words, this option causes the parser to report all structures and performs no entity replacements. To make the parser do the most work, returning only the pure element tree, set the option flag to kCFXMLParserAllOptions .

Table 1-2 Parser option Flags
Flag	Description	Status
`kCFXMLParserValidateDocument`	Validate the document against its DTD schema, reporting any errors.	Not supported
`kCFXMLParserSkipMetaData`	Silently skip over metadata constructs (the DTD and comments).	supported
`kCFXMLParserReplacePhysicalEntities`	Replace declared entities like <.	Not supported
`kCFXMLParserSkipWhitespace`	Skip over all whitespace that does not abut non-whitespace character data.For example, given <foo> <bar> blah </bar></foo>, the whitespace between foo's open tag and bar's open tag would be suppressed, but the whitespace around blah would be preserved.	Supported
`kCFXMLParserAddImpliedAttributes`	Where the DTD specifies implied attribute-value pairs for a particular element, add those pairs to any occurances of the element in the element tree.	Not Supported
`kCFXMLParserAllOptions`	All of the supported options.	Supported
`kCFXMLParserNoOptions`	No options.	Supported

The section Using the Low-Level Parser Interface shows you how to parse an XML document using the low-level parser API.