Next Page >

Hide TOC

CFXMLTree Reference

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

Overview

A CFXMLTree object is simply a CFTree object whose context data is known to be a CFXMLNode object. CFXMLTree is derived from CFTree—you can pass CFXMLTree objects in all the CFTree functions. As such, a CFXMLTree object can be used to represent an entire XML document; the CFTree object provides the tree structure of the document, while the CFXMLNode objects identify and describe the nodes of the tree. An XML document can be parsed to a CFXMLTree object, and a CFXMLTree object can generate the data for the equivalent XML document. This opaque type is expected to be used in conjunction with CFXMLParser and CFXMLNode objects.

Functions

CFXMLCreateStringByEscapingEntities

Given a CFString object containing XML source, returns a CFString object with the specified XML entities escaped. The standard XML entities are always replaced.

CFStringRef CFXMLCreateStringByEscapingEntities(
   CFAllocatorRef allocator,
   CFStringRef string,
   CFDictionaryRef entitiesDictionary,
);

Parameters

allocator: The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.
string: Any CFString object that may contain XML source. This function translates anything in the entities dictionary into the entities as specified. However, this function does not distinguish between tags and the text between tags.
entitiesDictionary: Specifies the entities to be replaced. Dictionary keys should be the entities themselves, and the values should be CFString objects containing the expansion. Pass NULL to indicate no entities other than the standard five.

Return Value

A CFString object derived from string with entities in entitiesDictionary replaced. Ownership follows the Create Rule.

Availability

Available in Mac OS X v10.3 and later.

Declared In

CFXMLParser.h

CFXMLCreateStringByUnescapingEntities

Given a CFString object containing XML source, returns a CFString object with the specified XML entities not escaped. The standard XML entities are always replaced.

CFStringRef CFXMLCreateStringByUnescapingEntities(
   CFAllocatorRef allocator,
   CFStringRef string,
   CFDictionaryRef entitiesDictionary,
);

Parameters

allocator: The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.
string: Any CFString object that may contain XML source. This function translates anything in the entities dictionary into the entities as specified. However, this function does not distinguish between tags and the text between tags.
entitiesDictionary: Specifies the entities that should be replaced. Dictionary keys should be the entities themselves, and the values should be CFString objects containing the expansion. Pass NULL to indicate no entities other than the standard five.

Return Value

A CFString object derived from string with entities in entitiesDictionary that are not replaced. Ownership follows the Create Rule.

Availability

Available in Mac OS X v10.3 and later.

Declared In

CFXMLParser.h

CFXMLTreeCreateFromData

Parses the given XML data and returns the resulting CFXMLTree object.

CFXMLTreeRef CFXMLTreeCreateFromData (
   CFAllocatorRef allocator,
   CFDataRef xmlData,
   CFURLRef dataSource,
   CFOptionFlags parseOptions,
   CFIndex versionOfNodes
);

Parameters

allocator: The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default 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 xmlData. Pass NULL if a valid URL is unavailable.
parseOptions: Flags which control how the XML data will be parsed. See “Parsing Options” for the list of available options.
versionOfNodes: Determines which version of CFXMLNode objects are produced by the parser.

Return Value

A new CFXMLTree object containing the data from the specified XML document. Ownership follows the Create Rule.

Discussion

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 object that you can examine and modify with the CFTree functions or obtain the node using the CFXMLTreeGetNode function and examine its attributes using CFXMLNode functions.

Availability

Available in CarbonLib v1.1 and later.
Available in Mac OS X v10.0 and later.

Declared In

CFXMLParser.h

CFXMLTreeCreateFromDataWithError

Parses the given XML data and returns the resulting CFXMLTree object and any error information.

CFXMLTreeRef CFXMLTreeCreateFromDataWithError (
   CFAllocatorRef allocator,
   CFDataRef xmlData,
   CFURLRef dataSource,
   CFOptionFlags parseOptions,
   CFIndex versionOfNodes
   CFDictionaryRef *errorDict
);

Parameters

allocator: The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default 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 xmlData. Pass NULL if a valid URL is unavailable.
parseOptions: Flags which control how the XML data will be parsed. See “Parsing Options” for the list of available options.
versionOfNodes: Determines which version of CFXMLNode objects are produced by the parser.
errorDict: Upon return, if an error occurs contains a CFDictionary object that describes the error. If no errors occur, this parameter is not changed. Pass NULL if you don’t want error information. See “Error Dictionary Keys” for a description of the key-value pairs in this dictionary. Ownership follows the Create Rule.

Return Value

A new CFXMLTree object containing the data from the specified XML document. Ownership follows the Create Rule.

Discussion

