CFXMLParser Reference

Derived from	CFType
Framework	CoreFoundation/CoreFoundation.h
Companion guide	XML Programming Topics for Core Foundation
Declared in	CFXMLParser.h

Overview

CFXMLParser provides an XML parser you can use to find and extract data in XML documents. You can use a high-level interface to load an XML document into a Core Foundation collection object. A low-level callback-based interface allows you to perform any action you wish on an XML structured type when it is detected by the parser. This opaque type is relevant for applications that need information about an XML document's structure or content.

Callbacks

CFXMLParserAddChildCallBack

Callback function invoked by the parser to notify your application of parent/child relationships between XML structures.

typedef void (*CFXMLParserAddChildCallBack) (
   CFXMLParserRef parser,
   void *parent,
   void *child,
   void *info
);

If you name your function MyCallBack, you would declare it like this:

void MyCallBack (
   CFXMLParserRef parser,
   void *parent,
   void *child,
   void *info
);

Parameters

parser: The CFXMLParser object making the callback.
parent: The program-defined value representing the XML element to whom child is being added. This value was returned by the CFXMLParserCreateXMLStructureCallBack callback when this element’s open tag was detected.
child: The program-defined value representing the XML element that is being added to parent. This value was returned by the CFXMLParserCreateXMLStructureCallBack callback when this element’s open tag was detected.
info: The program-defined context data you specified in the CFXMLParserContext structure when creating the parser.

Discussion

If the CFXMLParserCreateXMLStructureCallBack function returns NULL for a given structure, that structure is omitted entirely, and this callback will not be called for either a NULL child or parent.

Availability

Available in OS X v10.0 and later.

Declared In

CFXMLParser.h

CFXMLParserCopyDescriptionCallBack

Callback function invoked by the parser when handling the information pointer.

typedef CFStringRef (*CFXMLParserCopyDescriptionCallBack) (
   const void *info
);

If you name your function MyCallBack, you would declare it like this:

CFStringRef MyCallBack (
   const void *info
);

Parameters

info: The program-defined context data you specified in the CFXMLParserContext structure when creating the parser.

Return Value

A textual description of info. The caller is responsible for releasing this object.

Availability

Available in OS X v10.0 and later.

Declared In

CFXMLParser.h

CFXMLParserCreateXMLStructureCallBack

Callback function invoked when the parser encounters an XML open tag.

typedef void *(*CFXMLParserCreateXMLStructureCallBack) (
   CFXMLParserRef parser,
   CFXMLNodeRef nodeDesc,
   void *info
);

If you name your function MyCallBack, you would declare it like this:

void *MyCallBack (
   CFXMLParserRef parser,
   CFXMLNodeRef nodeDesc,
   void *info
);

Parameters

parser: The CFXMLParser object making the callback.
nodeDesc: The CFXMLNode object that represents the XML structure encountered.
info: The program-defined context data you specified in the CFXMLParserContext structure when creating the parser.

Return Value

A program-defined value representing the new XML element or NULL to indicate that the given structure should be skipped. This value is passed to the other callbacks.

Discussion

If NULL is returned for a given structure, only minimal parsing is done for that structure (enough to correctly determine its end, and to extract any data necessary for the remainder of the parse, such as Entity definitions). This callback (or any of the tree-creation callbacks) will not be called for any children of the skipped structure. The only exception is that the top-most element will always be reported even if NULL was returned for the document as a whole. For performance reasons, the node passed to this callback cannot be safely retained by the client; the node as a whole must be copied (using the CFXMLNodeCreateCopy function), or its contents must be extracted and copied. You are required to implement this callback for the parser to operate.

Availability

Available in OS X v10.0 and later.

Declared In

CFXMLParser.h

CFXMLParserEndXMLStructureCallBack

Callback function invoked by the parser to notify your application that an XML structure (and all its children) have been completely parsed.

typedef void (*CFXMLParserEndXMLStructureCallBack) (
   CFXMLParserRef parser,
   void *xmlType,
   void *info
);

If you name your function MyCallBack, you would declare it like this:

void MyCallBack (
   CFXMLParserRef parser,
   void *xmlType,
   void *info
);

Parameters

parser: The CFXMLParser object making the callback.
xmlType: The program-defined value representing the XML element whose end tag has been detected. This value was returned by the CFXMLParserCreateXMLStructureCallBack callback.
info: The program-defined context data you specified in the CFXMLParserContext structure when creating the parser.

Discussion

As elements are encountered, this callback is called first, then the CFXMLParserAddChildCallBack callback to add the new structure to its parent, then the CFXMLParserAddChildCallBack callback (potentially several times) to add the new structure's children to it, and then finally the CFXMLParserEndXMLStructureCallBack callback to show that the structure has been fully parsed.This callback is optional.

Availability

Available in OS X v10.0 and later.

Declared In

CFXMLParser.h

CFXMLParserHandleErrorCallBack

