Functions
Abstract: Causes a parse to abort with the given error code and description.
void CFXMLParserAbort(CFXMLParserRef parser, CFXMLParserStatusCode errorCode, CFStringRef errorDescription);
This function cannot be called asynchronously. In other words, it must be called from within a parser callback function.
Parameters
| Name | Description |
|---|
| errorCode | The error code you wish to return to the parser. See CFXMLStatus for a list of possible values. |
| errorDescription | The error description string you wish to return to the parser. This value may not be NULL. |
Abstract: The callback function invoked by the parser to notify your application of parent/child relationships between XML structures. You are required to implement this callback in order for the parser to operate.
typedef void(*CFXMLParserAddChildCallBack)(CFXMLParserRef parser, void *parent, void *child, void *info);
When the parser encounters a new XML structure, it first calls your createStructure function. If this new structure is a child of a previously encountered structure, the parser also calls your addChild function. The parser passes you pointers to the data you returned from createStructure for both the parent and child. If your implementation of createStructure returns NULL for a given structure, that structure is skipped, and addChild will NOT be called for either a NULL child or parent. The only exception is for the document as a whole, if you return NULL from your createStructure implementation for the document, you will still be called for the top-most element.
Parameters
| Name | Description |
|---|
| parser | The calling parser. |
| parent | The data returned from your createStructure callback for the parent XML structure. |
| child | The data returned from your createStructure callback for the child XML structure. |
| info | User defined. From the context associated with the parser when it was created. |
Abstract: The callback function invoked by the parser when handling the info pointer in a CFXMLParserContext.
typedef CFStringRef(*CFXMLParserCopyDescriptionCallBack)(const void *info);
If the parser has a context associated with it, this callback is invoked. The function should return a text description of the object or structure pointed to by the info pointer.
Parameters
| Name | Description |
|---|
| info | User defined. |
Result: A text description of the object or structure pointed to by the info pointer.
Abstract: Returns the user-readable description of the current error condition.
CFStringRef CFXMLParserCopyErrorDescription(CFXMLParserRef parser);
If no error has occurred, NULL is returned.
Parameters
| Name | Description |
|---|
| parser | The XML parser whose error string you wish to obtain. |
Result: A user-readable description of the current error condition.
Abstract: 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);
Parameters
| Name | Description |
|---|
| allocator | The memory allocator to use. Pass NULL or kCFAllocatorDefault to use the system allocator. |
| xmlData | The XML data you wish to parse. Do not pass NULL. |
| dataSource | 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. |
| parseOptions | Flags which control how the XML data will be parsed. See CFXMLParserOptions for a list of possible values. |
| versionOfNodes | Determines which version CFXMLNodes are produced by the parser |
| callbacks | callbacks called by the parser as the parse progresses. Do not pass NULL. |
| context | determines what if any info pointer is passed to the callbacks as the parse progresses; context may be NULL. |
Result: The newly created parser.
Abstract: The callback function invoked by the parser as new XML structures are encountered. You are required to implement this callback in order for the parser to operate.
typedef void *(*CFXMLParserCreateXMLStructureCallBack)(CFXMLParserRef parser, CFXMLNodeRef nodeDesc, void *info);
As an XML document is parsed, the data type for each XML structure is converted into a CFXMLNode. During this conversion, an identifier representing the XML data type and the XML data itself is placed in the node. For performance reasons, the node passed to createXMLStructure cannot be safely retained by the client; the node as a whole must be copied (via CFXMLNodeCreateCopy), or its contents must be extracted and copied.
Parameters
| Name | Description |
|---|
| parser | The calling parser. |
| nodeDesc | The node description. Any values that are to be kept should be copied - this includes CFStrings and other CF objects within the data returned. It is NOT sufficient to retain such objects, they must be copied. A convenience function - CFXMLNodeCreateCopy - is provided to perform the necessary copies. |
| info | User defined. From the context associated with the parser when it was created. |
Result: This return value can be anything you wish. It is kept by the parser and passed back to you via the AddChild and EndStructure callbacks. Return NULL to indicate that the given structure should be skipped. 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. The createStructure callback - or indeed, 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.
Abstract: The callback function invoked by the parser to notify your application that an XML structure (and all its children) have been completely parsed. Implementing this callback is optional.
typedef void(*CFXMLParserEndXMLStructureCallBack)(CFXMLParserRef parser, void *xmlType, void *info);
When the parser encounters a new XML structure, it first calls your createStructure function. The parser passes you pointers to the data you returned from createStructure for both the parent and child. If your implementation of createStructure returns NULL for a given structure, that structure is skipped. This callback will not be called for any children of the skipped structure.
Parameters
| Name | Description |
|---|
| parser | The calling parser. |
| xmlType | The data returned from your createStructure callback for the this XML structure. |
| info | User defined. A context is associated with a parser using the function CFXMLParserSetContext. |
Abstract: Returns the callbacks associated with an XML parser.
void CFXMLParserGetCallBacks(CFXMLParserRef parser, CFXMLParserCallBacks *callBacks);
A set of callbacks is associated with a parser using the CFXMLParserSetCallBacks function.
Parameters
| Name | Description |
|---|
| parser | The XML parser whose callbacks you wish to obtain. |
| callBacks | A pointer to your storage for the parser's CFXMLParserCallBacks structure. |
Abstract: Returns the context for an XML parser.
void CFXMLParserGetContext(CFXMLParserRef parser, CFXMLParserContext *context);
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 the CFXMLParserSetContext function.
Parameters
| Name | Description |
|---|
| parser | The XML parser whose context you wish to obtain. |
| context | On return, a pointer to the context structure for the parser. |
Abstract: Returns the top-most object returned by the createXMLStructure callback.
void *CFXMLParserGetDocument(CFXMLParserRef parser);
Parameters
| Name | Description |
|---|
| parser | The XML parser whose document object you wish to obtain. |
Result: The top-most object returned by the createXMLStructure callback.
Abstract: Returns the line number of the current parse location.
CFIndex CFXMLParserGetLineNumber(CFXMLParserRef parser);
This function is typically used in conjunction with the CFXMLParserHandleErrorCallBack function so that error location information can be reported.
Parameters
| Name | Description |
|---|
| parser | The XML parser whose parse location you wish to obtain. |
Result: The line number of the current parse location.
Abstract: Returns the character index of the current parse location.
CFIndex CFXMLParserGetLocation(CFXMLParserRef parser);
This function is typically used in conjunction with the CFXMLParserHandleErrorCallBack function so that error location information can be reported.
Parameters
| Name | Description |
|---|
| parser | The XML parser whose parse location you wish to obtain. |
Result: The character index of the current parse location.
Abstract: Obtains the URL for the XML data being parsed.
CFURLRef CFXMLParserGetSourceURL(CFXMLParserRef parser);
Parameters
| Name | Description |
|---|
| parser | The XML parser whose data URL you wish to obtain. |
Result: The URL for the XML document being parsed.
Abstract: Returns a numeric code indicating the current status of the parser.
CFXMLParserStatusCode CFXMLParserGetStatusCode(CFXMLParserRef parser);
If an error has occurred, the code for last error is returned. If no error has occurred, a status code is returned. See XXX for possible status return values.
Parameters
| Name | Description |
|---|
| parser | The XML parser whose status you wish to obtain. |
Result: A status code indicating the current parser.
Abstract: The callback function invoked by the parser to notify your application that an error has occured. You are required to implement this callback in order for the parser to operate.
typedef Boolean(*CFXMLParserHandleErrorCallBack)(CFXMLParserRef parser, CFXMLParserStatusCode error, void *info);
Use the function CFXMLParserCopyErrorDescription to get a textual description of the error condition. The HandleError function is not required for the parser to function. Set the appropriate field of the CFXMLParserCallbacks structure to NULL if you do not wish to implement this callback. If the function pointer is NULL, the parser will silently attempt to recover.
Parameters
| Name | Description |
|---|
| parser | The calling parser. |
| error | The error code indicating the type of problem the parser encountered. See CFXMLParserStatus for a list of possible values. |
| info | User defined. From the context associated with the parser when it was created. |
Result: Return FALSE to force the parser to stop. Return TRUE if you want the parser to attempt to recover. Fatal errors will still cause the parse to abort immediately)
Abstract: Begins a parse of the XML data that was associated with the parser when it was created.
Boolean CFXMLParserParse(CFXMLParserRef parser);
Upon success, use CFXMLParserGetDocument to get the product of the parse. Upon failure, use CFXMLParserGetErrorCode or CFXMLParserCopyErrorDescription to get information about the error. It is an error to call CFXMLParserParse while a parse is already underway.
Parameters
| Name | Description |
|---|
| parser | The XML parser to start. |
Result: TRUE if the parse was successful, FALSE if the parse failed.
Abstract: The callback function invoked by the parser when handling the info pointer in a CFXMLParserContext.
typedef void(*CFXMLParserReleaseCallBack)(const void *info);
If the parser has a context associated with it, this callback is invoked to decrement the retain count of the object the info pointer points to.
Parameters
| Name | Description |
|---|
| info | User defined. |
Result: User Defined.
Abstract: The callback function invoked by the parser to notify your application that an external entity has been referenced. Implementing this callback is optional.
typedef CFDataRef(*CFXMLParserResolveExternalEntityCallBack)(CFXMLParserRef parser, CFXMLExternalID *extID, void *info);
This callback is invoked when external entities are referenced, NOT when they are simply defined. Set the resolveExternalEntity field of the CFXMLParserCallbacks structure to NULL if you do not wish to implement this callback. If the function pointer is NULL, the parser tries to resolve the entity on its own. If the function pointer is set, and the function returns NULL, a place holder for the external entity is inserted into the tree. Using this technique, your application can prevent any external network or file accesses by the parser.
Parameters
| Name | Description |
|---|
| parser | The calling parser. |
| extID | The external ID for the external entity reference. |
| info | User defined. From the context associated with the parser when it was created. |
Result: The external entity data loaded by your ResolveExternalEntity function.
Abstract: The callback function invoked by the parser when handling the info pointer in a CFXMLParserContext.
typedef const void *(*CFXMLParserRetainCallBack)(const void *info);
If the parser has a context associated with it, this callback is invoked to increment the retain count of the object the info pointer points to.
Parameters
| Name | Description |
|---|
| info | User Defined. |
Result: User Defined.
Abstract: Parses the specified XML data and returns the resulting CFXMLTree.
CFXMLTreeRef CFXMLTreeCreateFromData(CFAllocatorRef allocator, CFDataRef xmlData, CFURLRef dataSource, CFOptionFlags parseOptions, CFIndex versionOfNodes);
This function represents the high-level interface to the XML parser. This single function creates a parser for the specified XML data using the specified options. The parser creates and returns a CFXMLTree that you can examine and modify with the CFTree API or with the profided convenience functions such as CFXMLTreeGetDescription, CFXMLTreeGetString, and CFXMLTreeGetDataType.
Parameters
| Name | Description |
|---|
| allocator | The memory allocator to use. Pass NULL or kCFAllocatorDefault to use the system allocator. |
| xmlData | The XML data you wish to parse. |
| dataSource | 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 unavailiable. |
| parseOptions | Flags which control how the XML data will be parsed. See XXX for a list of possible values. |
| versionOfNodes | Determines which version CFXMLNodes are produced by the parser |
Result: The newly created CFXMLTree containing the data from the specified XML document.
Abstract: Generates an XML document from a CFXMLTree which is ready to be written to permanent storage.
CFDataRef CFXMLTreeCreateXMLData(CFAllocatorRef allocator, CFXMLTreeRef xmlTree);
This function will NOT regenerate entity references replaced at the parse time (except those required for syntactic correctness). If you need this you must manually walk the tree and re-insert any entity references that should appear in the final output file.
Parameters
| Name | Description |
|---|
| allocator | The memory allocator to use. Pass NULL or kCFAllocatorDefault to use the system allocator. |
| xmlTree | The CFXMLTreeRef you wish to convert to an XML document. |
Result: The XML data.
© 2000 Apple Computer, Inc. — (Last Updated 7/20/2000)