CFXMLTree Reference

Derived from
CFTree Reference : CFType Reference
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 with unescaped entities, returns a string with specified XML entities escaped. 

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 any substring that is mapped to an entity in entitiesDictionary to the specified entity.

entitiesDictionary

Specifies the entities to be replaced. Dictionary keys should be the entity names (for example, “para” for ¶), 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 substrings identified in entitiesDictionary escaped to their corresponding entities. Ownership follows the Create Rule.

Discussion

The standard five predefined entities are automatically supported.

As an example of using this function, say you apply this function to string “Refer to ¶ 5 of the contract” with a key of “para” mapped to “¶” in entitiesDictionary. The resulting string is “Refer to ¶ 5 of the contract”.

Availability
  • Available in OS X v10.3 and later.
Declared In
CFXMLParser.h

CFXMLCreateStringByUnescapingEntities

Given a CFString object containing XML source with escaped entities, returns a string with specified XML entities unescaped. 

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 any entity that is mapped to an substring in entitiesDictionary to the specified substring.

entitiesDictionary

Specifies the entities to be replaced. Dictionary keys should be the entity names (for example, “para” for ¶), 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 identified in entitiesDictionary unescaped to their corresponding substrings. Ownership follows the Create Rule.

Discussion

The standard five predefined entities are automatically supported.

As an example of using this function, say you apply this function to string “Refer to ¶ 5 of the contract” with a key of “para” mapped to “¶” in entitiesDictionary. The resulting string is “Refer to ¶ 5 of the contract”.

Availability
  • Available in OS X v10.3 and later.
Declared In
CFXMLParser.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 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 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 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 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 Reference for possible status code values.

Available in 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 OS X v10.3 and later.


© 2003, 2008 Apple Inc. All Rights Reserved. (Last updated: 2008-10-15)

Did this document help you? Yes It's good, but... Not helpful...