Callback function invoked by the parser to notify your application that an error has occurred.

typedef Boolean (*CFXMLParserHandleErrorCallBack) (
   CFXMLParserRef parser,
   CFXMLParserStatusCode error,
   void *info
);

If you name your function MyCallBack, you would declare it like this:

Boolean MyCallBack (
   CFXMLParserRef parser,
   CFXMLParserStatusCode error,
   void *info
);

Parameters

parser: A CFXMLParser object making the callback.
error: A status code describing the error.
info: The program-defined context data you specified in the CFXMLParserContext structure when creating the parser.

Return Value

true if the parser should continue parsing the XML, false if the parser should stop.

Discussion

If this callback is not defined, the parser will silently attempt to recover. Otherwise, this callback may return false to force the parser to stop. If this callback returns true, the parser will attempt to recover (fatal errors will still cause the parse to abort immediately). This callback is optional.

Availability

Available in OS X v10.0 and later.

Declared In

CFXMLParser.h

CFXMLParserReleaseCallBack

Callback function invoked by the parser when it wants to release a reference to the information pointer.

typedef void (*CFXMLParserReleaseCallBack) (
   const void *info
);

If you name your function MyCallBack, you would declare it like this:

void MyCallBack (
   const void *info
);

Parameters

info: The program-defined context data you specified in the CFXMLParserContext structure when creating the parser.

Availability

Available in OS X v10.0 and later.

Declared In

CFXMLParser.h

CFXMLParserResolveExternalEntityCallBack

Callback function invoked by the parser to notify your application that an external entity has been referenced.

typedef CFDataRef (*CFXMLParserResolveExternalEntityCallBack) (
   CFXMLParserRef parser,
   CFXMLExternalID *extID,
   void *info
);

If you name your function MyCallBack, you would declare it like this:

CFDataRef MyCallBack (
   CFXMLParserRef parser,
   CFXMLExternalID *extID,
   void *info
);

Parameters

parser: The CFXMLParser object making the callback.
extID: The identifier for the external entity.
info: The program-defined context data you specified in the CFXMLParserContext structure when creating the parser.

Return Value

The external entity or NULL if it should not be resolved.

Discussion

If this callback is not defined, the parser uses its internal routines to try and resolve the entity. Otherwise, if this callback returns NULL, a place holder for the external entity is inserted into the tree. In this manner, the parser's client can prevent any external network or file accesses. This callback is optional.

Availability

Available in OS X v10.0 and later.

Declared In

CFXMLParser.h

CFXMLParserRetainCallBack

Callback function invoked by the parser when it needs another reference to the information pointer.

typedef const void *(*CFXMLParserRetainCallBack) (
   const void *info
);

If you name your function MyCallBack, you would declare it like this:

const void *MyCallBack (
   const void *info
);

Parameters

info: The program-defined context data you specified in the CFXMLParserContext structure when creating the parser.

Availability

Available in OS X v10.0 and later.

Declared In

CFXMLParser.h

Data Types

CFXMLParserCallBacks

Contains version information and function pointers to callbacks needed when parsing XML.

struct CFXMLParserCallBacks {
   CFIndex version;
   CFXMLParserCreateXMLStructureCallBack createXMLStructure;
   CFXMLParserAddChildCallBack addChild;
   CFXMLParserEndXMLStructureCallBack endXMLStructure;
   CFXMLParserResolveExternalEntityCallBack resolveExternalEntity;
   CFXMLParserHandleErrorCallBack handleError;
};
typedef struct CFXMLParserCallBacks CFXMLParserCallBacks;

Fields

version: Version number. Must be 0.
createXMLStructure: Called when an XML structure is created.
addChild: Called when a child is added.
endXMLStructure: Called when an XML structure has ended.
resolveExternalEntity: Called when an external entity needs to be resolved.
handleError: Called when a parse error needs to be handled.

Discussion

This structure is passed to one of the CFXMLParserCreate... functions. Only the createXMLStructure, addChild, and endXMLStructure fields are required. Set the others to NULL if you don't wish to implement them.

Availability

Available in OS X v10.0 and later.

Declared In

CFXMLParser.h

CFXMLParserContext

Contains version information and function pointers to callbacks used when handling a program-defined context.

struct CFXMLParserContext {
   CFIndex version;
   void *info;
   CFXMLParserRetainCallBack retain;
   CFXMLParserReleaseCallBack release;
   CFXMLParserCopyDescriptionCallBack copyDescription;
};
typedef struct CFXMLParserContext CFXMLParserContext;

Fields

version: Version number of this structure. Must be 0.
info: An arbitrary program-defined value passed to all the callbacks in this structure and in the CFXMLParserCallBacks structure.
retain: A retain callback for your program-defined context data. Optional.
release: A release callback for your program-defined context data. Optional.
copyDescription: A copy description callback for your program-defined context data. Optional.

Discussion

You can associate a context with a parser when the parser is created. The context can be anything you wish and will be passed as a parameter to all of the XML parser callbacks.

