| Derived from | |
| Framework | CoreFoundation/CoreFoundation.h |
| Companion guide | |
| Declared in | CFXMLParser.h |
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.
Causes a parser to abort with the given error code and description.
void CFXMLParserAbort ( CFXMLParserRef parser, CFXMLParserStatusCode errorCode, CFStringRef errorDescription );
The parser to abort.
The error code to return to the parser.
The error description string to return to the parser. This value may not be NULL.
This function cannot be called asynchronously. In other words, it must be called from within a parser callback function.
CFXMLParser.h
Returns the user-readable description of the current error condition.
CFStringRef CFXMLParserCopyErrorDescription ( CFXMLParserRef parser );
The XML parser to examine.
A user-readable description of the current error condition, or NULL if no error occurred. Ownership follows the Create Rule.
CFXMLParser.h
Creates a new XML parser for the specified XML data.
CFXMLParserRef CFXMLParserCreate ( CFAllocatorRef allocator, CFDataRef xmlData, CFURLRef dataSource, CFOptionFlags parseOptions, CFIndex versionOfNodes, CFXMLParserCallBacks *callBacks, CFXMLParserContext *context );
The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.
The XML data to parse. Do not pass NULL.
The URL from which the XML data was obtained. The URL is used to resolve any relative references found in XML Data. Pass NULL if a valid URL is unavailable.
Flags which control how the XML data will be parsed. See Parsing Options for the list of available options.
Determines which version of CFXMLNode objects are produced by the parser.
Callbacks called by the parser as the XML is processed. The callbacks are called as each XML tag is encountered, when an external entity needs to be resolved, and when an error occurs. See CFXMLParserCallBacks and the individual callbacks for more details. Do not pass NULL.
Determines what, if any, information pointer is passed to the callbacks as the parse progresses; context may be NULL.
The newly created parser. Ownership follows the Create Rule.
CFXMLParser.h
Creates a new XML parser for the specified XML data at the specified URL.
CFXMLParserRef CFXMLParserCreateWithDataFromURL ( CFAllocatorRef allocator, CFURLRef dataSource, CFOptionFlags parseOptions, CFIndex versionOfNodes, CFXMLParserCallBacks *callBacks, CFXMLParserContext *context );
The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.
The URL from which to load the XML data. The URL is used to resolve any relative references found in XML Data. May be NULL if a valid URL is unavailable.
Flags which control how the XML data will be parsed. See Parsing Options for the list of available options.
Determines which version of CFXMLNode objects are produced by the parser.
Callbacks called by the parser as the XML is processed. The callbacks are called as each XML tag is encountered, when an external entity needs to be resolved, and when an error occurs. See CFXMLParserCallBacks and the individual callbacks for more details. Do not pass NULL.
Determines what, if any, information pointer is passed to the callbacks as the parse progresses; may be NULL.
The newly created parser. Ownership follows the Create Rule.
CFXMLParser.h
Returns the callbacks associated with an XML parser when it was created.
void CFXMLParserGetCallBacks ( CFXMLParserRef parser, CFXMLParserCallBacks *callBacks );
The XML parser to examine.
On return, contains the callbacks for parser.
CFXMLParser.h
Returns the context for an XML parser.
void CFXMLParserGetContext ( CFXMLParserRef parser, CFXMLParserContext *context );
The XML parser to examine.
On return, a pointer to the context structure for parser.
If you set a context for the parser, it will be passed to you as a parameter in each of the parser callback functions. The context data structure is application defined and associated with a parser using one of the CFXMLParserCreate... functions.
CFXMLParser.h
Returns the top-most object returned by the create XML structure callback.
void *CFXMLParserGetDocument ( CFXMLParserRef parser );
The XML parser to examine.
The top-most object returned by the createXMLStructure field in the CFXMLParserCallBacks structure. If the returned value is a Core Foundation object, ownership follows the Get Rule.
CFXMLParser.h
Returns the line number of the current parse location.
CFIndex CFXMLParserGetLineNumber ( CFXMLParserRef parser );
The XML parser to examine.
The line number of the current location.
This function is typically used in conjunction with the CFXMLParserHandleErrorCallBack function so that error location information can be reported.
CFXMLParser.h
Returns the character index of the current parse location.
CFIndex CFXMLParserGetLocation ( CFXMLParserRef parser );
The XML parser to examine.
The character index of the current parse location.
This function is typically used in conjunction with the CFXMLParserHandleErrorCallBack function so that error location information can be reported.
CFXMLParser.h
Returns the URL for the XML data being parsed.
CFURLRef CFXMLParserGetSourceURL ( CFXMLParserRef parser );
The XML parser to examine.
The URL for the XML document being parsed. Ownership follows the Get Rule.
CFXMLParser.h
Returns a numeric code indicating the current status of the parser.
CFXMLParserStatusCode CFXMLParserGetStatusCode ( CFXMLParserRef parser );
The XML parser to examine.
A status code indicating the current parser. See Parser Status Codes for a list of possible status codes.
If an error has occurred, the code for the last error is returned. If no error has occurred, a status code is returned.
CFXMLParser.h
Returns the type identifier for the CFXMLParser opaque type.
CFTypeID CFXMLParserGetTypeID ();
The type identifier for the CFXMLParser opaque type.
CFXMLParser.h
Begins a parse of the XML data that was associated with the parser when it was created.
Boolean CFXMLParserParse ( CFXMLParserRef parser );
The XML parser to start.
true if the parse was successful, false otherwise.
Upon success, use the CFXMLParserGetDocument function to get the product of the parse. Upon failure, use the CFXMLParserGetContext or CFXMLParserCopyErrorDescription functions to get information about the error. It is an error to call the CFXMLParserParse function while a parse is already underway.
CFXMLParser.hCallback 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 );
The CFXMLParser object making the callback.
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.
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.
The program-defined context data you specified in the CFXMLParserContext structure when creating the parser.
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.
CFXMLParser.hCallback 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 );
The program-defined context data you specified in the CFXMLParserContext structure when creating the parser.
A textual description of info. The caller is responsible for releasing this object.
CFXMLParser.hCallback 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 );
The CFXMLParser object making the callback.
The CFXMLNode object that represents the XML structure encountered.
The program-defined context data you specified in the CFXMLParserContext structure when creating the parser.
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.
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.
CFXMLParser.hCallback 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 );
The CFXMLParser object making the callback.
The program-defined value representing the XML element whose end tag has been detected. This value was returned by the CFXMLParserCreateXMLStructureCallBack callback.
The program-defined context data you specified in the CFXMLParserContext structure when creating the parser.
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.
CFXMLParser.hCallback 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 );
A CFXMLParser object making the callback.
A status code describing the error.
The program-defined context data you specified in the CFXMLParserContext structure when creating the parser.
true if the parser should continue parsing the XML, false if the parser should stop.
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.
CFXMLParser.hCallback 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 );
The program-defined context data you specified in the CFXMLParserContext structure when creating the parser.
CFXMLParser.hCallback 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 );
The CFXMLParser object making the callback.
The identifier for the external entity.
The program-defined context data you specified in the CFXMLParserContext structure when creating the parser.
The external entity or NULL if it should not be resolved.
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.
CFXMLParser.hCallback 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 );
The program-defined context data you specified in the CFXMLParserContext structure when creating the parser.
CFXMLParser.hContains 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;
versionVersion number. Must be 0.
createXMLStructureCalled when an XML structure is created.
addChildCalled when a child is added.
endXMLStructureCalled when an XML structure has ended.
resolveExternalEntityCalled when an external entity needs to be resolved.
handleErrorCalled when a parse error needs to be handled.
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.
CFXMLParser.h
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;
versionVersion number of this structure. Must be 0.
infoAn arbitrary program-defined value passed to all the callbacks in this structure and in the CFXMLParserCallBacks structure.
retainA retain callback for your program-defined context data. Optional.
releaseA release callback for your program-defined context data. Optional.
copyDescriptionA copy description callback for your program-defined context data. Optional.
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.
CFXMLParser.hA reference to an XML parser object.
typedef struct __CFXMLParser *CFXMLParserRef;
CFXMLParser.hThe 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;
kCFXMLStatusParseNotBegunIndicates the parser has not begun.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLStatusParseInProgressIndicates the parser is in progress.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLStatusParseSuccessfulIndicates the parser was successful.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLErrorUnexpectedEOFIndicates an unexpected EOF occurred.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLErrorUnknownEncodingIndicates an unknown encoding error.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLErrorEncodingConversionFailureIndicates an encoding conversion error.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLErrorMalformedProcessingInstructionIndicates a malformed processing instruction.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLErrorMalformedDTDIndicates a malformed DTD.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLErrorMalformedNameIndicates a malformed name.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLErrorMalformedCDSectIndicates a malformed CDATA section.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLErrorMalformedCloseTagIndicates a malformed close tag.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLErrorMalformedStartTagIndicates a malformed start tag.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLErrorMalformedDocumentIndicates a malformed document.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLErrorElementlessDocumentIndicates a document containing no elements.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLErrorMalformedCommentIndicates a malformed comment.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLErrorMalformedCharacterReferenceIndicates a malformed character reference.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLErrorMalformedParsedCharacterDataIndicates malformed character data.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLErrorNoDataIndicates a no data error.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
Parser status is determined by calling the CFXMLParserGetStatusCode function. The parser reports errors to your application by invoking the CFXMLParserHandleErrorCallBack function.
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;
kCFXMLParserValidateDocumentValidates the document against its grammar from the DTD, reporting any errors. Currently not supported.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLParserSkipMetaDataSilently skip over metadata constructs (the DTD and comments).
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLParserReplacePhysicalEntitiesReplaces declared entities like <. 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 Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLParserSkipWhitespaceSkip 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 Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLParserResolveExternalEntitiesResolves all external entities.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLParserAddImpliedAttributesWhere 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 Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLParserAllOptionsMakes the parser do the most work, returning only the pure elementtree.
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
kCFXMLParserNoOptionsLeaves the XML as "intact" as possible (reports all structures; performs no replacements).
Available in Mac OS X v10.0 and later.
Declared in CFXMLParser.h
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.
Last updated: 2006-02-07