Use this function instead of CFXMLTreeCreateFromData if you need access to XML parsing errors.

Availability

Available in Mac OS X v10.3 and later.

Declared In

CFXMLParser.h

CFXMLTreeCreateWithDataFromURL

Creates a new CFXMLTree object by loading the data to be parsed directly from a data source.

CFXMLTreeRef CFXMLTreeCreateWithDataFromURL (
   CFAllocatorRef allocator,
   CFURLRef dataSource,
   CFOptionFlags parseOptions,
   CFIndex versionOfNodes
);

Parameters

allocator: The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.
dataSource: The URL from which the XML data is 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 “Parsing Options” for the list of available options.
versionOfNodes: Determines which version of CFXMLNode objects are produced by the parser.

Return Value

A new CFXMLTree object containing the data from the specified XML data source. Ownership follows the Create Rule.

Availability

Available in CarbonLib v1.1 and later.
Available in Mac OS X v10.0 and later.

Declared In

CFXMLParser.h

CFXMLTreeCreateWithNode

Creates a childless, parentless CFXMLTree object node for a CFXMLNode object.

CFXMLTreeRef CFXMLTreeCreateWithNode (
   CFAllocatorRef allocator,
   CFXMLNodeRef node
);

Parameters

allocator: The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.
node: The CFXMLNode object to use when creating the new CFXMLTree object.

Return Value

A CFXMLTree object. Ownership follows the Create Rule.

Availability

Available in CarbonLib v1.1 and later.
Available in Mac OS X v10.0 and later.

Declared In

CFXMLNode.h

CFXMLTreeCreateXMLData

Generates an XML document from a CFXMLTree object which is ready to be written to permanent storage.

CFDataRef CFXMLTreeCreateXMLData (
   CFAllocatorRef allocator,
   CFXMLTreeRef xmlTree
);

Parameters

allocator: The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.
xmlTree: The CFXMLTree object you wish to convert to an XML document.

Return Value

The XML data. Ownership follows the Create Rule.

Discussion

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.

Availability

Available in CarbonLib v1.1 and later.
Available in Mac OS X v10.0 and later.

Declared In

CFXMLParser.h

CFXMLTreeGetNode

Returns the node of a CFXMLTree object.

CFXMLNodeRef CFXMLTreeGetNode (
   CFXMLTreeRef xmlTree
);

Parameters

xmlTree: The CFXMLTree object whose node you wish to obtain.

Return Value

The node of xmlTree. Ownership follows the Get Rule.

Availability

Available in CarbonLib v1.1 and later.
Available in Mac OS X v10.0 and later.

Declared In

CFXMLNode.h

Data Types

CFXMLTreeRef

A reference to a CFXMLTree object.

typedef CFTreeRef CFXMLTreeRef;

Discussion

When using the high-level parser API, XML data is parsed to a special CFTree object which is simply a CFXMLTree object with known contexts and callbacks. The nodes of a CFXMLTree may be queried using the basic CFTree functions (to report on the structure of the tree itself), or via the functions here (to report on the XML contents of the nodes).

Availability

Available in Mac OS X v10.0 and later.

Declared In

CFXMLNode.h

Constants

Error Dictionary Keys

The keys used in an error dictionary returned by some functions to provide more information about XML parse errors.

const CFStringRef kCFXMLTreeErrorDescription;
const CFStringRef kCFXMLTreeErrorLineNumber;
const CFStringRef kCFXMLTreeErrorLocation;
const CFStringRef kCFXMLTreeErrorStatusCode;

Constants

kCFXMLTreeErrorDescription

Dictionary key whose value is a CFString containing a readable description of the error.

Available in Mac OS X v10.3 and later.

Declared in CFXMLParser.h

kCFXMLTreeErrorLineNumber

Dictionary key whose value is a CFNumber containing the line number where the error was detected. This may not be the line number where the actual XML error is located.

Available in Mac OS X v10.3 and later.

Declared in CFXMLParser.h

kCFXMLTreeErrorLocation

Dictionary key whose value is a CFNumber containing the byte location where the error was detected.

Available in Mac OS X v10.3 and later.

Declared in CFXMLParser.h

kCFXMLTreeErrorStatusCode

Dictionary key whose value is a CFNumber containing the error status code. See CFXMLParser for possible status code values.

Available in Mac OS X v10.3 and later.

Declared in CFXMLParser.h

Discussion

These keys are used in the error dictionary returned by the CFXMLTreeCreateFromDataWithError function.

Availability

Available in Mac OS X v10.3 and later.

Next Page >

Hide TOC

Last updated: 2006-02-07

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.




	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. \| Terms of use \| Privacy Notice