Mac Developer Library

Developer

CoreFoundation Framework Reference CFXMLTree Reference

Options
Deployment Target:

On This Page
Language:

CFXMLTree Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreFoundation

Objective-C

@import CoreFoundation;

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

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

    Declaration

    Swift

    func CFXMLCreateStringByEscapingEntities(_ allocator: CFAllocator!, _ string: CFString!, _ entitiesDictionary: CFDictionary!) -> CFString!

    Objective-C

    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”.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func CFXMLCreateStringByUnescapingEntities(_ allocator: CFAllocator!, _ string: CFString!, _ entitiesDictionary: CFDictionary!) -> CFString!

    Objective-C

    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”.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    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. The current version is 1.

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Returns the node of a CFXMLTree object.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

Data Types

Miscellaneous

  • A reference to a CFXMLTree object.

    Declaration

    Swift

    typealias CFXMLTreeRef = CFXMLTree

    Objective-C

    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).

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

Constants

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

    Declaration

    Swift

    let kCFXMLTreeErrorDescription: CFString! let kCFXMLTreeErrorLineNumber: CFString! let kCFXMLTreeErrorLocation: CFString! let kCFXMLTreeErrorStatusCode: CFString!

    Objective-C

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

    Constants

    • kCFXMLTreeErrorDescription

      kCFXMLTreeErrorDescription

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

      Available in OS X v10.3 and later.

    • kCFXMLTreeErrorLineNumber

      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.

    • kCFXMLTreeErrorLocation

      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.

    • kCFXMLTreeErrorStatusCode

      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.

    Discussion

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

    Availability

    Available in OS X v10.3 and later.