The high-level XML parser API is sufficient for many needs. However, there are some cases where using the low-level API is appropriate:
For these and other situations you can use the callback-based API.
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.
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.
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
.
The section Using the Low-Level Parser Interface shows you how to parse an XML document using the low-level parser API.