Availability

Available in OS X v10.0 and later.

Declared In

CFXMLParser.h

CFXMLParserRef

A reference to an XML parser object.

typedef struct __CFXMLParser *CFXMLParserRef;

Availability

Available in OS X v10.0 and later.

Declared In

CFXMLParser.h

Constants

Parser Status Codes

The various status and error flags that can be returned by the parser.

enum CFXMLParserStatusCode {
   kCFXMLStatusParseNotBegun = -2,
   kCFXMLStatusParseInProgress = -1,
   kCFXMLStatusParseSuccessful = 0,
   kCFXMLErrorUnexpectedEOF = 1,
   kCFXMLErrorUnknownEncoding = 2,
   kCFXMLErrorEncodingConversionFailure = 3,
   kCFXMLErrorMalformedProcessingInstruction = 4,
   kCFXMLErrorMalformedDTD = 5,
   kCFXMLErrorMalformedName = 6,
   kCFXMLErrorMalformedCDSect = 7,
   kCFXMLErrorMalformedCloseTag = 8,
   kCFXMLErrorMalformedStartTag = 9,
   kCFXMLErrorMalformedDocument = 10,
   kCFXMLErrorElementlessDocument = 11,
   kCFXMLErrorMalformedComment = 12,
   kCFXMLErrorMalformedCharacterReference = 13,
   kCFXMLErrorMalformedParsedCharacterData = 14,
   kCFXMLErrorNoData = 15
};
typedef enum CFXMLParserStatusCode CFXMLParserStatusCode;

Constants

kCFXMLStatusParseNotBegun

Indicates the parser has not begun.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLStatusParseInProgress

Indicates the parser is in progress.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLStatusParseSuccessful

Indicates the parser was successful.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLErrorUnexpectedEOF

Indicates an unexpected EOF occurred.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLErrorUnknownEncoding

Indicates an unknown encoding error.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLErrorEncodingConversionFailure

Indicates an encoding conversion error.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLErrorMalformedProcessingInstruction

Indicates a malformed processing instruction.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLErrorMalformedDTD

Indicates a malformed DTD.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLErrorMalformedName

Indicates a malformed name.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLErrorMalformedCDSect

Indicates a malformed CDATA section.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLErrorMalformedCloseTag

Indicates a malformed close tag.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLErrorMalformedStartTag

Indicates a malformed start tag.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLErrorMalformedDocument

Indicates a malformed document.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLErrorElementlessDocument

Indicates a document containing no elements.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLErrorMalformedComment

Indicates a malformed comment.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLErrorMalformedCharacterReference

Indicates a malformed character reference.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLErrorMalformedParsedCharacterData

Indicates malformed character data.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLErrorNoData

Indicates a no data error.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

Discussion

Parser status is determined by calling the CFXMLParserGetStatusCode function. The parser reports errors to your application by invoking the CFXMLParserHandleErrorCallBack function.

Parsing Options

Options you can use to control the parser's treatment of an XML document.

enum CFXMLParserOptions {
   kCFXMLParserValidateDocument = (1 << 0),
   kCFXMLParserSkipMetaData = (1 << 1),
   kCFXMLParserReplacePhysicalEntities = (1 << 2),
   kCFXMLParserSkipWhitespace = (1 << 3),
   kCFXMLParserResolveExternalEntities = (1 << 4),
   kCFXMLParserAddImpliedAttributes = (1 << 5),
   kCFXMLParserAllOptions = 0x00FFFFFF,
   kCFXMLParserNoOptions = 0
};
typedef enum CFXMLParserOptions CFXMLParserOptions;

Constants

kCFXMLParserValidateDocument

Validates the document against its grammar from the DTD, reporting any errors. Currently not supported.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLParserSkipMetaData

Silently skip over metadata constructs (the DTD and comments).

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLParserReplacePhysicalEntities

Replaces declared entities like &lt;. Note that other than the 5 predefined entities (lt, gt, quot, amp, apos), these must be defined in the DTD. Currently not supported.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLParserSkipWhitespace

Skip over all whitespace that does not abut non-whitespace character data. In other words, 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.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLParserResolveExternalEntities

Resolves all external entities.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLParserAddImpliedAttributes

Where the DTD specifies implied attribute-value pairs for a particular element, add those pairs to any occurrences of the element in the element tree. Currently not supported.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLParserAllOptions

Makes the parser do the most work, returning only the pure elementtree.

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

kCFXMLParserNoOptions

Leaves the XML as "intact" as possible (reports all structures; performs no replacements).

Available in OS X v10.0 and later.

Declared in CFXMLParser.h.

Discussion

These are the various options you use to configure the parser. An option flag of 0 (kCFXMLParserNoOptions) leaves the XML as "intact" as possible (reports all structures; performs no replacements). Hence, to make the parser do the most work, returning only the pure element tree, set the option flag to kCFXMLParserAllOptions.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.